/*

* Copyright (c) 2008-2009 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:  JavaStorage

*

*/

#ifndef JAVASTORAGE_H

#define JAVASTORAGE_H

#include <stdio.h>

#include <string>

#include <set>

#include <list>

#include "javaosheaders.h"

#include "javastorageentry.h"

#include "javastorageexception.h"

namespace java

{

namespace util

{

class Uid;

} // end namespace util

namespace storage

{

typedef std::list<std::multiset<java::storage::JavaStorageEntry> > JavaStorageApplicationList_t;

typedef std::multiset<JavaStorageEntry> JavaStorageApplicationEntry_t;

/**

 * JavaStorage provides access to Java platform data. Through this API

 * Java platform related data can be read and manipulated. It provides

 * transactions to enable integrity. However all operations can be executed

 * without transactions but integrity is not provided that way.

 *

 * API is single threaded i.e. same session cannot be shared between threads

 * or processes. If the session is used in multithreaded system each thread

 * must have own storage session.

 */

class JavaStorage

{

public:

    virtual ~JavaStorage() {}

    /**

     * Create API instance.

     *

     * @return Instance to JavaStorage API. Ownership is transfered to caller.

     */

    OS_IMPORT static JavaStorage* createInstance();

    /**

     * Open storage connection. If storage does not exist creates it.

     *

     * @param aStorageName Full path to storage if not predefined storage used

     *                     otherwise storage name.

     * @throws JavaStorageException with following error codes:

     *             EInvalidStorage: Storage name is invalid.

     *             EInternalError: Session creation failed.

     *         Storage error codes if storage handling fails. Codes are

     *         dependant on underlying storage component.

     */

    virtual void open(const std::string& aStorageName)

    throw(JavaStorageException) = 0;

    /**

     * Open connection to default Java storage.

     *

     * @throws JavaStorageException with following error codes:

     *             EInvalidStorage: Storage name is invalid.

     *             EInternalError: Session creation failed.

     *         Storage error codes if storage handling fails. Codes are

     *         dependant on underlying storage component.

     */

    virtual void open() throw(JavaStorageException) = 0;

    /**

     * Close JavaStorage and free its resources.

     *

     * @throws JavaStorageException with following error codes:

     *         Storage error codes if storage handling fails. Codes are

     *         dependant on underlying storage component.

     */

    virtual void close() throw(JavaStorageException) = 0;

    /**

     * Start transaction.

     * Starting transaction aquires exlusive lock to underlying storage

     * component. It means other connections cannot alter storage data

     * until lock is released. Lock is storage not table specific. Data

     * reading is possible while lock is on.

     *

     * For this reason transaction should be as short as possible. It

     * should be considered if storage connection is used only for reading

     * that transaction is not started at all.

     *

     * @throws JavaStorageException with following error codes:

     *         Storage error codes if storage handling fails. Codes are

     *         dependant on underlying storage component.

     */

    virtual void startTransaction() throw(JavaStorageException) = 0;

    /**

     * Commit transaction. After commit data is written to physical storage

     * as soon as it is possible. Data becomes visible to other clients

     * and lock is released.

     *

     * @throws JavaStorageException with following error codes:

     *         Storage error codes if storage handling fails. Codes are

     *         dependant on underlying storage component.

     */

    virtual void commitTransaction() throw(JavaStorageException) = 0;

    /**

     * Rollback changes from storage. After rollback data is retained

     * as soon as it is possible and lock is released.

     *

     * @throws JavaStorageException with following error codes:

     *         Storage error codes if storage handling fails. Codes are

     *         dependant on underlying storage component.

     */

    virtual void rollbackTransaction() throw(JavaStorageException) = 0;

    /**

     * Read storage entries from storage. All entries belogning to Uid

     * on given table are returned.

     *

     * @param aTablename table where entries are read.

     * @param aUid used to identify entries to be read.

     * @param[out] aEntries entries container that is populated by read

     *             entries. Container is left empty if no data read.

     * @throws JavaStorageException with following error codes:

     *             EInvalidConnection: Connection is not open.

     *             EInvalidArgument: Read argument is invalid.

     *         Storage error codes if storage handling fails. Codes are

     *         dependant on underlying storage component.

     */

    virtual void read(

        const std::string& aTablename,

        const java::util::Uid& aUid,

        JavaStorageApplicationEntry_t& aEntries

    ) throw(JavaStorageException) = 0;

    /**

     * Write storage entries. Entries are written to given table and

     * they're identified by given Uid. If table contains entry sharing same

     * primary key write fails. Use update to update these entries.

     *

     * @param aTablename table where entries are written.

     * @param aEntries entries to be written.

     * @throws JavaStorageException with following error codes:

     *             EInvalidConnection: Connection is not open.

     *             EInvalidArgument: Read argument is invalid.

     *         Storage error codes if storage handling fails. Codes are

     *         dependant on underlying storage component.

     */

    virtual void write(

        const std::string& aTablename,

        const JavaStorageApplicationEntry_t& aEntries

    ) throw(JavaStorageException) = 0;

    /**

     * Update storage entries. If application has already entry in the storage

     * table update must be used instead of write.

     *

     * @param aTablename table where entries are updated.

     * @param aUpdateEntry entries to be updated.

     * @param aMatchEntry is used to identify which entries are updated. Usually

     *                    this contains only ID.

     * @throws JavaStorageException with following error codes:

     *             EInvalidConnection: Connection is not open.

     *             EInvalidArgument: If given arguments are empty.

     *         Storage error codes if storage handling fails. Codes are

     *         dependant on underlying storage component.

     */

    virtual void update(

        const std::string& aTablename,

        const JavaStorageApplicationEntry_t& aUpdateEntry,

        const JavaStorageApplicationEntry_t& aMatchEntry

    ) throw(JavaStorageException) = 0;

    /**

     * Search entries from storage.

     * Query is used to search entries based on table attributes.<br>

     *

     * Example1: It can be used to search application Uid based on

     * application name and vendor pair. This case search query defines

     * NAME and VENDOR with their values. Result contain all matching

     * applications in given table. All application entries are returned.<br>

     *

     * @code

     * JavaStorageEntry attr;

     * JavaStorageApplicationEntry_t query;

     * attr.setEntry(NAME, L"MyName"); // Match item.

     * query.insert(attr);

     * attr.setEntry(VENDOR, L"MyVendor"); // Match item.

     * query.insert(attr);

     * attr.setEntry(ID, L""); // Fecth item.

     * query.insert(attr);

     * ...

     * @endcode

     *

     * Example2: It can be used to search all applications that are bound to

     * specific security domain. This case query contains entry name

     * like SECURITY_DOMAIN with intrested security domain value. All

     * applications belogning to given security domain with all entries

     * are returned.<br>

     *

     * @code

     * JavaStorageEntry attr;

     * JavaStorageApplicationEntry_t query;

     * attr.setEntry(SECYRITY_DOMAIN, L"MyDomain"); // Match item

     * query.insert(attr);

     * ...

     * @endcode

     *

     * Example3: It can be used to read only subset of application entries.

     * For this case only subset of entries is defined like PACKAGE_NAME,

     * VENDOR and VERSION without values. To match certain

     * application for instance ID must be specified with value. Otherwise

     * all defined entries of all table applications are returned

     * without possibility to identify which application they belong to.

     *

     * @code

     * JavaStorageEntry attr;

     * JavaStorageApplicationEntry_t query;

     * attr.setEntry(ID, L""); // Fetch item.

     * query.insert(attr);

     * attr.setEntry(NAME, L""); // Fetch item.

     * query.insert(attr);

     * ...  // No match item specified, fecthing all entries.

     * @endcode

     *

     * @param aTablename table where entries are searched.

     * @param[in] aSearchQuery to mach entries.

     * @param[out] aApplicationList matching applications. List contain

     *             JavaApplicationEntry_t objects that contain

     *             JavaStorageEntries depending on search.

     * @throws JavaStorageException with following error codes:

     *             EInvalidConnection: Connection is not open.

     *             EInvalidArgument: Read argument is invalid.

     *         Storage error codes if storage handling fails. Codes are

     *         dependant on underlying storage component.

     */

    virtual void search(

        const std::string& aTablename,

        const JavaStorageApplicationEntry_t& aSearchQuery,

        JavaStorageApplicationList_t& aApplicationList

    ) throw(JavaStorageException) = 0;

    /**

     * Remove entries from storage. All information of matching entries are

     * removed from the table. <br>If part of the entries need to be ramoved

     * update must be used. Update entries as null which represents same as

     * deletion.

     *

     * @param aTablename table where entries are removed.

     * @param aRemovePattern pattern to search removed entries.

     * @throws JavaStorageException with following error codes:

     *             EInvalidConnection: Connection is not open.

     *             EInvalidArgument: Read argument is invalid.

     *             EInvalidDataStructure: Query contains invalid entry.

     *         Storage error codes if storage handling fails. Codes are

     *         dependant on underlying storage component.

     */

    virtual int remove(

        const std::string& aTablename,

        const JavaStorageApplicationEntry_t& aRemoveQuery)

    throw(JavaStorageException) = 0;

    /**

     * Create storage table.

     *

     * @param aTablename table name.

     * @param aTableColumns table structure to be created.

     * @throws JavaStorageException with following error codes:

     *             EInvalidConnection: Connection is not open.

     *             EInvalidArgument: Read argument is invalid.

     *             EInvalidDataStructure: Query contains invalid entry.

     *         Storage error codes if storage handling fails. Codes are

     *         dependant on underlying storage component.

     */

    virtual void createTable(

        const std::string& aTablename,

        const JavaStorageApplicationEntry_t& aTableColumns

    ) throw(JavaStorageException) = 0;

    /**

     * Append column to existing storage table.

     *

     * @param aTablename table name.

     * @param aTableColumns table structure to be appended.

     * @throws JavaStorageException with following error codes:

     *             EInvalidConnection: Connection is not open.

     *             EInvalidArgument: Read argument is invalid.

     *             EInvalidDataStructure: Query contains invalid entry.

     *         Storage error codes if storage handling fails. Codes are

     *         dependant on underlying storage component.

     */

    virtual void appendTable(

        const std::string& aTablename,

        const JavaStorageApplicationEntry_t& aTableColumns

    ) throw(JavaStorageException) = 0;

};

} // end namespace storage

} // end namespace java

#endif // JAVASTORAGE_H