recordstore.java

用于移动设备上的java虚拟机源代码

/*
 * @(#)RecordStore.java	1.69 02/10/03 @(#)
 *
 * Portiona Copyright (c) 2000-2002 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. MIDlets within a MIDlet suite can
 * access each other's record stores directly. New APIs in MIDP 2.0
 * allow for the explicit sharing of record stores if the MIDlet
 * creating the RecordStore chooses to give such permission.</p>
 *
 * <p> Sharing is accomplished through the ability to name a
 * RecordStore created by another MIDlet suite.</p>
 *
 * <P> RecordStores are uniquely named using the unique name of the
 * MIDlet suite plus the name of the RecordStore. MIDlet suites are
 * identified by the MIDlet-Vendor and MIDlet-Name attributes from the
 * application descriptor.</p>
 *
 * <p> Access controls are defined when RecordStores to be shared are
 * created. Access controls are enforced when RecordStores are
 * opened. The access modes allow private use or shareable
 * with any other MIDlet suite.</p>
 *
 * <p>Record store names are case sensitive and may consist of any
 * combination of between one and 32 Unicode characters
 * inclusive. Record store names must be unique within the scope of a
 * given MIDlet suite. In other words, MIDlets within a MIDlet suite
 * are not allowed to create more than one record store with the same
 * name, however a MIDlet in one MIDlet suite is allowed to 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>
 *
 * <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>
 *
 * <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
 * sequences of the records in the RecordStore by using the
 * <code>RecordEnumeration</code> class.</p>
 *
 * <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> number, 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.</p>
 *
 * @since MIDP 1.0
 */

public class RecordStore 
{
    /*  
     * 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() {
    }

    /**
     * Deletes the named record store. MIDlet suites are only allowed
     * to delete their own record stores. If the named record store is
     * open (by a MIDlet in this suite or a MIDlet in a different
     * MIDlet suite) when this method is called, a
     * RecordStoreException will be thrown.  If the named record store
     * does not exist a RecordStoreNotFoundException will be
     * thrown. Calling this method does NOT result in recordDeleted
     * calls to any registered listeners of this RecordStore.
     *
     * @param recordStoreName the MIDlet suite unique record store to
     * 		delete
     *
     * @exception RecordStoreException if a record store-related
     * 		exception occurred
     * @exception RecordStoreNotFoundException if the record store
     * 		could not be found
     */
    public static void deleteRecordStore(String recordStoreName) 
        throws RecordStoreException, RecordStoreNotFoundException 
    {
	String uidPath = RecordStoreFile.getUniqueIdPath(recordStoreName);
        // Check the record store cache for a db with the same name
	synchronized (dbCacheLock) {
	    RecordStore db;
	    for (int n = 0; n < dbCache.size(); n++) {
		db = (RecordStore)dbCache.elementAt(n);
		if (db.uniqueIdPath.equals(uidPath)) {
		    // cannot delete an open record store
		    throw new RecordStoreException("deleteRecordStore error:"
						   + " record store is"
						   + " still open");
		}
	    }
	    // this record store is not currently open
	    if (RecordStoreFile.exists(uidPath)) {
		boolean success = RecordStoreFile.deleteFile(uidPath);
		if (!success) {
		    throw new RecordStoreException("deleteRecordStore " +
						   "failed");
		}
	    } else {
	        throw new RecordStoreNotFoundException("deleteRecordStore " +
						       "error: file " +
						       "not found"); 
	    }
	}
    }
    
    /**
     * 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 for the
     *          record store, consisting of between one and 32 Unicode
     *          characters inclusive.
     * @param createIfNecessary if true, the record store will be
     *		created if necessary
     *
     * @return <code>RecordStore</code> object for the 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
     * @exception IllegalArgumentException if
     *          recordStoreName is invalid
     */
    public static RecordStore openRecordStore(String recordStoreName, 
					      boolean createIfNecessary) 
        throws RecordStoreException, RecordStoreFullException, 
        RecordStoreNotFoundException 
    {
	String uidPath = RecordStoreFile.getUniqueIdPath(recordStoreName);
	synchronized (dbCacheLock) {

	    if (recordStoreName.length() > 32 ||
		recordStoreName.length() == 0) {
		throw new IllegalArgumentException();
	    }

	    // 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.uniqueIdPath.equals(uidPath)) {
		    db.opencount++;  // times rs has been opened
		    return db;  // return ref to cached record store
		}
	    }
	    
	    /*
	     * Record store not found in cache, so create it.
	     */
	    db = new RecordStore(uidPath, recordStoreName, createIfNecessary);

	    /*
	     * Now add the new record store to the cache
	     */
	    db.opencount = 1;
	    dbCache.addElement(db);
	    return db;
	}
    }

    /**
     * Open (and possibly create) a record store that can be shared
     * with other MIDlet suites. The RecordStore is owned by the
     * current MIDlet suite. The authorization mode is set when the
     * record store is created, as follows:
     *
     * <ul>
     * <li><code>AUTHMODE_PRIVATE</code> - Only allows the MIDlet
     *          suite that created the RecordStore to access it. This
     *          case behaves identically to
     *          <code>openRecordStore(recordStoreName,
     *          createIfNecessary)</code>.</li>
     * <li><code>AUTHMODE_ANY</code> - Allows any MIDlet to access the
     *          RecordStore. Note that this makes your recordStore
     *          accessible by any other MIDlet on the device. This
     *          could have privacy and security issues depending on
     *          the data being shared. Please use carefully.</li>
     * </ul>
     *
     * <p>The owning MIDlet suite may always access the RecordStore and
     * always has access to write and update the store.</p>
     *
     * <p> 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.</p>
     *
     * @param recordStoreName the MIDlet suite unique name for the
     *          record store, consisting of between one and 32 Unicode
     *          characters inclusive.
     * @param createIfNecessary if true, the record store will be
     * 		created if necessary
     * @param authmode the mode under which to check or create access.
     * 		Must be one of AUTHMODE_PRIVATE or AUTHMODE_ANY.
     *		This argument is ignored if the RecordStore exists.
     * @param writable true if the RecordStore is to be writable by
     *		other MIDlet suites that are granted access.
     *		This argument is ignored if the RecordStore exists.
     *
     * @return <code>RecordStore</code> object for the 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
     * @exception IllegalArgumentException if authmode or
     *          recordStoreName is invalid
     * @since MIDP 2.0
     */
    public static RecordStore openRecordStore(String recordStoreName,
					      boolean createIfNecessary,
					      int authmode,
					      boolean writable)
	throws RecordStoreException, RecordStoreFullException,
               RecordStoreNotFoundException
    {
	RecordStore rs = RecordStore.openRecordStore(recordStoreName, 
						     createIfNecessary);
	rs.setMode(authmode, writable);
	return rs;
    }
    
    /**
     * Open a record store associated with the named MIDlet suite.
     * The MIDlet suite is identified by MIDlet vendor and MIDlet
     * name.  Access is granted only if the authorization mode of the
     * RecordStore allows access by the current MIDlet suite.  Access
     * is limited by the authorization mode set when the record store
     * was created:
     *
     * <ul>
     * <li><code>AUTHMODE_PRIVATE</code> - Succeeds only if vendorName
     * 		and suiteName identify the current MIDlet suite; this
     * 		case behaves identically to
     *		<code>openRecordStore(recordStoreName,
     *		createIfNecessary)</code>.</li>
     * <li><code>AUTHMODE_ANY</code> - Always succeeds.
     *          Note that this makes your recordStore
     *          accessible by any other MIDlet on the device. This
     *          could have privacy and security issues depending on
     *          the data being shared. Please use carefully.
     *		Untrusted MIDlet suites are allowed to share data but
     *		this is not recommended. The authenticity of the
     *		origin of untrusted MIDlet suites cannot be verified
     *		so shared data may be used unscrupulously.</li>
     * </ul>
     *
     * <p> 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.</p>
     *
     * <p> If a MIDlet calls this method to open a record store from
     * its own suite, the behavior is identical to calling:
     * <code>{@link #openRecordStore(String, boolean)
     * openRecordStore(recordStoreName, false)}</code></p>
     *
     * @param recordStoreName the MIDlet suite unique name for the
     *          record store, consisting of between one and 32 Unicode
     *          characters inclusive.
     * @param vendorName the vendor of the owning MIDlet suite
     * @param suiteName the name of the MIDlet suite
     *
     * @return <code>RecordStore</code> object for the record store
     *
     * @exception RecordStoreException if a record store-related
     *		exception occurred
     * @exception RecordStoreNotFoundException if the record store
     * 		could not be found
     * @exception SecurityException if this MIDlet Suite is not
     *  	allowed to open the specified RecordStore.
     * @exception IllegalArgumentException if recordStoreName is
     *          invalid
     * @since MIDP 2.0
     */
    public static RecordStore openRecordStore(String recordStoreName,
					      String vendorName,
					      String suiteName)
	throws RecordStoreException, RecordStoreNotFoundException
    {
	if (vendorName == null || suiteName == null) {
	    throw new IllegalArgumentException("vendorName and " +
					       "suiteName must be " +
					       "non null");
	}
	synchronized (dbCacheLock) {
	    
	    if (recordStoreName.length() > 32 ||
		recordStoreName.length() == 0) {
		throw new IllegalArgumentException();
	    }
	    
	    // 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;	   
	    String uidPath = RecordStoreFile.getUniqueIdPath(vendorName, 
							     suiteName, 
							     recordStoreName);
	    for (int n = 0; n < dbCache.size(); n++) {
		db = (RecordStore)dbCache.elementAt(n);
		if (db.uniqueIdPath.equals(uidPath)) {
		    if (db.checkOwner() == false && 
			db.dbAuthMode == AUTHMODE_PRIVATE) {
			throw new SecurityException();
		    } else {
			db.opencount++;  // times rs has been opened
			return db;  // return ref to cached record store
		    }
		}
	    }
	    /*
	     * Record store not found in cache, so create it.
	     */
	    db = new RecordStore(uidPath, recordStoreName, false);
	    
	    /*
	     * Now add the new record store to the cache
	     */
	    db.opencount = 1;
	    dbCache.addElement(db);