diff -r e8e63152f320 -r 2a9601315dfc javaextensions/location/landmarks/javasrc.s60/com/nokia/mj/impl/location/LandmarkStoreManager.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/javaextensions/location/landmarks/javasrc.s60/com/nokia/mj/impl/location/LandmarkStoreManager.java Mon May 03 12:27:20 2010 +0300 @@ -0,0 +1,339 @@ +/* +* Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of "Eclipse Public License v1.0" +* which accompanies this distribution, and is available +* at the URL "http://www.eclipse.org/legal/epl-v10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: Landmark store manager for handling landmark stores + * +*/ + + +package com.nokia.mj.impl.location; + + +import com.nokia.mj.impl.location.NativeError; +import java.util.Vector; +import java.io.IOException; + +import javax.microedition.location.LandmarkStore; +import com.nokia.mj.impl.rt.support.Finalizer; + + +/** + * Landmark store manager for handling landmark stores + * + * This class provides functionalities to open, create and delete landmark + * stores. The class is a singleton instance which can be access using + * the getInstance() method from everywhere and any time possible. + */ +public class LandmarkStoreManager +{ + // Singleton instance for this class + private static LandmarkStoreManager sInstance; + + // Landmark store map + private final LandmarkStoreMap iStoreMap; + + // Handle to this class' native peer + private final int iManagerHandle; + + // Handle to native Function source + private final int iFunctionSourceHandle; + + private Finalizer mFinalizer; + + // Error messages + private static final String LANDMARKSTORE_OPERATION_ERROR + = "Unable to do landmarkStore operation"; + + private static final String LIST_LANDMARK_STORES_ERROR + = "Unable to list landmarkStores: "; + + /** + * Returns an instance from this class + */ + public static synchronized LandmarkStoreManager getInstance() + { + // Method level synhronization makes this thread-safe + if (sInstance == null) + { + sInstance = new LandmarkStoreManager(); + } + return sInstance; + } + + /** + * Hidden constructor. Creates an instance from this class + * the constructor also creates the native side peer object + */ + private LandmarkStoreManager() + { + // Register this object for finalization + mFinalizer = registerForFinalization(); + // Create native peer + iFunctionSourceHandle = + LAPIManager.getInstance().getFunctionSourceHandle(); + iManagerHandle = _createNativePeer(iFunctionSourceHandle); + // Check if the creation failed and throw error + if (iManagerHandle < NativeError.KErrNone) + { + throw new OutOfMemoryError(LANDMARKSTORE_OPERATION_ERROR); + } + + iStoreMap = new LandmarkStoreMap(); + } + + Finalizer registerForFinalization() + { + return new Finalizer() + { + public void finalizeImpl() + { + doFinalize(); + } + }; + + } + + /** + * Disposes the LandmarkStore Manager native peer, if the handles are valid. + * Invalid (negative) handles indicate that their creation failed in + * the first place. + */ + final void doFinalize() + { + _dispose(iFunctionSourceHandle, iManagerHandle); + } + + /** + * Returns an opened store. null is returned if the specified store + * has not been opened yet. Stores can be opened using openStore() method + * + * @param aLocator The locator indicating where the store is. null locator + * is interpreted as the default store + * @return The opened landmark store instance + */ + public LandmarkStore getStore(Locator aLocator) + { + String uri = aLocator != null ? aLocator.getStoreURI() : ""; + return iStoreMap.getStore(uri); + } + + /** + * Registers an opened landmark store to this manager + * + * @param aStore The store which is to be registered + * @param aStoreUri The uri of the registered store. Note that + * this cannot acquired from the store object because + * getURI() method must be package private + */ + public void registerStore(LandmarkStore aStore, String aStoreUri) + { + iStoreMap.registerStore(aStore, aStoreUri); + } + + /** + * Opens a landmark store. The invocation calls native side landmark store + * manager to open a specific landmark store. If the locator provides a + * null URI, the default store will be opened. Otherwise a named store will + * be opened if it is available + * + * @param aLocator The locator indicating where the store is + * @return Handle to the native side landmark store peer object + */ + public int openStore(Locator aLocator) + { + String uri = aLocator != null ? aLocator.getStoreURI() : null; + // Open the native side landmark store + int handle = _openStore(iFunctionSourceHandle, iManagerHandle, uri); + // return the handle to the caller which is responsible for + // interpreting possible errors when opening the store + return handle; + } + + /** + * Creates a landmark store. The invocation calls native side landmark store + * manager to create a specific landmark store. The URI must not be null + * + * @param aLocator The locator indicating where the store is + * @return NativeError.KErrNone if no error occured. Otherwise one of the + * system-wide error codes + */ + public int createStore(Locator aLocator) + { + if (aLocator == null) + { + throw new NullPointerException(); + } + + String uri = aLocator.getStoreURI(); + // Create the store to the native database + return _createStore(iFunctionSourceHandle, iManagerHandle, uri); + } + + /** + * Deletes a landmark store. The invocation calls native side landmark store + * manager to delete a specific landmark store. The URI must not be null. + * Note that all landmarks and categories will be removed from this store + * + * Note that this does not dispose the native side object. It only closes + * the store so the store must be disposed separately an informed to this + * class. + * + * @param aLocator The locator indicating where the store is + * @return NativeError.KErrNone if no error occured. Otherwise one of the + * system-wide error codes + */ + public int deleteStore(Locator aLocator) + { + if (aLocator == null) + { + throw new NullPointerException(); + } + + String uri = aLocator.getStoreURI(); + // Unregister the landmark store if there is an open store. This + // quarantees that the closed store will not be provided to any + // requesting client + iStoreMap.unregisterStore(uri); + + // Delete the store from the native database + return _deleteStore(iFunctionSourceHandle, iManagerHandle, uri); + } + + /** + * Removes a native side landmark store peer object from this class + * @param aStoreHandle A handle to the store which is to be removed + */ + public void removeStore(String aStoreUri, int aStoreHandle) + { + // Unregister the landmark store if there is an open store. This + // quarantees that the closed store will not be provided to any + // requesting client. Store URI must not be null. + // "" indicates the default store + if (aStoreUri != null) + { + iStoreMap.unregisterStore(aStoreUri); + } + + _removeStore(iFunctionSourceHandle, iManagerHandle, aStoreHandle); + } + + /** + * Lists the landmark stores in the device. The store names are returned + * as a vector holding Locator objects. The names can be acquired using + * Locator.getName() method + * + * @return Vector holding the list of landmark stores in the device + */ + public Vector listStores() throws IOException + { + int[] errors = new int[1]; + // Get store unified resource identifiers from the native + String[] storeUris = _listStores(iFunctionSourceHandle, iManagerHandle, + errors); + // Check for errors and throw an IOException if something went wrong + NativeError.checkIO(errors[0], LIST_LANDMARK_STORES_ERROR); + + Vector locators = null; + // Create locator list from the stores + if (storeUris != null && storeUris.length > 0) + { + locators = new Vector(storeUris.length); + for (int i = 0; i < storeUris.length; i++) + { + // Create a new locator explicitly using the constuctor since + // the URIs from the native side are already valid ones + try + { + Locator locator = new Locator(storeUris[i]); + locators.addElement(locator); + } + catch (IllegalArgumentException e) + { + // Ignore invalid store URIs + } + } + } + // Return the list of store locators. null indicates that there are no + // stores in the device + return locators; + } + + /** + * Creates the native peer for this object + * @param aEventSourceHandle Handle to event source + * @retutn Handle to the native side peer object + */ + private native int _createNativePeer(int aEventSourceHandle); + + /** + * Opens a native side landmark store + * @param aEventSourceHandle Handle to event source + * @param aManagerHandle Handle to the landmark store manager + * @param aURI Unified Resource Locator pointing where the store is + * @return Handle to the opened store. NativeError.KErrNotFound is returned + * if the specified store does not exist + */ + private native int _openStore(int aEventSourceHandle, int aManagerHandle, + String aURI); + + /** + * Creates a new landmark store to the native side + * @param aEventSourceHandle Handle to event source + * @param aManagerHandle Handle to the landmark store manager + * @param aURI Unified Resource Locator pointing where the store is + * @return NativeError.KErrNone if the was no error. Otherwise, one of the + * system wide error codes + */ + private native int _createStore(int aEventSourceHandle, int aManagerHandle, + String aURI); + + /** + * Deletes an existing native landmark database + * @param aEventSourceHandle Handle to event source + * @param aManagerHandle Handle to the landmark store manager + * @param aURI Unified Resource Locator pointing where the store is + * @return NativeError.KErrNone if the was no error. Otherwise, one of the + * system wide error codes + */ + private native int _deleteStore(int aEventSourceHandle, int aManagerHandle, + String aURI); + + /** + * Removes a landmark store native side peer object from this class + * If the specified store was not found this call is simply ignored + * @param aEventSourceHandle Handle to event source + * @param aManagerHandle Handle to the landmark store manager + * @param aStoreHandle Handle to the store which should be removed + */ + private native void _removeStore(int aEventSourceHandle, + int aManagerHandle, int aStoreHandle); + + /** + * Returns a list of landmark store uris + * @param aEventSourceHandle Handle to event source + * @param aManagerHandle Handle to the landmark store manager + * @param aErrors Error array. On return, contains the occured errors + * @return Array holding the uris of the native landmark databases + */ + private native String[] _listStores(int aEventSourceHandle, + int aManagerHandle, int[] aErrors); + + /** + * Disposes this object native side peer + * @param aEventSourceHandle Handle to the event source + * @param aManagerHandle Handle to the native side peer object + */ + private native void _dispose(int aEventSourceHandle, int aManagerHandle); +} + +// End of file