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 file system. 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.
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 name) Retrieve file or folder contained in this folder by name (no extension).
abstract FileObject	getFileObject(String name, String ext) Retrieve file or folder contained in this folder by name.
abstract FileSystem	getFileSystem() Get the file system 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) Get fully-qualified filename, but without extension.
String	getPackageNameExt(char separatorChar, char extSepChar) Get fully-qualified filename.
abstract FileObject	getParent() Get parent folder.
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() Test whether this file can be written to or not.
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) Indicate whether this file is important from a user perspective.
String	toString() Get fully-qualified filename.

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 file systems 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)

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

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

toString

public String toString()

Get fully-qualified filename. Does so by walking through all folders to the root of the file system. Separates files with provided '/'. The extension, if present, is separated from the basename with '.'.

Note: fo.getPackageNameExt ('/','.') will have the same effect as using this method. But it is not guaranteed that this will be so.

Overrides:

toString in class Object

Returns:

the fully-qualified filename e.g. path/from/root.ext

getPackageNameExt

public String getPackageNameExt(char separatorChar,
                                char extSepChar)

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

Note: fo.toString() 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)

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 file system containing this file.

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

Returns:

the file system

Throws:

FileStateInvalidException - if the reference to the file system has been lost (e.g., if the file system 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 file system

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 file systems 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:

l - the listener

removeFileChangeListener

public abstract void removeFileChangeListener(FileChangeListener fcl)

Remove listener from this object.

Parameters:

l - the listener

fireFileDataCreatedEvent

protected void fireFileDataCreatedEvent(Enumeration en,
                                        FileEvent fe)

Fire data creation event.

Parameters:

en - enumeration of FileChangeListeners 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 FileChangeListeners 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 FileChangeListeners 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 FileChangeListeners 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 FileChangeListeners 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 FileChangeListeners 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 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

setImportant

public abstract void setImportant(boolean b)

Indicate whether this file is important from a user perspective. This method allows a file system 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 file system 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 final FileObject getFileObject(String name)

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

Parameters:

name - basename of the file (in this folder)

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 fileCreated event.

Parameters:

name - the name of folder to create. Periods in name are allowed.

Returns:

the new folder

Throws:

IOException - if the folder cannot be created (e.g. already exists)

createData

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

Create new data file in this folder with the specified name. Fires fileCreated event.

Parameters:

name - the name of data object to create (can contain a period)

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)

createData

public FileObject createData(String name)
                      throws IOException

Create new data file in this folder with the specified name. Fires fileCreated event.

Parameters:

name - the name of data object to create (can contain a period)

Returns:

the new data file object

Throws:

IOException - if the file cannot be created (e.g. already exists)

Since:

1.17

isReadOnly

public abstract boolean isReadOnly()

Test whether this file can be written to or not.

Returns:

true if file is read-only

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. The URL is only usable within the IDE as it uses a special protocol handler. NbClassLoader must be installed (this is done automatically in the Repository constructor).

Returns:

URL of this file object

Throws:

FileStateInvalidException - if the file is not valid

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