Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| org.openide.filesystems 6.4.22
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.openide.filesystems
Class FileObject

    java.lang.Object
      org.openide.filesystems.FileObject

All Implemented Interfaces:
  Serializable

    public abstract class FileObject

extends Object
implements Serializable

This is the base for all implementations of file objects on a filesystem. Provides basic information about the object (its name, parent, whether it exists, etc.) and operations on it (move, delete, etc.).

See Also:
  Serialized Form

Constructor Summary
`FileObject()`

Method Summary
`abstract void` | `addFileChangeListener(FileChangeListener fcl)` Add new listener to this object.
`boolean` | `canRead()` Tests if this file can be read.
`boolean` | `canWrite()` Tests if this file can be written to.
`FileObject` | `copy(FileObject target, String name, String ext)` Copies this file.
`FileObject` | `createData(String name)` Create new data file in this folder with the specified name.
`abstract FileObject` | `createData(String name, String ext)` Create new data file in this folder with the specified name.
`abstract FileObject` | `createFolder(String name)` Create a new folder below this one with the specified name.
`void` | `delete()` Delete this file.
`abstract void` | `delete(FileLock lock)` Delete this file.
`boolean` | `existsExt(String ext)` Test whether there is a file with the same basename and only a changed extension in the same folder.
`protected void` | `fireFileAttributeChangedEvent(Enumeration en, FileAttributeEvent fe)` Fire file attribute change event.
`protected void` | `fireFileChangedEvent(Enumeration en, FileEvent fe)` Fire file change event.
`protected void` | `fireFileDataCreatedEvent(Enumeration en, FileEvent fe)` Fire data creation event.
`protected void` | `fireFileDeletedEvent(Enumeration en, FileEvent fe)` Fire file deletion event.
`protected void` | `fireFileFolderCreatedEvent(Enumeration en, FileEvent fe)` Fire folder creation event.
`protected void` | `fireFileRenamedEvent(Enumeration en, FileRenameEvent fe)` Fire file rename event.
`abstract Object` | `getAttribute(String attrName)` Get the file attribute with the specified name.
`abstract Enumeration` | `getAttributes()` Get all file attribute names for this file.
`abstract FileObject[]` | `getChildren()` Get all children of this folder (files and subfolders).
`Enumeration` | `getChildren(boolean rec)` Enumerate all children of this folder.
`Enumeration` | `getData(boolean rec)` Enumerate all data files in this folder.
`abstract String` | `getExt()` Get the extension of this file or folder.
`FileObject` | `getFileObject(String relativePath)` Retrieve file or folder relative to a current folder, with a given relative path.
`abstract FileObject` | `getFileObject(String name, String ext)` Retrieve file or folder contained in this folder by name.
`abstract FileSystem` | `getFileSystem()` Get the filesystem containing this file.
`Enumeration` | `getFolders(boolean rec)` Enumerate the subfolders of this folder.
`abstract InputStream` | `getInputStream()` Get input stream.
`String` | `getMIMEType()` Get the MIME type of this file.
`abstract String` | `getName()` Get the name without extension of this file or folder.
`String` | `getNameExt()` Getter for name and extension of a file object.
`abstract OutputStream` | `getOutputStream(FileLock lock)` Get output stream.
`String` | `getPackageName(char separatorChar)` Deprecated. Please use the ClassPath API instead.
`String` | `getPackageNameExt(char separatorChar, char extSepChar)` Deprecated. Please use the ClassPath API instead.
`abstract FileObject` | `getParent()` Get parent folder.
`String` | `getPath()` Get the full resource path of this file object starting from the filesystem root.
`abstract long` | `getSize()` Get the size of the file.
`URL` | `getURL()` Get URL that can be used to access this file.
`boolean` | `hasExt(String ext)` Test whether this file has the specified extension.
`abstract boolean` | `isData()` Test whether this object is a data object.
`abstract boolean` | `isFolder()` Test whether this object is a folder.
`abstract boolean` | `isReadOnly()` Deprecated. Please use the `canWrite()`.
`abstract boolean` | `isRoot()` Test whether this object is the root folder.
`abstract boolean` | `isValid()`
`boolean` | `isVirtual()` Tests if file really exists or is missing.
`abstract Date` | `lastModified()` Get last modification time.
`abstract FileLock` | `lock()` Lock this file.
`FileObject` | `move(FileLock lock, FileObject target, String name, String ext)` Moves this file.
`void` | `refresh()` Should check for external modifications.
`void` | `refresh(boolean expected)` Should check for external modifications.
`abstract void` | `removeFileChangeListener(FileChangeListener fcl)` Remove listener from this object.
`abstract void` | `rename(FileLock lock, String name, String ext)` Renames this file (or folder).
`abstract void` | `setAttribute(String attrName, Object value)` Set the file attribute with the specified name.
`abstract void` | `setImportant(boolean b)` Deprecated. No longer used. Instead use `SharabilityQuery`.
`String` | `toString()` Gets a textual represtentation of this `FileObject`.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Constructor Detail

### FileObject

    public FileObject()

Method Detail

### getName

    public abstract String getName()

  Get the name without extension of this file or folder. Period at first position is not considered as extension-separator For the root folder of a filesystem, this will be the empty string (the extension will also be the empty string, and the fully qualified name with any delimiters will also be the empty string).

  Returns:
    name of the file or folder(in its enclosing folder)

### getExt

    public abstract String getExt()

  Get the extension of this file or folder. Period at first position is not considered as extension-separator This is the string after the last dot of the full name, if any.

  Returns:
    extension of the file or folder (if any) or empty string if there is none

### rename

    public abstract void rename(FileLock lock,
                                String name,
                                String ext)
                         throws IOException

  Renames this file (or folder). Both the new basename and new extension should be specified.

  Note that using this call, it is currently only possible to rename within a parent folder, and not to do moves across folders. Conversely, implementing filesystems need only implement "simple" renames. If you wish to move a file across folders, you should call `FileUtil.moveFile(org.openide.filesystems.FileObject, org.openide.filesystems.FileObject, java.lang.String)`.

  Parameters:
    `lock` - File must be locked before renaming.
    `name` - new basename of file
    `ext` - new extension of file (ignored for folders)
  Throws:
    `IOException`

### copy

    public FileObject copy(FileObject target,
                           String name,
                           String ext)
                    throws IOException

  Copies this file. This allows the filesystem to perform any additional operation associated with the copy. But the default implementation is simple copy of the file and its attributes

  Parameters:
    `target` - target folder to move this file to
    `name` - new basename of file
    `ext` - new extension of file (ignored for folders)
  Returns:
    the newly created file object representing the moved file
  Throws:
    `IOException`

### move

    public FileObject move(FileLock lock,
                           FileObject target,
                           String name,
                           String ext)
                    throws IOException

  Moves this file. This allows the filesystem to perform any additional operation associated with the move. But the default implementation is encapsulated as copy and delete.

  Parameters:
    `lock` - File must be locked before renaming.
    `target` - target folder to move this file to
    `name` - new basename of file
    `ext` - new extension of file (ignored for folders)
  Returns:
    the newly created file object representing the moved file
  Throws:
    `IOException`

### toString

    public String toString()

  Gets a textual represtentation of this `FileObject`. The precise format is not defined. In particular it is probably not a resource path. For that purpose use `getPath()` directly.

  Typically it is useful for debugging purposes. Example of correct usage:

       FileObject fo = getSomeFileObject();
       ErrorManager.getDefault().log("Got a change from " + fo);

  Overrides:
    `toString` in class `Object`
  Returns:
    some representation of this file object

### getPath

    public String getPath()

  Get the full resource path of this file object starting from the filesystem root. Folders are separated with forward slashes. File extensions, if present, are included. The root folder's path is the empty string. The path of a folder never ends with a slash.

  Subclasses are strongly encouraged to override this method.

  Never use this to get a display name for the file! Use `FileUtil.getFileDisplayName(org.openide.filesystems.FileObject)`.

  Do not use this method to find a file path on disk! Use `FileUtil.toFile(org.openide.filesystems.FileObject)`.

  Returns:
    the path, for example `path/from/root.ext`
  Since:
    3.7
  See Also:
    `FileSystem.findResource(java.lang.String)`

### getPackageNameExt

    public String getPackageNameExt(char separatorChar,
                                    char extSepChar)

  Deprecated. Please use the ClassPath API instead.

  Get fully-qualified filename. Does so by walking through all folders to the root of the filesystem. Separates files with provided `separatorChar`. The extension, if present, is separated from the basename with `extSepChar`.

  Note: `fo.getPath()` will have the same effect as using this method with `/` and `.` (the standard path and extension delimiters).

  Parameters:
    `separatorChar` - char to separate folders and files
    `extSepChar` - char to separate extension
  Returns:
    the fully-qualified filename

### getPackageName

    public String getPackageName(char separatorChar)

  Deprecated. Please use the ClassPath API instead.

  Get fully-qualified filename, but without extension. Like `getPackageNameExt(char, char)` but omits the extension.

  Parameters:
    `separatorChar` - char to separate folders and files
  Returns:
    the fully-qualified filename

### getNameExt

    public String getNameExt()

  Getter for name and extension of a file object. Dot is used as separator between name and ext.

  Returns:
    string name of the file in the folder (with extension)

### getFileSystem

    public abstract FileSystem getFileSystem()
                                      throws FileStateInvalidException

  Get the filesystem containing this file.

  Note that it may be possible for a stale file object to exist which refers to a now-defunct filesystem. If this is the case, this method will throw an exception.

  Returns:
    the filesystem
  Throws:
    `FileStateInvalidException` - if the reference to the file system has been lost (e.g., if the filesystem was deleted)

### getParent

    public abstract FileObject getParent()

  Get parent folder. The returned object will satisfy `isFolder()`.

  Returns:
    the parent folder or `null` if this object `isRoot()`.

### isFolder

    public abstract boolean isFolder()

  Test whether this object is a folder.

  Returns:
    true if the file object is a folder (i.e., can have children)

### lastModified

    public abstract Date lastModified()

  Get last modification time.

  Returns:
    the date

### isRoot

    public abstract boolean isRoot()

  Test whether this object is the root folder. The root should always be a folder.

  Returns:
    true if the object is the root of a filesystem

### isData

    public abstract boolean isData()

  Test whether this object is a data object. This is exclusive with `isFolder()`.

  Returns:
    true if the file object represents data (i.e., can be read and written)

### isValid

    public abstract boolean isValid()

### existsExt

    public boolean existsExt(String ext)

  Test whether there is a file with the same basename and only a changed extension in the same folder. The default implementation asks this file's parent using `getFileObject(String name, String ext)`.

  Parameters:
    `ext` - the alternate extension
  Returns:
    true if there is such a file

### delete

    public abstract void delete(FileLock lock)
                         throws IOException

  Delete this file. If the file is a folder and it is not empty then all of its contents are also recursively deleted.

  Parameters:
    `lock` - the lock obtained by a call to `lock()`
  Throws:
    `IOException` - if the file could not be deleted

### delete

    public final void delete()
                      throws IOException

  Delete this file. If the file is a folder and it is not empty then all of its contents are also recursively deleted. FileObject is locked before delete and finally is this lock released.

  Throws:
    `IOException` - if the file could not be deleted or FileAlreadyLockedException if the file is already locked `lock()`
  Since:
    1.15

### getAttribute

    public abstract Object getAttribute(String attrName)

  Get the file attribute with the specified name.

  Parameters:
    `attrName` - name of the attribute
  Returns:
    appropriate (serializable) value or `null` if the attribute is unset (or could not be properly restored for some reason)

### setAttribute

    public abstract void setAttribute(String attrName,
                                      Object value)
                               throws IOException

  Set the file attribute with the specified name.

  Parameters:
    `attrName` - name of the attribute
    `value` - new value or `null` to clear the attribute. Must be serializable, although particular filesystems may or may not use serialization to store attribute values.
  Throws:
    `IOException` - if the attribute cannot be set. If serialization is used to store it, this may in fact be a subclass such as `NotSerializableException`.

### getAttributes

    public abstract Enumeration getAttributes()

  Get all file attribute names for this file.

  Returns:
    enumeration of keys (as strings)

### hasExt

    public final boolean hasExt(String ext)

  Test whether this file has the specified extension.

  Parameters:
    `ext` - the extension the file should have
  Returns:
    true if the text after the last period (`.`) is equal to the given extension

### addFileChangeListener

    public abstract void addFileChangeListener(FileChangeListener fcl)

  Add new listener to this object.

  Parameters:
    `fcl` - the listener

### removeFileChangeListener

    public abstract void removeFileChangeListener(FileChangeListener fcl)

  Remove listener from this object.

  Parameters:
    `fcl` - the listener

### fireFileDataCreatedEvent

    protected void fireFileDataCreatedEvent(Enumeration en,
                                            FileEvent fe)

  Fire data creation event.

  Parameters:
    `en` - enumeration of `FileChangeListener`s that should receive the event
    `fe` - the event to fire in this object

### fireFileFolderCreatedEvent

    protected void fireFileFolderCreatedEvent(Enumeration en,
                                              FileEvent fe)

  Fire folder creation event.

  Parameters:
    `en` - enumeration of `FileChangeListener`s that should receive the event
    `fe` - the event to fire in this object

### fireFileChangedEvent

    protected void fireFileChangedEvent(Enumeration en,
                                        FileEvent fe)

  Fire file change event.

  Parameters:
    `en` - enumeration of `FileChangeListener`s that should receive the event
    `fe` - the event to fire in this object

### fireFileDeletedEvent

    protected void fireFileDeletedEvent(Enumeration en,
                                        FileEvent fe)

  Fire file deletion event.

  Parameters:
    `en` - enumeration of `FileChangeListener`s that should receive the event
    `fe` - the event to fire in this object

### fireFileAttributeChangedEvent

    protected void fireFileAttributeChangedEvent(Enumeration en,
                                                 FileAttributeEvent fe)

  Fire file attribute change event.

  Parameters:
    `en` - enumeration of `FileChangeListener`s that should receive the event
    `fe` - the event to fire in this object

### fireFileRenamedEvent

    protected void fireFileRenamedEvent(Enumeration en,
                                        FileRenameEvent fe)

  Fire file rename event.

  Parameters:
    `en` - enumeration of `FileChangeListener`s that should receive the event
    `fe` - the event to fire in this object

### getMIMEType

    public String getMIMEType()

  Get the MIME type of this file. The MIME type identifies the type of the file's contents and should be used in the same way as in the Java Activation Framework or in the `java.awt.datatransfer` package.

  The default implementation calls `FileUtil.getMIMEType(java.lang.String)`. (As a fallback return value, `content/unknown` is used.)

  Returns:
    the MIME type textual representation, e.g. `"text/plain"`; never `null`

### getSize

    public abstract long getSize()

  Get the size of the file.

  Returns:
    the size of the file in bytes or zero if the file does not contain data (does not exist or is a folder).

### getInputStream

    public abstract InputStream getInputStream()
                                        throws FileNotFoundException

  Get input stream.

  Returns:
    an input stream to read the contents of this file
  Throws:
    `FileNotFoundException` - if the file does not exists, is a folder rather than a regular file or is invalid

### getOutputStream

    public abstract OutputStream getOutputStream(FileLock lock)
                                          throws IOException

  Get output stream.

  Parameters:
    `lock` - the lock that belongs to this file (obtained by a call to `lock()`)
  Returns:
    output stream to overwrite the contents of this file
  Throws:
    `IOException` - if an error occures (the file is invalid, etc.)

### lock

    public abstract FileLock lock()
                           throws IOException

  Lock this file.

  Returns:
    lock that can be used to perform various modifications on the file
  Throws:
    `FileAlreadyLockedException` - if the file is already locked
    `UserQuestionException` - in case when the lock cannot be obtained now, but the underlaying implementation is able to do it after some complex/dangerous/long-lasting operation and request confirmation from the user
    `IOException`

### setImportant

    public abstract void setImportant(boolean b)

  Deprecated. No longer used. Instead use `SharabilityQuery`.

  Indicate whether this file is important from a user perspective. This method allows a filesystem to distingush between important and unimportant files when this distinction is possible.

  For example: Java sources have important `.java` files and unimportant `.class` files. If the filesystem provides an "archive" feature it should archive only `.java` files.

  Parameters:
    `b` - true if the file should be considered important

### getChildren

    public abstract FileObject[] getChildren()

  Get all children of this folder (files and subfolders). If the file does not have children (does not exist or is not a folder) then an empty array should be returned. No particular order is assumed.

  Returns:
    array of direct children
  See Also:
    `getChildren(boolean)`, `getFolders(boolean)`, `getData(boolean)`

### getChildren

    public Enumeration getChildren(boolean rec)

  Enumerate all children of this folder. If the children should be enumerated recursively, first all direct children are listed; then children of direct subfolders; and so on.

  Parameters:
    `rec` - whether to enumerate recursively
  Returns:
    enumeration of type `FileObject`

### getFolders

    public Enumeration getFolders(boolean rec)

  Enumerate the subfolders of this folder.

  Parameters:
    `rec` - whether to recursively list subfolders
  Returns:
    enumeration of type `FileObject` (satisfying `isFolder()`)

### getData

    public Enumeration getData(boolean rec)

  Enumerate all data files in this folder.

  Parameters:
    `rec` - whether to recursively search subfolders
  Returns:
    enumeration of type `FileObject` (satisfying `isData()`)

### getFileObject

    public abstract FileObject getFileObject(String name,
                                             String ext)

  Retrieve file or folder contained in this folder by name. Note that neither file nor folder is created on disk.

  Parameters:
    `name` - basename of the file or folder (in this folder)
    `ext` - extension of the file; `null` or `""` if the file should have no extension or if folder is requested
  Returns:
    the object representing this file or `null` if the file or folder does not exist
  Throws:
    `IllegalArgumentException` - if `this` is not a folder

### getFileObject

    public FileObject getFileObject(String relativePath)

  Retrieve file or folder relative to a current folder, with a given relative path. Note that neither file nor folder is created on disk. This method isn't final since revision 1.93.

  Parameters:
    `relativePath` - is just basename of the file or (since 4.16) the relative path delimited by '/'
  Returns:
    the object representing this file or `null` if the file or folder does not exist
  Throws:
    `IllegalArgumentException` - if `this` is not a folder

### createFolder

    public abstract FileObject createFolder(String name)
                                     throws IOException

  Create a new folder below this one with the specified name. Fires `FileChangeListener.fileFolderCreated(org.openide.filesystems.FileEvent)`.

  Parameters:
    `name` - the name of folder to create. Periods in name are allowed (but no slashes).
  Returns:
    the new folder
  Throws:
    `IOException` - if the folder cannot be created (e.g. already exists), or if `this` is not a folder
  See Also:
    `FileUtil.createFolder(org.openide.filesystems.FileObject, java.lang.String)`

### createData

    public abstract FileObject createData(String name,
                                          String ext)
                                   throws IOException

  Create new data file in this folder with the specified name. Fires `FileChangeListener.fileDataCreated(org.openide.filesystems.FileEvent)`.

  Parameters:
    `name` - the name of data object to create (can contain a period, but no slashes)
    `ext` - the extension of the file (or `null` or `""`)
  Returns:
    the new data file object
  Throws:
    `IOException` - if the file cannot be created (e.g. already exists), or if `this` is not a folder
  See Also:
    `FileUtil.createData(org.openide.filesystems.FileObject, java.lang.String)`

### createData

    public FileObject createData(String name)
                          throws IOException

  Create new data file in this folder with the specified name. Fires `FileChangeListener.fileDataCreated(org.openide.filesystems.FileEvent)`.

  Parameters:
    `name` - the name of data object to create (can contain a period, but no slashes)
  Returns:
    the new data file object
  Throws:
    `IOException` - if the file cannot be created (e.g. already exists), or if `this` is not a folder
  Since:
    1.17
  See Also:
    `FileUtil.createData(org.openide.filesystems.FileObject, java.lang.String)`

### isReadOnly

    public abstract boolean isReadOnly()

  Deprecated. Please use the `canWrite()`.

  Test whether this file can be written to or not.

  The value returned from this method should indicate the capabilities of the file from the point of view of users of the FileObject's API, the actual state of the file on a disk does not matter if the implementation of the filesystem can change it when requested.

  The result returned from this method should be tight together with the expected behaviour of `getOutputStream`. If it is likely that the method successfully returns a stream that can be written to, let the `isReadOnly` return `false`.

  Also other fileobject methods like `delete` are suggested to be connected to result of this method. If not read only, then it can be deleted, etc.

  It is a good idea to call this method before attempting to perform any operation on the FileObject that might throw an IOException simply because it is read-only. If isReadOnly returns true, the operation may be skipped, or the user notified that it cannot be done. However it is often desirable for the user to be able to continue the operation in case the filesystem supports making a file writable. In this case calling code should:

  1. Call `lock()` and catch any exception thrown.
  2. Then:
     - If no exception is thrown, proceed with the operation.
     - If a `UserQuestionException` is thrown, call `UserQuestionException.confirmed()` on it (asynchronously - do not block any important threads). If `true`, proceed with the operation. If `false`, exit. If an `IOException` is thrown, notify it and exit.
     - If another `IOException` is thrown, call `isReadOnly()`. If `true`, ignore the exception (it is expected). If `false`, notify it.
     In either case, exit.

  Returns:
    `true` if file is read-only

### canWrite

    public boolean canWrite()

  Tests if this file can be written to.

  The default implementation simply uses `java.io.File.canWrite` if there exists conversion to `java.io.File` (see `FileUtil.toFile(org.openide.filesystems.FileObject)`). If conversion is not possible, then deprecated method `isReadOnly()` is used.

  Returns:
    true if this file can be written, false if not.
  Since:
    3.31

### canRead

    public boolean canRead()

  Tests if this file can be read.

  The default implementation simply uses `java.io.File.canRead` if there exists conversion to `java.io.File` (see `FileUtil.toFile(org.openide.filesystems.FileObject)`). If conversion is not possible, then `true` is returned.

  Returns:
    true if this file can be read, false if not.
  Since:
    3.31

### refresh

    public void refresh(boolean expected)

  Should check for external modifications. For folders it should reread the content of disk, for data file it should check for the last time the file has been modified.

  Parameters:
    `expected` - should the file events be marked as expected change or not?
  See Also:
    `FileEvent.isExpected()`

### refresh

    public void refresh()

  Should check for external modifications. For folders it should reread the content of disk, for data file it should check for the last time the file has been modified.

  The file events are marked as unexpected.

### getURL

    public final URL getURL()
                     throws FileStateInvalidException

  Get URL that can be used to access this file. If the file object does not correspond to a disk file or JAR entry, the URL will only be usable within the IDE as it uses a special protocol handler. Otherwise an attempt is made to produce an external URL.

  Returns:
    URL of this file object
  Throws:
    `FileStateInvalidException` - if the file is not valid
  See Also:
    `URLMapper.findURL(org.openide.filesystems.FileObject, int)`, `URLMapper.INTERNAL`

### isVirtual

    public boolean isVirtual()

  Tests if file really exists or is missing. Some operation on it may be restricted.

  Returns:
    true indicates that the file is missing.
  Since:
    1.9

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| org.openide.filesystems 6.4.22
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Built on December 7 2006. | Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.