1 /*

     2 * Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Landmark store manager for handling landmark stores

    15  *

    16 */

    17 

    18 

    19 package com.nokia.mj.impl.location;

    20 

    21 

    22 import com.nokia.mj.impl.location.NativeError;

    23 import java.util.Vector;

    24 import java.io.IOException;

    25 

    26 import javax.microedition.location.LandmarkStore;

    27 import com.nokia.mj.impl.rt.support.Finalizer;

    28 

    29 

    30 /**

    31  * Landmark store manager for handling landmark stores

    32  *

    33  * This class provides functionalities to open, create and delete landmark

    34  * stores. The class is a singleton instance which can be access using

    35  * the getInstance() method from everywhere and any time possible.

    36  */

    37 public class LandmarkStoreManager

    38 {

    39     // Singleton instance for this class

    40     private static LandmarkStoreManager sInstance;

    41 

    42     // Landmark store map

    43     private final LandmarkStoreMap iStoreMap;

    44 

    45     // Handle to this class' native peer

    46     private final int iManagerHandle;

    47 

    48     // Handle to native Function source

    49     private final int iFunctionSourceHandle;

    50 

    51     private Finalizer mFinalizer;

    52 

    53     // Error messages

    54     private static final String LANDMARKSTORE_OPERATION_ERROR

    55     = "Unable to do landmarkStore operation";

    56 

    57     private static final String LIST_LANDMARK_STORES_ERROR

    58     = "Unable to list landmarkStores: ";

    59 

    60     /**

    61      * Returns an instance from this class

    62      */

    63     public static synchronized LandmarkStoreManager getInstance()

    64     {

    65         // Method level synhronization makes this thread-safe

    66         if (sInstance == null)

    67         {

    68             sInstance = new LandmarkStoreManager();

    69         }

    70         return sInstance;

    71     }

    72 

    73     /**

    74      * Hidden constructor. Creates an instance from this class

    75      * the constructor also creates the native side peer object

    76      */

    77     private LandmarkStoreManager()

    78     {

    79         // Register this object for finalization

    80         mFinalizer = registerForFinalization();

    81         // Create native peer

    82         iFunctionSourceHandle =

    83             LAPIManager.getInstance().getFunctionSourceHandle();

    84         iManagerHandle = _createNativePeer(iFunctionSourceHandle);

    85         // Check if the creation failed and throw error

    86         if (iManagerHandle < NativeError.KErrNone)

    87         {

    88             throw new OutOfMemoryError(LANDMARKSTORE_OPERATION_ERROR);

    89         }

    90 

    91         iStoreMap = new LandmarkStoreMap();

    92     }

    93 

    94     Finalizer registerForFinalization()

    95     {

    96         return new Finalizer()

    97         {

    98             public void finalizeImpl()

    99             {

   100                 doFinalize();

   101             }

   102         };

   103 

   104     }

   105 

   106     /**

   107      * Disposes the LandmarkStore Manager native peer, if the handles are valid.

   108      * Invalid (negative) handles indicate that their creation failed in

   109      * the first place.

   110      */

   111     final void doFinalize()

   112     {

   113         _dispose(iFunctionSourceHandle, iManagerHandle);

   114     }

   115 

   116     /**

   117      * Returns an opened store. null is returned if the specified store

   118      * has not been opened yet. Stores can be opened using openStore() method

   119      *

   120      * @param aLocator The locator indicating where the store is. null locator

   121      *        is interpreted as the default store

   122      * @return The opened landmark store instance

   123      */

   124     public LandmarkStore getStore(Locator aLocator)

   125     {

   126         String uri = aLocator != null ? aLocator.getStoreURI() : "";

   127         return iStoreMap.getStore(uri);

   128     }

   129 

   130     /**

   131      * Registers an opened landmark store to this manager

   132      *

   133      * @param aStore The store which is to be registered

   134      * @param aStoreUri The uri of the registered store. Note that

   135      *        this cannot acquired from the store object because

   136      *        getURI() method must be package private

   137      */

   138     public void registerStore(LandmarkStore aStore, String aStoreUri)

   139     {

   140         iStoreMap.registerStore(aStore, aStoreUri);

   141     }

   142 

   143     /**

   144      * Opens a landmark store. The invocation calls native side landmark store

   145      * manager to open a specific landmark store. If the locator provides a

   146      * null URI, the default store will be opened. Otherwise a named store will

   147      * be opened if it is available

   148      *

   149      * @param aLocator The locator indicating where the store is

   150      * @return Handle to the native side landmark store peer object

   151      */

   152     public int openStore(Locator aLocator)

   153     {

   154         String uri = aLocator != null ? aLocator.getStoreURI() : null;

   155         // Open the native side landmark store

   156         int handle = _openStore(iFunctionSourceHandle, iManagerHandle, uri);

   157         // return the handle to the caller which is responsible for

   158         // interpreting possible errors when opening the store

   159         return handle;

   160     }

   161 

   162     /**

   163      * Creates a landmark store. The invocation calls native side landmark store

   164      * manager to create a specific landmark store. The URI must not be null

   165      *

   166      * @param aLocator The locator indicating where the store is

   167      * @return NativeError.KErrNone if no error occured. Otherwise one of the

   168      *         system-wide error codes

   169      */

   170     public int createStore(Locator aLocator)

   171     {

   172         if (aLocator == null)

   173         {

   174             throw new NullPointerException();

   175         }

   176 

   177         String uri = aLocator.getStoreURI();

   178         // Create the store to the native database

   179         return _createStore(iFunctionSourceHandle, iManagerHandle, uri);

   180     }

   181 

   182     /**

   183      * Deletes a landmark store. The invocation calls native side landmark store

   184      * manager to delete a specific landmark store. The URI must not be null.

   185      * Note that all landmarks and categories will be removed from this store

   186      *

   187      * Note that this does not dispose the native side object. It only closes

   188      * the store so the store must be disposed separately an informed to this

   189      * class.

   190      *

   191      * @param aLocator The locator indicating where the store is

   192      * @return NativeError.KErrNone if no error occured. Otherwise one of the

   193      *         system-wide error codes

   194      */

   195     public int deleteStore(Locator aLocator)

   196     {

   197         if (aLocator == null)

   198         {

   199             throw new NullPointerException();

   200         }

   201 

   202         String uri = aLocator.getStoreURI();

   203         // Unregister the landmark store if there is an open store. This

   204         // quarantees that the closed store will not be provided to any

   205         // requesting client

   206         iStoreMap.unregisterStore(uri);

   207 

   208         // Delete the store from the native database

   209         return _deleteStore(iFunctionSourceHandle, iManagerHandle, uri);

   210     }

   211 

   212     /**

   213      * Removes a native side landmark store peer object from this class

   214      * @param aStoreHandle A handle to the store which is to be removed

   215      */

   216     public void removeStore(String aStoreUri, int aStoreHandle)

   217     {

   218         // Unregister the landmark store if there is an open store. This

   219         // quarantees that the closed store will not be provided to any

   220         // requesting client. Store URI must not be null.

   221         // "" indicates the default store

   222         if (aStoreUri != null)

   223         {

   224             iStoreMap.unregisterStore(aStoreUri);

   225         }

   226 

   227         _removeStore(iFunctionSourceHandle, iManagerHandle, aStoreHandle);

   228     }

   229 

   230     /**

   231      * Lists the landmark stores in the device. The store names are returned

   232      * as a vector holding Locator objects. The names can be acquired using

   233      * Locator.getName() method

   234      *

   235      * @return Vector holding the list of landmark stores in the device

   236      */

   237     public Vector listStores() throws IOException

   238     {

   239         int[] errors = new int[1];

   240         // Get store unified resource identifiers from the native

   241         String[] storeUris = _listStores(iFunctionSourceHandle, iManagerHandle,

   242                                          errors);

   243         // Check for errors and throw an IOException if something went wrong

   244         NativeError.checkIO(errors[0], LIST_LANDMARK_STORES_ERROR);

   245 

   246         Vector locators = null;

   247         // Create locator list from the stores

   248         if (storeUris != null && storeUris.length > 0)

   249         {

   250             locators = new Vector(storeUris.length);

   251             for (int i = 0; i < storeUris.length; i++)

   252             {

   253                 // Create a new locator explicitly using the constuctor since

   254                 // the URIs from the native side are already valid ones

   255                 try

   256                 {

   257                     Locator locator = new Locator(storeUris[i]);

   258                     locators.addElement(locator);

   259                 }

   260                 catch (IllegalArgumentException e)

   261                 {

   262                     // Ignore invalid store URIs

   263                 }

   264             }

   265         }

   266         // Return the list of store locators. null indicates that there are no

   267         // stores in the device

   268         return locators;

   269     }

   270 

   271     /**

   272      * Creates the native peer for this object

   273      * @param aEventSourceHandle Handle to event source

   274      * @retutn Handle to the native side peer object

   275      */

   276     private native int _createNativePeer(int aEventSourceHandle);

   277 

   278     /**

   279      * Opens a native side landmark store

   280      * @param aEventSourceHandle Handle to event source

   281      * @param aManagerHandle Handle to the landmark store manager

   282      * @param aURI Unified Resource Locator pointing where the store is

   283      * @return Handle to the opened store. NativeError.KErrNotFound is returned

   284      *         if the specified store does not exist

   285      */

   286     private native int _openStore(int aEventSourceHandle, int aManagerHandle,

   287                                   String aURI);

   288 

   289     /**

   290      * Creates a new landmark store to the native side

   291      * @param aEventSourceHandle Handle to event source

   292      * @param aManagerHandle Handle to the landmark store manager

   293      * @param aURI Unified Resource Locator pointing where the store is

   294      * @return NativeError.KErrNone if the was no error. Otherwise, one of the

   295      *         system wide error codes

   296      */

   297     private native int _createStore(int aEventSourceHandle, int aManagerHandle,

   298                                     String aURI);

   299 

   300     /**

   301      * Deletes an existing native landmark database

   302      * @param aEventSourceHandle Handle to event source

   303      * @param aManagerHandle Handle to the landmark store manager

   304      * @param aURI Unified Resource Locator pointing where the store is

   305      * @return NativeError.KErrNone if the was no error. Otherwise, one of the

   306      *         system wide error codes

   307      */

   308     private native int _deleteStore(int aEventSourceHandle, int aManagerHandle,

   309                                     String aURI);

   310 

   311     /**

   312      * Removes a landmark store native side peer object from this class

   313      * If the specified store was not found this call is simply ignored

   314      * @param aEventSourceHandle Handle to event source

   315      * @param aManagerHandle Handle to the landmark store manager

   316      * @param aStoreHandle Handle to the store which should be removed

   317      */

   318     private native void _removeStore(int aEventSourceHandle,

   319                                      int aManagerHandle, int aStoreHandle);

   320 

   321     /**

   322      * Returns a list of landmark store uris

   323      * @param aEventSourceHandle Handle to event source

   324      * @param aManagerHandle Handle to the landmark store manager

   325      * @param aErrors Error array. On return, contains the occured errors

   326      * @return Array holding the uris of the native landmark databases

   327      */

   328     private native String[] _listStores(int aEventSourceHandle,

   329                                         int aManagerHandle, int[] aErrors);

   330 

   331     /**

   332      * Disposes this object native side peer

   333      * @param aEventSourceHandle Handle to the event source

   334      * @param aManagerHandle Handle to the native side peer object

   335      */

   336     private native void _dispose(int aEventSourceHandle, int aManagerHandle);

   337 }

   338 

   339 // End of file