javax.microedition.location
Interface ExchangeFormatHandler

public interface ExchangeFormatHandler

This interface provides methods to exchange landmarks. Each of the different exchange format handlers will implement this interface in the exchange format specific class.

Methods in this interface are blocking and they may take a long time to execute. Therefore they should be executed in a separate thread.

Since:

2.0

Method Summary

void	abort() Cancels the ongoing import or export operation.
void	exportAllLandmarks(LandmarkStore store, java.lang.String additionalCategory, java.io.OutputStream output) Exports all landmarks in the landmark store to the specified output stream.
void	exportLandmarks(Landmark[] landmarks, java.lang.String additionalCategory, java.io.OutputStream output) Exports selected landmarks into the specified output stream.
int	importLandmarks(java.io.InputStream input, LandmarkStore store, java.lang.String additionalCategory, boolean forced) Imports landmarks from the specified input stream to the specified landmark store.

Method Detail

importLandmarks

int importLandmarks(java.io.InputStream input,
                    LandmarkStore store,
                    java.lang.String additionalCategory,
                    boolean forced)
                    throws java.io.IOException,
                           java.lang.InterruptedException,
                           LandmarkException

Imports landmarks from the specified input stream to the specified landmark store. An application may specify a category that is applied to all imported landmarks. If the exchange format contains information about the categories of landmarks, those categories are added to the landmark store and the landmarks are added to those categories during import operation. The number of imported landmarks is returned to the application. If the forced parameter is true, the method returns the total number of landmarks that were added and updated in the landmark store.

Importing landmarks into the landmark store is an atomic operation. Either all or none of the landmarks is imported to the landmark store. The application can control the behaviour with forced parameter. If forced if false and any of the imported landmarks has an identifier and author combination matching already stored landmark in the landmark store, importing must aborted and none of the imported landmarks must be stored to the landmark store and the method throws an LandmarkException. If forced is set to true all the landmarks are imported into the landmark store. If there is already an existing landmark with a matching identifier and author combination, that landmark must be updated by the imported landmark.

Since support for adding, renaming and deleting categories in a landmark store is an optional feature, importing landmarks may also fail because adding categories is not supported. If additionalCategory already exists on the landmark store, the landmarks are added to that category.

If the import fails or the operation is aborted, the landmark store must be restored into the same state it was before the import was started.

When the importing landmark has been completed, the API implementation must send LandmarkStoreListener.landmarkStoreUpdated notification to the registered applications.

Parameters:

input - the input stream from where the landmarks are imported

store - the landmark store where the landmarks are imported

additionalCategory - an additional landmark category that is applied to all imported landmarks, null or an empty String can be used to indicate no additional category

forced - true if import updates matching existing landmarks in the store, false if no update is allowed

Returns:

the number of imported landmarks

Throws:

java.io.IOException - if an I/O error happened when accessing the landmark store or the input stream

java.lang.InterruptedException - if the operation has been canceled

java.lang.NullPointerException - if input or store is null

LandmarkException - if the LandmarkStore does not support adding new categories or if there already is a landmark with the same identifier and author combination in the landmark store and forced is set to false or if the store is read-only and new landmarks can not be added to it

java.lang.SecurityException - if the application does not have the permission to write to the landmark store

exportLandmarks

void exportLandmarks(Landmark[] landmarks,
                     java.lang.String additionalCategory,
                     java.io.OutputStream output)
                     throws java.io.IOException,
                            java.lang.InterruptedException

Exports selected landmarks into the specified output stream. If Landmark objects in the landmarks array belong to a landmark store, they contains also information about the categories of the landmark store they have been added to. That category information must be included into the landmark exchange format. The specified additional category is added to the existing categories to the landmarks. If the Landmark object does not belong to a landmark store, it does no have information about the categories. These landmarks are exported only with the specified additional category. The additional category may be null. The output stream provided as the input parameter can not be extended later. If an application needs to do another export, it must create another output stream for that purpose.

Parameters:

landmarks - landmarks to be exported

additionalCategory - category that is applied to the exported landmarks, null or an empty String can be used to indicate no additional category

output - the output stream where the landmarks are exported

Throws:

java.io.IOException - if an error happened when accessing the output stream

java.lang.IllegalArgumentException - if landmarks is an empty array

java.lang.InterruptedException - if the operation has been canceled

java.lang.NullPointerException - if landmarks or output is null or if landmarks contains null elements

exportAllLandmarks

void exportAllLandmarks(LandmarkStore store,
                        java.lang.String additionalCategory,
                        java.io.OutputStream output)
                        throws java.io.IOException,
                               java.lang.InterruptedException

Exports all landmarks in the landmark store to the specified output stream. Exporting landmarks preserves the existing categories the landmark belongs to. The specified category is added to the existing categories of all exported landmarks, but not to the landmark store. The additional category may be null. The output stream provided as the parameter can not be extended later. If an application needs to do another export, it must create another output stream for that purpose.

Parameters:

store - the name of the landmark store, from where the landmarks are exported

additionalCategory - landmark category that is applied to all of the exported landmarks, null or an empty String can be used to indicate no additional category

output - the output stream where the landmarks are exported

Throws:

java.io.IOException - if an I/O error happened when accessing the landmark store or the output stream

java.lang.InterruptedException - if the operation has been canceled

java.lang.NullPointerException - if store or output is null

abort

void abort()

Cancels the ongoing import or export operation. The ongoing operation is stopped on the best effort basis and the import and export methods throws an InterrupedException when this methods is called.