org.openide.filesystems
Class FileSystem

java.lang.Object
  |
  +--org.openide.filesystems.FileSystem

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

AbstractFileSystem, MultiFileSystem

public abstract class FileSystem

extends Object

implements Serializable

Interface that provides basic information about a virtual filesystem in the IDE. Classes that implement it should follow JavaBean conventions because when a new instance of a file system class is inserted into the system, it should permit the user to modify it with standard Bean properties.

Implementing classes should also have associated subclasses of FileObject.

Although the class is serializable, only the hidden state and system name are serialized, and the deserialized object is by default invalid (and may be a distinct object from a valid file system in the Repository). If you wish to safely deserialize a file system, you should after deserialization try to replace it with a file system of the same name in the Repository.

See Also:

Serialized Form

Inner Class Summary

static interface	FileSystem.AtomicAction An action that it is to be called atomically with respect to file system event notification.
static class	FileSystem.Environment Interface that allows filesystems to set up the Java environment for external execution and compilation.
static interface	FileSystem.Status Allows a filesystem to annotate a group of files (typically comprising a data object) with additional markers.

Field Summary

static String	PROP_HIDDEN Property name indicating whether file system is hidden.
static String	PROP_READ_ONLY Property name giving read-only state.
static String	PROP_ROOT Property name giving root folder of file system.
static String	PROP_SYSTEM_NAME Property name giving internal system name of file system.
static String	PROP_VALID Property name indicating validity of file system.

Constructor Summary

FileSystem()
Default constructor.

Method Summary

void	addFileStatusListener(FileStatusListener listener) Registers FileStatusListener to receive events.
void	addNotify() Notifies this file system that it has been added to the repository.
void	addPropertyChangeListener(PropertyChangeListener listener) Registers PropertyChangeListener to receive events.
void	addVetoableChangeListener(VetoableChangeListener listener) Adds listener for the veto of property change.
FileObject	find(String aPackage, String name, String ext) Finds file in the filesystem by name.
abstract FileObject	findResource(String name) Finds file when its resource name is given.
protected void	fireFileStatusChanged(FileStatusEvent event) Notifies all registered listeners about change of status of some files.
protected void	firePropertyChange(String name, Object o, Object n) Fires property change event.
protected void	fireVetoableChange(String name, Object o, Object n) Fires property vetoable event.
abstract SystemAction[]	getActions() Returns an array of actions that can be invoked on any file in this file system.
SystemAction[]	getActions(Set foSet)
FileSystemCapability	getCapability() The object describing capabilities of this filesystem.
abstract String	getDisplayName() Provides a name for the system that can be presented to the user.
abstract FileObject	getRoot() Getter for root folder in the filesystem.
FileSystem.Status	getStatus() Get a status object that can annotate a set of files by changing the names or icons associated with them.
String	getSystemName() Internal (system) name of the file system.
boolean	isDefault() Returns true if the filesystem is default one of the IDE.
boolean	isHidden() Getter for the hidden property.
protected boolean	isPersistent() Tests whether file system will survive reloading of system pool.
abstract boolean	isReadOnly() Test if the filesystem is read-only or not.
boolean	isValid() Test whether file system is valid.
void	prepareEnvironment(FileSystem.Environment env) Allows filesystems to set up the environment for external execution and compilation.
void	removeFileStatusListener(FileStatusListener listener) Removes FileStatusListener from the list of listeners.
void	removeNotify() Notifies this file system that it has been removed from the repository.
void	removePropertyChangeListener(PropertyChangeListener listener) Removes PropertyChangeListener from the list of listeners.
void	removeVetoableChangeListener(VetoableChangeListener listener) Removes listener for the veto of property change.
void	runAtomicAction(FileSystem.AtomicAction run) Executes atomic action.
protected void	setCapability(FileSystemCapability capability) Allows subclasses to change a set of capabilities of the file system.
void	setHidden(boolean hide) Set hidden state of the object.
protected void	setSystemName(String name) Changes system name of the file system.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

PROP_VALID

public static final String PROP_VALID

Property name indicating validity of file system.

PROP_HIDDEN

public static final String PROP_HIDDEN

Property name indicating whether file system is hidden.

PROP_SYSTEM_NAME

public static final String PROP_SYSTEM_NAME

Property name giving internal system name of file system.

PROP_ROOT

public static final String PROP_ROOT

Property name giving root folder of file system.

PROP_READ_ONLY

public static final String PROP_READ_ONLY

Property name giving read-only state.

Constructor Detail

FileSystem

public FileSystem()

Default constructor.

Method Detail

isValid

public final boolean isValid()

Test whether file system is valid. Generally invalidity would be caused by a name conflict in the file system pool.

Returns:

true if the file system is valid

setHidden

public final void setHidden(boolean hide)

Set hidden state of the object. A hidden file system is not presented to the user in the Repository list (though it may be present in the Repository Settings list).

Parameters:

hide - true if the file system should be hidden

isHidden

public final boolean isHidden()

Getter for the hidden property.

isPersistent

protected boolean isPersistent()

Tests whether file system will survive reloading of system pool. If true then when Repository is reloading its content, it preserves this file system in the pool.

This can be used when the pool contains system level and user level file systems. The system ones should be preserved when the user changes the content (for example when he is loading a new project).

The default implementation returns false.

Returns:

true if the file system should be persistent

getDisplayName

public abstract String getDisplayName()

Provides a name for the system that can be presented to the user.

This call should never be used to attempt to identify the file root of the filesystem. On some systems it may happen to look the same but this is a coincidence and may well change in the future. Either check whether you are working with a LocalFileSystem or similar implementation and use LocalFileSystem.getRootDirectory(); or better, try FileUtil.toFile(org.openide.filesystems.FileObject) which is designed to do this correctly.

Returns:

user presentable name of the file system

getSystemName

public final String getSystemName()

Internal (system) name of the file system. Should uniquely identify the file system, as it will be used during serialization of its files. The preferred way of doing this is to concatenate the name of the file system type (e.g. the class) and the textual form of its parameters.

A change of the system name should be interpreted as a change of the internal state of the file system. For example, if the root directory is moved to different location, one should rebuild representations for all files in the system.

This call should never be used to attempt to identify the file root of the filesystem. On Unix systems it may happen to look the same but this is a coincidence and may well change in the future. Either check whether you are working with a LocalFileSystem or similar implementation and use LocalFileSystem.getRootDirectory(); or better, try FileUtil.toFile(org.openide.filesystems.FileObject) which is designed to do this correctly.

Returns:

string with system name

setSystemName

protected final void setSystemName(String name)
                            throws PropertyVetoException

Changes system name of the file system. This property is bound and constrained: first of all all vetoable listeners are asked whether they agree with the change. If so, the change is made and all change listeners are notified of the change.

Warning: this method is protected so that only subclasses can change the system name.

Parameters:

name - new system name

Throws:

PropertyVetoException - if the change is not allowed by a listener

isDefault

public final boolean isDefault()

Returns true if the filesystem is default one of the IDE.

See Also:

Repository.getDefaultFileSystem()

isReadOnly

public abstract boolean isReadOnly()

Test if the filesystem is read-only or not.

Returns:

true if the system is read-only

getRoot

public abstract FileObject getRoot()

Getter for root folder in the filesystem.

Returns:

root folder of whole filesystem

find

public FileObject find(String aPackage,
                       String name,
                       String ext)

Finds file in the filesystem by name.

The default implementation converts dots in the package name into slashes, concatenates the strings, adds any extension prefixed by a dot and calls the findResource method.

Note: when both of name and ext are null then name and extension should be ignored and scan should look only for a package.

Parameters:

aPackage - package name where each package component is separated by a dot

name - name of the file (without dots) or null if one wants to obtain a folder (package) and not a file in it

ext - extension of the file (without leading dot) or null if one needs a package and not a file

Returns:

a file object that represents a file with the given name or null if the file does not exist

findResource

public abstract FileObject findResource(String name)

Finds file when its resource name is given. The name has the usual format for the ClassLoader.getResource(String) method. So it may consist of "package1/package2/filename.ext". If there is no package, it may consist only of "filename.ext".

Parameters:

name - resource name

Returns:

FileObject that represents file with given name or null if the file does not exist

getActions

public abstract SystemAction[] getActions()

Returns an array of actions that can be invoked on any file in this file system. These actions should preferably support the Menu, Popup, and Toolbar presenters.

Returns:

array of available actions

getActions

public SystemAction[] getActions(Set foSet)

toString

public String toString()

Overrides:

toString in class Object

prepareEnvironment

public void prepareEnvironment(FileSystem.Environment env)
                        throws EnvironmentNotSupportedException

Allows filesystems to set up the environment for external execution and compilation. Each filesystem can add its own values that influence the environment. The set of operations that can modify environment is described by the FileSystem.Environment interface.

The default implementation throws an exception to signal that it does not support external compilation or execution.

Parameters:

env - the environment to setup

Throws:

EnvironmentNotSupportedException - if external execution and compilation cannot be supported

getStatus

public FileSystem.Status getStatus()

Get a status object that can annotate a set of files by changing the names or icons associated with them.

The default implementation returns a status object making no modifications.

Returns:

the status object for this file system

getCapability

public final FileSystemCapability getCapability()

The object describing capabilities of this filesystem. Subclasses can override it.

setCapability

protected final void setCapability(FileSystemCapability capability)

Allows subclasses to change a set of capabilities of the file system.

Parameters:

capability - the capability to use

runAtomicAction

public final void runAtomicAction(FileSystem.AtomicAction run)
                           throws IOException

Executes atomic action. The atomic action represents a set of operations constituting one logical unit. It is guaranteed that during execution of such an action no events about changes in the file system will be fired.

Warning: the action should not take a significant amount of time, and should finish as soon as possible--otherwise all event notifications will be blocked.

Warning: do not be misled by the name of this method; it does not require the filesystem to treat the changes as an atomic block of commits in the database sense! That is, if an exception is thrown in the middle of the action, partial results will not be undone (in general this would be impossible to implement for all filesystems anyway).

Parameters:

run - the action to run

Throws:

IOException - if there is an IOException thrown in the actions' run method

addFileStatusListener

public final void addFileStatusListener(FileStatusListener listener)

Registers FileStatusListener to receive events. The implementation registers the listener only when getStatus () is overriden to return a special value.

Parameters:

listener - The listener to register.

removeFileStatusListener

public final void removeFileStatusListener(FileStatusListener listener)

Removes FileStatusListener from the list of listeners.

Parameters:

listener - The listener to remove.

fireFileStatusChanged

protected final void fireFileStatusChanged(FileStatusEvent event)

Notifies all registered listeners about change of status of some files.

Parameters:

e - The event to be fired

addVetoableChangeListener

public final void addVetoableChangeListener(VetoableChangeListener listener)

Adds listener for the veto of property change.

Parameters:

listener - the listener

removeVetoableChangeListener

public final void removeVetoableChangeListener(VetoableChangeListener listener)

Removes listener for the veto of property change.

Parameters:

listener - the listener

fireVetoableChange

protected final void fireVetoableChange(String name,
                                        Object o,
                                        Object n)
                                 throws PropertyVetoException

Fires property vetoable event.

Parameters:

name - name of the property

o - old value of the property

n - new value of the property

Throws:

PropertyVetoException - if an listener vetoed the change

addPropertyChangeListener

public final void addPropertyChangeListener(PropertyChangeListener listener)

Registers PropertyChangeListener to receive events.

Parameters:

listener - The listener to register.

removePropertyChangeListener

public final void removePropertyChangeListener(PropertyChangeListener listener)

Removes PropertyChangeListener from the list of listeners.

Parameters:

listener - The listener to remove.

firePropertyChange

protected final void firePropertyChange(String name,
                                        Object o,
                                        Object n)

Fires property change event.

Parameters:

name - name of the property

o - old value of the property

n - new value of the property

addNotify

public void addNotify()

Notifies this file system that it has been added to the repository. Various initialization tasks could go here. The default implementation does nothing.

Note that this method is advisory and serves as an optimization to avoid retaining resources for too long etc. Filesystems should maintain correct semantics regardless of whether and when this method is called.

removeNotify

public void removeNotify()

Notifies this file system that it has been removed from the repository. Concrete file system implementations could perform clean-up here. The default implementation does nothing.

Note that this method is advisory and serves as an optimization to avoid retaining resources for too long etc. Filesystems should maintain correct semantics regardless of whether and when this method is called.