1 /*

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

    15 *

    16 */

    17 

    18 

    19 #ifndef JAVASTORAGE_H

    20 #define JAVASTORAGE_H

    21 

    22 #include <stdio.h>

    23 #include <string>

    24 #include <set>

    25 #include <list>

    26 

    27 #include "javaosheaders.h"

    28 #include "javastorageentry.h"

    29 #include "javastorageexception.h"

    30 

    31 namespace java

    32 {

    33 namespace util

    34 {

    35 class Uid;

    36 } // end namespace util

    37 namespace storage

    38 {

    39 

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

    41 typedef std::multiset<JavaStorageEntry> JavaStorageApplicationEntry_t;

    42 

    43 /**

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

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

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

    47  * without transactions but integrity is not provided that way.

    48  *

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

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

    51  * must have own storage session.

    52  */

    53 class JavaStorage

    54 {

    55 public:

    56 

    57     virtual ~JavaStorage() {}

    58 

    59     /**

    60      * Create API instance.

    61      *

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

    63      */

    64     OS_IMPORT static JavaStorage* createInstance();

    65 

    66     /**

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

    68      *

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

    70      *                     otherwise storage name.

    71      * @throws JavaStorageException with following error codes:

    72      *             EInvalidStorage: Storage name is invalid.

    73      *             EInternalError: Session creation failed.

    74      *         Storage error codes if storage handling fails. Codes are

    75      *         dependant on underlying storage component.

    76      */

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

    78     throw(JavaStorageException) = 0;

    79 

    80     /**

    81      * Open connection to default Java storage.

    82      *

    83      * @throws JavaStorageException with following error codes:

    84      *             EInvalidStorage: Storage name is invalid.

    85      *             EInternalError: Session creation failed.

    86      *         Storage error codes if storage handling fails. Codes are

    87      *         dependant on underlying storage component.

    88      */

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

    90 

    91     /**

    92      * Close JavaStorage and free its resources.

    93      *

    94      * @throws JavaStorageException with following error codes:

    95      *         Storage error codes if storage handling fails. Codes are

    96      *         dependant on underlying storage component.

    97      */

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

    99 

   100     /**

   101      * Start transaction.

   102      * Starting transaction aquires exlusive lock to underlying storage

   103      * component. It means other connections cannot alter storage data

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

   105      * reading is possible while lock is on.

   106      *

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

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

   109      * that transaction is not started at all.

   110      *

   111      * @throws JavaStorageException with following error codes:

   112      *         Storage error codes if storage handling fails. Codes are

   113      *         dependant on underlying storage component.

   114      */

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

   116 

   117     /**

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

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

   120      * and lock is released.

   121      *

   122      * @throws JavaStorageException with following error codes:

   123      *         Storage error codes if storage handling fails. Codes are

   124      *         dependant on underlying storage component.

   125      */

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

   127 

   128     /**

   129      * Rollback changes from storage. After rollback data is retained

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

   131      *

   132      * @throws JavaStorageException with following error codes:

   133      *         Storage error codes if storage handling fails. Codes are

   134      *         dependant on underlying storage component.

   135      */

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

   137 

   138     /**

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

   140      * on given table are returned.

   141      *

   142      * @param aTablename table where entries are read.

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

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

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

   146      * @throws JavaStorageException with following error codes:

   147      *             EInvalidConnection: Connection is not open.

   148      *             EInvalidArgument: Read argument is invalid.

   149      *         Storage error codes if storage handling fails. Codes are

   150      *         dependant on underlying storage component.

   151      */

   152     virtual void read(

   153         const std::string& aTablename,

   154         const java::util::Uid& aUid,

   155         JavaStorageApplicationEntry_t& aEntries

   156     ) throw(JavaStorageException) = 0;

   157 

   158     /**

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

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

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

   162      *

   163      * @param aTablename table where entries are written.

   164      * @param aEntries entries to be written.

   165      * @throws JavaStorageException with following error codes:

   166      *             EInvalidConnection: Connection is not open.

   167      *             EInvalidArgument: Read argument is invalid.

   168      *         Storage error codes if storage handling fails. Codes are

   169      *         dependant on underlying storage component.

   170      */

   171     virtual void write(

   172         const std::string& aTablename,

   173         const JavaStorageApplicationEntry_t& aEntries

   174     ) throw(JavaStorageException) = 0;

   175 

   176     /**

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

   178      * table update must be used instead of write.

   179      *

   180      * @param aTablename table where entries are updated.

   181      * @param aUpdateEntry entries to be updated.

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

   183      *                    this contains only ID.

   184      * @throws JavaStorageException with following error codes:

   185      *             EInvalidConnection: Connection is not open.

   186      *             EInvalidArgument: If given arguments are empty.

   187      *         Storage error codes if storage handling fails. Codes are

   188      *         dependant on underlying storage component.

   189      */

   190     virtual void update(

   191         const std::string& aTablename,

   192         const JavaStorageApplicationEntry_t& aUpdateEntry,

   193         const JavaStorageApplicationEntry_t& aMatchEntry

   194     ) throw(JavaStorageException) = 0;

   195 

   196     /**

   197      * Search entries from storage.

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

   199      *

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

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

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

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

   204      *

   205      * @code

   206      * JavaStorageEntry attr;

   207      * JavaStorageApplicationEntry_t query;

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

   209      * query.insert(attr);

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

   211      * query.insert(attr);

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

   213      * query.insert(attr);

   214      * ...

   215      * @endcode

   216      *

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

   218      * specific security domain. This case query contains entry name

   219      * like SECURITY_DOMAIN with intrested security domain value. All

   220      * applications belogning to given security domain with all entries

   221      * are returned.<br>

   222      *

   223      * @code

   224      * JavaStorageEntry attr;

   225      * JavaStorageApplicationEntry_t query;

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

   227      * query.insert(attr);

   228      * ...

   229      * @endcode

   230      *

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

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

   233      * VENDOR and VERSION without values. To match certain

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

   235      * all defined entries of all table applications are returned

   236      * without possibility to identify which application they belong to.

   237      *

   238      * @code

   239      * JavaStorageEntry attr;

   240      * JavaStorageApplicationEntry_t query;

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

   242      * query.insert(attr);

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

   244      * query.insert(attr);

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

   246      * @endcode

   247      *

   248      * @param aTablename table where entries are searched.

   249      * @param[in] aSearchQuery to mach entries.

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

   251      *             JavaApplicationEntry_t objects that contain

   252      *             JavaStorageEntries depending on search.

   253      * @throws JavaStorageException with following error codes:

   254      *             EInvalidConnection: Connection is not open.

   255      *             EInvalidArgument: Read argument is invalid.

   256      *         Storage error codes if storage handling fails. Codes are

   257      *         dependant on underlying storage component.

   258      */

   259     virtual void search(

   260         const std::string& aTablename,

   261         const JavaStorageApplicationEntry_t& aSearchQuery,

   262         JavaStorageApplicationList_t& aApplicationList

   263     ) throw(JavaStorageException) = 0;

   264 

   265     /**

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

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

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

   269      * deletion.

   270      *

   271      * @param aTablename table where entries are removed.

   272      * @param aRemovePattern pattern to search removed entries.

   273      * @throws JavaStorageException with following error codes:

   274      *             EInvalidConnection: Connection is not open.

   275      *             EInvalidArgument: Read argument is invalid.

   276      *             EInvalidDataStructure: Query contains invalid entry.

   277      *         Storage error codes if storage handling fails. Codes are

   278      *         dependant on underlying storage component.

   279      */

   280     virtual int remove(

   281         const std::string& aTablename,

   282         const JavaStorageApplicationEntry_t& aRemoveQuery)

   283     throw(JavaStorageException) = 0;

   284 

   285     /**

   286      * Create storage table.

   287      *

   288      * @param aTablename table name.

   289      * @param aTableColumns table structure to be created.

   290      * @throws JavaStorageException with following error codes:

   291      *             EInvalidConnection: Connection is not open.

   292      *             EInvalidArgument: Read argument is invalid.

   293      *             EInvalidDataStructure: Query contains invalid entry.

   294      *         Storage error codes if storage handling fails. Codes are

   295      *         dependant on underlying storage component.

   296      */

   297     virtual void createTable(

   298         const std::string& aTablename,

   299         const JavaStorageApplicationEntry_t& aTableColumns

   300     ) throw(JavaStorageException) = 0;

   301 

   302     /**

   303      * Append column to existing storage table.

   304      *

   305      * @param aTablename table name.

   306      * @param aTableColumns table structure to be appended.

   307      * @throws JavaStorageException with following error codes:

   308      *             EInvalidConnection: Connection is not open.

   309      *             EInvalidArgument: Read argument is invalid.

   310      *             EInvalidDataStructure: Query contains invalid entry.

   311      *         Storage error codes if storage handling fails. Codes are

   312      *         dependant on underlying storage component.

   313      */

   314     virtual void appendTable(

   315         const std::string& aTablename,

   316         const JavaStorageApplicationEntry_t& aTableColumns

   317     ) throw(JavaStorageException) = 0;

   318 

   319 };

   320 

   321 } // end namespace storage

   322 } // end namespace java

   323 

   324 #endif // JAVASTORAGE_H