Class ClientStoreFile

public class ClientStoreFile extends File
{
  // Constructors
  public ClientStoreFile (String stgfilename) throws IOException;
  public ClientStoreFile (ClientStore store,
        String stgfilename) throws IOException;
  public ClientStoreFile (String stgfilename, int flags)
        throws IOException;
  public ClientStoreFile (ClientStore store, String stgfilename,
        int flags) throws IOException;

  // Methods
  public boolean canRead ();
  public boolean canWrite ();
  public boolean delete ();
  public boolean equals (Object obj);
  public boolean exists ();
  public String getAbsolutePath();
  public String getCanonicalPath() throws IOException;
  public boolean isAbsolute ();
  public boolean isDirectory ();
  public boolean isFile ();
  public long lastModified ();
  public long length ();
  public String[] list ();
  public String[] list (FilenameFilter filter);
  public boolean mkdir ();
  public boolean mkdirs ();
  public InputStream openInputStream () throws IOException;
  public OutputStream openOutputStream () throws IOException;
  public OutputStream openOutputStream (boolean append)
        throws IOException;
  public RandomAccessFile openRandom () throws IOException;
  public RandomAccessFile openRandom (boolean writable)
        throws IOException;
  public boolean renameTo (File dest);
}

This class manages and provides access to individual files within client stores. Using the methods in this class, you can delete a file, rename it, make a directory for it, determine whether you can read from the file, get the absolute or canonical path for the file, and retrieve other file characteristics.

This class extends the java.io.File class and uses the java.io.File.getPath method to retrieve the pathfor the ClientStoreFile object.

File
  |
  +--ClientStoreFile

Constructors

ClientStoreFile

public ClientStoreFile (String stgfilename) throws IOException;

Creates a ClientStoreFile object from the specified filename.

Return Value:

Returns the ClientStoreFile object that represents the specified file.

Parameter	Description
stgfilename	The name of the file.

Exceptions:

IOException if there is an I/O error.

ClientStoreFile

public ClientStoreFile (ClientStore store, String stgfilename)
        throws IOException;

Creates a ClientStoreFile object from the filename and the ClientStore object that the file is located in.

Return Value:

Returns the ClientStoreFile object representing the file that is located in the client store.

Parameter	Description
store	The client store that contains the specified file.
stgfilename	The name of the file.

Exceptions:

IOException if there is an I/O error.

ClientStoreFile

public ClientStoreFile (String stgfilename, int flags) throws IOException;

Creates a ClientStoreFile object from the filename and any specified file flags.

Return Value:

Returns the ClientStoreFile object representing the file that is located in the client store.

Parameter	Description
stgfilename	The name of the file.
flags	The flags that can be used with any of the file operations in this class. They can be any combination of the following: OPEN_FL_SHARED STORE_FL_ROAMING OPEN_FL_APPEND OPEN_FL_EXPENDABLE OPEN_FL_WRITABLE STORE_FL_LOCAL

Exceptions:

IOException if there is an I/O error.

ClientStoreFile

public ClientStoreFile (ClientStore store, String stgfilename,
        int flags) throws IOException;

Creates a ClientStoreFile object from the filename, the ClientStore object that the file is located in, and any specified file flags.

Return Value:

Returns the ClientStoreFile object representing the file that is located in the client store.

Parameter	Description
store	The client store that contains the specified file.
stgfilename	The name of the file.
flags	The flags that can be used with any of the file operations in this class. They can be any combination of the following: OPEN_FL_SHARED STORE_FL_ROAMING OPEN_FL_APPEND OPEN_FL_EXPENDABLE OPEN_FL_WRITABLE STORE_FL_LOCAL

Exceptions:

IOException if there is an I/O error.

Methods

canRead

public boolean canRead ();

Determines whether the application can read from the specified file.

Return Value:

Returns true if the file specified by this object exists and the application can read the file; otherwise, returns false.

canWrite

public boolean canWrite ();

Determines whether the application can write to this file.

Return Value:

Returns true if the application is allowed to write to the file whose name is specified by this object; otherwise, returns false.

delete

public boolean delete ();

Deletes the file specified by the ClientStoreFile object.

Return Value:

Returns true if the file is successfully deleted; otherwise, returns false.

equals

public boolean equals (Object obj);

Determines whether this ClientStoreFile instance is equal to another object.

Return Value:

Returns false if obj is not an instance of ClientStoreFile or if the file specified by this instance is not identical to the object specified by obj; otherwise, returns true.

Parameter	Description
obj	The object that the ClientStoreFile instance is being compared with.

exists

public boolean exists ();

Determines whether this ClientStoreFile object exists.

Return Value:

Returns true if the file specified by this object exists; otherwise, returns false.

getAbsolutePath

public String getAbsolutePath();

Retrieves the absolute path of the file represented by this object.

Return Value:

Returns an absolute path for this ClientStoreFile object.

Remarks:

If the ClientStoreFile object represents an absolute path, this method returns the path. Otherwise, it returns a path that is a concatenation of the current storage directory, the separator character, and the path of this file object.

getCanonicalPath

public String getCanonicalPath() throws IOException;

Retrieves the canonical form of this ClientStoreFile object's path. The precise definition of the canonical form is system-dependent, but it usually specifies an absolute path in which all relative references and references to the current user directory have been completely resolved. The canonical form of a path of a nonexistent file cannot be defined.

Return Value:

Returns the canonical form of the object's path.

Exceptions:

IOException if an I/O error occurs. Errors are possible because the construction of the canonical path may require file system queries.

isAbsolute

public boolean isAbsolute ();

Determines whether the file represented by this ClientStoreFile object is an absolute path.

Return Value:

Returns true if the path indicated by the ClientStoreFile object is an absolute path; otherwise, returns false.

Remarks:

The definition of an absolute pathname is system dependent. For example, on UNIX, a pathname is absolute if its first character is the separator character. On Microsoft® Windows® platforms, a pathname is absolute if its first character is an ASCII '\' or '/', or if it begins with a letter followed by a colon. This method uses the java.io.File.separator field to retrieve the separator for the file system.

isDirectory

public boolean isDirectory ();

Determines whether the file represented by this ClientStoreFile object is a directory.

Return Value:

Returns true if this ClientStoreFile object exists and is a directory; otherwise, returns false.

isFile

public boolean isFile ();

Determines whether the file represented by this ClientStoreFile object is a "normal" file. A file is normal if it is not a directory and, in addition, satisfies other system-dependent criteria. Any non-directory file created by a Java application is guaranteed to be a normal file.

Return Value:

Returns true if the file specified by this object exists and is a normal file; otherwise, returns false.

lastModified

public long lastModified ();

Retrieves the time that the file represented by this ClientStoreFile object was last modified.

Caution The return value is system dependent and should only be used to compare with other values returned by lastModified. It should not be interpreted as an absolute time.

Return Value:

Returns the time the file specified by this object was last modified, or 0L if the specified file does not exist.

length

public long length ();

Retrieves the length of the file represented by this ClientStoreFile object.

Return Value:

Returns the length, in bytes, of the file specified by this object, or 0L if the specified file does not exist.

list

public String[] list ();

Returns a list of the files in the directory specified by the ClientStoreFile object.

Return Value:

Returns an array that contains the names of files in the specified directory. This list does not include the current directory or the parent directory ("." and ".." on Unix systems).

list

public String[] list (FilenameFilter filter);

Retrieves a list of files that satisfy the specified filter and that are located in the directory specified by the ClientStoreFile object. The filter parameter, which is an instance of a class that implements the java.io.FilenameFilter interface, indicates the properties that the file must have to be included in the returned list of files.

Return Value:

Returns an array that contains the names of files in the specified directory. This list does not include the current directory or the parent directory ("." and ".." on Unix systems).

Parameter	Description
filter	A filename filter.

mkdir

public boolean mkdir ();

Creates a directory whose path is specified by the ClientStoreFile object.

Return Value:

Returns true if the directory could be created; otherwise, returns false.

mkdirs

public boolean mkdirs ();

Creates a directory whose path is specified by the ClientStoreFile object, including any necessary parent directories.

Return Value:

Returns true if the directory (or directories) could be created; otherwise, returns false.

openInputStream

public InputStream openInputStream () throws IOException;

Opens an input stream to the file.

Return Value:

Returns the InputStream that is open for reading.

Exceptions:

IOException if the file could not be created or truncated.

openOutputStream

public OutputStream openOutputStream () throws IOException;

Opens an output stream to the file.

Return Value:

Returns the OutputStream that is open for writing.

Exceptions:

IOException if the file could not be created or truncated.

openOutputStream

public OutputStream openOutputStream (boolean append) throws IOException;

Opens an output stream to the file, optionally appending to an existing file.

Return Value:

Returns the output stream that is open for writing.

Parameter	Description
append	The value that determines whether to append to an existing file. If true, this method appends to an existing file; otherwise, it truncates an existing file.

Exceptions:

IOException if the file could not be created or truncated.

openRandom

public RandomAccessFile openRandom () throws IOException;

Opens a RandomAccessFile from the store for read operations, with no specified flags.

Return Value:

Returns the RandomAccessFile that is opened.

Exceptions:

IOException if the method fails to open the specified file.

openRandom

public RandomAccessFile openRandom (boolean writable) throws IOException;

Opens a RandomAccessFile from the store for read or write operations, with no specified flags.

Return Value:

Returns the RandomAccessFile that is opened.

Parameter	Description
writable	Set this value to true if the file should be opened as OPEN_FL_WRITABLE; otherwise, set writable to false.

Exceptions:

IOException if the method fails to open the specified file.

renameTo

public boolean renameTo (File dest);

Renames the file specified by this ClientStoreFile object to have the path given by the File argument.

Return Value:

Returns true if the renaming succeeds; otherwise, returns false.

Parameter	Description
dest	The new filename.