001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package com.sun.midp.rms;
028:
029: import java.io.IOException;
030:
031: /**
032: * A RecordStoreFile is a file abstraction layer between a
033: * a RecordStore and an underlying persistent storage mechanism.
034: * The underlying storage methods are provided by the
035: * RandomAccessStream and File classes.
036: *
037: * RecordStoreFile confines the namespace of a record store to
038: * the scope of the MIDlet suite of its creating application.
039: * It also ensures unicode recordstore names are ascii filesystem safe.
040: *
041: * The RecordStoreImpl class can be implemented directly using the
042: * RandomAccessStream and File classes. However,
043: * RecordStoreFile served as the java/native code boundary for
044: * RMS in the MIDP 1.0 release. It exists now for
045: * backwards compatibility with older ports.
046: */
047: interface AbstractRecordStoreFile {
048:
049: /** extension for RecordStore database files */
050: static final int DB_EXTENSION = 0;
051:
052: /** extension for RecordStore database files */
053: static final int IDX_EXTENSION = 1;
054:
055: /**
056: * Approximation of remaining space in storage.
057: *
058: * Usage Warning: This may be a slow operation if
059: * the platform has to look at the size of each file
060: * stored in the MIDP memory space and include its size
061: * in the total.
062: *
063: * @param suiteId ID of the MIDlet suite that owns the record store
064: * can be null
065: *
066: * @return the approximate space available to grow the
067: * record store in bytes.
068: */
069: int spaceAvailable(int suiteId);
070:
071: /**
072: * Sets the position within <code>recordStream</code> to
073: * <code>pos</code>. This will implicitly grow
074: * the underlying stream if <code>pos</code> is made greater
075: * than the current length of the storage stream.
076: *
077: * @param pos position within the file to move the current_pos
078: * pointer to.
079: *
080: * @exception IOException if there is a problem with the seek.
081: */
082: void seek(int pos) throws IOException;
083:
084: /**
085: * Write all of <code>buf</code> to <code>recordStream</code>.
086: *
087: * @param buf buffer to read out of.
088: *
089: * @exception IOException if a write error occurs.
090: */
091: void write(byte[] buf) throws IOException;
092:
093: /**
094: * Write <code>buf</code> to <code>recordStream</code>, starting
095: * at <code>offset</code> and continuing for <code>numBytes</code>
096: * bytes.
097: *
098: * @param buf buffer to read out of.
099: * @param offset starting point write offset, from beginning of buffer.
100: * @param numBytes the number of bytes to write.
101: *
102: * @exception IOException if a write error occurs.
103: */
104: void write(byte[] buf, int offset, int numBytes) throws IOException;
105:
106: /**
107: * Commit pending writes
108: *
109: * @exception IOException if an error occurs while flushing
110: * <code>recordStream</code>.
111: */
112: void commitWrite() throws IOException;
113:
114: /**
115: * Read up to <code>buf.length</code> into <code>buf</code>.
116: *
117: * @param buf buffer to read in to.
118: *
119: * @return the number of bytes read.
120: *
121: * @exception IOException if a read error occurs.
122: */
123: int read(byte[] buf) throws IOException;
124:
125: /**
126: * Read up to <code>buf.length</code> into <code>buf</code>
127: * starting at offset <code>offset</code> in <code>recordStream
128: * </code> and continuing for up to <code>numBytes</code> bytes.
129: *
130: * @param buf buffer to read in to.
131: * @param offset starting point read offset, from beginning of buffer.
132: * @param numBytes the number of bytes to read.
133: *
134: * @return the number of bytes read.
135: *
136: * @exception IOException if a read error occurs.
137: */
138: int read(byte[] buf, int offset, int numBytes) throws IOException;
139:
140: /**
141: * Disconnect from <code>recordStream</code> if it is
142: * non null. May be called more than once without error.
143: *
144: * @exception IOException if an error occurs closing
145: * <code>recordStream</code>.
146: */
147: void close() throws IOException;
148:
149: /**
150: * Sets the length of this <code>RecordStoreFile</code>
151: * <code>size</code> bytes. If this file was previously
152: * larger than <code>size</code> the extra data is lost.
153: *
154: * <code>size</code> must be <= the current length of
155: * <code>recordStream</code>
156: *
157: * @param size new size for this file.
158: *
159: * @exception IOException if an error occurs, or if
160: * <code>size</code> is less than zero.
161: */
162: void truncate(int size) throws IOException;
163: }
|