/*

* 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

     */

    {

        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

     */

    {

        // 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