com.exln.stylus.io
Interface StylusFileSystem

All Known Subinterfaces:

StylusFileSystemOptions

public interface StylusFileSystem

Represents a custom file system. This includes information needed by Stylus Studio to create an entry in the button bar in the Open File dialog. In addition, it provides information for connecting to data servers if necessary.

Stylus Studio has a list of known custom file systems. Some are built-in, while others can be implemented by users. To implement a custom file system, you must create a class that implements StylusFileSystem and a class that implements StylusFile. You then declare thoses classes to Stylus Studio through the menu: Tools->Options->Application Settings->Custom File Systems.

For more information, see the Stylus Studio online documention section: Custom File Systems.

Stylus Studio uses custom file systems to read and write files in two contexts:

• Interactively through the File->Open and File->Save As dialogs.
• Non-interactively, when reading input for or writing output from an .XSL transform, for example.

The File->Open and File->Save As dialogs create one instance of the StylusFileSystem object for each custom file system. The StylusFileSystem object is used to connect to a server (if applicable), and browse the files available through that custom file system. The dialog uses the StylusFileSystem method listRoots() to find the top of the file system, and the StylusFile method listFiles() to browse the rest of the directories and files. As soon as the user dismisses the dialog, all references to all the StylusFileSystem objects and StylusFile objects are deleted, so the StylusFileSystem and StylusFile objects are subject to garbage collection. Finally, Stylus Studio creates a new StylusFileSystem object and a new StylusFile object, and it uses them to read the data from or to write the data to the selected file.

A non-interactive read or write is the same as the last step of an interactive operation. Stylus Studio creates a StylusFileSystem object and a StylusFile object and uses them to read or write the data.

StylusFileSystem File Naming Conventions
Stylus Studio accesses all external files using a URL: scheme://server/pathname where

• scheme is a scheme name unique to each custom file system. Each custom file system chooses a name and declares it to Stylus Studio with the method getScheme().
• server is optional. If a custom file system does not support servers, then the URL will be: scheme:///pathname.
• pathname consists of a series of names separated by the character "/".

Pathnames passed as parameters to the custom file system may have various forms, depending on the particular situation. The custom file system code must be prepared to handle any of these forms:

• pathname (eg c:/dirname/filename.xml)
• /pathname (eg /c:/dirname/filename.xml)
• /pathname/ (eg /c:/dirname/)
• scheme:///pathname
• scheme://server/pathname

Pathnames returned by the custom file system methods must be in the 2nd form: /pathname except getURLForPathName(String path), which should return the complete URL: scheme://server/pathname.

Method Summary

void	buildDirectoryStructure(String path) Create a hierarchy of directories as specified by the parameter path.
boolean	canChangeServers()
boolean	canCreateDirectories() Check whether this custom file system can create directories.
boolean	connectServer(String bindString)
boolean	disconnectServer()
boolean	exists(String path) Check whether a file exists.
String	getCurrentDirectory() Retrieve the name of the last directory the user visited in a File->Open or File->Save As dialog.
String	getFileClassName() Get the class name of the StylusFile class for this file system.
String	getName() Get the name of this custom file system.
String	getScheme() Return the character string scheme name that this file system supports.
String	getSeparator() Get the separator character used to separate element names in a pathname.
String	getServerName()
String	getURLForPathName(String path) Return the complete URL scheme://server/pathname.
int	getVersion() Get the current version number of this custom file system.
boolean	isAbsolute(String path) Check whether a pathname is an absolute or relative pathname.
boolean	isDirectory(String path) Check whether a file is a directory.
boolean	isPathValid(String path) Check whether a pathname is a valid pathname.
StylusFile[]	listRoots() List all the roots of the file system.
boolean	matchesScheme(String scheme) Check whether this StylusFileSystem can process URLs with the specified scheme.
boolean	mkdir(String path) Create a new directory in the file system.
boolean	renameTo(String oldPath, String newPath) Rename an existing directory in the file system.
String	resolveShortcuts(String path) Return the target pathname of a shortcut or link.
void	setCurrentDirectory(String path) Store the name of the last directory the user visited in a File->Open or File->Save As dialog.
boolean	supportsDirectories() Check whether this custom file system is modeled as a tree or is flat.
boolean	supportServer()

Method Detail

connectServer

public boolean connectServer(String bindString)

disconnectServer

public boolean disconnectServer()

getServerName

public String getServerName()

matchesScheme

public boolean matchesScheme(String scheme)

Check whether this StylusFileSystem can process URLs with the specified scheme.

Parameters:

scheme - A URL scheme name.

Returns:

true if this StylusFileSystem can serve the parameter scheme name.

exists

public boolean exists(String path)

Check whether a file exists.

Parameters:

path - The pathname to be checked.
Note: The first time a user uses a custom file system, Stylus Studio will call exists(""). This method must be able to handle that case. The correct behavior in most cases is to return false.

Returns:

true if the file exists.

isDirectory

public boolean isDirectory(String path)

Check whether a file is a directory.

Parameters:

path - The pathname to be checked.

Returns:

true if the file is a directory.

isAbsolute

public boolean isAbsolute(String path)

Check whether a pathname is an absolute or relative pathname.

Parameters:

path - The pathname to be checked.

Returns:

true if the pathname is an absolute pathname.

isPathValid

public boolean isPathValid(String path)

Check whether a pathname is a valid pathname.

Parameters:

path - The pathname to be checked.

Returns:

true if the pathname is valid.

listRoots

public StylusFile[] listRoots()

List all the roots of the file system. The file system is modeled as a branching tree with one or more root nodes. All files should be accessible starting at one of these root nodes. For example, the root nodes in a Windows based file system would be A:, B:, C:, and so on. In general, all custom file system pathnames begin with a /, however, the leading / can be omitted from the roots' pathnames.

Returns:

An array of StylusFile objects, one for each root node.

getScheme

public String getScheme()

Return the character string scheme name that this file system supports.

Returns:

The scheme name (without the ://).

supportServer

public boolean supportServer()

canChangeServers

public boolean canChangeServers()

canCreateDirectories

public boolean canCreateDirectories()

Check whether this custom file system can create directories. The File->Open and File->Save As dialogs may allow the user to create directories. This method indicates whether the dialog should activate that feature for this file system.

Returns:

true if the user should be allowed to create directories.

See Also:

mkdir(String), buildDirectoryStructure(String)

supportsDirectories

public boolean supportsDirectories()

Check whether this custom file system is modeled as a tree or is flat. If the file system is flat, there are no directories.

Returns:

true if the file system does have directories.

getVersion

public int getVersion()

Get the current version number of this custom file system.

Returns:

The current version number.

getSeparator

public String getSeparator()

Get the separator character used to separate element names in a pathname. The Stylus Studio input/output framework only supports the "/" character. This method should return "/".

Returns:

The separator character as a string, "/".

getName

public String getName()

Get the name of this custom file system. The File->Open and File->Save As dialog will display this name along with the custom file system's icon.

Returns:

The name.

getFileClassName

public String getFileClassName()

Get the class name of the StylusFile class for this file system. When you use the Tools->Options menu to register a custom file system, you register the name of the class that implements the StylusFileSystem interface. Stylus Studio then uses the getFileClassName method to get the name of the class that implements the StylusFile interface.

Returns:

The name of the class that implements the StylusFile interface.

setCurrentDirectory

public void setCurrentDirectory(String path)

Store the name of the last directory the user visited in a File->Open or File->Save As dialog. As a convenience to the user, each time the File->Open or File->Save As dialog is opened, it starts at the last directory visited by the user. When the dialog is closed, it calls setCurrentDirectory to save that directory name. Shortly after this call, Stylus Studio will delete all references to this StylusFileSystem object making it unreachable, so all non-static member variables will be lost. setCurrentDirectory should, therefore, save this pathname in a static member variable.

Parameters:

path - The pathname of the last directory visited by the dialog.

See Also:

getCurrentDirectory()

getCurrentDirectory

public String getCurrentDirectory()

Retrieve the name of the last directory the user visited in a File->Open or File->Save As dialog. As a convenience to the user, each time the File->Open or File->Save As dialog is opened, it starts at the last directory visited by the user.

Returns:

The pathname saved by the last call to setCurrentDirectory(String path).

See Also:

setCurrentDirectory(String)

mkdir

public boolean mkdir(String path)

Create a new directory in the file system. This method is called by the File->Open or File->Save As dialogs only if the method canCreateDirectories() returns true. The last filename element of the parameter path will be "New Folder" and the user will be given the opportunity to rename it. The parent of this new directory already exists, so mkdir() will only have to create a single directory node.

Parameters:

path - The pathname of the directory to be created.

Returns:

true if the mkdir succeeded, false if it failed.

See Also:

renameTo(String, String), buildDirectoryStructure(String)

renameTo

public boolean renameTo(String oldPath,
                        String newPath)

Rename an existing directory in the file system. This method may be called shortly after a call to mkdir, to give a name to a newly created directory, or it may be called in response to a user request to rename a previously existing directory.

Parameters:

oldPath - The current name of the directory to be renamed.

newPath - The desired new name of the directory.

Returns:

true if the rename succeeded, false if it failed.

See Also:

mkdir(String), buildDirectoryStructure(String)

buildDirectoryStructure

public void buildDirectoryStructure(String path)

Create a hierarchy of directories as specified by the parameter path. Stylus Studio uses this method as another way to create directories besides mkdir(). This method may be called even if canCreateDirectories returns false. It is called whenever a non-interactive write (output from a .xsl transform for example) requires the creation of one or more directories. It can also be called from the File->Save As dialog if a user types a pathname in the URL field.

See Also:

renameTo(String, String), mkdir(String)

resolveShortcuts

public String resolveShortcuts(String path)

Return the target pathname of a shortcut or link.

Parameters:

path - The shortcut or link file pathname.

Returns:

The pathname of the file to which the paramter points.

getURLForPathName

public String getURLForPathName(String path)

Return the complete URL scheme://server/pathname. If the custom file system does not support servers, then the URL will look like scheme:///pathname

Parameters:

path - The pathname to be converted to a URL.

Returns:

The URL.