## org.gjt.sp.jedit.io
Class VFS

    java.lang.Object
      org.gjt.sp.jedit.io.VFS

Direct Known Subclasses:
  FavoritesVFS, FileRootsVFS, FileVFS, UrlVFS

public abstract class VFS
extends java.lang.Object

A virtual filesystem implementation.

Plugins can provide virtual file systems by defining entries in their `services.xml` files like so:

    <SERVICE CLASS="org.gjt.sp.jedit.io.VFS" NAME="name">
        new MyVFS();
    </SERVICE>

URLs of the form `name:path` will then be handled by the VFS named `name`.

See `ServiceManager` for details.

### Session objects:

A session is used to persist things like login information, any network sockets, etc. File system implementations that do not need this kind of persistence return a dummy object as a session.

Methods whose names are prefixed with "_" expect to be given a previously-obtained session object. A session must be obtained from the AWT thread in one of two ways:

- `createVFSSession(String,Component)`
- `showBrowseDialog(Object[],Component)`

When done, the session must be disposed of using `_endVFSSession(Object,Component)`.

### Thread safety:

The following methods cannot be called from an I/O thread:

- `createVFSSession(String,Component)`
- `insert(View,Buffer,String)`
- `load(View,Buffer,String)`
- `save(View,Buffer,String)`
- `showBrowseDialog(Object[],Component)`

All remaining methods are required to be thread-safe in subclasses.

### Implementing a VFS

You can override as many or as few methods as you want. Make sure `getCapabilities()` returns a value reflecting the functionality implemented by your VFS.

Author:
  Slava Pestov, $Id: VFS.java,v 1.39 2003/09/08 01:24:11 spestov Exp $
See Also:
  `VFSManager.getVFSForPath(String)`, `VFSManager.getVFSForProtocol(String)`

Nested Class Summary
`static class` `VFS.DirectoryEntry` A directory entry.
`static class` `VFS.DirectoryEntryCompare` Implementation of `MiscUtilities.Compare` interface that compares `VFS.DirectoryEntry` instances.

Field Summary

`static int`

`BROWSE_CAP`
Deprecated. Do not define this capability.

This was the official API for adding items to a file system browser's Plugins menu in jEdit 4.1 and earlier. In jEdit 4.2, there is a different way of doing this, you must provide a `browser.actions.xml` file in your plugin JAR, and define `plugin.class.browser-menu-item` or `plugin.class.browser-menu` properties. See `EditPlugin` for details.

`static int` `CASE_INSENSITIVE_CAP` Case insensitive file system capability.
`static int` `DELETE_CAP` Delete file capability.
`static java.lang.String` `EA_MODIFIED` File last modified date.
`static java.lang.String` `EA_SIZE` File size.
`static java.lang.String` `EA_STATUS` File status (read only, read write, etc).
`static java.lang.String` `EA_TYPE` File type.
`static int` `LOW_LATENCY_CAP` Low latency capability.
`static int` `MKDIR_CAP` Make directory capability.
`static int` `READ_CAP` Read capability.
`static int` `RENAME_CAP` Rename file capability.
`static int` `WRITE_CAP` Write capability.

Constructor Summary
`VFS(java.lang.String name)` Deprecated. Use the form where the constructor takes a capability list.
`VFS(java.lang.String name, int caps)` Creates a new virtual filesystem.
`VFS(java.lang.String name, int caps, java.lang.String[] extAttrs)` Creates a new virtual filesystem.

Method Summary
`void` `_backup(java.lang.Object session, java.lang.String path, java.awt.Component comp)` Backs up the specified file.
`java.lang.String` `_canonPath(java.lang.Object session, java.lang.String path, java.awt.Component comp)` Returns the canonical form of the specified path name.
`java.io.InputStream` `_createInputStream(java.lang.Object session, java.lang.String path, boolean ignoreErrors, java.awt.Component comp)` Creates an input stream.
`java.io.OutputStream` `_createOutputStream(java.lang.Object session, java.lang.String path, java.awt.Component comp)` Creates an output stream.
`boolean` `_delete(java.lang.Object session, java.lang.String path, java.awt.Component comp)` Deletes the specified URL.
`void` `_endVFSSession(java.lang.Object session, java.awt.Component comp)` Finishes the specified VFS session.
`VFS.DirectoryEntry` `_getDirectoryEntry(java.lang.Object session, java.lang.String path, java.awt.Component comp)` Returns the specified directory entry.
`VFS.DirectoryEntry[]` `_listDirectory(java.lang.Object session, java.lang.String directory, java.awt.Component comp)` Lists the specified directory.
`java.lang.String[]` `_listDirectory(java.lang.Object session, java.lang.String directory, java.lang.String glob, boolean recursive, java.awt.Component comp)` A convinience method that matches file names against globs, and can optionally list the directory recursively.
`boolean` `_mkdir(java.lang.Object session, java.lang.String directory, java.awt.Component comp)` Creates a new directory with the specified URL.
`boolean` `_rename(java.lang.Object session, java.lang.String from, java.lang.String to, java.awt.Component comp)` Renames the specified URL.
`void` `_saveComplete(java.lang.Object session, Buffer buffer, java.lang.String path, java.awt.Component comp)` Called after a file has been saved.
`java.lang.String` `constructPath(java.lang.String parent, java.lang.String path)` Constructs a path from the specified directory and file name component.
`java.lang.Object` `createVFSSession(java.lang.String path, java.awt.Component comp)` Creates a VFS session.
`int` `getCapabilities()` Returns the capabilities of this VFS.
`static java.awt.Color` `getDefaultColorFor(java.lang.String name)` Returns color of the specified file name, by matching it against user-specified regular expressions.
`java.lang.String[]` `getExtendedAttributes()` Returns the extended attributes supported by this VFS.
`java.lang.String` `getFileName(java.lang.String path)` Returns the file name component of the specified path.
`char` `getFileSeparator()` Returns the file separator used by this VFS.
`java.lang.String` `getName()` Returns this VFS's name.
`java.lang.String` `getParentOfPath(java.lang.String path)` Returns the parent of the specified path.
`java.lang.String` `getTwoStageSaveName(java.lang.String path)` Returns a temporary file name based on the given path.
`boolean` `insert(View view, Buffer buffer, java.lang.String path)` Inserts a file into the specified buffer.
`boolean` `load(View view, Buffer buffer, java.lang.String path)` Loads the specified buffer.
`void` `reloadDirectory(java.lang.String path)` Called before a directory is reloaded by the file system browser.
`boolean` `save(View view, Buffer buffer, java.lang.String path)` Saves the specifies buffer.
`java.lang.String` `showBrowseDialog(java.lang.Object[] session, java.awt.Component comp)` Displays a dialog box that should set up a session and return the initial URL to browse.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### READ_CAP

    public static final int READ_CAP

  Read capability.

  Since:
    jEdit 2.6pre2
  See Also:
    Constant Field Values

### WRITE_CAP

    public static final int WRITE_CAP

  Write capability.

  Since:
    jEdit 2.6pre2
  See Also:
    Constant Field Values

### BROWSE_CAP

    public static final int BROWSE_CAP

  Deprecated. Do not define this capability.

  This was the official API for adding items to a file system browser's Plugins menu in jEdit 4.1 and earlier. In jEdit 4.2, there is a different way of doing this, you must provide a `browser.actions.xml` file in your plugin JAR, and define `plugin.class.browser-menu-item` or `plugin.class.browser-menu` properties. See `EditPlugin` for details.

  See Also:
    Constant Field Values

### DELETE_CAP

    public static final int DELETE_CAP

  Delete file capability.

  Since:
    jEdit 2.6pre2
  See Also:
    Constant Field Values

### RENAME_CAP

    public static final int RENAME_CAP

  Rename file capability.

  Since:
    jEdit 2.6pre2
  See Also:
    Constant Field Values

### MKDIR_CAP

    public static final int MKDIR_CAP

  Make directory capability.

  Since:
    jEdit 2.6pre2
  See Also:
    Constant Field Values

### LOW_LATENCY_CAP

    public static final int LOW_LATENCY_CAP

  Low latency capability. If this is not set, then a confirm dialog will be shown before doing a directory search in this VFS.

  Since:
    jEdit 4.1pre1
  See Also:
    Constant Field Values

### CASE_INSENSITIVE_CAP

    public static final int CASE_INSENSITIVE_CAP

  Case insensitive file system capability.

  Since:
    jEdit 4.1pre1
  See Also:
    Constant Field Values

### EA_TYPE

    public static final java.lang.String EA_TYPE

  File type.

  Since:
    jEdit 4.2pre1
  See Also:
    Constant Field Values

### EA_STATUS

    public static final java.lang.String EA_STATUS

  File status (read only, read write, etc).

  Since:
    jEdit 4.2pre1
  See Also:
    Constant Field Values

### EA_SIZE

    public static final java.lang.String EA_SIZE

  File size.

  Since:
    jEdit 4.2pre1
  See Also:
    Constant Field Values

### EA_MODIFIED

    public static final java.lang.String EA_MODIFIED

  File last modified date.

  Since:
    jEdit 4.2pre1
  See Also:
    Constant Field Values

Constructor Detail

### VFS

    public VFS(java.lang.String name)

  Deprecated. Use the form where the constructor takes a capability list.

### VFS

    public VFS(java.lang.String name,
               int caps)

  Creates a new virtual filesystem.

Parameters:
  `name` - The name
  `caps` - The capabilities

### VFS

    public VFS(java.lang.String name,
               int caps,
               java.lang.String[] extAttrs)

  Creates a new virtual filesystem.

Parameters:
  `name` - The name
  `caps` - The capabilities
  `extAttrs` - The extended attributes
Since:
  jEdit 4.2pre1

Method Detail

### getName

    public java.lang.String getName()

  Returns this VFS's name. The name is used to obtain the label stored in the `vfs.name.label` property.

### getCapabilities

    public int getCapabilities()

  Returns the capabilities of this VFS.

  Since:
    jEdit 2.6pre2

### getExtendedAttributes

    public java.lang.String[] getExtendedAttributes()

  Returns the extended attributes supported by this VFS.

  Since:
    jEdit 4.2pre1

### showBrowseDialog

    public java.lang.String showBrowseDialog(java.lang.Object[] session,
                                             java.awt.Component comp)

  Displays a dialog box that should set up a session and return the initial URL to browse.

  Parameters:
    `session` - Where the VFS session will be stored
    `comp` - The component that will parent error dialog boxes
  Returns:
    The URL
  Since:
    jEdit 2.7pre1

### getFileName

    public java.lang.String getFileName(java.lang.String path)

  Returns the file name component of the specified path.

  Parameters:
    `path` - The path
  Since:
    jEdit 3.1pre4

### getParentOfPath

    public java.lang.String getParentOfPath(java.lang.String path)

  Returns the parent of the specified path. This must be overridden to return a non-null value for browsing of this filesystem to work.

  Parameters:
    `path` - The path
  Since:
    jEdit 2.6pre5

### constructPath

    public java.lang.String constructPath(java.lang.String parent,
                                          java.lang.String path)

  Constructs a path from the specified directory and file name component. This must be overridden to return a non-null value, otherwise browsing this filesystem will not work.

  Unless you are writing a VFS, this method should not be called directly. To ensure correct behavior, you must call `MiscUtilities.constructPath(String,String)` instead.

  Parameters:
    `parent` - The parent directory
    `path` - The path
  Since:
    jEdit 2.6pre2

### getFileSeparator

    public char getFileSeparator()

  Returns the file separator used by this VFS.

  Since:
    jEdit 2.6pre9

### getTwoStageSaveName

    public java.lang.String getTwoStageSaveName(java.lang.String path)

  Returns a temporary file name based on the given path. By default jEdit first saves a file to `#name#save#` and then renames it to the original file. However some virtual file systems might not support the `#` character in filenames, so this method permits the VFS to override this behavior.

  Parameters:
    `path` - The path name
  Since:
    jEdit 4.1pre7

### reloadDirectory

    public void reloadDirectory(java.lang.String path)

  Called before a directory is reloaded by the file system browser. Can be used to flush a cache, etc.

  Since:
    jEdit 4.0pre3

### createVFSSession

    public java.lang.Object createVFSSession(java.lang.String path,
                                             java.awt.Component comp)

  Creates a VFS session. This method is called from the AWT thread, so it should not do any I/O. It could, however, prompt for a login name and password, for example.

  Parameters:
    `path` - The path in question
    `comp` - The component that will parent any dialog boxes shown
  Returns:
    The session
  Since:
    jEdit 2.6pre3

### load

    public boolean load(View view,
                        Buffer buffer,
                        java.lang.String path)

  Loads the specified buffer. The default implementation posts an I/O request to the I/O thread.

  Parameters:
    `view` - The view
    `buffer` - The buffer
    `path` - The path

### save

    public boolean save(View view,
                        Buffer buffer,
                        java.lang.String path)

  Saves the specifies buffer. The default implementation posts an I/O request to the I/O thread.

  Parameters:
    `view` - The view
    `buffer` - The buffer
    `path` - The path

### insert

    public boolean insert(View view,
                          Buffer buffer,
                          java.lang.String path)

  Inserts a file into the specified buffer. The default implementation posts an I/O request to the I/O thread.

  Parameters:
    `view` - The view
    `buffer` - The buffer
    `path` - The path

### _canonPath

    public java.lang.String _canonPath(java.lang.Object session,
                                       java.lang.String path,
                                       java.awt.Component comp)
                                throws java.io.IOException

  Returns the canonical form of the specified path name. For example, `~` might be expanded to the user's home directory.

  Parameters:
    `session` - The session
    `path` - The path
    `comp` - The component that will parent error dialog boxes
  Throws:
    `java.io.IOException` - if an I/O error occurred
  Since:
    jEdit 4.0pre2

### _listDirectory

    public java.lang.String[] _listDirectory(java.lang.Object session,
                                             java.lang.String directory,
                                             java.lang.String glob,
                                             boolean recursive,
                                             java.awt.Component comp)
                                      throws java.io.IOException

  A convinience method that matches file names against globs, and can optionally list the directory recursively.

  Parameters:
    `session` - The session
    `directory` - The directory. Note that this must be a full URL, including the host name, path name, and so on. The username and password (if needed by the VFS) is obtained from the session instance.
    `glob` - Only file names matching this glob will be returned
    `recursive` - If true, subdirectories will also be listed.
    `comp` - The component that will parent error dialog boxes
  Throws:
    `java.io.IOException` - if an I/O error occurred
  Since:
    jEdit 4.1pre1

### _listDirectory

    public VFS.DirectoryEntry[] _listDirectory(java.lang.Object session,
                                               java.lang.String directory,
                                               java.awt.Component comp)
                                        throws java.io.IOException

  Lists the specified directory.

  Parameters:
    `session` - The session
    `directory` - The directory. Note that this must be a full URL, including the host name, path name, and so on. The username and password (if needed by the VFS) is obtained from the session instance.
    `comp` - The component that will parent error dialog boxes
  Throws:
    `java.io.IOException` - if an I/O error occurred
  Since:
    jEdit 2.7pre1

### _getDirectoryEntry

    public VFS.DirectoryEntry _getDirectoryEntry(java.lang.Object session,
                                                 java.lang.String path,
                                                 java.awt.Component comp)
                                          throws java.io.IOException

  Returns the specified directory entry.

  Parameters:
    `session` - The session
    `path` - The path
    `comp` - The component that will parent error dialog boxes
  Returns:
    The specified directory entry, or null if it doesn't exist.
  Throws:
    `java.io.IOException` - if an I/O error occurred
  Since:
    jEdit 2.7pre1

### _delete

    public boolean _delete(java.lang.Object session,
                           java.lang.String path,
                           java.awt.Component comp)
                    throws java.io.IOException

  Deletes the specified URL.

  Parameters:
    `session` - The VFS session
    `path` - The path
    `comp` - The component that will parent error dialog boxes
  Throws:
    `java.io.IOException` - if an I/O error occurs
  Since:
    jEdit 2.7pre1

### _rename

    public boolean _rename(java.lang.Object session,
                           java.lang.String from,
                           java.lang.String to,
                           java.awt.Component comp)
                    throws java.io.IOException

  Renames the specified URL. Some filesystems might support moving URLs between directories, however others may not. Do not rely on this behavior.

  Parameters:
    `session` - The VFS session
    `from` - The old path
    `to` - The new path
    `comp` - The component that will parent error dialog boxes
  Throws:
    `java.io.IOException` - if an I/O error occurs
  Since:
    jEdit 2.7pre1

### _mkdir

    public boolean _mkdir(java.lang.Object session,
                          java.lang.String directory,
                          java.awt.Component comp)
                   throws java.io.IOException

  Creates a new directory with the specified URL.

  Parameters:
    `session` - The VFS session
    `directory` - The directory
    `comp` - The component that will parent error dialog boxes
  Throws:
    `java.io.IOException` - if an I/O error occurs
  Since:
    jEdit 2.7pre1

### _backup

    public void _backup(java.lang.Object session,
                        java.lang.String path,
                        java.awt.Component comp)
                 throws java.io.IOException

  Backs up the specified file. This should only be overriden by the local filesystem VFS.

  Parameters:
    `session` - The VFS session
    `path` - The path
    `comp` - The component that will parent error dialog boxes
  Throws:
    `java.io.IOException` - if an I/O error occurs
  Since:
    jEdit 3.2pre2

### _createInputStream

    public java.io.InputStream _createInputStream(java.lang.Object session,
                                                  java.lang.String path,
                                                  boolean ignoreErrors,
                                                  java.awt.Component comp)
                                           throws java.io.IOException

  Creates an input stream. This method is called from the I/O thread.

  Parameters:
    `session` - the VFS session
    `path` - The path
    `ignoreErrors` - If true, file not found errors should be ignored
    `comp` - The component that will parent error dialog boxes
  Throws:
    `java.io.IOException` - If an I/O error occurs
  Since:
    jEdit 2.7pre1

### _createOutputStream

    public java.io.OutputStream _createOutputStream(java.lang.Object session,
                                                    java.lang.String path,
                                                    java.awt.Component comp)
                                             throws java.io.IOException

  Creates an output stream. This method is called from the I/O thread.

  Parameters:
    `session` - the VFS session
    `path` - The path
    `comp` - The component that will parent error dialog boxes
  Throws:
    `java.io.IOException` - If an I/O error occurs
  Since:
    jEdit 2.7pre1

### _saveComplete

    public void _saveComplete(java.lang.Object session,
                              Buffer buffer,
                              java.lang.String path,
                              java.awt.Component comp)
                       throws java.io.IOException

  Called after a file has been saved.

  Parameters:
    `session` - The VFS session
    `buffer` - The buffer
    `path` - The path the buffer was saved to (can be different from `Buffer.getPath()` if the user invoked the Save a Copy As command, for example).
    `comp` - The component that will parent error dialog boxes
  Throws:
    `java.io.IOException` - If an I/O error occurs
  Since:
    jEdit 4.1pre9

### _endVFSSession

    public void _endVFSSession(java.lang.Object session,
                               java.awt.Component comp)
                        throws java.io.IOException

  Finishes the specified VFS session. This must be called after all I/O with this VFS is complete, to avoid leaving stale network connections and such.

  Parameters:
    `session` - The VFS session
    `comp` - The component that will parent error dialog boxes
  Throws:
    `java.io.IOException` - if an I/O error occurred
  Since:
    jEdit 2.7pre1

### getDefaultColorFor

    public static java.awt.Color getDefaultColorFor(java.lang.String name)

  Returns color of the specified file name, by matching it against user-specified regular expressions.

  Since:
    jEdit 4.0pre1