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


package com.nokia.mj.impl.storage;

import com.nokia.mj.impl.utils.Uid;

/**
 * StorageSession 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.
 */
public interface StorageSession
{
    /*** ----------------------------- PUBLIC ------------------------------ */

    /**
     * Open storage connection. If storage does not exists creates it.
     * 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.
     *
     * @param aStorageName Full path to storage if not predefined storage used
     *                     otherwise storage name.
     * @throws StorageException if open fails or invalid storage name.
     */
    public void open(String aStorageName) throws StorageException;

    /**
     * Open session to default storage.
     * 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.
     *
     * @throws StorageException if open fails.
     */
    public void open() throws StorageException;

    /**
     * Close session connection. If transaction is open it will be rollbacked.
     *
     * @throws StorageException if closing fails.
     */
    public void close() throws StorageException;

    /**
     * Free reserved resources. This must be called before StorageSession
     * object goes out of the context.
     */
    public void destroySession();

    /**
     * Start transaction. Transactions must be as short as possible to prevent
     * other clients starving. Transaction must be started immediately before
     * storage data is altered. Other clients can perform reads from
     * storage while other client is having transaction.
     *
     * @throws StorageException if communication fails.
     */
    public void startTransaction() throws StorageException;

    /**
     * Commit transaction. After commit data is written to physical storage
     * as soon as it is possible. Changes become visible to other clients.
     *
     * @throws StorageException if communication fails.
     */
    public void commitTransaction() throws StorageException;

    /**
     * Rollback changes from storage. After rollback data is retained
     * as soon as it is possible.
     *
     * @throws StorageException if communication fails.
     */
    public void rollbackTransaction() throws StorageException;

    /**
     * Read storage entries from storage.
     * If subset of data needs to be read search must be used. This returns
     * exactly one entry.
     *
     * It is recommended to use readEntry without transaction.
     *
     * @param aTablename table where entries are read.
     * @param aUid key used to identify entries to be read.
     * @return StorageEntry entries read from storage.
     *                 Null if no entry.
     * @see StorageSession#search
     * @see StorageSession#readEntries
     * @throws StorageException if table does not exist or communication fails.
     */
    public StorageEntry readEntry(String aTablename, Uid aUid)
    throws StorageException;

    /**
     * Read all entries having same UID.
     *
     * It is recommended to use readEntries without transaction.
     *
     * @return array of storage entries. Null if no entries.
     * @throws StorageException if table does not exist or communication fails.
     */
    public StorageEntry[] readEntries(String aTablename, Uid aUid)
    throws StorageException;

    /**
     * Search entries from storage.
     * Query is used to search entries based on attributes. All attributes of
     * the maching entries are returned.<br>
     * Example1: Query can be used to search application identifier (UID) based on
     * application name and vendor pair. For this case StorageEntry must define
     * name, vendor and their values.<br>
     * Example2: Query can be used to search all applications that are bound to
     * specific security domain. For this case StorateEntry must define only
     * attribute names without their values.<br>
     *
     * To define which parameters are returned they must be added to query
     * without value.
     *
     * It is recommended to use readEntry without transaction.
     *
     * @param aTablename table where entries are searched.
     * @param aSearchQuery to be used in search.
     * @return array containing all matching StorageEntry entries.
     *         Null if none.
     * @throws StorageException if table does not exist, communication fails or
     *         invalid search query.
     */
    public StorageEntry[] search(String aTablename, StorageEntry aSearchQuery)
    throws StorageException;

    /**
     * Write storage entry. Data can be written with or without transaction.
     * If write is executed without transaction storage will do autocommit and
     * data is visible to all clients after performing write call.
     * If transaction is used data becomes visible to other clients after
     * committing transaction.
     *
     * @param aTablename table where entry is written.
     * @param aEntry to be written.
     * @see StorageSession#update
     * @throws StorageException if table does not exist, communication fails,
     *         invalid entry or entry exists.
     */
    public void write(String aTablename, StorageEntry aEntry)
    throws StorageException;

    /**
     * Update storage entry. If application has already entry in the storage
     * table update must be used instead of write. Update entry contains
     * StorageAttributes to be updated whereas match entry defines entries
     * to be updated.
     *
     * Data can be updated with or without transaction. If update is executed
     * without transaction storage will do autocommit and data is visible
     * to all clients after performing the call. If transaction is used data
     * becomes visible to other clients after committing transaction.
     *
     * @param aTablename table where entry is updated.
     * @param aUpdateEntry updated attributes.
     * @param aMatchEntry used to match entries to be updated.
     * @see StorageSession#write
     * @throws StorageException if table does not exist, communication fails or
     *         invalid entry.
     */
    public void update(String aTablename,
                       StorageEntry aUpdateEntry,
                       StorageEntry aMatchEntry)
    throws StorageException;

    /**
     * Remove entries from storage. All entries by given Uid are removed
     * from given table. If one column must be deleted instead of row update
     * must be done. StorageAttribute type must be null and type also set as
     * NULL_TYPE.
     *
     * Data can be removed with or without transaction. If remove is executed
     * without transaction storage will do autocommit and removal is visible
     * to all clients after performing the call. If transaction is used removal
     * becomes visible to other clients after committing transaction.
     *
     * @param aTablename table where entries are removed.
     * @param aUid key used to identify entries to be removed.
     * @return number of removed entries. -1 if problems occurred.
     * @throws StorageException if table does not exist, communication fails or
     *         invalid entry.
     */
    public int remove(String aTablename, Uid aUid)
    throws StorageException;

    /**
     * Remove entries from storage. All entries matching to StorageEntry are
     * removed from given table. Whole table contents can be removed by
     * calling remove with empty StorageEntry.
     *
     * Data can be removed with or without transaction. If remove is executed
     * without transaction storage will do autocommit and removal is visible
     * to all clients after performing the call. If transaction is used removal
     * becomes visible to other clients after committing transaction.
     *
     * @param aTablename table where entries are removed.
     * @param aEntry used to search removed entries.
     * @return number of removed entries. -1 if problems occurred.
     * @throws StorageException if table does not exist, communication fails or
     *         invalid entry.
     */
    public int remove(String aTablename, StorageEntry aEntry)
    throws StorageException;

    /**
     * Create storage table. PrimaryKey is created automatically by the
     * first StorageAttribute of the StorageEntry. If StorageAttribute
     * type is not set column type is defaultly set as VARCHAR.
     *
     * @param aTablename table name to be created.
     * @param aTableColumns table structure to be created.
     * @param aPrimaryKey primary key for the table. Leave null
     *                    if not needed.
     * @throws StorageException if communication fails or
     *         table structure is invalid.
     */
    public void createTable(String aTablename,
                            StorageEntry aTableColumns,
                            StorageAttribute aPrimaryKey)
    throws StorageException;

    /**
     * Append column to existing storage table. If StorageAttribute
     * type is not defined column is marked as default ie. VARCHAR.
     *
     * @param aTablename table name.
     * @param aTableColumns table structure to be appended.
     * @throws StorageException if table does not exist, communication fails or
     *         appended table structure is invalid.
     */
    public void appendTable(String aTablename, StorageEntry aTableColumns)
    throws StorageException;

    /*** ---------------------------- PROTECTED --------------------------- */
    /*** ----------------------------- PACKAGE ---------------------------- */
    /*** ----------------------------- PRIVATE ---------------------------- */
    /*** ----------------------------- NATIVE ----------------------------- */
}