org.openide.filesystems 7.13.1 1

org.openide.filesystems
Class AbstractFileSystem

java.lang.Object
  extended by org.openide.filesystems.FileSystem
      extended by org.openide.filesystems.AbstractFileSystem
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
JarFileSystem, LocalFileSystem, XMLFileSystem

public abstract class AbstractFileSystem
extends FileSystem

This convenience implementation does much of the hard work of FileSystem and is generally more pleasant to create subclasses of.

It caches information about the filesystem in memory and periodically refreshes its content. Many other operations are performed in a safer manner so as to reuse experience of NetBeans developers; should be substantially simpler to subclass than FileSystem itself.

Besides what is mentioned here, the AbstractFileSystem subclass be configurable as a JavaBean (e.g. server address, prefix, whatever it needs).

First of all, you need not separately implement a FileObject - this is taken care of for you. You need only provide some information about how essential actions should be carried out.

You should implement getDisplayName() to set the display name.

You may cause the filesystem to automatically refresh itself at periodic intervals, in case it is not possible to be notified of changes directly. To do so, call setRefreshTime(int), e.g. from the constructor.

refreshRoot() must be called if the filesystem supports changing of its root directory (as the local filesystem does, for example).

Most of the meat of the implementation is provided by setting appropriate values for four protected variables, which should be initialized in the constructor; each represents an implementation of a separate interface handling one aspect of the filesystem.

List member

The variable list should contain an implementation of AbstractFileSystem.List. This only specifies a way of accessing the list of children in a folder.

Info member

info contains an AbstractFileSystem.Info which provides basic file statistics.

It also specifies the raw implementation of two basic types of actions: getting input and output streams for the file; and locking and unlocking it physically (optional and not to be confused with locking within NetBeans).

Change member

change is an AbstractFileSystem.Change which provides the interface to create new folders and files; delete them; and rename them (within the same directory).

Attribute member

attr is an AbstractFileSystem.Attr allowing NetBeans to read and write serializable attributes (meta-information) to be associated with the file. Such attributes are not much used any more, but they are occasionally.

There is a default implementation in DefaultAttributes which stores attributes in a file called .nbattrs in each folder for which a file has some attributes, using XML augmented by Java serialization, though the regular filesystems in NetBeans now instead store all attributes globally in $userdir/var/attributes.xml. If you do use DefaultAttributes, use it not only for attr but also for list (passing in a separate private AbstractFileSystem.List implementation to its constructor) in order to filter the .nbattrs files from view.

See Also:
Serialized Form

Nested Class Summary
static interface AbstractFileSystem.Attr
          Handle attributes of files.
static interface AbstractFileSystem.Change
          Controls modification of files.
static interface AbstractFileSystem.Info
          Information about files.
static interface AbstractFileSystem.List
          Provides access to the hierarchy of resources.
static interface AbstractFileSystem.Transfer
          Controls on moving of files.
 
Nested classes/interfaces inherited from class org.openide.filesystems.FileSystem
FileSystem.AtomicAction, FileSystem.Environment, FileSystem.HtmlStatus, FileSystem.Status
 
Field Summary
protected  AbstractFileSystem.Attr attr
          Handling of attributes for files.
protected  AbstractFileSystem.Change change
          Methods for modification of files.
protected  AbstractFileSystem.Info info
          Methods for obtaining information about files.
protected  AbstractFileSystem.List list
          Provider of hierarchy of files.
protected  AbstractFileSystem.Transfer transfer
          Methods for moving of files.
 
Fields inherited from class org.openide.filesystems.FileSystem
PROP_DISPLAY_NAME, PROP_HIDDEN, PROP_READ_ONLY, PROP_ROOT, PROP_SYSTEM_NAME, PROP_VALID
 
Constructor Summary
AbstractFileSystem()
           
 
Method Summary
protected  boolean canRead(String name)
          Tests if this file can be read.
protected  boolean canWrite(String name)
          Tests if this file can be written to.
protected  boolean checkVirtual(String name)
          This method is called from AbstractFileObject.isVirtual.
protected
<T extends FileObject>
Reference<T>
createReference(T fo)
          Creates Reference.
protected  Enumeration<? extends FileObject> existingFileObjects(FileObject fo)
          For the FileObject specified as parameter, returns the recursive enumeration of existing children fileobjects (both folders and data).
 FileObject find(String aPackage, String name, String ext)
          Deprecated. 
protected  Reference<? extends FileObject> findReference(String resourceName)
          This method allows to find Reference to resourceName
 FileObject findResource(String name)
          Finds a file given its full resource path.
 SystemAction[] getActions()
          Returns an array of actions that can be invoked on any file in this filesystem.
abstract  String getDisplayName()
          Provides a name for the system that can be presented to the user.
protected  int getRefreshTime()
          Get the number of milliseconds between automatic refreshes of the directory structure.
 FileObject getRoot()
          Getter for root folder in the filesystem.
protected  void markImportant(String name, boolean important)
          Mark the file as being important or unimportant.
 void refresh(boolean expected)
          Actually implements contract of FileSystem.refresh().
protected  void refreshResource(String name, boolean expected)
          Allows subclasses to fire that a change occured in a file or folder.
protected  FileObject refreshRoot()
          Instruct the filesystem that the root should change.
protected  void setRefreshTime(int ms)
          Set the number of milliseconds between automatic refreshes of the directory structure.
 
Methods inherited from class org.openide.filesystems.FileSystem
addFileChangeListener, addFileStatusListener, addNotify, addPropertyChangeListener, addVetoableChangeListener, fireFileStatusChanged, firePropertyChange, fireVetoableChange, getActions, getCapability, getStatus, getSystemName, isDefault, isHidden, isPersistent, isReadOnly, isValid, prepareEnvironment, removeFileChangeListener, removeFileStatusListener, removeNotify, removePropertyChangeListener, removeVetoableChangeListener, runAtomicAction, setCapability, setHidden, setSystemName, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

list

protected AbstractFileSystem.List list
Provider of hierarchy of files.


change

protected AbstractFileSystem.Change change
Methods for modification of files.


transfer

protected AbstractFileSystem.Transfer transfer
Methods for moving of files. This field can be left null if the filesystem does not require special handling handling of FileObject.move and is satified with the default implementation.


info

protected AbstractFileSystem.Info info
Methods for obtaining information about files.


attr

protected AbstractFileSystem.Attr attr
Handling of attributes for files.

Constructor Detail

AbstractFileSystem

public AbstractFileSystem()
Method Detail

refresh

public void refresh(boolean expected)
Actually implements contract of FileSystem.refresh().

Overrides:
refresh in class FileSystem
Parameters:
expected - should the file events be marked as expected change or not?
See Also:
FileEvent.isExpected()

getDisplayName

public abstract String getDisplayName()
Description copied from class: FileSystem
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).

Specified by:
getDisplayName in class FileSystem
Returns:
user presentable name of the filesystem

getRoot

public FileObject getRoot()
Description copied from class: FileSystem
Getter for root folder in the filesystem.

Specified by:
getRoot in class FileSystem
Returns:
root folder of whole filesystem

find

@Deprecated
public FileObject find(String aPackage,
                                  String name,
                                  String ext)
Deprecated. 

Description copied from class: FileSystem
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.

Overrides:
find in class FileSystem
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 FileObject findResource(String name)
Description copied from class: FileSystem
Finds a file given its full resource path.

Specified by:
findResource in class FileSystem
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

createReference

protected <T extends FileObject> Reference<T> createReference(T fo)
Creates Reference. In FileSystem, which subclasses AbstractFileSystem, you can overload method createReference(FileObject fo) to achieve another type of Reference (weak, strong etc.)

Parameters:
fo - is FileObject. It`s reference yourequire to get.
Returns:
Reference to FileObject

findReference

protected final Reference<? extends FileObject> findReference(String resourceName)
This method allows to find Reference to resourceName

Parameters:
resourceName - is name of resource
Returns:
Reference to resourceName

getActions

public SystemAction[] getActions()
Description copied from class: FileSystem
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.

Specified by:
getActions in class FileSystem
Returns:
array of available actions

setRefreshTime

protected final void setRefreshTime(int ms)
Set the number of milliseconds between automatic refreshes of the directory structure.

Parameters:
ms - number of milliseconds between two refreshes; if <= 0 then refreshing is disabled

getRefreshTime

protected final int getRefreshTime()
Get the number of milliseconds between automatic refreshes of the directory structure. By default, automatic refreshing is disabled.

Returns:
the number of milliseconds, or 0 if refreshing is disabled

refreshRoot

protected final FileObject refreshRoot()
Instruct the filesystem that the root should change. A fresh root is created. Subclasses that support root changes should use this.

Returns:
the new root

refreshResource

protected final void refreshResource(String name,
                                     boolean expected)
Allows subclasses to fire that a change occured in a file or folder. The change can be "expected" when it is a result of an user action and the user knows that such change should occur.

Parameters:
name - resource name of the file where the change occured
expected - true if the user initiated change and expects it

existingFileObjects

protected final Enumeration<? extends FileObject> existingFileObjects(FileObject fo)
For the FileObject specified as parameter, returns the recursive enumeration of existing children fileobjects (both folders and data). It doesn't create any new FileObject instances. Direct children are at the begining of the enumeration.

Parameters:
fo - the starting point for the recursive fileobject search
Returns:
enumeration of currently existing fileobjects.

checkVirtual

protected boolean checkVirtual(String name)
This method is called from AbstractFileObject.isVirtual. Tests if file really exists or is missing. Some operation on it may be restricted if returns true.

Parameters:
name - of the file
Returns:
true indicates that the file is missing.
Since:
1.9

canWrite

protected boolean canWrite(String name)
Tests if this file can be written to.

Parameters:
name - resource name
Returns:
true if this file can be written, false if not.
Since:
3.31

canRead

protected boolean canRead(String name)
Tests if this file can be read.

Parameters:
name - resource name
Returns:
true if this file can be read, false if not.
Since:
3.31

markImportant

protected void markImportant(String name,
                             boolean important)
Mark the file as being important or unimportant.

Parameters:
name - the file to mark
important - true indicates that file is important, false conversely file is unimportant.
Since:
1.9

org.openide.filesystems 7.13.1 1

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