com.exln.stylus.io
Class StylusFileFactory

java.lang.Object
  com.exln.stylus.io.StylusFileFactory

All Implemented Interfaces:

URIResolver

public final class StylusFileFactory

extends Object

implements URIResolver

Defines a factory API that enables applications to read and write data streams using any custom file system which implements the StylusFile interface. To use this class:

• Your CLASSPATH must include CustomFileSystem.jar from the Stylus Studio bin directory
• Your CLASSPATH must be set to include any classes required by any custom file systems you use.
• Your PATH must be set to include any modules required by any custom file systems you use.
• You must set whatever system properties your custom file systems use.

In particular, the built-in custom file systems (see registerScheme(String, String)) have these requirements:

• dbxml: scheme:
  • CLASSPATH must include the DBXMLFileSystem.jar in Stylus Studio bin\lib\sleepycat
  • CLASSPATH must include db.jar and dbxml.jar from Sleepycat Software
  • PATH must include all required .dll files from Sleeypcat Software
  • The system property com.stylusstudio.bindir must contain the pathname of the Stylus Studio bin directory
• db: scheme:
  • CLASSPATH must include ddall.jar from the Stylus Studio bin\lib\datadirect directory
  • The system property com.stylusstudio.rootdir must contain the pathname of the Stylus Studio product directory
• adapter: scheme:
  • CLASSPATH must include AdapterFileSystem.jar and adapters.jar in the Stylus Studio bin directory
  • The system property com.stylusstudio.rootdir must contain the pathname of the Stylus Studio product directory
  • The system property com.stylusstudio.appdata must contain the pathname of the directory containing the adaptermap.properties file

The simplest way to use this class is:

	StylusFile sf = 
		StylusFileFactory.getFactory().createStylusFile(String url);
 

The resulting StylusFile object can be used to access the specified url using one of the built-in protocols listed above. See StylusFile and createStylusFile.

If you have implemented a custom file system and wish to use this class to access it, you must register your custom file system as follows, before calling createStylusFile:

	StylusFileFactory.getFactory().registerScheme(String scheme, String className);
 

For more details, see registerScheme.

Method Summary

StylusFile	createStylusFile(String url) Create a StylusFile object for file access through a custom file system.
StylusFile	createStylusFile(String url, InputStream is) Create a StylusFile object for file access through a custom file system.
static StylusFileFactory	getFactory() Get the singleton StylusFileFactory.
void	registerScheme(String scheme, String className) Register a scheme name and its associated StylusFile class name.
Source	resolve(String URI, String URIBase) Resolve a URI and return a Source which can be used to read data from the URI.

Methods inherited from class java.lang.Object

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

Method Detail

getFactory

public static StylusFileFactory getFactory()

Get the singleton StylusFileFactory. If the factory does not yet exist, it will be created and initialized.

createStylusFile

public StylusFile createStylusFile(String url)
                            throws IOException

Create a StylusFile object for file access through a custom file system. The parameter String url is parsed to get the scheme prefix. The scheme is used to select a custom file system which can access files via that protocol. The scheme should either be a built-in scheme or should have been registered with registerScheme.

The scheme:// prefix is then removed from the url and the rest is passed as the String parameter to the constructor for that StylusFile class for the selected custom file system.

The StylusFile object returned by createStylusFile can be used to:

• Read data from the file with StylusFile.getInputStream() or StylusFile.copyToFile(String)
• Write data to the file with StylusFile.getOutputStream() or StylusFile.copyToFile(String)

For more details, see StylusFile.

Returns:

A new StylusFile object for the class which was registered to the scheme.

Throws:

IOException - in any of the following conditions:

• The parameter url could not be parsed
• The scheme is not a built-in scheme and has not been registered. see registerScheme
• The registered class could not be found
• The registered class does not implement StylusFile
• The constructor for the registered class throws an exception

createStylusFile

public StylusFile createStylusFile(String url,
                                   InputStream is)
                            throws IOException

Create a StylusFile object for file access through a custom file system. This method differs from createStylusFile(String) in that it invokes a 2 argument constructor (String, InputStream). This is useful if the StylusFile object being created is an adapter or converter which will read input from the InputStream. The application will normally get the result of the conversion by calling getInputStream() and reading the converted data from that stream.

The parameter String url is parsed to get the scheme prefix. The scheme is used to select a custom file system which can access files via that protocol. The scheme should either be a built-in scheme or should have been registered with registerScheme.

The scheme:// prefix is then removed from the url and the rest is passed as the String parameter to the constructor for that StylusFile class for the selected custom file system.

The StylusFile object returned by createStylusFile can be used to:

• Read data from the file with StylusFile.getInputStream() or StylusFile.copyToFile(String)

For more details, see StylusFile.

Returns:

A new StylusFile object for the class which was registered to the scheme.

Throws:

IOException - in any of the following conditions:

• The parameter url could not be parsed
• The scheme is not a built-in scheme and has not been registered. see registerScheme
• The registered class could not be found
• The registered class does not implement StylusFile
• There is no (String, InputStream) constructor for the registered class
• The constructor for the registered class throws an exception

registerScheme

public void registerScheme(String scheme,
                           String className)
                    throws IllegalArgumentException

Register a scheme name and its associated StylusFile class name. The method StylusFileFactory.createStylusFile examines the scheme: part of its URL parameter to know which class to instantiate. StylusFileFactory has a built-in association from the scheme: to the class name to be instantiated. This built-in list is:

• adapter: class com.stylusstudio.adapter.fs.AdapterFile
• dbxml: class com.stylusstudio.sleepycat.dbxml.DBXMLFile
• db: class com.stylusstudio.SQLXFile

If you will be using one of the built-in classes, you do not need to use the registerScheme method.
If, however, you have implemented another custom file system (that is, a class which implements StylusFile) and wish to use that class through the StylusFileFactory API, you must register the association between a scheme: and your class name. You do this by calling the registerScheme method. You must call it exactly once for each scheme you wish to register.

Parameters:

scheme - The scheme you wish to register.

className - The name of the class which implements StylusFile and which should be instantiated when a URL with the registered scheme is passed to the createStylusFile method.

Throws:

IllegalArgumentException - if

• The parameter scheme is a built-in scheme, or
• The parameter scheme has already been registered

resolve

public Source resolve(String URI,
                      String URIBase)
               throws TransformerException

Resolve a URI and return a Source which can be used to read data from the URI. The Source returned by this method is a StreamSource. To get the data, cast it as a StreamSource and call getInputStream().

Specified by:

resolve in interface URIResolver

Parameters:

URI - The URI to be resolved.

URIBase - The base URI in effect when the URI was encountered.

Returns:

A Source object which can be used to read the URI data, or null if the scheme: is not registered.

Throws:

TransformerException - If the URI is malformed.