recordstore.java

有关j2me的很好的例子可以研究一下

/*
 * @(#)RecordStore.java	1.51 01/08/22
 * Copyright (c) 2000-2001 Sun Microsystems, Inc. All Rights Reserved.
 *
 * Copyright 2000 Motorola, Inc. All Rights Reserved.
 * This notice does not imply publication.
 */

package javax.microedition.rms; 

import com.sun.midp.rms.RecordStoreFile;

/**
 * A class representing a record store. A record store consists of a 
 * collection of records which will remain persistent across multiple 
 * invocations of the MIDlet. The platform is responsible for 
 * making its best effort to maintain the integrity of the 
 * MIDlet's record stores throughout the normal use of the 
 * platform, including reboots, battery changes, etc. 
 * 
 * <p>Record stores are created in platform-dependent locations,
 * which are not exposed to the MIDlets. The naming space for
 * record stores is controlled at the MIDlet suite granularity.
 * MIDlets within a MIDlet suite are allowed to create multiple
 * record stores, as long as they are each given different names.
 * When a MIDlet suite is removed from a platform all the record
 * stores associated with its MIDlets will also be removed. These
 * APIs only allow the manipulation of the MIDlet suite's own
 * record stores, and does not provide any mechanism for record
 * sharing between MIDlets in different MIDlet suites. MIDlets
 * within a MIDlet suite can access each other's record stores
 * directly.
 *
 * <p>Record store names are case sensitive and may consist of
 * any combination of up to 32 Unicode characters. 
 * Record store names must be unique within the scope of a given
 * MIDlet suite. In other words, a MIDlets within a MIDlet suite
 * are is not allowed to create more than one record store with
 * the same name, however a MIDlet in different one MIDlet suites
 * are is allowed to each have a record store with the same name
 * as a MIDlet in another MIDlet suite. In that case, the record
 * stores are still distinct and separate.
 * 
 * <p>No locking operations are provided in this API. Record store
 * implementations ensure that
 * all individual record store operations are atomic, synchronous,
 * and serialized, so no corruption will occur with multiple accesses.
 * However, if a MIDlet uses multiple threads 
 * to access a record store, it is the MIDlet's responsibility to 
 * coordinate this access or unintended consequences may result. 
 * Similarly, if a platform performs transparent synchronization of 
 * a record store, it is the platform's responsibility to enforce 
 * exclusive access to the record store between the MIDlet and 
 * synchronization engine. 
 * 
 * <p>Records are uniquely identified within a given record store by their 
 * recordId, which is an integer value. This recordId is used as the 
 * primary key for the records. The first record created in a record
 * store will have recordId equal to one (1). Each subsequent
 * record added to a RecordStore will be assigned a recordId one greater
 * than the record added before it. That is, if two records are added
 * to a record store, and the first has a recordId of 'n', the next will
 * have a recordId of 'n + 1'. MIDlets can create other indices 
 * by using the <code>RecordEnumeration</code> class. 
 * 
 * <p>This record store uses long integers for time/date stamps, in 
 * the format used by System.currentTimeMillis(). The record store 
 * is time stamped with the last time it was 
 * modified. The record store also maintains a <em>version</em>, which 
 * is an integer that is incremented for each operation that modifies 
 * the contents of the RecordStore.   These are useful 
 * for synchronization engines as well as other things. 
 *
 * @version MIDP 1.0
 * @author Jim Van Peursem
 */ 
public class RecordStore 
{
    /** pre initialized RecordStore header structure */
    private static final byte[] DB_INIT = {
	(byte)'m', (byte)'i', (byte)'d', (byte)'p', 
	(byte)'-', (byte)'r', (byte)'m', (byte)'s',
	0, 0, 0, 0, // num live records
	0, 0, 0, 0, // reserved
	0, 0, 0, 0, // version
	0, 0, 0, 1, // next record id
	0, 0, 0, 0, // first record offset
	0, 0, 0, 0, // first free-space offset
	0, 0, 0, 0, // last modified (1st half)
	0, 0, 0, 0, // last modified (2nd half)
	0, 0, 0, 0, // start of data offset
	0, 0, 0, 0  // end of data offset
    };

    /** length of the signature string in bytes */
    private static final int SIGNATURE_LENGTH = 8;
    
    /** size of a per record meta-data object */
    private static final int DB_RECORD_HEADER_LENGTH = 16;

    /** 
     * storage space allocated in multiples of <code>DB_BLOCK_SIZE</code>,
     * which can not be smaller than DB_RECORD_HEADER_LENGTH and
     * must be a multiple of DB_RECORD_HEADER_LENGTH
     */
    private static final int DB_BLOCK_SIZE = 16; 

    /** size of the buffer for compacting record store */
    private static final int DB_COMPACTBUFFER_SIZE = 64;
    
    /** cache of open RecordStore instances */
    private static java.util.Vector dbCache = new java.util.Vector(3);

    /** lock to protect static dbcache state */
    private static final Object dbCacheLock = new Object();
    
    /** name of this record store */
    private String recordStoreName;
    
    /** number of open instances of this record store */
    private int opencount;
    
    /** RecordStoreFile where this record store is stored */
    private RecordStoreFile dbraf;
    
    /** lock used to synchronize this record store */
    Object rsLock;

    /** recordListeners of this record store */
    private java.util.Vector recordListener;
    
    /** cache of record headers */
    private RecordHeaderCache recHeadCache;

    /** number of direct mapped cache entries */
    private static int CACHE_SIZE = 8;

    /** static buffer used in loading/storing RecordHeader data */
    private static byte[] recHeadBuf = new byte[DB_RECORD_HEADER_LENGTH];

    /*
     * This implementation assumes (and enforces) that there is only
     * one instance of a RecordStore object for any given database file 
     * in the file system. This assumption is enforceable when there 
     * is only one VM running, but will lead to data corruption problems
     * if multiple VM's are used to read/write into the same database.
     *
     * As a consequence of this assumption, the following database
     * attributes are read from the RecordStoreFile when the RecordStore
     * is opened, maintained in memory for performance efficiency, and
     * reflected back to the file only when necessary for the sake of
     * error resilience.
     */

    /** next record's id */
    private int dbNextRecordID = 1;
    
    /** record store version */
    private int dbVersion;	
    
    /** count of live records */
    private int dbNumLiveRecords;

    /** time record store was last modified (in milliseconds */
    private long dbLastModified;
    
    /** offset of first record */
    private int dbFirstRecordOffset;
    
    /** offset of first free block */
    private int dbFirstFreeBlockOffset; 

    /** offset of the first data block */
    private int dbDataStart = 48;

    /** offset of the last data block */
    private int dbDataEnd = 48;

    /** static buffer used in loading/storing dbState */
    private static byte[] dbState = new byte[DB_INIT.length];
	    

    /*
     * The layout of the database file is as follows:
     *
     * Bytes - Usage
     * 00-07 - Signature = 'midp-rms'
     * 08-11 - Number of live records in the database (big endian)
     * 12-15 - Reserved - Always nice to keep a few spare bits around
     * 16-19 - Database "version" - a monotonically increasing revision 
     *         number (big endian)
     * 20-23 - Next record ID to use (big endian)
     * 24-27 - First record offset (bytes from beginning of file - big endian)
     * 28-31 - First free-block offset (bytes from beginning of file - big 
     *         endian)
     * 32-39 - Last modified (64-bit long, big endian, milliseconds since 
     *         jan 1970)
     * 40-43 - Start of Data storage
     * 44-47 - End of Data storage
     * 48-xx - Record storage
     */

    /** RS_SIGNATURE offset */
    private static final int RS_SIGNATURE = 0;
    /** RS_NUM_LIVE offset */
    private static final int RS_NUM_LIVE = 8;
    /** RS_RESERVED offset */
    private static final int RS_RESERVED = 12;
    /** RS_VERSION offset */
    private static final int RS_VERSION = 16;
    /** RS_NEXT_ID offset */
    private static final int RS_NEXT_ID = 20;
    /** RS_REC_START offset */
    private static final int RS_REC_START = 24;
    /** RS_FREE_START offset */
    private static final int RS_FREE_START = 28;
    /** RS_LAST_MODIFIED offset */
    private static final int RS_LAST_MODIFIED = 32;
    /** RS_START_OF_DATA offset */
    private static final int RS_DATA_START = 40;
    /** RS_END_OF_DATA offset */
    private static final int RS_DATA_END = 44;

    /*  
     * RecordStore Constructors 
     */

    /**
     * MIDlets must use <code>openRecordStore()</code> to get 
     * a <code>RecordStore</code> object. If this constructor 
     * is not declared (as private scope), Javadoc (and Java) 
     * will assume a public constructor. 
     */ 
    private RecordStore() 
    {
    }


    /**
     * Apps must use <code>openRecordStore()</code> to get
     * a <code>RecordStore</code> object. This constructor
     * is used internally for creating RecordStore objects.
     *
     * <code>dbCacheLock</code> must be held before calling
     * this constructor.
     *
     * @param recordStoreName a string to name the record store.
     * @param create if true, create the record store if it doesn't exist.
     *
     * @exception RecordStoreException if something goes wrong setting up
     *            the new RecordStore.
     * @exception RecordStoreNotFoundException if can't find the record store
     *            and create is set to false.
     */
    
    private RecordStore(String recordStoreName, boolean create)
        throws RecordStoreException, RecordStoreNotFoundException
    {
	this.recordStoreName = recordStoreName;
	recHeadCache = new RecordHeaderCache(CACHE_SIZE);
	rsLock = new Object();
	recordListener = new java.util.Vector(3); 

	boolean exists = RecordStoreFile.exists(recordStoreName);
	
	// Check for errors between app and record store existance.
	if (!create && !exists) {
	    throw new RecordStoreNotFoundException("cannot find record " 
						   + "store file");
	}

	// Create a RecordStoreFile for storing the record store.
	try {
	    dbraf = new RecordStoreFile(recordStoreName);
	    /*
	     * At this point we've opened the RecordStoreFile.  If we
	     * created a new record store, initialize the db attributes.
	     */
	    if (create && !exists) {
		// Initialize record store attributes
		dbraf.seek(RS_SIGNATURE);
		// Update the timestamp
		RecordStore.putLong(System.currentTimeMillis(),
				    DB_INIT, RS_LAST_MODIFIED);
		RecordStore.putInt(48, DB_INIT, RS_DATA_START);
		RecordStore.putInt(48, DB_INIT, RS_DATA_END);
		dbraf.write(DB_INIT);
	    } else {
		/*
		 * Create a buffer and read the database attributes
		 * Read the record store attributes. Set up internal state.
		 */
		byte[] buf = new byte[DB_INIT.length];
		dbraf.seek(RS_SIGNATURE);
		dbraf.read(buf);
		/*
		 * Verify that the file is actually a record store
		 * by verifying the record store "signature."
		 */
		for (int i = 0; i < SIGNATURE_LENGTH; i++) {
		    if (buf[i] != DB_INIT[i])
			throw new RecordStoreException("invalid record "+
						       "store contents");
		}
		
		// Convert byte array to internal state variables.
		dbNumLiveRecords = RecordStore.getInt(buf, RS_NUM_LIVE);
		dbVersion = RecordStore.getInt(buf, RS_VERSION);
		dbNextRecordID = RecordStore.getInt(buf, RS_NEXT_ID);
		dbFirstRecordOffset = RecordStore.getInt(buf, RS_REC_START);
		dbFirstFreeBlockOffset = RecordStore.getInt(buf, 
							    RS_FREE_START);
		dbLastModified = RecordStore.getLong(buf, RS_LAST_MODIFIED);
		dbDataStart = RecordStore.getInt(buf, RS_DATA_START);
		dbDataEnd = RecordStore.getInt(buf, RS_DATA_END);
	    }

	} catch (java.io.IOException ioe) {
	    try {
		if (dbraf != null) {
		    dbraf.close();
		}
	    } catch (java.io.IOException ioe2) { 
		// ignore exception within exception block
	    } finally {
		dbraf = null;
	    }
	    throw new RecordStoreException("error opening record store " + 
					   "file");
	} 
    }

    /*
     * Public Static Methods
     */

    /**
     * Open (and possibly create) a record store associated with the 
     * given MIDlet suite. If this method is called by a MIDlet when
     * the record store is already open by a MIDlet in the MIDlet suite,
     * this method returns a reference to the same RecordStore object.
     * 
     * @param recordStoreName the MIDlet suite unique name, not to exceed
     *        32 characters, of the record store.
     * @param createIfNecessary if true, the record store will be created
     *        if necessary. 
     * 
     * @return the RecordStore object for this record store.
     * 
     * @exception RecordStoreException if a record store related exception
     *            occurred. 
     * @exception RecordStoreNotFoundException if the record store could 
     *            not be found. 
     * @exception RecordStoreFullException if the operation cannot be 
     *            completed because the record store is full. 
     */ 
    public static RecordStore openRecordStore(String recordStoreName, 
					      boolean createIfNecessary) 
        throws RecordStoreException, RecordStoreFullException, 
        RecordStoreNotFoundException 
    {
	synchronized (dbCacheLock) {

	    if (recordStoreName.length() > 32) {
		throw new RecordStoreException("record store name too long");
	    }

	    // Cache record store objects and ensure that there is only
	    // one record store object in memory for any given record
	    // store file. This is good for memory use. This is NOT safe
	    // in the situation where multiple VM's may be executing code
	    // concurrently. In that case, you have to sync things through
	    // file locking or something similar.
	    
	    // Check the record store cache for a db with the same name
	    RecordStore db;	    
	    for (int n = 0; n < dbCache.size(); n++) {
		db = (RecordStore)dbCache.elementAt(n);
		if (db.recordStoreName.equals(recordStoreName)) {
		    db.opencount++;  // times rs has been opened
		    return db;  // return ref to cached record store
		}
	    }

	    /*
	     * Record store not found in cache. Check