javax.microedition.location.LandmarkStore
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Object
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. Public landmark stores must be shared between all
Java ME 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:
'\''/'':''*''?''"''<''>''|'Support for the listed characters is not required and therefore applications are strongly encouraged not to use the characters listed above in landmark store names in order to ensure interoperability of the application on different platform implementations.
The Landmark objects 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 objects with the same name can appear in multiple
categories or even several Landmark objects 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:
LandmarkStoreA 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 a 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").
An instance of Landmark object can belong only to one
LandmarkStore at a time. The Landmark object always
belongs to the Landmark where it was last added. However the data
contained in a Landmark object may be stored in
more than one 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 would not
necessarily have the permission to delete them. Appendix A defines
the permissions (names etc.) for security framework in MIDP 2.0 and
later versions.
As Location API 2.0 provides capabilities for importing landmarks the number of landmarks in the landmark store may grow quite much. Therefore new and more advanced search mechanism for the landmarks is needed. The Location API 2.0 provides new search method to search landmarks using different filters.
The landmark stores created with JSR 179 are always accessible for all applications on the terminal. However there are use cases to store landmark data so that it is not available to other applications. Location API 2.0 adds a mechanism to create private landmark stores that are accessible only for the application that created it. There is also a mechanism to query if an application has access to certain landmark store and to change private landmark store to public. When an application that has created a private landmark store is removed from the terminal, the private landmark store must also be removed.
JSR 179 does not restrict the location of the landmark stores in any way. This means that a landmark store may be on a removable media or even on a remote location. However in JSR 179 there is no way for an application to identify the location of the landmark store. This issue is being addressed in the Location API 2.0. This specification defines a mechanism to get the features of a landmark store and identify if the store is on a remote location. The API implementation is responsible for deciding where a new landmark store is created and what remote landmark store are supported. Remote landmark stores must not support landmark store listeners.
Since landmark store is shared between all Java applications and also possibly
with the native applications, the content of the landmark store may be changed
during the application runtime by some other application. This may cause some
landmarks to appear or disappear from the landmark store. To address this
problem, the Location API 2.0 adds a mechanism for the applications to be
notified about the changes in the landmark store. By listening to the changes
the application is able to prepare for the possible changes in the landmark
store. The support for LandmarkStoreListener is optional to be
implemented. If the implementation does not support
LandmarkStoreListener a LandmarkException if thrown
when an application tries to add a listener to the landmark store.
Location API [JSR179] does not define any landmark categories, but they are all left to the application to decide. This approach makes the landmark category names hard to localize. In Location API 2.0 a set of global landmark categories are defined. These global categories are also localized to enable better user experience. And since all devices implementing Location API 2.0 have these same categories, landmarks can be imported and exported into same global category in different devices. The user or application is still able to create their own landmark categories.
The following table lists the global landmark categories that
must be present in all Location API 2.0 compliant
implementations. This specification defines constants for these global categories
and those constants should be used to refer to them. The implementation
must localize the names of the global categories. The localized
name for a category can be retrieved with method
getCategoryDisplayName.
Additional useful categories can be found from RFC 4589 (see reference [RFC4589]).
| Category name | Example landmarks |
| Accommodation | Hotel, Camping site |
| Business | Bank, Factory, Office |
| Communication | Internet Access Point, Public Telephone, Wireless LAN Hot Spot |
| Educational institute | School, College |
| Entertainment | Amusement park, Cinema, Concert hall, Night club |
| Food and Beverage | Fast food, Restaurant, Cafe, Bar |
| Geographical Area | City, City center, Town |
| Outdoor activities | Camping site, Fishing place, Hunting, National park, Playground |
| People | My home, My friend's home, Father's summer cottage, Child's school |
| Public service | Tourist information office, Government office, Library, Post office, Hospital, Police |
| Religious places | Church, Mosque |
| Shopping | Market place, Pharmacy, Shop, Shopping center |
| Sightseeing | Monument, Mountain top, Museum |
| Sports | Bowling, Golf course, Ice hockey hall, Stadium |
| Transport | Airport, Bus stop, Harbor, Railway station, Rest area |
| User location | Location of the user |
| Field Summary | |
|---|---|
static java.lang.String |
ACCOMMODATION
Constant for global landmark category accommodation. |
static int |
AUTHMODE_PRIVATE
Constant for private authorization mode. |
static int |
AUTHMODE_PUBLIC
Constant for public authorization mode. |
static java.lang.String |
BUSINESS
Constant for global landmark category business. |
static int |
CATEGORY_MANAGEMENT_SUPPORTED
Constant for defining that the landmark store supports adding, renaming and removing landmark categories. |
static java.lang.String |
COMMUNICATION
Constant for global landmark category communication. |
static java.lang.String |
EDUCATIONAL_INSTITUTE
Constant for global landmark category educational institutes. |
static java.lang.String |
ENTERTAINMENT
Constant for global landmark category entertainment. |
static java.lang.String |
FOOD_AND_BEVERAGE
Constant for global landmark category food and beverage. |
static java.lang.String |
GEOGRAPHICAL_AREA
Constant for global landmark category geographical areas. |
static int |
IS_READ_ONLY
Constant for defining whether landmark store is read-only or not. |
static int |
IS_REMOTE
Constant for defining that the landmark store is remote. |
static int |
LANDMARKSTORE_LISTENER_SUPPORTED
Constant for defining that the landmark store supports adding and removing landmark store listeners. |
static java.lang.String |
OUTDOOR_ACTIVITIES
Constant for global landmark category outdoor activities. |
static java.lang.String |
PEOPLE
Constant for global landmark category people. |
static java.lang.String |
PUBLIC_SERVICE
Constant for global landmark category public service. |
static java.lang.String |
RELIGIOUS_PLACES
Constant for global landmark category religious places. |
static java.lang.String |
SHOPPING
Constant for global landmark category shopping. |
static java.lang.String |
SIGHTSEEING
Constant for global landmark category sightseeing. |
static int |
SORT_BY_DESCRIPTION
Constant for sorting the landmark search results by description of the landmark. |
static int |
SORT_BY_DISTANCE
Constant for sorting the landmark search results by the distance of the coordinates given as parameter in the method. |
static int |
SORT_BY_NAME
Constant for sorting the landmark search results by name of the landmark. |
static int |
SORT_ORDER_ASCENDING
Constant for sorting landmark results in ascending order. |
static int |
SORT_ORDER_DESCENDING
Constant for sorting landmark search results in descending order. |
static int |
SORT_ORDER_NO_SORTING
Constant for indicating thet landmark search results are not sorted. |
static int |
SORTING_SUPPORTED
Constant for defining that the landmark store supports sorting in getLandmarks
method. |
static java.lang.String |
SPORTS
Constant for global landmark category sports. |
static java.lang.String |
TRANSPORT
Constant for global landmark category transport. |
static java.lang.String |
USER_LOCATION
Constant for global landmark category user location. |
static int |
WILDCARDS_SUPPORTED
Constant for defining that the landmark store supports wildcards in getLandmarks
method. |
| 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 category in the landmark store. |
void |
addLandmarkStoreListener(LandmarkStoreListener listener)
Adds a LandmarkStoreListener that is notified
when there are changes in the specified landmark store. |
void |
changeToPublic()
Changes the authorization mode of a private landmark store to public. |
static void |
createLandmarkStore(java.lang.String storeName)
Creates a new landmark store with a specified name. |
static java.lang.String |
createLandmarkStore(java.lang.String storeName,
int authMode)
Creates a new landmark store with a specified name and access restrictions. |
void |
deleteCategory(java.lang.String categoryName)
Removes a category from this LandmarkStore. |
void |
deleteLandmark(Landmark landmark)
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. |
java.util.Enumeration |
getCategoriesOfLandmark(Landmark landmark)
Returns the landmark categories for the specified landmark. |
java.lang.String |
getCategoryDisplayName(java.lang.String category,
java.lang.String language)
Returns the name of the requested landmark category in the specified language. |
static int |
getFeatures(java.lang.String storeName)
Returns the list of optional features the specified landmark store supports. |
static LandmarkStore |
getInstance(java.lang.String storeName)
Gets a LandmarkStore instance for storing, deleting and
retrieving landmarks. |
Landmark |
getLandmark(int identifier,
java.lang.String author)
Returns the Landmark object for the given identifier and
author combination. |
java.util.Enumeration |
getLandmarks()
Lists all landmarks stored in the store. |
Landmark[] |
getLandmarks(GeographicArea areaFilter,
AddressInfo addrFilter,
java.lang.String nameFilter,
java.lang.String descFilter,
java.lang.String authorFilter,
java.lang.String catFilter,
Coordinates distFrom,
int maxResults,
int sortOrder,
int sortBy)
With this method an application can search landmarks in the store using filters. |
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. |
java.lang.String |
getName()
This convenience method returns the name of this landmark store. |
int |
getNumberOfLandmarks(java.lang.String category)
This convenience method returns the number of landmarks in the given category. |
static java.lang.String[] |
listLandmarkStores()
Lists the names of all the landmark stores that the requesting application has access to. |
void |
removeLandmarkFromAllCategories(Landmark landmark)
Removes the named landmark from all the categories it is associated to. |
void |
removeLandmarkFromCategory(Landmark landmark,
java.lang.String category)
Removes the named landmark from the specified category. |
void |
removeLandmarkStoreListener(LandmarkStoreListener listener)
Removes the specified listener from receiving notifications about changes in the landmark store. |
void |
renameCategory(java.lang.String oldCategoryName,
java.lang.String newCategoryName)
Renames a landmark category. |
void |
updateLandmark(Landmark landmark)
Updates the information about a landmark. |
| Methods inherited from class java.lang.Object |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Field Detail |
|---|
public static final java.lang.String ACCOMMODATION
Constant for global landmark category accommodation. This category may contain, for example, hotels or camping sites.
public static final java.lang.String BUSINESS
Constant for global landmark category business. This category may contain, for example, banks, factories or offices.
public static final java.lang.String COMMUNICATION
Constant for global landmark category communication. This category may contain, for example, Internet access points, public telephones or wireless LAN hot spots.
public static final java.lang.String EDUCATIONAL_INSTITUTE
Constant for global landmark category educational institutes. This category may contain, for example, schools or colleges.
public static final java.lang.String ENTERTAINMENT
Constant for global landmark category entertainment. This category may contain, for example, cinemas, concert halls or night clubs.
public static final java.lang.String FOOD_AND_BEVERAGE
Constant for global landmark category food and beverage. This category may contain, for example, restaurants, bars of cafes.
public static final java.lang.String GEOGRAPHICAL_AREA
Constant for global landmark category geographical areas. This category may contain, for example, cities, towns or city centers.
public static final java.lang.String OUTDOOR_ACTIVITIES
Constant for global landmark category outdoor activities. This category may contain, for example, camping sites or playgrounds.
public static final java.lang.String PEOPLE
Constant for global landmark category people. This category may contain, for example, parent's house or friend's house.
public static final java.lang.String PUBLIC_SERVICE
Constant for global landmark category public service. This category may contain, for example, hospitals or libraries.
public static final java.lang.String RELIGIOUS_PLACES
Constant for global landmark category religious places. This category may contain, for example, churches or mosques.
public static final java.lang.String SHOPPING
Constant for global landmark category shopping. This category may contain, for example, market places or shopping centers.
public static final java.lang.String SIGHTSEEING
Constant for global landmark category sightseeing. This category may contain, for example, museums or monuments.
public static final java.lang.String SPORTS
Constant for global landmark category sports. This category may contain, for example, golf course or ice hockey hall.
public static final java.lang.String TRANSPORT
Constant for global landmark category transport. This category may contain, for example, bus stops or railway stations.
public static final java.lang.String USER_LOCATION
Constant for global landmark category user location. This category can be used to indicate the location of the user.
public static final int AUTHMODE_PRIVATE
Constant for private authorization mode. The access to the landmark store is allowed only for the application that created it.
This constant is also used in method
getFeatures to indicate whether the
landmark store is private or not. If the landmark store has been created in
private authorization mode, this bit is set. If the landmarks store is
public, the bit is not set.
public static final int AUTHMODE_PUBLIC
Constant for public authorization mode. The access to the landmark store is allowed to all applications.
public static final int SORT_ORDER_ASCENDING
Constant for sorting landmark results in ascending order.
public static final int SORT_ORDER_DESCENDING
Constant for sorting landmark search results in descending order.
public static final int SORT_ORDER_NO_SORTING
Constant for indicating thet landmark search results are not sorted.
public static final int SORT_BY_NAME
Constant for sorting the landmark search results by name of the landmark.
public static final int SORT_BY_DESCRIPTION
Constant for sorting the landmark search results by description of the landmark.
public static final int SORT_BY_DISTANCE
Constant for sorting the landmark search results by the distance of the coordinates given as parameter in the method.
public static final int IS_READ_ONLY
Constant for defining whether landmark store is read-only or not. If
landmark store is read-only, this bit is set and methods
addLandmark,
updateLandmark and
deleteLandmark
throw IOException. If the landmark store is read-only then
also the category management is not supported and bit
CATEGORY_MANAGEMENT_SUPPORTED is not set. If the landmark store
is not read-only and landmark data can be modified, this bit is not set.
An application does not have a mechanism to create read-only landmark stores,
they may only be provided by the API implementation.
public static final int CATEGORY_MANAGEMENT_SUPPORTED
Constant for defining that the landmark store supports adding, renaming
and removing landmark categories. If it does, this bit is set and methods
addCategory,
renameCategory and
deleteCategory do not throw
LandmarkException. If category management is not supported,
this bit is not set.
public static final int LANDMARKSTORE_LISTENER_SUPPORTED
Constant for defining that the landmark store supports adding and
removing landmark store listeners. If it does, this bit is set and methods
addLandmarkStoreListener
does not throw LandmarkException. If landmark store listeners
are not supported, this bit is not set. Remote landmark stores
must not support landmark store listeners.
public static final int IS_REMOTE
Constant for defining that the landmark store is remote. If the landmark store is remote, this bit is set. If the landmarks store resides on the terminal or on a removable media, the bit is not set.
public static final int WILDCARDS_SUPPORTED
Constant for defining that the landmark store supports wildcards in
getLandmarks
method. If wildcards are supported, this bit is set. If they are not supported,
the bit is not set.
public static final int SORTING_SUPPORTED
Constant for defining that the landmark store supports sorting in
getLandmarks
method. If sorting is supported, this bit is set. If sorting is not
supported, this bit is not set.
| Method Detail |
|---|
public static LandmarkStore getInstance(java.lang.String storeName)
Gets a 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. The authorization mode of the default landmark store is
AUTHMODE_PUBLIC.
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 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 or if the authorization mode of the
landmark store is private and it was created by the other application
public static void createLandmarkStore(java.lang.String storeName)
throws java.io.IOException,
LandmarkException
Creates a new landmark store with a specified name. The landmark stores created with this method are public stores.
All public landmark stores are shared between all Java ME 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.
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.io.IOException - if the landmark store could not be created due to an
I/O error
java.lang.IllegalArgumentException - if the name is too long or if a landmark
store with the specified name already exists or if the
name contains characters that are not supported by the API
implementation
java.lang.NullPointerException - if the storeName is null
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 java.lang.String createLandmarkStore(java.lang.String storeName,
int authMode)
throws java.io.IOException,
LandmarkException
Creates a new landmark store with a specified name and access restrictions. With this method an application may create landmark stores that has a private authorization mode and is accessible only by that application.
The application creating the landmark store decides whether it is public
or private store. The authorization mode is indicated with the
authMode parameter and it may be either of the two constants
defined in this class starting with prefix AUTHMODE_.
Landmark stores created as public with AUTHMODE_PUBLIC are
available to all applications. But if a landmark store is created with
authorization mode AUTHMODE_PRIVATE, only the application which
created the landmark store has access to it. An application which created
the private landmark store may change it to public with method
changeToPublic.
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.
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. 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. The actual name used in the
implementation and returned with listLandmarkStores
method is returned from this method.
storeName - the name of the landmark store to createauthMode - the authorization mode of the landmark store
java.io.IOException - if the landmark store could not be created due to an
I/O error
java.lang.IllegalArgumentException - if the name is too long or if a landmark
store with the specified name already exists or if the
name contains characters that are not supported by the API
implementation or authMode is not one of the constants
starting with prefix AUTHMODE_ defined in this class
java.lang.NullPointerException - if the storeName is null
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
Delete a landmark store with a specified name. All the landmarks and categories defined in the named landmark store are irrevocably removed.
If a landmark store with the specified name does not exist, this method returns silently without any error.
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.io.IOException - if the landmark store could not be deleted due to an
I/O error
java.lang.NullPointerException - if the storeName is
null (the default landmark store can not be deleted)
java.lang.SecurityException - if the application does not have permissions to
delete a landmark store or if the authorization mode of the
landmark store is private and it was created by the other application
LandmarkException - if the implementation does
not support deleting landmark stores
public static java.lang.String[] listLandmarkStores()
throws java.io.IOException
Lists the names of all the landmark stores that the requesting application has access to. So the list contains public landmark stores and the private landmark stores that have been created by the calling application. In case of MIDP, the application means the MIDlet suite.
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.
The store names must be returned in a form that is
directly usable as input to getInstance and
deleteLandmarkStore methods.
java.io.IOException - if an I/O error occurred when trying to access the
landmark stores
java.lang.SecurityException - if the application does not have the permission
to access landmark stores
public static int getFeatures(java.lang.String storeName)
throws java.io.IOException
Returns the list of optional features the specified landmark store supports.
The return value is a bitwise combination (OR) of the following constants
defined in this class: IS_READ_ONLY, CATEGORY_MANAGEMENT_SUPPORTED,
LANDMARKSTORE_LISTENER_SUPPORTED, AUTHMODE_PRIVATE,
IS_REMOTE, WILDCARDS_SUPPORTED and
SORTING_SUPPORTED. If null is passed in as the
parameter, the supported features of the default landmark store are returned.
Only bits with constants defined above are allowed to be used. Other bits are reserved and must be set to 0.
The following table defined rules for combinations of certain features.
yes in the column means the feature bit must be
set and no that the feature bit must not be
set.
| Landmark store | Read only | Private | Remote | Listener supported | Category management |
| Default landmark store | no | no | no | ||
| Public landmark store | no | ||||
| Private landmark store | no | yes | |||
| Remote landmark store | yes | no | |||
| Read-only landmark store | yes | no | no |
storeName - the name of the landmark store, null to
indicate default landmark store
java.lang.IllegalArgumentException - if storeName is not
one of the landmark store names returned from the
listLandmarkStores method
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 store
public void changeToPublic()
throws java.io.IOException
Changes the authorization mode of a private landmark store to public. This means that after calling the method, all applications have access to the specified landmark store. If the given landmark store is already public, this method silently returns without actions.
java.io.IOException - if an I/O error occurred when trying to access the
landmark store
public java.lang.String getName()
throws java.io.IOException
This convenience method returns the name of this landmark store. The
name is the same that was used in getInstance
method. In case of default landmark store, null is returned.
null for default landmark
store
java.io.IOException - if an I/O error occurred when trying to access the
landmark store
public void addLandmark(Landmark landmark,
java.lang.String category)
throws java.io.IOException
Adds a landmark to the specified category in the landmark store.
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 landmark's name and author fields must not be
truncated. Every implementation must be able to support
name fields that are 32 Unicode 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, an IllegalArgumentException
is thrown.
When the landmark store is empty, every implementation is required to
be able to store a landmark where each String field (including
landmark's description and all fields in the AddressInfo
associated with the landmark) 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. If the Landmark object is an instance that does not
belong to this LandmarkStore and the identifier for the landmark
has been set to value > 0, the implementation must
check that there is not already a landmark with the same identifier and author
combination in the LandmarkStore. If there is, an
IllegalArgumentException is thrown. After this method call,
the Landmark object that is passed as a parameter belongs to
this LandmarkStore.
If a landmark is to be added to more than one category, the additions must be done one by one with this method. Adding a landmark to any of the global landmark categories must be done using the constant global category names defined in this class.
Calling this method updates the timestamp of the landmark.
In some cases the landmark store may be read-only, so no changes are
allowed to it. In this case this method throws an IOException.
If there is a LandmarkStoreListener assigned
for this landmark store, the API implementation must
send LandmarkStoreListener.landmarkStoreUpdated notification
to registered applications before this method returns.
landmark - the landmark to be addedcategory - category where the landmark is added, null
or an empty String can be used to indicate that
the landmark does not belong to a category
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 or if the landmark store is read-only
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 or if this LandmarkStore
already contains a different Landmark with the
same identifier and author combination
java.lang.NullPointerException - if the landmark parameter is
null
java.lang.SecurityException - if the application is not allowed to add landmarks
public Landmark getLandmark(int identifier,
java.lang.String author)
throws java.io.IOException
Returns the Landmark object for the given identifier and
author combination. If the identifier is
Landmark.NO_IDENTIFIER and there is more than one landmark
with the same author, null is returned. If the
LandmarkStore does not contain matching landmark, this method
returns null.
identifier - the landmark's identifierauthor - the landmark's author
Landmark or null if the
landmark can not be found or there are several matches
java.io.IOException - if an I/O error happened when accessing the
landmark store
java.lang.IllegalArgumentException - if identifier = 0 or
identifier < Landmark.NO_IDENTIFIER (=-1)
public java.util.Enumeration getLandmarks(java.lang.String category,
java.lang.String name)
throws java.io.IOException
Gets the Landmarks from the storage where the category and/or name matches the given parameters.
category - the category of the landmark, null or an empty
String implies a wildcard that matches all categoriesname - the name of the desired landmark, null or an empty
String implies a wildcard that matches all
the names within the category indicated by the category parameter
Enumeration containing all the matching landmarks or
null if no landmark matched the given parameters
java.io.IOException - if an I/O error happened when accessing the landmark store
public java.util.Enumeration getLandmarks()
throws java.io.IOException
Lists all landmarks stored in the store.
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 store
public java.util.Enumeration getLandmarks(java.lang.String category,
double minLatitude,
double maxLatitude,
double minLongitude,
double maxLongitude)
throws java.io.IOException
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. The bounds are considered to belong to the area.
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 or an empty
String 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]
Enumeration containing all the matching landmarks
or null if no landmark matched
the given parameters
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 > maxLatitude
public Landmark[] getLandmarks(GeographicArea areaFilter,
AddressInfo addrFilter,
java.lang.String nameFilter,
java.lang.String descFilter,
java.lang.String authorFilter,
java.lang.String catFilter,
Coordinates distFrom,
int maxResults,
int sortOrder,
int sortBy)
throws java.io.IOException
With this method an application can search landmarks in the store
using filters. The filter parameters may be null,
if an application does not want to filter landmarks using that particular
filter. If a filter is given, it must match exactly in
each resulting landmark. If multiple filters are given, the resulting landmarks
must match to all given filters. All the String
filters and filter fields must be handled in case
insensitive way.
The API implementation may support wildcards in the
String based search filters. An application can query the
support for them getFeatures. If
the API implementation supports wildcards, the bit for WILDCARDS_SUPPORTED
must be set in the returned value. ? character
can be used as a wildcard that matches any character. *
character is a wildcard that matches 0 or more characters.
If areaFilter is given and it is not null, the
API implementation must support finding landmarks whose
coordinates are inside given areaFilter. The API implementation
may support finding landmarks whose coverage area is
completely or partially inside the given areaFilter.
If an application uses an AddressInfo as the filter, the
fields given in the AddressInfo must match
the address fields in the resulting landmark. The filter fields that are not
given (set to null) are ignored. Wildcards can be used in the
String fields of addrFilter. If the application
knows only address and wants to do 'proximity' query, for example, relative
to the user's current location, it must first geocode the address to
coordinates using the GeocodingServiceProvder.
The API implementation may support sorting of the found
landmarks. An application can query the support for them
getFeatures. If the API implementation supports
sorting, the bit for SORTING_SUPPORTED
must be set in the returned value. If sorting is not
supported, the sortOrder parameter is ignored.
The sortBy parameter indicates what field in the
Landmark object is used to sort the result set. In addition to
that sorting may be done based on the distance of landmark from the coordinates
given as parameter. The field may be any of the fields
defined in the AddressInfo object or the the constants
starting with prefix SORT_BY_ defined in this class. Since the
only mandatory field for a landmark is the name, the result set may contain
landmarks that do not have the sort field set. These landmarks must
be placed to the end of the returned Enumeration after the landmarks
that have the sort field set.
If there are more matches than what is allowed with the
maxMatches the implementation sorts them according to
sorting parameters and maxMatches landmarks are returned
from the beginning of the sorted list of matching landmarks. If the landmark
store is not modified, the results of the subsequent calls returned from
this method, must be the same.
areaFilter - a GeographicArea used as a filter, may be
nulladdrFilter - an AddressInfo used as a filter,
may be nullnameFilter - the name of the landmark, may be nulldescFilter - the description of the landmark, may be nullauthorFilter - the author of the landmark, may be nullcatFilter - the category of the landmark, may be nulldistFrom - coordinates from which the distance is calculated if
sorting is done based on that, may be nullmaxResults - the maximum number of results this query can return,
-1 if an application has no restrictionsortOrder - the order in which the sorting is donesortBy - the field used to sort the result set
Landmark array for containing the matching landmarks,
null if no matches are found
java.io.IOException - if an I/O error happened when accessing the
landmark store
java.lang.IllegalArgumentException - if sortOrder is not
one of the constants starting with prefix SORT_ORDER
defined in this class or if maxResults = 0 or <-1
or if sortBy is not one of the constants
defined in AddressInfo class or constants starting
with prefix SORT_BY_ defined in this class
or if sortOrder is SORT_BY_DISTANCE and
distFrom is null
public int getNumberOfLandmarks(java.lang.String category)
throws java.io.IOException
This convenience method returns the number of landmarks in the given category.
If the category is null the method returns the number of landmarks
in the landmark store. If the specified category is not found from the
landmark store an IllegalArgumentException is thrown.
Applications may use this method, for example, to check if the number of
landmarks has changed after receiving
LandmarkStoreListener.landmarkStoreUpdated
notification.
category - the landmark category, from which the landmark number is
requested, null if the total number of landmarks in
the landmark store is requested
java.io.IOException - if an I/O error happened when accessing the landmark store
java.lang.IllegalArgumentException - if category does not
exist in the landmark store
public void removeLandmarkFromCategory(Landmark landmark,
java.lang.String category)
throws java.io.IOException
Removes the named landmark from the specified category. To remove the named landmark from a global landmark category, the constant defined for that global landmark category must be used.
The landmark passed in as the parameter must be an
instance that belongs to this LandmarkStore.
If the landmark parameter does not belong to the
specified category or to the landmark store at all, 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.
In some cases the landmark store may be read-only, so no changes are
allowed to it. In this case this method throws an IOException.
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 method.
landmark - the landmark to be removedcategory - the category from which it will be removed
java.io.IOException - if an I/O error happened when accessing the
landmark store or if the landmark store is read-only
java.lang.NullPointerException - if either parameter is null
java.lang.SecurityException - if the application is not allowed to
modify the landmark
public void removeLandmarkFromAllCategories(Landmark landmark)
throws java.io.IOException
Removes the named landmark from all the categories it is associated to.
The Landmark instance passed in as the parameter must be
an instance that belongs to this LandmarkStore.
If the landmark parameter does not belong to any category
or to the landmark store at all, the request is silently ignored and the
method call returns with no error.
In some cases the landmark store may be read-only, so no changes are
allowed to it. In this case this method throws an IOException.
The landmark is only removed from the categories but the
landmark still belongs to the store. The landmark can still be
obtained from the store by passing null as the category to
getLandmarks method.
landmark - landmark to be removed from all categories
java.io.IOException - if an I/O error happened when accessing the
landmark store or if the landmark store is read-only
java.lang.NullPointerException - if landmark is null
java.lang.SecurityException - if the application is not allowed to
modify the landmark
public void updateLandmark(Landmark landmark)
throws java.io.IOException,
LandmarkException
Updates the information about a landmark. This method only updates the information about a landmark and does not modify the categories the landmark belongs to.
The Landmark instance passed in as the parameter must be
an instance that belongs to this LandmarkStore.
This method can not be used to add a new landmark to the store.
Calling this method updates the timestamp of the landmark.
In some cases the landmark store may be read-only, so no changes are
allowed to it. In this case this method throws an IOException.
If there is a LandmarkStoreListener assigned
for this landmark store, the API implementation must
send LandmarkStoreListener.landmarkStoreUpdated notification
to registered applications before this method returns.
landmark - the landmark to be updated
java.io.IOException - if an I/O error happened when accessing the landmark store
or if the landmark store is read-only
java.lang.IllegalArgumentException - if the landmark has a longer
name field than the implementation can support
java.lang.NullPointerException - if the landmark is null
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
public void deleteLandmark(Landmark landmark)
throws java.io.IOException,
LandmarkException
Deletes a landmark from this LandmarkStore. This method
removes the specified landmark from all categories and deletes the
information from this LandmarkStore.
The Landmark instance passed as the parameter must be
an instance that belongs to this LandmarkStore.
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.
In some cases the landmark store may be read-only, so no changes are
allowed to it. In this case this method throws an IOException.
If there is a LandmarkStoreListener assigned
for this landmark store, the API implementation must
send LandmarkStoreListener.landmarkStoreUpdated notification
to registered applications before this method returns.
landmark - the landmark to be deleted
java.io.IOException - if an I/O error happened when accessing the landmark store
or if the landmark store is read-only
java.lang.NullPointerException - if the landmark is null
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
public java.util.Enumeration getCategories()
throws java.io.IOException
Returns the category names that are defined in this LandmarkStore.
The returned Enumeration contains at least the global landmark
categories as the constants defined in this class. The global categories
must be in the beginning of the Enumeration
and in the order defined in the description of this class. The names of the
global landmark categories in certain language can be retrieved with
getCategoryDisplayName
method.
Enumeration containing String objects
representing the category names, at least the global
categories in the specified order are returned
java.io.IOException - if an I/O error occurred when trying to access the
landmark store
public void addCategory(java.lang.String categoryName)
throws java.io.IOException,
LandmarkException
Adds a category to this LandmarkStore. If an application
tries to add a category that is the same as the name of the global landmark
category (defined in the constants in this class) an
IllegalArgumentException is thrown.
All implementations must support names that have length up to and including 32 Unicode 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.io.IOException - if an I/O error occurs or there are no resources to add
a new category
java.lang.IllegalArgumentException - if a category with the specified name
already exists or categoryName in an empty
String
java.lang.NullPointerException - if the categoryName is null
java.lang.SecurityException - if the application does not have the permission
to manage categories
LandmarkException - if this LandmarkStore
does not support adding new categories
public void deleteCategory(java.lang.String categoryName)
throws java.io.IOException,
LandmarkException
Removes a category from this LandmarkStore. Global landmark
categories can not be removed. All the landmarks belonging to the removed
category will no longer belong to the category after this method call.
This method will not remove any of 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.io.IOException - if an I/O error occurs
java.lang.IllegalArgumentException - if categoryName is
one of the global landmark categories defined in this class
or an empty String
java.lang.NullPointerException - if the categoryName is null
java.lang.SecurityException - if the application does not have the permission
to manage categories
LandmarkException - if this LandmarkStore
does not support deleting categories
public void renameCategory(java.lang.String oldCategoryName,
java.lang.String newCategoryName)
throws java.io.IOException,
LandmarkException
Renames a landmark category. This method can not be used to global
landmark categories. The renaming affects all landmarks belong to the
given category. If a category with the supplied current category name does
not exist in this LandmarkStore, this method returns silently
with no error.
oldCategoryName - the current name of the landmark categorynewCategoryName - the new name for the category
java.io.IOException - if an I/O exception occurs
java.lang.IllegalArgumentException - if the oldCateogryName
is the name of one of the global landmark categories or
if oldcategoryName or newCategoryName
is an empty String or if newCategory
is one of the global category constants defined in this class
java.lang.NullPointerException - if oldCategoryName or
newCategoryName is null
java.lang.SecurityException - if the application does not have the permission
to manage categories
LandmarkException - if this LandmarkStore
does not support renaming categories
public java.lang.String getCategoryDisplayName(java.lang.String category,
java.lang.String language)
throws java.io.IOException
Returns the name of the requested landmark category in the
specified language. The returned category name is intended to be shown
to the user. The language String is a language tags
as defined in RFC 4646 (see reference [RFC4646]). Localized names are supported
only for the global landmark categories. If the category
is not one of the global categories, the name passed in as the
category parameter is returned. If the category
passed in is not added to this landmark store, the same name is returned
to the application. If language is null or an empty
String, the current language of the device must
be used. If the given language is not supported by the API implementation,
null is returned.
category - the category namelanguage - the language tag in which the category name is requested,
null or empty String if the current
language of the device is used
null if
the implementation does not supported the specified language
(for all category names)
java.io.IOException - if an I/O error happened when accessing the landmark store
java.lang.NullPointerException - if category is null
public java.util.Enumeration getCategoriesOfLandmark(Landmark landmark)
throws java.io.IOException,
LandmarkException
Returns the landmark categories for the specified landmark. If the specified
landmark does not belong to any landmark category, an empty
Enumeration is returned. If the specified landmark does not
belong to this landmark store, a LandmarkException
is thrown. If a landmark belongs to global categories, the names of them are
returned as constants defined in this class.
landmark - landmark whose categories are queried
Enumeration of String objects that
specify categories of the landmark, an empty Enumeration
if the landmark does not belong to any category
java.io.IOException - if an I/O error happened when accessing the landmark store
java.lang.NullPointerException - if landmark is null
LandmarkException - if the landmark
does not belong to this landmark store
public void addLandmarkStoreListener(LandmarkStoreListener listener)
throws LandmarkException
Adds a LandmarkStoreListener that is notified
when there are changes in the specified landmark store. The listener is removed
with method removeLandmarkStoreListener method. There
may be more than one LandmarkStoreListener
set at a time. If an application tries to add a listener that is already
set, this method returns without actions.
If this method is called with a listener that is null, the
method returns silently without any actions.
Support for landmark store listeners is optional. The support for them
can be checked with method getFeatures.
If the landmark store listeners for this landmark store are supported,
the bit for LANDMARKSTORE_LISTENER_SUPPORTED must
be set in the returned value.
listener - a listener for the changes in the landmark store
LandmarkException - if the landmark store
implementation does not support adding listeners to the landmark storepublic void removeLandmarkStoreListener(LandmarkStoreListener listener)
Removes the specified listener from receiving notifications about changes in the landmark store.
If this method is called with a listener that is null, or
with a listener that has not been set this method return silently without
any actions. If the landmark store implementation does not support landmark
store listeners, the method returns silently without any actions.
listener - listener to be removed from receiving notifications
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||