1 /*

     2 * Copyright (c) 2008 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:  Base class for CommDB Tables.

    15  *

    16 */

    17 

    18 package com.nokia.mid.iapinfo;

    19 

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

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

    22 

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

    24 

    25 /**

    26  * <p>

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

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

    29  * The possible data operations are the followings:

    30  * <ul>

    31  * <li>list the records of a given table

    32  * <li>find a record by its name

    33  * <li>find a record by its record ID

    34  * </ul>

    35  * <p>

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

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

    38  * <br>

    39  *

    40  *

    41  */

    42 abstract class CommsTable

    43 {

    44 

    45     /*

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

    47      */

    48 

    49     /**

    50      * Unique identifier for the record;

    51      */

    52     public int iRecordId;

    53 

    54     /**

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

    56      */

    57     public int iRecordTag;

    58 

    59     /**

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

    61      */

    62     public String iRecordName;

    63 

    64     /**

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

    66      */

    67     public static final int ERROR_NONE = 0;

    68 

    69     /**

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

    71      */

    72     public static final int ERROR_OPEN_FAILED = -1;

    73 

    74     /**

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

    76      * would require an open table.

    77      */

    78     public static final int ERROR_TABLE_CLOSED = -2;

    79 

    80     /**

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

    82      * not found.

    83      */

    84     public static final int RECORD_NOT_FOUND = -3;

    85 

    86     /**

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

    88      */

    89     public static final int ERROR_INVALID_PARAMETER = -4;

    90 

    91     /**

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

    93      * values are not filled correctly.

    94      */

    95     public static final int ERROR_TABLE_READ = -5;

    96 

    97     /**

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

    99      */

   100     public static final int ERROR_TABLE_END = -6;

   101 

   102     protected String iTableName = "";

   103 

   104     protected static final String TABLE_IAP = "IAP";

   105 

   106     protected static final String TABLE_CONNECTION_PREFERENCES = "ConnectionPreferences";

   107 

   108     protected static final String TABLE_NETWORK = "Network";

   109 

   110     protected static final String TABLE_GLOBALSETTINGS = "GlobalSettings";

   111 

   112     /*

   113      * Handle for native peer.

   114      */

   115     private int iHandle;

   116 

   117     private int state = UNKNOWN;

   118 

   119     private static final int UNKNOWN = -1;

   120 

   121     private static final int CREATED = 0;

   122 

   123     private static final int CLOSED = 1;

   124 

   125     private static final int OPENED = 2;

   126 

   127     private Finalizer iFinalizer;

   128 

   129     public CommsTable(String tableName) throws CommDBException

   130     {

   131 

   132         iTableName = tableName;

   133 

   134         // create native peer

   135         iHandle = _construct();

   136         if (iHandle < NativeError.KErrNone)

   137         {

   138             throw new CommDBException("Native constructor failed!", ERROR_NONE,

   139                                       iHandle);

   140         }

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

   142         iFinalizer = createFinalizer();

   143         state = CREATED;

   144     }

   145 

   146     /**

   147      * Opens the corresponding CommDB table.

   148      */

   149     public void open() throws CommDBException

   150     {

   151 

   152         int err = _open(iHandle, iTableName);

   153         if (NativeError.KErrNone == err)

   154         {

   155             state = OPENED;

   156             readFieldValues();

   157         }

   158         else

   159         {

   160             throw new CommDBException("Open failed!", ERROR_OPEN_FAILED, err);

   161         }

   162 

   163     }

   164 

   165     /**

   166      * Close the actual table and release associated resources.

   167      */

   168     public void close()

   169     {// throws CommDBException

   170         state = CLOSED;

   171         _close(iHandle);

   172         clearFieldValues();

   173     }

   174 

   175     /**

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

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

   178      * this record.

   179      *

   180      * @param recordName name of the record

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

   182      *         no record found with the given name.

   183      */

   184     public int findByName(String recordName) throws CommDBException

   185     {

   186 

   187         int rec = 0;

   188         rec = _findByName(iHandle, recordName);

   189         if (rec >= 0)

   190         {

   191             readFieldValues();

   192         }

   193         else

   194         {

   195             return RECORD_NOT_FOUND;

   196         }

   197         return rec;

   198 

   199     }

   200 

   201     /**

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

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

   204      *

   205      * @param id RecordId of the record

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

   207      *         no record found with the given RecordId.

   208      */

   209     public int findById(int id) throws CommDBException

   210     {

   211 

   212         int rec = 0;

   213 

   214         rec = _findById(iHandle, id);

   215         if (rec >= 0)

   216         {

   217             readFieldValues();

   218         }

   219         else

   220         {

   221             return RECORD_NOT_FOUND;

   222         }

   223         return rec;

   224     }

   225 

   226     /**

   227      * Retreives the number of records in the current table.

   228      *

   229      * @return with the number of records

   230      */

   231     public int getRecordCount() throws CommDBException

   232     {

   233         return _getRecordCount(iHandle);

   234     }

   235 

   236     /**

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

   238      * CommDBException when the current record is the last record.

   239      */

   240     public void nextRecord() throws CommDBException

   241     {

   242 

   243         int ret = _next(iHandle);

   244         if (NativeError.KErrEof == ret)

   245         {

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

   247         }

   248         readFieldValues();

   249     }

   250 

   251     /**

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

   253      * CommDBException when the current record is the first record.

   254      */

   255     public void previousRecord() throws CommDBException

   256     {

   257         int ret = _previous(iHandle);

   258         if (NativeError.KErrEof == ret)

   259         {

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

   261         }

   262         readFieldValues();

   263     }

   264 

   265     /*

   266      * Read field values of the current record.

   267      */

   268     abstract protected void readFieldValues() throws CommDBException;

   269 

   270     /*

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

   272      */

   273     abstract protected void clearFieldValues();

   274 

   275     protected int readIntFieldValue(String fieldName) throws CommDBException

   276     {

   277 

   278         // Retreive native error code if any

   279         int[] error = new int[1];

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

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

   282         {

   283             clearFieldValues();

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

   285                                       ERROR_TABLE_READ, error[0]);

   286         }

   287         return value;

   288     }

   289 

   290     protected String readStringFieldValue(String fieldName)

   291     throws CommDBException

   292     {

   293 

   294         // Retreive native error code if any

   295         int[] error = new int[1];

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

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

   298         {

   299             clearFieldValues();

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

   301                                       ERROR_TABLE_READ, error[0]);

   302         }

   303         return value;

   304     }

   305 

   306     Finalizer createFinalizer()

   307     {

   308         // Logger.LOG(Logger.ESOCKET,

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

   310         return new Finalizer()

   311         {

   312             public void finalizeImpl()

   313             {

   314                 doFinalize();

   315             }

   316         };

   317     }

   318     // Gets called when the object is garbage collected

   319     public void doFinalize()

   320     {

   321         // Logger.LOG(Logger.ESOCKET,

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

   323         _destroy(iHandle);

   324     }

   325     /*----------------------------------------------------------------*/

   326     /* Native funcions */

   327     /*----------------------------------------------------------------*/

   328     /*

   329      * Creates native peer.

   330      *

   331      * @return handle for native peer

   332      */

   333     private static native int _construct();

   334 

   335     /*

   336      * Destructs native peer.

   337      *

   338      * @param aHandle - handle for native peer

   339      */

   340     private static native void _destroy(int aHandle);

   341 

   342     /*

   343      * Initializes and opens the actual CommDB table for reading.

   344      *

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

   346      *

   347      * @return - error code

   348      */

   349     private static native int _open(int aHandle, String tableName);

   350 

   351     /*

   352      * Close the actual CommDB table.

   353      *

   354      * @param aHandle - handle for native peer

   355      */

   356     private static native void _close(int aHandle);

   357 

   358     /*

   359      * Retrieves the next record from the database.

   360      *

   361      * @param aHandle - handle for native peer

   362      *

   363      * @return - error code

   364      */

   365     private static native int _next(int aHandle);

   366 

   367     /*

   368      * Retrieves the next record from the database.

   369      *

   370      * @param aHandle - handle for native peer

   371      *

   372      * @return - error code

   373      */

   374     private static native int _previous(int aHandle);

   375 

   376     /*

   377      * Retrieves the record count from the database.

   378      *

   379      * @param aHandle - handle for native peer

   380      *

   381      * @return - number of records in the current table

   382      */

   383     private static native int _getRecordCount(int aHandle);

   384 

   385     /*

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

   387      *

   388      * @param recordName - the name of the record.

   389      *

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

   391      */

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

   393 

   394     /*

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

   396      *

   397      * @param id - the ID of the record.

   398      *

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

   400      */

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

   402 

   403     /*

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

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

   406      * member variable in the appropriate class.

   407      *

   408      * @param aHandle - handle for native peer

   409      *

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

   411      *

   412      * @param aError - array for native error code

   413      *

   414      * @return - integer field value

   415      */

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

   417             int[] aError);

   418 

   419     /*

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

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

   422      * member variable in the appropriate class.

   423      *

   424      * @param aHandle - handle for native peer

   425      *

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

   427      *

   428      * @param aError - array for native error code

   429      *

   430      * @return - string field value

   431      */

   432     private static native String _readStringFieldValue(int aHandle,

   433             String fieldName, int[] aError);

   434 

   435 }