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.io.j2me.file;
028:
029: import java.io.IOException;
030: import java.util.Vector;
031:
032: /**
033: * Base file handler.
034: */
035: interface BaseFileHandler {
036:
037: /**
038: * Connect file handler to the abstract file target. This operation should
039: * not trigger any access to the native filesystem.
040: *
041: * @param rootName The name of the root directory.
042: *
043: * @param absFile Full path to the file to be handled by this handler.
044: *
045: * @throws IllegalArgumentException if filename contains characters
046: * not allowed by the file system. This check should not involve
047: * any actual access to the filesystem.
048: */
049: public void connect(String rootName, String absFile);
050:
051: /**
052: * Creates dedicated private working directory for the MIDlet suite.
053: * Does nothing if specified root is not private root or the directory
054: * already exists.
055: *
056: * @param rootName the name of file root
057: */
058: public void createPrivateDir(String rootName) throws IOException;
059:
060: /**
061: * Open the file for reading, on the underlying file system. File name is
062: * passed in the link#connect() method.
063: *
064: * @throws IOException if file is directory, file does not exists,
065: * if file is already open for read or other
066: * I/O error occurs
067: */
068: public void openForRead() throws IOException;
069:
070: /**
071: * Closes for reading the file that was open by openForRead method.
072: * If the file is already closed for reading this method does nothing.
073: *
074: * @throws IOException if file is directory, file does not exists or other
075: * I/O error occurs
076: */
077: public void closeForRead() throws IOException;
078:
079: /**
080: * Open the file for writing, on the underlying file system. File name is
081: * passed in the link#connect() method.
082: *
083: * @throws IOException if file is directory, file does not exists,
084: * i if file is already open for write or other
085: * I/O error occurs
086: */
087: public void openForWrite() throws IOException;
088:
089: /**
090: * Closes for writing the file that was open by openForWrite method.
091: * If the file is already closed for writing this method does nothing.
092: *
093: * @throws IOException if file is directory, file does not exists or other
094: * I/O error occurs
095: */
096: public void closeForWrite() throws IOException;
097:
098: /**
099: * Closes the file for both reading and writing.
100: * If the file is already closed for reading and writing this method does
101: * nothing.
102: *
103: * @throws IOException if file is directory, file does not exists or other
104: * I/O error occurs
105: */
106: public void closeForReadWrite() throws IOException;
107:
108: /**
109: * Gets a filtered list of files and directories contained in a directory.
110: * The directory is the handler's target as specified in
111: * <code>create()</code>.
112: *
113: * @param filter String against which all files and directories are
114: * matched for retrieval. An asterisk ("*") can be used as a
115: * wildcard to represent 0 or more occurrences of any character.
116: * If null no filtering is performed
117: * @param includeHidden boolean indicating whether files marked as hidden
118: * should be included or not in the list of files and directories
119: * returned.
120: * @return An Enumeration of strings, denoting the files and directories
121: * in the directory matching the filter. Directories are denoted
122: * with a trailing slash "/" in their returned name. The
123: * Enumeration has zero length if the directory is empty or no
124: * files and/or directories are found matching the given filter.
125: * Any current directory indication (".") and any parent directory
126: * indication ("..") is not included in the list of files and
127: * directories returned.
128: * @throws IOException if invoked on a file, the directory does not exist,
129: * the directory is not accessible, or an I/O error occurs.
130: * @throws IllegalArgumentException if filter contains any path
131: * specification or is an invalid filename for the platform
132: * (e.g. contains characters invalid for a filename on the
133: * platform).
134: */
135: public Vector list(String filter, boolean includeHidden)
136: throws IOException;
137:
138: /**
139: * List filesystem roots available on the device. For the description of
140: * the correct root format see <code>FileConnection</code> documentation.
141: * @return array of roots
142: */
143: public Vector listRoots();
144:
145: /**
146: * Create file corresponding to this file handler. The
147: * file is created immediately on the actual file system upon invocation of
148: * this method. Files are created with zero length and data can be put
149: * into the file through write method after opening the file.This method
150: * does not create any directories specified in the file's path.
151: *
152: * @throws IOException if invoked on the existing file or unexpected error
153: * occurs.
154: */
155: public void create() throws IOException;
156:
157: /**
158: * Check is file or directory corresponding to this filehandler exists.
159: *
160: * @return true if file exists, otherwise false
161: */
162: public boolean exists();
163:
164: /**
165: * Check is file corresponding to this filehandler exists and is a
166: * directory.
167: *
168: * @return true if directory exists, otherwise false
169: */
170: public boolean isDirectory();
171:
172: /**
173: * Deletes the file or directory associated with this handler.
174: * The file or directory is deleted immediately on
175: * the actual file system upon invocation of this method. Previously open
176: * native file should be closed.The
177: * handler instance object remains connected and available for use.
178: *
179: * @throws IOException If the target is a directory and it is not empty,
180: * the connection target does not exist or is unaccessible, or
181: * an unspecified error occurs preventing deletion of the target.
182: */
183: public void delete() throws IOException;
184:
185: /**
186: * Renames the selected file or directory to a new name in the same
187: * directory. The file or directory is renamed immediately on the actual
188: * file system upon invocation of this method. No file or directory by the
189: * original name exists after this method call. Previously open native file
190: * should be closed. The handler
191: * instance object remains connected and available for use,
192: * referring now to the file or directory by its new name.
193: *
194: * @param newName The new name of the file or directory. The name must
195: * be the full qualified name of the new file
196: * @throws IOException if the connection's target does not exist, the
197: * connection's target is not accessible, a file or directory
198: * already exists by the <code>newName</code>, or
199: * <code>newName</code> is an invalid filename for the platform
200: * (e.g. contains characters invalid in a filename on
201: * the platform).
202: */
203: public void rename(String newName) throws IOException;
204:
205: /**
206: * Truncates the file, discarding all data from the given byte offset to
207: * the current end of the file. If the byte offset provided is greater
208: * than or equal to the file's current byte count, the method returns
209: * without changing the file.
210: *
211: * @param byteOffset the offset into the file from which truncation
212: * occurs.
213: * @throws IOException if invoked on a directory or the file does not
214: * exist or is not accessible.
215: */
216: public void truncate(long byteOffset) throws IOException;
217:
218: /**
219: * Determines the size of a file on the file system. The size of a file
220: * always represents the number of bytes contained in the file; there is
221: * no pre-allocated but empty space in a file. Users should perform an
222: * explicit <code>flush()</code> on any open output streams to the file
223: * prior to invoking this method to ensure accurate results.
224: *
225: * @return The size in bytes of the selected file, or -1 if the
226: * file does not exist or is not accessible.
227: * @throws IOException if the method is invoked on a directory.
228: */
229: public long fileSize() throws IOException;
230:
231: /**
232: * Determines the size in bytes on a file system of all of the files
233: * that are contained in a directory.
234: *
235: * @param includeSubDirs if <code>true</code>, size calculation will
236: * include all subdirectories' size.
237: * @return The size in bytes occupied by the files included in the
238: * directory, or -1 if the directory does not exist or is
239: * not accessible.
240: * @throws IOException if some error occures while accessing the directory.
241: */
242: public long directorySize(boolean includeSubDirs)
243: throws IOException;
244:
245: /**
246: * Check if file corresponding to this filehandler exists and has a
247: * read permission.
248: *
249: * @return true if file has read permission, otherwise false
250: */
251: public boolean canRead();
252:
253: /**
254: * Check is file corresponding to this filehandler exists and has a
255: * write permission.
256: *
257: * @return true if file has write permission, otherwise false
258: */
259: public boolean canWrite();
260:
261: /**
262: * Check is file corresponding to this filehandler exists and is
263: * hidden.
264: *
265: * @return true if file is hidden, otherwise false
266: */
267: public boolean isHidden();
268:
269: /**
270: * Sets the file or directory readable attribute to the
271: * indicated value. The readable attribute for the file on the actual
272: * file system is set immediately upon invocation of this method. If the
273: * file system doesn't support a settable read attribute, this method is
274: * ignored and <code>canRead()</code> always returns true.
275: *
276: * @param readable The new state of the readable flag of the
277: * selected file.
278: * @throws IOException if the connection's target does not exist or is not
279: * accessible.
280: * @see #canRead
281: */
282: public void setReadable(boolean readable) throws IOException;
283:
284: /**
285: * Sets the file or directory associated with this file handler writable
286: * attribute to the
287: * indicated value. The writable attribute for the file on the actual
288: * file system is set immediately upon invocation of the method. If the
289: * file system doesn't support a settable write attribute, this method is
290: * ignored and <code>canWrite()</code> always returns true.
291: *
292: * @param writable The new state of the writable flag of the selected
293: * file.
294: * @throws IOException if the connection's target does not exist or is not
295: * accessible.
296: * @see #canWrite
297: */
298: public void setWritable(boolean writable) throws IOException;
299:
300: /**
301: * Sets the hidden attribute of the file associated with this file handler
302: * to the value provided. The attribute is applied to the file on the
303: * actual file system immediately upon invocation of this method if the
304: * file system
305: * and platform support it. If the file system doesn't support a hidden
306: * attribute, this method is ignored and <code>isHidden()</code> always
307: * returns false. Since the exact definition of hidden is
308: * system-dependent,
309: * this method only works on file systems that support a settable file
310: * attribute. For example, on Win32 and FAT file systems, a file may be
311: * considered hidden if it has been marked as such in the file's
312: * attributes; therefore this method is applicable. However on UNIX
313: * systems a file may be considered to be hidden if its name begins with a
314: * period character ('.'). In the UNIX case, this method may be ignored and
315: * the method to make a file hidden may be the <code>rename()</code>
316: * method.
317: *
318: * @param hidden The new state of the hidden flag of the selected file.
319: * @throws IOException if the connection's target does not exist or is not
320: * accessible.
321: * @see #isHidden
322: */
323: public void setHidden(boolean hidden) throws IOException;
324:
325: /**
326: * Returns the time that the file denoted by this file handler
327: * was last modified.
328: *
329: * @return time when the file was last modified.
330: */
331: public long lastModified();
332:
333: /**
334: * Creates a directory corresponding to the directory
335: * string provided in the connect() method.
336: * The directory is created immediately on the actual
337: * file system upon invocation of this method. Directories in the
338: * specified path are not recursively created and must be explicitly
339: * created before subdirectories can be created.
340: *
341: * @throws IOException if invoked on an existing directory or on any file
342: * (<code>create()</code> is used to create files), the target
343: * file system is not accessible, or an unspecified error occurs
344: * preventing creation of the directory.
345: */
346: public void mkdir() throws IOException;
347:
348: /**
349: * Reads up to <code>len</code> bytes of data from the input stream into
350: * an array of bytes, blocks until at least one byte is available.
351: *
352: * @param b the buffer into which the data is read.
353: * @param off the start offset in array <code>b</code>
354: * at which the data is written.
355: * @param len the maximum number of bytes to read.
356: * @return the total number of bytes read into the buffer, or
357: * <code>-1</code> if there is no more data because the end of
358: * the stream has been reached.
359: * @exception IOException if an I/O error occurs.
360: */
361: public int read(byte b[], int off, int len) throws IOException;
362:
363: /**
364: * Writes <code>len</code> bytes from the specified byte array
365: * starting at offset <code>off</code> to this output stream.
366: * <p>
367: * Polling the native code is done here to allow for simple
368: * asynchronous native code to be written. Not all implementations
369: * work this way (they block in the native code) but the same
370: * Java code works for both.
371: *
372: * @param b the data.
373: * @param off the start offset in the data.
374: * @param len the number of bytes to write.
375: * @return number of bytes written
376: * @exception IOException if an I/O error occurs. In particular,
377: * an <code>IOException</code> is thrown if the output
378: * stream is closed.
379: */
380: public int write(byte b[], int off, int len) throws IOException;
381:
382: /**
383: * Forces any buffered output bytes to be written out.
384: * The general contract of <code>flush</code> is
385: * that calling it is an indication that, if any bytes previously
386: * written that have been buffered by the connection,
387: * should immediately be written to their intended destination.
388: * <p>
389: * The <code>flush</code> method of <code>ConnectionBaseAdapter</code>
390: * does nothing.
391: *
392: * @exception IOException if an I/O error occurs.
393: */
394: public void flush() throws IOException;
395:
396: /**
397: * Sets the location for the next write operation.
398: * @param offset location for next write
399: * @throws IOException if an error occurs
400: */
401: public void positionForWrite(long offset) throws IOException;
402:
403: /**
404: * Determines the free memory that is available on the file system the file
405: * or directory resides on. This may only be an estimate and may vary based
406: * on platform-specific file system blocking and metadata information.
407: *
408: * @return The available size in bytes on a file system, or -1 if an
409: * error occurs.
410: */
411: public long availableSize();
412:
413: /**
414: * Determines the total size of the file system the connection's target
415: * resides on.
416: *
417: * @return The total size of the file system in bytes, or -1 if an
418: * error occurs.
419: */
420: public long totalSize();
421:
422: /**
423: * Returns a string that contains all characters forbidden for the use on
424: * the given platform except "/" (forward slash) which is always considered
425: * illegal. If there are no such characters an empty string is returned.
426: * @return string of characters not allowed in file names
427: */
428: public String illegalFileNameChars();
429:
430: /**
431: * Determines the used memory of a file system the connection's target
432: * resides on. This may only be an estimate and may vary based
433: * on platform-specific file system blocking and metadata information.
434: *
435: * @return The used size of bytes on a file system, or -1 if an
436: * error occurs.
437: */
438: public long usedSize();
439:
440: /**
441: * Close file associated with this handler. Open file and all system
442: * resources should be released by this call. Handler object can be
443: * reused by subsequent call to connect().
444: *
445: * @throws IOException if I/O error occurs
446: */
447: public void close() throws IOException;
448: }
|