org.openide.filesystems 7.3.1

org.openide.filesystems
Class FileSystem

java.lang.Object
  extended by 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. Classes that implement it should follow JavaBean conventions because when a new instance of a filesystem 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 filesystem in the Repository). If you wish to safely deserialize a file system, you should after deserialization try to replace it with a filesystem of the same name in the Repository.

See Also:
Serialized Form

Nested Class Summary
static interface FileSystem.AtomicAction
          An action that it is to be called atomically with respect to filesystem event notification.
static class FileSystem.Environment
          Deprecated. Please use the ClassPath API instead.
static interface FileSystem.HtmlStatus
          Extension interface for Status provides HTML-formatted annotations.
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_DISPLAY_NAME
          Property name giving display name of filesystem.
static String PROP_HIDDEN
          Deprecated. The property is now hidden.
static String PROP_READ_ONLY
          Property name giving read-only state.
static String PROP_ROOT
          Property name giving root folder of filesystem.
static String PROP_SYSTEM_NAME
          Deprecated. This system name should now be avoided in favor of identifying files persistently by URL.
static String PROP_VALID
          Property name indicating validity of filesystem.
 
Constructor Summary
FileSystem()
          Default constructor.
 
Method Summary
 void addFileChangeListener(FileChangeListener fcl)
          Add new listener to this object.
 void addFileStatusListener(FileStatusListener listener)
          Registers FileStatusListener to receive events.
 void addNotify()
          Notifies this filesystem 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)
          Deprecated. Please use the ClassPath API instead, or use findResource(java.lang.String) if you are not interested in classpaths.
abstract  FileObject findResource(String name)
          Finds a file given its full resource path.
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 filesystem.
 SystemAction[] getActions(Set<FileObject> foSet)
          Get actions appropriate to a certain file selection.
 FileSystemCapability getCapability()
          Deprecated. Capabilities are no longer used.
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()
          Deprecated. The system name should now be avoided in favor of identifying files persistently by URL.
 boolean isDefault()
          Returns true if the filesystem is default.
 boolean isHidden()
          Deprecated. This property is now useless.
protected  boolean isPersistent()
          Deprecated. This property is long since useless.
abstract  boolean isReadOnly()
          Test if the filesystem is read-only or not.
 boolean isValid()
          Test whether filesystem is valid.
 void prepareEnvironment(FileSystem.Environment env)
          Deprecated. Please use the ClassPath API instead.
 void refresh(boolean expected)
          Should check for external modifications.
 void removeFileChangeListener(FileChangeListener fcl)
          Remove listener from this object.
 void removeFileStatusListener(FileStatusListener listener)
          Removes FileStatusListener from the list of listeners.
 void removeNotify()
          Notifies this filesystem 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)
          Deprecated. Capabilities are no longer used.
 void setHidden(boolean hide)
          Deprecated. This property is now useless.
protected  void setSystemName(String name)
          Deprecated. The system name should now be avoided in favor of identifying files persistently by URL.
 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 filesystem.

See Also:
Constant Field Values

PROP_HIDDEN

@Deprecated
public static final String PROP_HIDDEN
Deprecated. The property is now hidden.
Property name indicating whether filesystem is hidden.

See Also:
Constant Field Values

PROP_SYSTEM_NAME

@Deprecated
public static final String PROP_SYSTEM_NAME
Deprecated. This system name should now be avoided in favor of identifying files persistently by URL.
Property name giving internal system name of filesystem.

See Also:
Constant Field Values

PROP_DISPLAY_NAME

public static final String PROP_DISPLAY_NAME
Property name giving display name of filesystem.

Since:
2.1
See Also:
Constant Field Values

PROP_ROOT

public static final String PROP_ROOT
Property name giving root folder of filesystem.

See Also:
Constant Field Values

PROP_READ_ONLY

public static final String PROP_READ_ONLY
Property name giving read-only state.

See Also:
Constant Field Values
Constructor Detail

FileSystem

public FileSystem()
Default constructor.

Method Detail

refresh

public void refresh(boolean expected)
Should check for external modifications. All existing FileObjects will be refreshed. 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 default implementation is to do nothing, in contradiction to the rest of the description. Unless subclasses override it, the method does not work.

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

isValid

public final boolean isValid()
Test whether filesystem is valid. Generally invalidity would be caused by a name conflict in the filesystem pool.

Returns:
true if the filesystem is valid

setHidden

@Deprecated
public final void setHidden(boolean hide)
Deprecated. This property is now useless.

Set hidden state of the object. A hidden filesystem 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 filesystem should be hidden

isHidden

@Deprecated
public final boolean isHidden()
Deprecated. This property is now useless.

Getter for the hidden property.


isPersistent

@Deprecated
protected boolean isPersistent()
Deprecated. This property is long since useless.

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

This can be used when the pool contains system level and user level filesystems. 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 filesystem 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.

Note: for most purposes it is probably a bad idea to use this method. Instead look at FileUtil.getFileDisplayName(org.openide.filesystems.FileObject).

Returns:
user presentable name of the filesystem

getSystemName

@Deprecated
public final String getSystemName()
Deprecated. The system name should now be avoided in favor of identifying files persistently by URL.

Internal (system) name of the filesystem. Should uniquely identify the filesystem, as it will be used during serialization of its files. The preferred way of doing this is to concatenate the name of the filesystem 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 filesystem. 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

@Deprecated
protected final void setSystemName(String name)
                            throws PropertyVetoException
Deprecated. The system name should now be avoided in favor of identifying files persistently by URL.

Changes system name of the filesystem. 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.

Returns:
true if this is 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

@Deprecated
public FileObject find(String aPackage,
                                  String name,
                                  String ext)
Deprecated. Please use the ClassPath API instead, or use findResource(java.lang.String) if you are not interested in classpaths.

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 a file given its full resource path.

Parameters:
name - the resource path, e.g. "dir/subdir/file.ext" or "dir/subdir" or "dir"
Returns:
a file object with the given path or null if no such file exists

getActions

public abstract SystemAction[] getActions()
Returns an array of actions that can be invoked on any file in this filesystem. These actions should preferably support the Menu, Popup, and Toolbar presenters.

Returns:
array of available actions

getActions

public SystemAction[] getActions(Set<FileObject> foSet)
Get actions appropriate to a certain file selection. By default, returns the same list as getActions().

Parameters:
foSet - one or more files which may be selected
Returns:
zero or more actions appropriate to those files

toString

public String toString()
Overrides:
toString in class Object

prepareEnvironment

@Deprecated
public void prepareEnvironment(FileSystem.Environment env)
                        throws EnvironmentNotSupportedException
Deprecated. Please use the ClassPath API instead.

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 filesystem

getCapability

@Deprecated
public final FileSystemCapability getCapability()
Deprecated. Capabilities are no longer used.

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


setCapability

@Deprecated
protected final void setCapability(FileSystemCapability capability)
Deprecated. Capabilities are no longer used.

Allows subclasses to change a set of capabilities of the filesystem.

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 filesystem 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:
event - 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 filesystem 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 filesystem that it has been removed from the repository. Concrete filesystem 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.


addFileChangeListener

public final void addFileChangeListener(FileChangeListener fcl)
Add new listener to this object.

Parameters:
fcl - the listener
Since:
2.8

removeFileChangeListener

public final void removeFileChangeListener(FileChangeListener fcl)
Remove listener from this object.

Parameters:
fcl - the listener
Since:
2.8

org.openide.filesystems 7.3.1

Built on January 29 2008.  |  Portions Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.