File	Doc	Category	Size	Date	Package
RecordStoreFile.java	API Doc	J2ME MIDP 2.0	15663	Thu Nov 07 12:02:26 GMT 2002	com.sun.midp.rms

RecordStoreFile

• java.lang.Object

Fields Summary
private static com.sun.midp.security.SecurityToken	classSecurityToken This class has a different security domain than the MIDlet suite
private static final String	dbExtension Easily recognize record store files in the file system
private com.sun.midp.io.j2me.storage.RandomAccessStream	recordStream Stream to read/write record store data to
private String	myStoragePath MIDlet suite and vendor specific storage path used as a unique identifier for a record store

Constructors Summary

public RecordStoreFile(String uidPath) Constructs a new RecordStoreFile instance. This process involves a few discrete steps and concludes with with opening a RandomAccessStream that this RecordStoreFile instance will use for persistant storage. The steps in constructing a RecordStoreFile instance are: The storage path for the desired MIDlet suite is acquired in argument uidPath. The caller must get this path using the getUniqueIdPath() method before calling this constructor. This result is then connected with a new RandomAccessStrem where record data for this instance is stored.. param uidPath unique identifier path for this RecordStoreFile object. exception IOException if there is an error opening the file. RandomAccessStream newStream; myStoragePath = uidPath; newStream = new RandomAccessStream(classSecurityToken); newStream.connect(myStoragePath, Connector.READ_WRITE); recordStream = newStream;

Methods Summary
public void	close() Disconnect from recordStream if it is non null. May be called more than once without error. exception IOException if an error occurs closing recordStream. // close recordStream if it exists if (recordStream != null) { recordStream.disconnect(); recordStream = null; }
public static boolean	deleteFile(java.lang.String uidPath) Removes the storage file for record store filename if it exists. param uidPath unique identifier path to the file to delete. return true if successful or false if an IOException occurred internally. File file; file = new File(classSecurityToken); try { file.delete(uidPath); return true; } catch (IOException ioe) { return false; }
public static boolean	exists(java.lang.String uidPath) Looks to see if the storage file for record store identified by uidPath exists param uidPath the unique identifier for this record store file return true if the file exists, false if it does not. File file; file = new File(classSecurityToken); return file.exists(uidPath);
private static java.lang.String	getStoragePath(java.lang.String name) Given a null argument this helper functions returns a path to where record stores should be stored for the MIDlet suite of the calling MIDlet process. If name is non null it returns the full path of that record store in the file system: .db param name name of target record store, or null if only the storage path for the current MIDlet suite is desired. return the relative path to where record store files for the current MIDlet suite are stored if name is null, or the complete system path for storage of the record store name. String str; MIDletSuite mSuite; StringBuffer path; mSuite = Scheduler.getScheduler().getMIDletSuite(); // MIDletSuite msuite should not be null. str = mSuite.getStorageRoot(); if (name != null) { path = new StringBuffer(str); // convert the unicode filename into a system acceptable string path.append(File.unicodeToAsciiFilename(name)); path.append(dbExtension); str = path.toString(); } return str;
private static java.lang.String	getStoragePath(java.lang.String vendor, java.lang.String suite, java.lang.String name) If name, suite, and vendor are all non null, returns the full path of that record store in the file system: .db param vendor vendor of target record store param suite suite of target record store param name name of target record store return the complete system path for storage of the record store name. String str = File.getStorageRoot(); StringBuffer path = new StringBuffer(str); if (vendor != null && suite != null) { path.append(File.unicodeToAsciiFilename(vendor)); path.append('_"); path.append(File.unicodeToAsciiFilename(suite)); path.append('_"); } if (name != null) { path.append(File.unicodeToAsciiFilename(name)); path.append(dbExtension); str = path.toString(); } return str;
public static java.lang.String	getUniqueIdPath(java.lang.String fileName) Returns a storage system unique string for this record store file based on the current vendor and suite of the running MIDlet. The native storage path for the desired MIDlet suite is acquired from the Scheduler. The filename arg is converted into an ascii equivalent safe to use directly in the underlying file system and appended to the native storage path. See the com.sun.midp.io.j2me.storage.File.unicodeToAsciiFilename() method for conversion details. Finally a ".db" extension is appeded to the file name. param fileName name of the record store return a unique identifier for this record store file return getStoragePath(fileName);
public static java.lang.String	getUniqueIdPath(java.lang.String vendorName, java.lang.String suiteName, java.lang.String fileName) Returns a storage system unique string for this record store file based on the vendor, suite, and record store name passed in. param vendorName name of the vendor of the MIDlet suite param suiteName name of the MIDlet suite param fileName name of the record store return a unique identifier for this record store file return getStoragePath(vendorName, suiteName, fileName);
public java.lang.String	getUniqueIdPath() Get the path of this object when it was created return the storage path of this RecordStoreFile return myStoragePath;
public static void	initSecurityToken(com.sun.midp.security.SecurityToken token) Initializes the security token for this class, so it can perform actions that a normal MIDlet Suite cannot. param token security token for this class. if (classSecurityToken != null) { return; } classSecurityToken = token;
public static java.lang.String[]	listRecordStores() Returns an array of the names of record stores owned by the MIDlet suite. Note that if the MIDlet suite does not have any record stores, this function will return NULL. return an array of record store names. return listRecordStoresForSuite(new File(classSecurityToken), getStoragePath(null), false);
private static java.lang.String[]	listRecordStoresForSuite(com.sun.midp.io.j2me.storage.File storage, java.lang.String suiteStorageRoot, boolean rawNames) Returns an array of the names of record stores owned by the MIDlet suite. Note that if the MIDlet suite does not have any record stores, this function will return NULL. param storage persisent storage access object param suiteStorageRoot storage root name of the suite param rawNames if true, raw filenames will be output instead of processed record store names. return an array of record store names. Vector files; Vector names; String file; String asciiName; files = storage.filenamesThatStartWith(suiteStorageRoot); names = new Vector(); // work through list of strings from the directory for (int i = 0; i < files.size(); i++) { file = (String)files.elementAt(i); if (file.endsWith(dbExtension)) { if (rawNames) { names.addElement(file); } else { /* * some or all of the strings in foo may be encoded * into a system specific format. decode them before * adding to names. */ asciiName = file.substring(suiteStorageRoot.length(), file.length() - 3); names.addElement(File.asciiFilenameToUnicode(asciiName)); } } } if (names.size() == 0) { return null; } String[] rv = new String[names.size()]; names.copyInto(rv); return rv;
public int	read(byte[] buf) Read up to buf.length into buf. param buf buffer to read in to. return the number of bytes read. exception IOException if a read error occurs. return read(buf, 0, buf.length);
public int	read(byte[] buf, int offset, int numBytes) Read up to buf.length into buf starting at offset offset in recordStream and continuing for up to numBytes bytes. param buf buffer to read in to. param offset starting point read offset, from beginning of buffer. param numBytes the number of bytes to read. return the number of bytes read. exception IOException if a read error occurs. return recordStream.readBytes(buf, offset, numBytes);
public static void	removeRecordStoresForSuite(com.sun.midp.security.SecurityToken token, java.lang.String suiteStorageRoot) Remove all the Record Stores for a suite. param token security token with MIDP internal permisison param suiteStorageRoot storage root name of the suite File storage; String[] filenames; storage = new File(token); filenames = listRecordStoresForSuite(storage, suiteStorageRoot, true); if (filenames == null) { return; } for (int i = 0; i < filenames.length; i++) { try { storage.delete(filenames[i]); } catch (IOException ioe) { // move on to the next suite } }
public void	seek(int pos) Sets the position within recordStream to pos. This will implicitly grow the underlying stream if pos is made greater than the current length of the storage stream. param pos position within the file to move the current_pos pointer to. exception IOException if there is a problem with the seek. recordStream.setPosition(pos);
public static int	spaceAvailable() Approximation of remaining space in storage. Usage Warning: This may be a slow operation if the platform has to look at the size of each file stored in the MIDP memory space and include its size in the total. return the aproximate space available to grow the record store in bytes. return new File(classSecurityToken).getBytesAvailableForFiles();
public static boolean	suiteHasRmsData(java.lang.String suiteStorageRoot) Returns true if the suite has created at least one record store. param suiteStorageRoot storage root name of the suite return true if the suite has at least one record store File storage = new File(classSecurityToken); Vector files = storage.filenamesThatStartWith(suiteStorageRoot); for (int i = 0; i < files.size(); i++) { String file = (String)files.elementAt(i); if (file.endsWith(dbExtension)) { return true; } } return false;
public void	truncate(int size) Sets the length of this RecordStoreFile size bytes. If this file was previously larger than size the extra data is lost. size must be <= the current length of recordStream param size new size for this file. exception IOException if an error occurs, or if size is less than zero. if (recordStream != null) { recordStream.truncate(size); }
public void	write(byte[] buf, int offset, int numBytes) Write buf to recordStream, starting at offset and continuing for numBytes bytes. param buf buffer to read out of. param offset starting point write offset, from beginning of buffer. param numBytes the number of bytes to write. exception IOException if a write error occurs. recordStream.writeBytes(buf, offset, numBytes);
public void	write(byte[] buf) Write all of buf to recordStream. param buf buffer to read out of. exception IOException if a write error occurs. write(buf, 0, buf.length);