MultiFileSystem (NetBeans File Systems API) - NetBeans API Javadoc 5.0.0

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.openide.filesystems
Class MultiFileSystem

java.lang.Object
  org.openide.filesystems.FileSystem
      org.openide.filesystems.MultiFileSystem

All Implemented Interfaces:: Serializable

public class MultiFileSystem
extends FileSystem

General base class for filesystems which proxy to others.

This filesystem has no form of storage in and of itself. Rather, it composes and proxies one or more "delegate" filesystems. The result is that of a "layered" sandwich of filesystems, each able to provide files to appear in the merged result. The layers are ordered so that a filesystem in "front" can override one in "back". Often the frontmost layer will be writable, and all changes to the filesystem are sent to this layer, but that behavior is configurable.

Creating a new MultiFileSystem is easy in the simplest cases: just call MultiFileSystem(FileSystem[]) and pass a list of delegates. If you pass it only read-only delegates, the composite will also be read-only. Or you may pass it one or more writable filesystems (make sure the first file system is one of them); then it will be able to act as a writable file system, by default storing all actual changes on the first file system.

This class is intended to be subclassed more than to be used as is, since typically a user of it will want finer-grain control over several aspects of its operation. When subclassed, delegates may be changed dynamically and the "contents" of the composite filesystem will automatically be updated.

One of the more common methods to override is createWritableOn(java.lang.String), which should provide the delegate filesystem which should be used to store changes to the indicated file (represented as a resource path). Normally, this is hardcoded to provide the first filesystem (assuming it is writable); subclasses may store changes on another filesystem, or they may select a filesystem to store changes on according to (for example) file extension. This could be used to separate source from compiled/deployable files, for instance. Or some filesystems may prefer to attempt to make changes in whatever filesystem provided the original file, assuming it is writable; this is also possible, getting information about the file's origin from findSystem(org.openide.filesystems.FileObject).

Another likely candidate for overriding is findResourceOn(org.openide.filesystems.FileSystem, java.lang.String). Normally this method just looks up resources by the normal means on delegate filesystems and provides the resultant file objects. However it could be customized to "warp" the delegates somehow; for example, selecting a different virtual root for one of them.

notifyMigration(org.openide.filesystems.FileObject) provides a means for subclasses to update some state (for example, visual annotations) when the filesystem used to produce a given file changes dynamically. This most often happens when a file provided by a back delegate is written to, and the result stored on the foremost delegate, but it could occur in other situations too (e.g. change of delegates, removal of overriding file on underlying front delegate, etc.).

When new files are added to the MultiFileSystem, normally they will be physically added to the foremost delegate, although as previously mentioned they can be customized. When their contents (or attributes) are changed, by default these changes are again made in the foremost delegate. But what if a file is deleted? There must be a way to indicate on the foremost delegate that it should not appear in the composite (even while it remains in one of the delegates). For this reason, MultiFileSystem uses "masks" which are simply empty files named according to the file they should hide, but with the suffix _hidden. Thus, for example, if there is a file subdir/readme.txt_hidden in a front delegate it will hide any files named subdir/readme.txt in delegates further back. These masks are automatically created as needed when files are "deleted" from MultiFileSystem; or delegate filesystems may explicitly provide them. Normally the mask files are not themselves visible as FileObjects, since they are an artifact of the deletion logic. However, when nesting MultiFileSystems inside other MultiFileSystems, it can be useful to have delegates be able to mask files not provided by their immediate siblings, but by cousins. For this reason, nested subclasses may call setPropagateMasks(boolean) to make the mask files propagate up one or more nesting levels and thus remain potent against cousin delegates.

See Also:: Serialized Form

Nested Class Summary

Nested classes inherited from class org.openide.filesystems.FileSystem

FileSystem.AtomicAction, FileSystem.Environment, FileSystem.HtmlStatus, FileSystem.Status

Field Summary

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

protected MultiFileSystem()
          Creates new empty MultiFileSystem.

MultiFileSystem(FileSystem[] fileSystems)
          Creates new MultiFileSystem.

Method Summary

void addNotify()
          Notifies all encapsulated filesystems in advance to superclass behaviour.

protected Set createLocksOn(String name)
          When a file is about to be locked this method is consulted to choose which delegates should be locked.

protected FileSystem createWritableOn(String name)
          Finds the system to create writable version of the file on.

protected FileSystem createWritableOnForRename(String oldName, String newName)
          Special case of createWritableOn (@see #createWritableOn).

FileObject find(String aPackage, String name, String ext)
          Finds file in the filesystem by name.

FileObject findResource(String name)
          Finds a file given its full resource path.

protected FileObject findResourceOn(FileSystem fs, String res)
          Finds a resource on given filesystem.

protected FileSystem findSystem(FileObject fo)
          For given file object finds the filesystem that the object is placed on.

SystemAction[] getActions()
          Merge actions from all delegates.

SystemAction[] getActions(Set foSet)


protected FileSystem[] getDelegates()
          All filesystem that this system delegates to.

String getDisplayName()
          The name of the filesystem.

boolean getPropagateMasks()
          Will mask files that are not used be listed as children?

FileObject getRoot()
          Root of the filesystem.

protected static Enumeration hiddenFiles(FileObject folder, boolean rec)
          Finds all hidden files on given filesystem.

protected void hideResource(String res, boolean hide)
          Marks a resource as hidden.

boolean isReadOnly()
          This filesystem is readonly if it has not writable system.

protected void markUnimportant(FileObject fo)
          Notification that a file has been marked unimportant.

protected void notifyMigration(FileObject fo)
          Notification that a file has migrated from one filesystem to another.

void prepareEnvironment(FileSystem.Environment env)
          Deprecated. Useless.

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

void removeNotify()
          Notifies all encapsulated filesystems in advance to superclass behaviour.

protected void setDelegates(FileSystem[] fileSystems)
          Changes the filesystems that this system delegates to

protected void setPropagateMasks(boolean pm)
          Set whether unused mask files should be listed as children.

Methods inherited from class org.openide.filesystems.FileSystem

addFileChangeListener, addFileStatusListener, addPropertyChangeListener, addVetoableChangeListener, fireFileStatusChanged, firePropertyChange, fireVetoableChange, getCapability, getStatus, getSystemName, isDefault, isHidden, isPersistent, isValid, removeFileChangeListener, removeFileStatusListener, removePropertyChangeListener, removeVetoableChangeListener, runAtomicAction, setCapability, setHidden, setSystemName, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

MultiFileSystem

protected MultiFileSystem()

Creates new empty MultiFileSystem. Useful only for subclasses.

MultiFileSystem

public MultiFileSystem(FileSystem[] fileSystems)

Creates new MultiFileSystem.
Parameters:: fileSystems - array of filesystems (can contain nulls)

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()

setDelegates

protected final void setDelegates(FileSystem[] fileSystems)

Changes the filesystems that this system delegates to

Parameters:: fileSystems - array of filesystems

getDelegates

protected final FileSystem[] getDelegates()

All filesystem that this system delegates to.

Returns:: the array of delegates

getPropagateMasks

public final boolean getPropagateMasks()

Will mask files that are not used be listed as children?

Returns:: true if so

setPropagateMasks

protected final void setPropagateMasks(boolean pm)

Set whether unused mask files should be listed as children.

Parameters:: pm - true if so

isReadOnly

public boolean isReadOnly()

This filesystem is readonly if it has not writable system.

Specified by:: isReadOnly in class FileSystem

Returns:: true if the system is read-only

getDisplayName

public String getDisplayName()

The name of the filesystem.

Specified by:: getDisplayName in class FileSystem

Returns:: user presentable name of the filesystem

getRoot

public FileObject getRoot()

Root of the filesystem.

Specified by:: getRoot in class FileSystem

Returns:: root folder of whole filesystem

getActions

public SystemAction[] getActions()

Merge actions from all delegates.

Specified by:: getActions in class FileSystem

Returns:: array of available actions

getActions

public SystemAction[] getActions(Set foSet)

Overrides:: getActions in class FileSystem

find

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

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

findSystem

protected final FileSystem findSystem(FileObject fo)
                               throws IllegalArgumentException

For given file object finds the filesystem that the object is placed on. The object must be created by this filesystem orherwise IllegalArgumentException is thrown.

Parameters:: fo - file object
Returns:: the filesystem (from the list we delegate to) the object has file on
Throws:: IllegalArgumentException - if the file object is not represented in this filesystem

hideResource

protected final void hideResource(String res,
                                  boolean hide)
                           throws IOException

Marks a resource as hidden. It will not be listed in the list of files. Uses createMaskOn method to determine on which filesystem to mark the file.

Parameters:: res - resource name of file to hide or show; hide - true if we should hide the file/false otherwise
Throws:: IOException - if it is not possible

hiddenFiles

protected static Enumeration hiddenFiles(FileObject folder,
                                         boolean rec)

Finds all hidden files on given filesystem. The methods scans all files for ones with hidden extension and returns enumeration of names of files that are hidden.

Parameters:: folder - folder to start at; rec - proceed recursivelly
Returns:: enumeration of String with names of hidden files

findResourceOn

protected FileObject findResourceOn(FileSystem fs,
                                    String res)

Finds a resource on given filesystem. The default implementation simply uses FileSystem.findResource, but subclasses may override this method to hide/show some resources.

Parameters:: fs - the filesystem to scan on; res - the resource name to look for
Returns:: the file object or null

createWritableOn

protected FileSystem createWritableOn(String name)
                               throws IOException

Finds the system to create writable version of the file on.

Parameters:: name - name of the file (full)
Returns:: the first one
Throws:: IOException - if the filesystem is readonly

createWritableOnForRename

protected FileSystem createWritableOnForRename(String oldName,
                                               String newName)
                                        throws IOException

Special case of createWritableOn (@see #createWritableOn).

Parameters:: oldName - original name of the file (full); newName - name new of the file (full)
Returns:: the first one
Throws:: IOException - if the filesystem is readonly
Since:: 1.34

createLocksOn

protected Set createLocksOn(String name)
                     throws IOException

When a file is about to be locked this method is consulted to choose which delegates should be locked. By default this method returns only one filesystem; the same returned by createWritableOn.

If an delegate resides on a filesystem returned in the resulting set, it will be locked. All others will remain unlocked.

Parameters:: name - the resource name to lock
Returns:: set of filesystems
Throws:: IOException - if the resource cannot be locked

notifyMigration

protected void notifyMigration(FileObject fo)

Notification that a file has migrated from one filesystem to another. Usually when somebody writes to file on readonly file system and the file has to be copied to write one.

This method allows subclasses to fire for example FileSystem.PROP_STATUS change to notify that annotation of this file should change.

Parameters:: fo - file object that change its actual filesystem

markUnimportant

protected void markUnimportant(FileObject fo)

Notification that a file has been marked unimportant.

Parameters:: fo - file object that change its actual filesystem

prepareEnvironment

public void prepareEnvironment(FileSystem.Environment env)
                        throws EnvironmentNotSupportedException

Deprecated. Useless.

Lets any sub filesystems prepare the environment. If they do not support it, it does not care.

Overrides:: prepareEnvironment in class FileSystem

Parameters:: env - the environment to setup
Throws:: EnvironmentNotSupportedException - if external execution and compilation cannot be supported

addNotify

public void addNotify()

Notifies all encapsulated filesystems in advance to superclass behaviour.

Overrides:: addNotify in class FileSystem

removeNotify

public void removeNotify()

Notifies all encapsulated filesystems in advance to superclass behaviour.

Overrides:: removeNotify in class FileSystem

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Constructor Summary
`protected`	`MultiFileSystem()` Creates new empty MultiFileSystem.
	`MultiFileSystem(FileSystem[] fileSystems)` Creates new MultiFileSystem.

Method Summary
`void`	`addNotify()` Notifies all encapsulated filesystems in advance to superclass behaviour.
`protected Set`	`createLocksOn(String name)` When a file is about to be locked this method is consulted to choose which delegates should be locked.
`protected FileSystem`	`createWritableOn(String name)` Finds the system to create writable version of the file on.
`protected FileSystem`	`createWritableOnForRename(String oldName, String newName)` Special case of createWritableOn (@see #createWritableOn).
`FileObject`	`find(String aPackage, String name, String ext)` Finds file in the filesystem by name.
`FileObject`	`findResource(String name)` Finds a file given its full resource path.
`protected FileObject`	`findResourceOn(FileSystem fs, String res)` Finds a resource on given filesystem.
`protected FileSystem`	`findSystem(FileObject fo)` For given file object finds the filesystem that the object is placed on.
`SystemAction[]`	`getActions()` Merge actions from all delegates.
`SystemAction[]`	`getActions(Set foSet)`
`protected FileSystem[]`	`getDelegates()` All filesystem that this system delegates to.
`String`	`getDisplayName()` The name of the filesystem.
`boolean`	`getPropagateMasks()` Will mask files that are not used be listed as children?
`FileObject`	`getRoot()` Root of the filesystem.
`protected static Enumeration`	`hiddenFiles(FileObject folder, boolean rec)` Finds all hidden files on given filesystem.
`protected void`	`hideResource(String res, boolean hide)` Marks a resource as hidden.
`boolean`	`isReadOnly()` This filesystem is readonly if it has not writable system.
`protected void`	`markUnimportant(FileObject fo)` Notification that a file has been marked unimportant.
`protected void`	`notifyMigration(FileObject fo)` Notification that a file has migrated from one filesystem to another.
`void`	`prepareEnvironment(FileSystem.Environment env)` Deprecated. Useless.
`void`	`refresh(boolean expected)` Actually implements contract of FileSystem.refresh().
`void`	`removeNotify()` Notifies all encapsulated filesystems in advance to superclass behaviour.
`protected void`	`setDelegates(FileSystem[] fileSystems)` Changes the filesystems that this system delegates to
`protected void`	`setPropagateMasks(boolean pm)` Set whether unused mask files should be listed as children.

MultiFileSystem (NetBeans File Systems API) - NetBeans API Javadoc 5.0.0

org.openide.filesystems Class MultiFileSystem

MultiFileSystem

MultiFileSystem

refresh

setDelegates

getDelegates

getPropagateMasks

setPropagateMasks

isReadOnly

getDisplayName

getRoot

getActions

getActions

find

findResource

findSystem

hideResource

hiddenFiles

findResourceOn

createWritableOn

createWritableOnForRename

createLocksOn

notifyMigration

markUnimportant

prepareEnvironment

addNotify

removeNotify

org.openide.filesystems
Class MultiFileSystem