net.rim.device.api.lbs.maps.model
Class MapDataModel

java.lang.Object
  net.rim.device.api.lbs.maps.model.MapDataModel

All Implemented Interfaces:

Collection, CollectionEventSource, ReadableList

public class MapDataModel
extends Object
implements ReadableList, CollectionEventSource

Represents a container of information for a MapField.

The MapDataModel contains items that can be displayed on the field, including whether the mappable item is visible or not, and what tags apply to the mappable item.

Instances of Mappable that are added to this container must correctly implement hashCode() and equals(Object) because the container uses these methods for storage, retrieval and duplication checking.

Sample Usage

Create a MapDataModel to manage mappable items

 RichMapField map = MapFactory.getInstance().generateRichMapField();
 MapDataModel data = map.getModel();
 

Tag a location

 // create Bob's work location and add it with appropriate tags
 MapLocation bobWork = new MapLocation( 45.34296, -75.91606, "Bob - Work", null );
 int bobWorkId = data.add( bobWork, "bob" );
 data.tag( bobWorkId, "work" );  //locations can have more than one tag
 

Specify visibility of a location

 // set items tagged "work" as visible
 data.setVisibleNone();
 data.setVisible( "work" );
 

Since:

BlackBerry API 6.0.0

Constructor Summary

MapDataModel()
Constructs a new MapDataModel instance.

Method Summary
int	add(Mappable data) Adds the mappable item to the model.
int	add(Mappable data, String tag) Adds the mappable item to the model with a specified tag.
int	add(Mappable data, String tag, boolean visible) Adds the mappable item to the model with a tag and the specified visibility.
void	addAll(MapDataModel data) Adds all the items in the given parameter to this storage container.
void	addAll(Mappable[] data) Adds all the mappable entities in the given array to this storage container.
void	addAll(MappableVector data) Adds all the mappable entities in the given vector to this storage container.
boolean	contains(Mappable data) Determines if this store already contains the specified mappable data.
Mappable	get(int id) Retrieves the mappable item based on the item's ID.
Mappable	get(Integer id) Retrieves the mappable item based on the item's ID.
MappableVector	get(String tag) Retrieves all the mappable elements that are tagged with the specified tag.
Object	getAt(int index) Retrieves element by index.
int	getAt(int index, int count, Object[] elements, int destIndex) Retrieves range of elements starting at provided index.
int	getId(Mappable data) Retrieves the ID for the specified data.
IntVector	getIds(String tag) Retrieves a list of all the IDs that are tagged with the specified tag.
int	getIndex(Object element) Retrieves index by element.
Vector	getTags(int id) Retrieves a vector containing all the tags for a given mappable element.
MappableVector	getVisible() Retrieves all mappable items that are flagged as visible, regardless of the visible area.
LatLonRectangle	getVisibleBoundingBox() Calculates a bounding box of all visible data.
MappableVector	getVisibleData(LatLonRectangle visBoundingBox) Retrieves all the mappable elements in this store that are visible in the specified rectangle.
MappableVector	getVisibleData(MapDimensions visibleArea) Retrieves all the mappable elements in this store that are visible in the specified dimensions.
IntVector	getVisibleIds() Returns the IDs for all visible mappable items.
boolean	isVisible(int id) Determines if the mappable item with the specified ID is visible.
void	remove(int id) Removes the item with the specified ID from the store.
void	remove(String tag) Removes all elements tagged with the specified tag.
void	remove(IntVector ids) Removes all items with the specified IDs.
void	removeAll() Removes all mappable elements from storage.
void	setVisible(int id) Sets the mappable item with the specified ID to visible.
void	setVisible(int id, boolean visible) Sets the visible state of the mappable item that has the specified ID.
void	setVisible(String tag) Sets all mappables items with the specified tag to visible.
void	setVisible(String tag, boolean visible) Sets the visible state for all mappable items with the specified tag.
void	setVisible(Mappable[] visibles) Sets all mappable items in this collection to visible.
void	setVisibleNone() Sets all visible elements to not visible.
int	size() Retrieves the number of elements in this collection.
void	tag(int id, String tag) Tags a single mappable element with the specified tag.
void	tag(Mappable data, String tag) Tags a single element with the specified tag.
Mappable[]	toArray() Retrieves all mappable items in this storage container.
void	untag(int id) Removes all tags from the specified element.
void	untag(int id, String tag) Removes the specified tag from the element with the specified ID.
void	untag(Mappable data, String tag) Removes a tag from a single element.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface net.rim.device.api.collection.CollectionEventSource

addCollectionListener, removeCollectionListener

Constructor Detail

MapDataModel

public MapDataModel()

Constructs a new MapDataModel instance.

Since:

BlackBerry API 6.0.0

Method Detail

add

public int add(Mappable data)

Adds the mappable item to the model. This method is the same as using add( data, null, true ).

Parameters:

data - The new value to be added.

Returns:

The unique ID for the added data.

See Also:

MapDataModel.add(Mappable, String, boolean)

Since:

BlackBerry API 6.0.0

add

public int add(Mappable data,
               String tag)

Adds the mappable item to the model with a specified tag. This method is the same as using add( data, tag, true ).

Parameters:

data - The new value to add.

tag - The tag to apply to the new data.

Returns:

The unique ID for the added data.

See Also:

MapDataModel.add(Mappable, String, boolean)

Since:

BlackBerry API 6.0.0

add

public int add(Mappable data,
               String tag,
               boolean visible)

Adds the mappable item to the model with a tag and the specified visibility. If the mappable entity already exists, the data is not added again. If the existing data does not contain the given tag or visibility, these parameters are set.

Parameters:

data - The new value to data.

tag - The tag to apply to the new data.

visible - If true the mappable item is visible, if false, the mappable item is not visible.

Returns:

The unique ID for the added data or -1 if data is not added.

Since:

BlackBerry API 6.0.0

addAll

public void addAll(Mappable[] data)

Adds all the mappable entities in the given array to this storage container. None of the added entities are tagged, and all entities are labeled as visible.

Parameters:

data - the mappable entities to add.

Since:

BlackBerry API 6.0.0

addAll

public void addAll(MappableVector data)

Adds all the mappable entities in the given vector to this storage container. None of the added entities are tagged, and all entities are labeled as visible.

Parameters:

data - The mappables entities to add.

Since:

BlackBerry API 6.0.0

addAll

public void addAll(MapDataModel data)

Adds all the items in the given parameter to this storage container. All the tags and visibility properties for the items are also copied.

Parameters:

data - The entities to add.

Since:

BlackBerry API 6.0.0

get

public Mappable get(int id)

Retrieves the mappable item based on the item's ID.

Parameters:

id - ID of the mappable item.

Returns:

The mappable item or NullMappable if the item is not found, never returns null.

Since:

BlackBerry API 6.0.0

get

public Mappable get(Integer id)

Retrieves the mappable item based on the item's ID.

Parameters:

id - ID of the mappable item.

Returns:

The mappable item or NullMappable if the item is not found, never returns null.

Since:

BlackBerry API 6.0.0

get

public MappableVector get(String tag)

Retrieves all the mappable elements that are tagged with the specified tag. If there are no items with the specified tag, the returned value is an empty vector.

Parameters:

tag - The tag of the elements to retrieve.

Returns:

The mappable elements with the specified tag, never returns null.

Since:

BlackBerry API 6.0.0

getIds

public IntVector getIds(String tag)

Retrieves a list of all the IDs that are tagged with the specified tag.

Parameters:

tag - The tag of the IDs to retrieve.

Returns:

A collection of IDs, never returns null.

Since:

BlackBerry API 6.0.0

getId

public int getId(Mappable data)

Retrieves the ID for the specified data.

Parameters:

data - The mappable item of the ID to retrieve.

Returns:

The ID of the mappable item, negative is returned if the item does not exist.

Since:

BlackBerry API 6.0.0

contains

public boolean contains(Mappable data)

Determines if this store already contains the specified mappable data.

Parameters:

data - The mappable data to verify.

Returns:

true if the data is already stored, false otherwise.

Since:

BlackBerry API 6.0.0

tag

public void tag(int id,
                String tag)

Tags a single mappable element with the specified tag.

Parameters:

id - The unique ID of the element to be tagged.

tag - The tag to apply.

Since:

BlackBerry API 6.0.0

tag

public void tag(Mappable data,
                String tag)

Tags a single element with the specified tag. This is a convenience method that equates to using tag( getId( data ), tag ).

Parameters:

data - The element (that is already in the store) to be tagged.

tag - The tag to apply.

Since:

BlackBerry API 6.0.0

untag

public void untag(int id,
                  String tag)

Removes the specified tag from the element with the specified ID.

Parameters:

id - The unique ID of the element.

tag - The tag to remove.

Since:

BlackBerry API 6.0.0

untag

public void untag(Mappable data,
                  String tag)

Removes a tag from a single element. This is a convenience method that equates to using untag( getId( data ), tag ).

Parameters:

data - The mappable element that is already in the store.

tag - The tag to remove.

Since:

BlackBerry API 6.0.0

untag

public void untag(int id)

Removes all tags from the specified element.

Parameters:

id - The unique ID of the element to remove all tags from.

Since:

BlackBerry API 6.0.0

remove

public void remove(String tag)

Removes all elements tagged with the specified tag.

Parameters:

tag - The tag for the elements that are to be removed.

Since:

BlackBerry API 6.0.0

remove

public void remove(IntVector ids)

Removes all items with the specified IDs.

Parameters:

ids - The collection of IDs to remove.

Since:

BlackBerry API 6.0.0

remove

public void remove(int id)

Removes the item with the specified ID from the store.

Parameters:

id - The ID of the item to remove.

Since:

BlackBerry API 6.0.0

removeAll

public void removeAll()

Removes all mappable elements from storage.

Since:

BlackBerry API 6.0.0

setVisible

public void setVisible(int id)

Sets the mappable item with the specified ID to visible.

Parameters:

id - The ID of the item that is to be made visible.

Since:

BlackBerry API 6.0.0

setVisible

public void setVisible(int id,
                       boolean visible)

Sets the visible state of the mappable item that has the specified ID.

Parameters:

id - The ID of the mappable item.

visible - true to make this item visible, false to make this item not visible.

Since:

BlackBerry API 6.0.0

setVisible

public void setVisible(String tag)

Sets all mappables items with the specified tag to visible. This is the same as using setVisible( tag, true ).

Parameters:

tag - The tag of the mappable item.

Since:

BlackBerry API 6.0.0

setVisible

public void setVisible(String tag,
                       boolean visible)

Sets the visible state for all mappable items with the specified tag.

Parameters:

tag - The tag of the mappable item.

visible - true to make this item visible, false to make it not visible.

Since:

BlackBerry API 6.0.0

setVisible

public void setVisible(Mappable[] visibles)

Sets all mappable items in this collection to visible. If the item does not exist in the store, the item is added automatically.

Note: The object must correctly implement equals(Object).

Parameters:

visibles - The collection of mappable items to be visible.

Since:

BlackBerry API 6.0.0

setVisibleNone

public void setVisibleNone()

Sets all visible elements to not visible.

Since:

BlackBerry API 6.0.0

isVisible

public boolean isVisible(int id)

Determines if the mappable item with the specified ID is visible.

Parameters:

id - The ID of the mappable item.

Returns:

true if the item is visible, false otherwise.

Since:

BlackBerry API 6.0.0

getVisibleIds

public IntVector getVisibleIds()

Returns the IDs for all visible mappable items.

Returns:

A list of all IDs that are visible. The vector is sorted.

Since:

BlackBerry API 6.0.0

getVisible

public MappableVector getVisible()

Retrieves all mappable items that are flagged as visible, regardless of the visible area.

Returns:

All visible elements.

See Also:

MapDataModel.getVisibleData(MapDimensions)

Since:

BlackBerry API 6.0.0

getVisibleData

public MappableVector getVisibleData(MapDimensions visibleArea)

Retrieves all the mappable elements in this store that are visible in the specified dimensions.

Note: Only those elements that are in the specified area and that are flagged as visible are returned.

Parameters:

visibleArea - The area to search for visible elements.

Returns:

A list of all elements that are visible within this specified area, never returns null.

Since:

BlackBerry API 6.0.0

getVisibleData

public MappableVector getVisibleData(LatLonRectangle visBoundingBox)

Retrieves all the mappable elements in this store that are visible in the specified rectangle.

Note: Only those elements that are in the specified rectangle and that are flagged as visible are returned.

Parameters:

visBoundingBox - The rectangular area to search for visible elements.

Returns:

A list of all elements that are visible within this given area, never returns null.

Since:

BlackBerry API 6.0.0

getVisibleBoundingBox

public LatLonRectangle getVisibleBoundingBox()

Calculates a bounding box of all visible data.

Returns:

A bounding box, or null if there is no visible data.

Since:

BlackBerry API 6.0.0

toArray

public Mappable[] toArray()

Retrieves all mappable items in this storage container.

Returns:

All mappable items.

Since:

BlackBerry API 6.0.0

getTags

public Vector getTags(int id)

Retrieves a vector containing all the tags for a given mappable element.

Parameters:

id - The unique ID of the element.

Returns:

A vector of tags (Strings) that the given element is tagged with, never returns null.

Since:

BlackBerry API 6.0.0

getAt

public Object getAt(int index)

Description copied from interface: ReadableList

Retrieves element by index.

Specified by:

getAt in interface ReadableList

Parameters:

index - Index of the element to retrieve.

Returns:

Element at provided index.

See Also:

ReadableList.getAt(int)

Since:

BlackBerry API 6.0.0

getAt

public int getAt(int index,
                 int count,
                 Object[] elements,
                 int destIndex)

Description copied from interface: ReadableList

Retrieves range of elements starting at provided index.

Specified by:

getAt in interface ReadableList

Parameters:

index - Index of first element to retrieve.

count - Number of elements to retrieve.

elements - Object array to contain returned elements; this array must have enough space to hold the number of elements you expect to receive.

destIndex - Index within destination array to contain the first element retrieved (the destination array must therefore be at least destIndex + count elements long).

Returns:

Number of elements actually retrieved.

See Also:

ReadableList.getAt(int, int, Object[], int)

Since:

BlackBerry API 6.0.0

getIndex

public int getIndex(Object element)

Description copied from interface: ReadableList

Retrieves index by element.

Note: this operation may be linear with respect to the number of elements in the list.

Specified by:

getIndex in interface ReadableList

Parameters:

element - Element to locate.

Returns:

Index of provided element, or -1 if the element isn't contained in this collection.

See Also:

ReadableList.getIndex(Object)

Since:

BlackBerry API 6.0.0

size

public int size()

Description copied from interface: ReadableList

Retrieves the number of elements in this collection.

Specified by:

size in interface ReadableList

Returns:

Number of elements in the collection.

See Also:

ReadableList.size()

Since:

BlackBerry API 6.0.0