|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.openlapi.LandmarkStore
public class LandmarkStore
The LandmarkStore
class provides methods to store, delete and retrieve
landmarks from a persistent landmark store. There is one default landmark store and
there may be multiple other named 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 with the same name, it must present them
with unique names in the API e.g. by adding some postfix to those names that have
multiple instances in order to differentiate them.
Because native landmark stores may be stored as files in a file system and file systems have sometimes limitations for the allowed characters in file names, the implementations MUST support all other Unicode characters in landmark store names except the following list:
'\'
'/'
':'
'*'
'?'
'"'
'<'
'>'
'|'
The Landmark
s 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 within a LandmarkStore
.
However, the names of the landmarks are not guaranteed to be unique.
Landmark
s with the same name can appear in multiple categories or even
several Landmark
s 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 store is modified subsequently by this or some other
application.
The Landmark
object instances can be in two states:
LandmarkStore
Landmark
object belongs to a LandmarkStore
if it has
been obtained from the LandmarkStore
using getLandmarks
or if it has been added to the LandmarkStore
using
addLandmark
. A Landmark
object is initially constructed
by an application when it has been constructed using the constructor but has not been
added to a LandmarkStore
using addLandmark
.
Note that the term "belongs to a LandmarkStore
" is defined above in a
way that "belong to a LandmarkStore
" has an different meaning than the
landmark "being currently stored in a LandmarkStore
". According to the
above definition, a Landmark
object instance may be in a state where it
is considered to "belong to a LandmarkStore
" even when it is not stored
in that LandmarkStore
(e.g. if the landmark is deleted from the
LandmarkStore
using deleteLandmark
method, the
Landmark
object instance still is considered to "belong to this
LandmarkStore
").
The landmark stores created by an application and landmarks added in landmark stores persist even if the application itself is deleted from the terminal.
Accessing the landmark store 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 MIDP 2.0 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 store. |
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 |
---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Method Detail |
---|
public static void createLandmarkStore(java.lang.String storeName) throws java.lang.NullPointerException, java.lang.IllegalArgumentException, java.io.IOException, LandmarkException, java.lang.SecurityException
A newly created landmark store does not contain any landmarks.
Note that the landmark store name MAY be modified by the implementation when the store is created, e.g. by adding an implementation specific post-fix to differentiate stores on different storage drives as described in the class overview. Therefore, the application needs to use the listLandmarkStores method to discover the form the name was stored as. However, when creating stores to the default storage location, it is recommended that the implementation does not modify the store name but preserves it in the form it was passed to this method. It is strongly recommended that this method is implemented as character case preserving for the store name.
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 storespublic static void deleteLandmarkStore(java.lang.String storeName) throws java.lang.NullPointerException, java.io.IOException, java.lang.SecurityException, LandmarkException
Note that the landmark store names MAY be handled as either case-sensitive or case-insensitive (e.g. Unicode collation algorithm level 2). Therefore, the implementation MUST accept the names in the form returned by listLandmarkStores and MAY accept the name in other variations of character case.
storeName
- the name of the landmark store to delete
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 application does not have permissions to delete a landmark store
LandmarkException
- if the implementation does not support deleting landmark storespublic static LandmarkStore getInstance(java.lang.String storeName) throws java.lang.SecurityException
storeName
- the name of the landmark store to open. if null, the default landmark
store will be returned
java.lang.SecurityException
- if the application does not have a permission to read landmark storespublic static java.lang.String[] listLandmarkStores() throws java.lang.SecurityException, java.io.IOException
The store names must be returned in a form that is directly usable as input to getInstance and deleteLandmarkStore.
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 storespublic void addCategory(java.lang.String categoryName) throws java.lang.IllegalArgumentException, java.lang.NullPointerException, LandmarkException, java.io.IOException, java.lang.SecurityException
categoryName
- name for the category to be added
java.lang.IllegalArgumentException
- if a category with the specified name already exists
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 categoriespublic void addLandmark(Landmark landmark, java.lang.String category) throws java.lang.SecurityException, java.lang.IllegalArgumentException, java.io.IOException, java.lang.NullPointerException
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 store 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 that belongs to this LandmarkStore, 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 has been deleted after obtaining it from getLandmarks, it will be added back when this method is called.
If the Landmark object that is passed as a parameter is an instance initially constructed by the application using the constructor or an instance that belongs to a different LandmarkStore, a new landmark will be created in this LandmarkStore and it will belong initially to only the category specified in the category parameter. After this method call, the Landmark object that is passed as a parameter belongs to this LandmarkStore.
landmark
- the landmark to be addedcategory
- 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 store or if there
are no resources available to store this landmark
java.lang.NullPointerException
- if the landmark parameter is nullpublic void deleteCategory(java.lang.String categoryName) throws java.lang.NullPointerException, LandmarkException, java.io.IOException, java.lang.SecurityException
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 categoriespublic void deleteLandmark(Landmark lm) throws java.lang.SecurityException, LandmarkException, java.io.IOException, java.lang.NullPointerException
If the Landmark belongs to this LandmarkStore but has already been deleted from this LandmarkStore, then the request is silently ignored and the method call returns with no error. Note that LandmarkException is thrown if the Landmark instance does not belong to this LandmarkStore, and this is different from not being stored currently in this LandmarkStore.
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 does not belong to
this LandmarkStore
java.io.IOException
- if an I/O error happened when accessing the landmark store
java.lang.NullPointerException
- if the parameter is nullpublic java.util.Enumeration getCategories()
public java.util.Enumeration getLandmarks() throws java.io.IOException
java.io.IOException
- if an I/O error happened when accessing the landmark storepublic java.util.Enumeration getLandmarks(java.lang.String category, double minLatitude, double maxLatitude, double minLongitude, double maxLongitude) throws java.io.IOException, java.lang.IllegalArgumentException
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)
java.io.IOException
- if an I/O error happened when accessing the landmark store
java.lang.IllegalArgumentException
- if the minLongitude or maxLongitude is out of the range [-180.0,
180.0), or minLatitude or maxLatitude is out of the range [-90.0,90.0],
or if minLatitude > maxLatitudepublic java.util.Enumeration getLandmarks(java.lang.String category, java.lang.String name) throws java.io.IOException
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
java.io.IOException
- if an I/O error happened when accessing the landmark storepublic void removeLandmarkFromCategory(Landmark lm, java.lang.String category) throws java.lang.SecurityException, java.io.IOException, java.lang.NullPointerException
If the Landmark is not found in this LandmarkStore in the specified category or if the parameter is a Landmark instance that does not belong to this LandmarkStore, 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.
The landmark is only removed from the specified category but the landmark information is retained in the store. If the landmark no longer belongs to any category, it can still be obtained from the store 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 store
java.lang.NullPointerException
- if either parameter is nullpublic void updateLandmark(Landmark lm) throws java.lang.SecurityException, LandmarkException, java.io.IOException, java.lang.NullPointerException, java.lang.IllegalArgumentException
This method can't be used to add a new landmark to the store.
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 does not belong to
this LandmarkStore or does not exist in the store any more
java.io.IOException
- if an I/O error happened when accessing the landmark store
java.lang.NullPointerException
- if the parameter is null
java.lang.IllegalArgumentException
- if the landmark has a longer name field than the implementation can
support
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |