/*

* 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:  Base class for CommDB Tables.

 *

*/

package com.nokia.mid.iapinfo;

import com.nokia.mj.impl.rt.support.Finalizer;

import com.nokia.mj.impl.gcf.utils.NativeError;

//import com.nokia.mj.impl.vmport.VmPort;

/**

 * <p>

 * Base class for <B>CommDB</B> tables. The descendant tables are defining the

 * CommDB data structure through their public member variables.<br>

 * The possible data operations are the followings:

 * <ul>

 * <li>list the records of a given table

 * <li>find a record by its name

 * <li>find a record by its record ID

 * </ul>

 * <p>

 * Before the user can access the actual table has to be opened with the

 * <CODE>open()</CODE> function of the current descendant table implementation.

 * <br>

 *

 *

 */

abstract class CommsTable

{

    /*

     * static { VmPort.getInstance().enableFinalization(CommsTable.class); }

     */

    /**

     * Unique identifier for the record;

     */

    public int iRecordId;

    /**

     * User-defined numeric tag for this record. Can be null.

     */

    public int iRecordTag;

    /**

     * User-defined name for this record. Should be unique in this table

     */

    public String iRecordName;

    /**

     * Error code - can be used for error code checking.

     */

    public static final int ERROR_NONE = 0;

    /**

     * Error code - indicates that the table cannot be opened.

     */

    public static final int ERROR_OPEN_FAILED = -1;

    /**

     * Error code - indicates that the table is closed but the actual operation

     * would require an open table.

     */

    public static final int ERROR_TABLE_CLOSED = -2;

    /**

     * Return value for search functions - indicates that the required record

     * not found.

     */

    public static final int RECORD_NOT_FOUND = -3;

    /**

     * Error code - indicates that the actual parameter is invalid (e.g. null).

     */

    public static final int ERROR_INVALID_PARAMETER = -4;

    /**

     * Error code - indicates that reading from the table failed and the field

     * values are not filled correctly.

     */

    public static final int ERROR_TABLE_READ = -5;

    /**

     * Error code - indicates that the end of table reached.

     */

    public static final int ERROR_TABLE_END = -6;

    protected String iTableName = "";

    protected static final String TABLE_IAP = "IAP";

    protected static final String TABLE_CONNECTION_PREFERENCES = "ConnectionPreferences";

    protected static final String TABLE_NETWORK = "Network";

    protected static final String TABLE_GLOBALSETTINGS = "GlobalSettings";

    /*

     * Handle for native peer.

     */

    private int iHandle;

    private int state = UNKNOWN;

    private static final int UNKNOWN = -1;

    private static final int CREATED = 0;

    private static final int CLOSED = 1;

    private static final int OPENED = 2;

    private Finalizer iFinalizer;

    public CommsTable(String tableName) throws CommDBException

    {

        iTableName = tableName;

        // we need this so we can do some cleanup when we are garbage collected

        iFinalizer = createFinalizer();

        state = CREATED;

    }

    /**

     * Opens the corresponding CommDB table.

     */

    {

        {

            state = OPENED;

            readFieldValues();

        }

        else

        {

        }

    }

    /**

     * Close the actual table and release associated resources.

     */

    public void close()

    {// throws CommDBException

        state = CLOSED;

        _close(iHandle);

        clearFieldValues();

    }

    /**

     * Finds a record in the current table by its name. The search is case

     * sensitive. If the record exists the current record will be changed to

     * this record.

     *

     * @param recordName name of the record

     * @return with the RecordId of the found record or with RECORD_NOT_FOUND if

     *         no record found with the given name.

     */

    public int findByName(String recordName) throws CommDBException

    {

        int rec = 0;

        rec = _findByName(iHandle, recordName);

        if (rec >= 0)

        {

            readFieldValues();

        }

        else

        {

            return RECORD_NOT_FOUND;

        }

        return rec;

    }

    /**

     * Finds a record in the current table by its record RecordId. If the record

     * exists the current record will be changed to this record.

     *

     * @param id RecordId of the record

     * @return with the RecordId of the found record or with RECORD_NOT_FOUND if

     *         no record found with the given RecordId.

     */

    public int findById(int id) throws CommDBException

    {

        int rec = 0;

        rec = _findById(iHandle, id);

        if (rec >= 0)

        {

            readFieldValues();

        }

        else

        {

            return RECORD_NOT_FOUND;

        }

        return rec;

    }

    /**

     * Retreives the number of records in the current table.

     *

     * @return with the number of records

     */

    public int getRecordCount() throws CommDBException

    {

        return _getRecordCount(iHandle);

    }

    /**

     * Retrieves data from the next record in the database. Throws

     * CommDBException when the current record is the last record.

     */

    public void nextRecord() throws CommDBException

    {

        int ret = _next(iHandle);

        if (NativeError.KErrEof == ret)

        {

            throw new CommDBException("End of table reached!", ERROR_TABLE_END);

        }

        readFieldValues();

    }

    /**

     * Retrieves data from the previous record in the database. Throws

     * CommDBException when the current record is the first record.

     */

    public void previousRecord() throws CommDBException

    {

        int ret = _previous(iHandle);

        if (NativeError.KErrEof == ret)

        {

            throw new CommDBException("End of table reached!", ERROR_TABLE_END);

        }

        readFieldValues();

    }

    /*

     * Read field values of the current record.

     */

    abstract protected void readFieldValues() throws CommDBException;

    /*

     * Sets default values for all fields in the current record.

     */

    abstract protected void clearFieldValues();

    protected int readIntFieldValue(String fieldName) throws CommDBException

    {

        // Retreive native error code if any

        int[] error = new int[1];

        int value = _readIntFieldValue(iHandle, fieldName, error);

        if (NativeError.KErrNone != error[0])

        {

            clearFieldValues();

            throw new CommDBException("Error while reading table data!",

                                      ERROR_TABLE_READ, error[0]);

        }

        return value;

    }

    protected String readStringFieldValue(String fieldName)

    throws CommDBException

    {

        // Retreive native error code if any

        int[] error = new int[1];

        String value = _readStringFieldValue(iHandle, fieldName, error);

        if (NativeError.KErrNone != error[0])

        {

            clearFieldValues();

            throw new CommDBException("Error while reading table data!",

                                      ERROR_TABLE_READ, error[0]);

        }

        return value;

    }

    Finalizer createFinalizer()

    {

        // Logger.LOG(Logger.ESOCKET,

        // Logger.EInfo,"creating a socket finalizer object ");

        return new Finalizer()

        {

            public void finalizeImpl()

            {

                doFinalize();

            }

        };

    }

    // Gets called when the object is garbage collected

    public void doFinalize()

    {

        // Logger.LOG(Logger.ESOCKET,

        // Logger.EInfo,"socket doFinalize() called :");

        _destroy(iHandle);

    }

    /*----------------------------------------------------------------*/

    /* Native funcions */

    /*----------------------------------------------------------------*/

    /*

     * Destructs native peer.

     *

     * @param aHandle - handle for native peer

     */

    private static native void _destroy(int aHandle);

    /*

     * Initializes and opens the actual CommDB table for reading.

     *

     * @param table - the name of the current table.

     *

     * @return - error code

     */

    /*

     * Close the actual CommDB table.

     *

     * @param aHandle - handle for native peer

     */

    private static native void _close(int aHandle);

    /*

     * Retrieves the next record from the database.

     *

     * @param aHandle - handle for native peer

     *

     * @return - error code

     */

    private static native int _next(int aHandle);

    /*

     * Retrieves the next record from the database.

     *

     * @param aHandle - handle for native peer

     *

     * @return - error code

     */

    private static native int _previous(int aHandle);

    /*

     * Retrieves the record count from the database.

     *

     * @param aHandle - handle for native peer

     *

     * @return - number of records in the current table

     */

    private static native int _getRecordCount(int aHandle);

    /*

     * Finds a record in the current table by its record name.

     *

     * @param recordName - the name of the record.

     *

     * @return - record ID, KErrNotFound if no record found

     */

    private static native int _findByName(int aHandle, String recordName);

    /*

     * Finds a record in the current table by its record ID.

     *

     * @param id - the ID of the record.

     *

     * @return - record ID, KErrNotFound if no record found

     */

    private static native int _findById(int aHandle, int id);

    /*

     * Retrieves the integer type field value for a given field. The values will

     * be set by the actual table descendant. All field has the corresponding

     * member variable in the appropriate class.

     *

     * @param aHandle - handle for native peer

     *

     * @param fieldName - name of the field to be read.

     *

     * @param aError - array for native error code

     *

     * @return - integer field value

     */

    private static native int _readIntFieldValue(int aHandle, String fieldName,

            int[] aError);

    /*

     * Retrieves the String type field value for a given field. The values will

     * be set by the actual table descendant. All field has the corresponding

     * member variable in the appropriate class.

     *

     * @param aHandle - handle for native peer

     *

     * @param fieldName - name of the field to be read.

     *

     * @param aError - array for native error code

     *

     * @return - string field value

     */

    private static native String _readStringFieldValue(int aHandle,

            String fieldName, int[] aError);

}