|
BenQ Mobile |
||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Objectjavax.microedition.location.LandmarkStore
The LandmarkStore class provides methods to store, delete
and retrieve landmarks from a persistent landmark database.
There is one default landmark store and there may be multiple
other names landmark stores. The implementation may support
creating and deleting landmark stores by the application.
All landmark stores MUST be shared between all J2ME applications and
MAY be shared
with native applications in the terminal. Named landmark stores
have unique names in this API. If the underlying implementation
allows multiple landmark stores when the same name, it must
present them with unique names in this API e.g. by adding some
postfix to those names that have multiple instances in order
to differentiate them.
The Landmarks have a name and may be placed in a category
or several categories.
The category is intended to group landmarks that are of similar
type to the end user, e.g. restaurants, museums, etc.
The landmark names are strings that identify the landmark to the
end user. The category names describe the category to the
end user. The language used in the names may be any and
depends on the preferences of the end user. The names of
the categories are unique.
However, the names of the landmarks are not guaranteed to be
unique. Landmarks with
the same name can appear in multiple categories or even several
Landmarks with the same name in the same category.
The Landmark objects returned from the getLandmarks
methods in this class shall guarantee that the application can
read a consistent set of the landmark data valid at the time of
obtaining the object instance, even if the landmark information
in the database is modified subsequently by this or some other application.
The landmarks and landmark stores created by an application persist even if the application itself is deleted from the terminal.
Accessing the landmark database may cause a
SecurityException, if the calling application does
not have the required permissions. The permissions to read and
write (including add and delete) landmarks are distinct. An
application having e.g.
a permission to read landmarks wouldn't necessarily
have the permission to delete them.
The permissions (names etc.) for the appropriate security framework are
defined elsewhere in this specification.
| Method Summary | |
void |
addCategory(java.lang.String categoryName)
Adds a category to this LandmarkStore.
|
void |
addLandmark(Landmark landmark,
java.lang.String category)
Adds a landmark to the specified group in the landmark store. |
static void |
createLandmarkStore(java.lang.String storeName)
Creates a new landmark store with a specified name. |
void |
deleteCategory(java.lang.String categoryName)
Removes a category from this LandmarkStore.
|
void |
deleteLandmark(Landmark lm)
Deletes a landmark from this LandmarkStore.
|
static void |
deleteLandmarkStore(java.lang.String storeName)
Delete a landmark store with a specified name. |
java.util.Enumeration |
getCategories()
Returns the category names that are defined in this LandmarkStore.
|
static LandmarkStore |
getInstance(java.lang.String storeName)
Gets a LandmarkStore instance for storing, deleting and
retrieving landmarks. |
java.util.Enumeration |
getLandmarks()
Lists all landmarks stored in the database. |
java.util.Enumeration |
getLandmarks(java.lang.String category,
double minLatitude,
double maxLatitude,
double minLongitude,
double maxLongitude)
Lists all the landmarks that are within an area defined by bounding minimum and maximum latitude and longitude and belong to the defined category, if specified. |
java.util.Enumeration |
getLandmarks(java.lang.String category,
java.lang.String name)
Gets the Landmarks from the storage where the
category and/or name matches the given parameters. |
static java.lang.String[] |
listLandmarkStores()
Lists the names of all the available landmark stores. |
void |
removeLandmarkFromCategory(Landmark lm,
java.lang.String category)
Removes the named landmark from the specified category. |
void |
updateLandmark(Landmark lm)
Updates the information about a landmark. |
| Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Method Detail |
public static LandmarkStore getInstance(java.lang.String storeName)
LandmarkStore instance for storing, deleting and
retrieving landmarks. There must be one default landmark store and there
may be other landmark stores that can be accessed by name.
storeName - the name of the landmark store to open.
if null,
the default landmark store will be returned
LandmarkStore object representing the
specified landmark store or null if a landmark
store with the specified name does not exist.
java.lang.SecurityException - if the application does not have
a permission to read landmark stores
public static void createLandmarkStore(java.lang.String storeName)
throws java.io.IOException,
LandmarkException
All LandmarkStores all shared between
all J2ME applications and may be shared with native
applications. Implementations may support creating
landmark stores on a removable media. However, the Java
application is not able to directly choose where the
landmark store is stored, if the implementation supports
several storage media. The implementation of this method
may e.g. prompt the end user to make the choice if the
implementation supports several storage media.
If the landmark store is stored on a removable media,
this media might be removed by the user possibly at
any time causing it to become unavailable.
A newly created landmark store does not contain any landmarks.
storeName - the name of the landmark store to create
java.lang.NullPointerException - if the parameter is null
java.lang.IllegalArgumentException - if the name is too long or
if a landmark store with the
specified name already exists
java.io.IOException - if the landmark store couldn't be created
due to an I/O error
java.lang.SecurityException - if the application does not have
permissions to create a new landmark store
LandmarkException - if the implementation does not support
creating new landmark stores
public static void deleteLandmarkStore(java.lang.String storeName)
throws java.io.IOException,
LandmarkException
If a landmark store with the specified name does not exist, this method returns silently without any error.
storeName - the name of the landmark store to create
java.lang.NullPointerException - if the parameter is null
(the default
landmark store can't be deleted)
java.io.IOException - if the landmark store couldn't be deleted
due to an I/O error
java.lang.SecurityException - if the appliction does not have
permissions to delete a landmark store
LandmarkException - if the implementation does not support
deleting landmark stores
public static java.lang.String[] listLandmarkStores()
throws java.io.IOException
The default landmark store is obtained from getInstance
by passing null as the parameter. The
null name for the
default landmark store is not included in the list returned
by this method. If there are no named landmark stores, other than
the default landmark store, this method returns null.
java.lang.SecurityException - if the application does not have
the permission to access landmark stores
java.io.IOException - if an I/O error occurred when trying to
access the landmark stores
public void addLandmark(Landmark landmark,
java.lang.String category)
throws java.io.IOException
If some textual String field inside the landmark object
is set to a value that is too long to be stored, the implementation
is allowed to automatically truncate fields that are too long.
However, the name field MUST NOT be truncated.
Every implementation shall be able to support name fields that
are 32 characters or shorter. Implementations may support longer
names but are not required to. If an application tries to add
a Landmark with a longer name field than the
implementation can support, IllegalArgumentException is thrown.
When the landmark database is empty, every implementation is required to be able to store a landmark where each String field is set to a 30 character long string.
If the Landmark object that is passed as a parameter
is an instance obtained with the getLandmarks method
and already exists in the database or an instance that has been
used in an earlier call to this method, the same landmark instance will
be added to the specified category in addition to the
category/categories which it already belongs to. If the landmark
already belongs to the specified category, this method returns with
no effect.
If the Landmark object that is passed as a parameter
is an instance constructed by the application using the constructor and
that has not been added to the database yet, a new landmark will be
created in the database and it will belong initially to only the
category specified in the category parameter.
landmark - the landmark to be addedcategory - category where the landmark is added. null
can be used to indicate that the landmark does not
belong to a category
java.lang.SecurityException - if the application is not allowed to
add landmarks
java.lang.IllegalArgumentException - if the landmark has a longer
name field than the implementation can support or
if the category is not null or one of the categories
defined in this
LandmarkStore
java.io.IOException - if an I/O error happened when accessing the
landmark database or if there are no resources available to
store this landmark
java.lang.NullPointerException - if the landmark parameter is
null
public java.util.Enumeration getLandmarks(java.lang.String category,
java.lang.String name)
throws java.io.IOException
Landmarks from the storage where the
category and/or name matches the given parameters.
category - the category of the landmark. null implies
a wildcard that matches all categoriesname - the name of the desired landmark. null implies
a wildcard that matches all the names within the category
indicated by the category parameter
null if no Landmark matched the given parameters
java.io.IOException - if an I/O error happened when accessing the
landmark database
public java.util.Enumeration getLandmarks()
throws java.io.IOException
Enumeration object containing
Landmark objects
representing all the landmarks stored in this
LandmarkStore or null if there
^ are no landmarks in the store
java.io.IOException - if an I/O error happened when accessing the
landmark database
public java.util.Enumeration getLandmarks(java.lang.String category,
double minLatitude,
double maxLatitude,
double minLongitude,
double maxLongitude)
throws java.io.IOException
If minLongitude <= maxLongitude, this area covers the
longitude range [minLongitude, maxLongitude].
If minLongitude > maxLongitude, this area covers the
longitude range [-180.0, maxLongitude] and [minLongitude, 180.0).
For latitude, the area covers the latitude range [minLatitude, maxLatitude].
category - the category of the landmark. null implies
a wildcard
that matches all categoriesminLatitude - minimum latitude of the area. Must be within
the range [-90.0, 90.0]maxLatitude - maximum latitude of the area. Must be within
the range [minLatitude, 90.0]minLongitude - minimum longitude of the area. Must be within
the range [-180.0, 180.0)maxLongitude - maximum longitude of the area. Must be within
the range [-180.0, 180.0)
null if no Landmark matched the given parameters
java.io.IOException - if an I/O error happened when accessing the
landmark database
java.lang.IllegalArgumentException - if the minLongitude or
maxLongitude is out of the range [-180.0, 180.0), or
minLatitude or minLongitude is out of the range
[-90.0,90.0], or if minLatitude > maxLatitude
public void removeLandmarkFromCategory(Landmark lm,
java.lang.String category)
throws java.io.IOException
The Landmark instance passed in as the parameter
must be an instance that has been previously obtained from this
LandmarkStore with one of the
getLandmarks methods.
If the Landmark is not found in this
LandmarkStore in the specified category or if the
parameter is not a Landmark instance previously
obtained from this LandmarkStore
with one of the getLandmarks methods, then the
request is silently ignored and the method call returns with no error.
The request is also silently ignored if the specified category
does not exist in this LandmarkStore or if the
specified category or landmark is null.
The landmark is only removed from the specified category
but the landmark information is retained in the database.
If the landmark no longer belongs to any category, it can
still be obtained from the database by passing null
as the category to getLandmarks.
lm - the landmark to be removedcategory - the category from which it will be removed.
java.lang.SecurityException - if the application is not allowed to
delete the landmark
java.io.IOException - if an I/O error happened when accessing the
landmark database
public void updateLandmark(Landmark lm)
throws java.io.IOException,
LandmarkException
The Landmark instance passed in as the parameter
must be an instance that has been previously obtained from this
LandmarkStore with one of the
getLandmarks methods.
This method can't be used to add a new landmark to the database.
lm - the landmark to be updated
java.lang.SecurityException - if the application is not allowed to
update the landmark
LandmarkException - if the landmark instance passed as
the parameter has not been obtained
using getLandmarks or
does not exist in the database any more
java.io.IOException - if an I/O error happened when accessing the
landmark database
public void deleteLandmark(Landmark lm)
throws java.io.IOException,
LandmarkException
LandmarkStore.
This method removes the specified landmark from all categories
and deletes the information from this LandmarkStore.
The Landmark instance passed in as the parameter
must be an instance that has been previously obtained from this
LandmarkStore with one of the
getLandmarks methods.
If the Landmark is not found in this
LandmarkStore, then the
request is silently ignored and the method call returns with no error.
The request is also silently ignored if the landmark parameter is
null.
lm - the landmark to be deleted
java.lang.SecurityException - if the application is not allowed to
delete the landmark
LandmarkException - if the landmark instance passed as
the parameter has not been obtained
using getLandmarks
java.io.IOException - if an I/O error happened when accessing the
landmark databasepublic java.util.Enumeration getCategories()
LandmarkStore.
The language and locale used for these names depends on
the implementation and end user settings. The names shall be
such that they can be displayed to the end user and have a meaning
to the end user.
Enumeration containing Strings
representing
the category names. If there are no categories defined in
this LandmarkStore, an Enumeration with no
entries is returned.
public void addCategory(java.lang.String categoryName)
throws LandmarkException,
java.io.IOException
LandmarkStore.
All implementations must support names that have length up to and including 32 characters. If the provided name is longer it may be truncated by the implementation if necessary.
categoryName - name for the category to be added
java.lang.IllegalArgumentException - if a category with the specified
name already exists or if the
name is too long
java.lang.NullPointerException - if the parameter is null
LandmarkException - if this LandmarkStore does not
support adding new categories
java.io.IOException - if an I/O error occurs or there are no resources
to add a new category
java.lang.SecurityException - if the application does not have the
permission to manage categories
public void deleteCategory(java.lang.String categoryName)
throws LandmarkException,
java.io.IOException
LandmarkStore.
The category will be removed from all landmarks that are
in that category. However, this method will not remove any
of the landmarks, only the associated category information
from the landmarks.
If a category with the supplied name does not exist in this
LandmarkStore, the method returns silently with
no error.
categoryName - name for the category to be removed
java.lang.NullPointerException - if the parameter is null
LandmarkException - if this LandmarkStore does not
support deleting categories
java.io.IOException - if an I/O error occurs
java.lang.SecurityException - if the application does not have the
permission to manage categories
|
BenQ Mobile |
||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
|
Copyright © 2006 BenQ Mobile GmbH & Co. OHG or respective copyright owner. All Rights Reserved. BenQ Corp. is a trademark licensee of Siemens AG. |
For further information about Mobility Toolkit (MTK) visit our Developer Portal. |