com.exln.stylus.io
Class StylusFileFactory

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

All Implemented Interfaces:

EntityResolver, URIResolver

public final class StylusFileFactory

extends Object

implements URIResolver, EntityResolver

Defines a factory API that enables applications to read and write data streams using any custom file system which implements the StylusFile interface. This class also implements the interfaces URIResolver and EntityResolver. If you register an instance of this class as the URIResolver and/or EntityResolver for your parser or transformer, it will use StylusFileFactory to resolve references as needed.
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. (Unless you supply the classpath when you call registerScheme(String scheme, String className, String classPath)).
• 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.
• You must have an Installation ID (supplied with your Stylus Studio license) and use it to unlock the StylusFileFactory with unlockAPI(String installID).

In particular, the built-in custom file systems have these requirements:

• dbxml: scheme:
  • CLASSPATH must include db.jar and dbxml.jar from Sleepycat Software
  • PATH must include all required .dll files from Sleeypcat Software
• ws: scheme:
  • If you use a proxy server, these system properties must be set appropriately:
    • http.proxySet=true
    • http.proxyHost=proxy server hostname
    • http.proxyPort=proxy server port (default is 80)
    • http.nonProxyHosts= a | separated list of hosts which may bypass the proxy server
    • http.proxyUser
    • http.proxyPassword

The built-in custom file systems (adapter: db: dbxml: ws:) are automatically registered with the registerScheme(String scheme, String className, String classPath) method. Except as described above, the class paths are determined automatically from the location of CustomFileSystem.jar.

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.

Nested Class Summary

static class

StylusFileFactory.ResolverWrapper Wraps the singleton StylusFileFactory object in a class which can be instantiated with a constructor.

Method Summary

static InputStream	createInputStream(String uri, String URIBase) A convenience method to resolve a Stylus Studio URI and return an InputStream.
static Result	createOutputResult(String uri, String URIBase) A convenience method to resolve a Stylus Studio URI and return a StreamResult.
static OutputStream	createOutputStream(String uri, String URIBase) A convenience method to resolve a Stylus Studio URI and return an OutputStream.
static StreamSource	createSource(String uri, String URIBase, boolean useResolver) A convenience method to resolve a Stylus Studio uri and return a StreamSource.
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.
StylusFile	createStylusFile(String url, OutputStream os) Create a StylusFile object for file access through a custom file system.
static StylusFileFactory	getFactory() Get the singleton StylusFileFactory.
static String	getUnlockAPIError() Get the error message generated from the last call to unlockAPI.
Result	outputStreamResolver(String uri, String URIBase) Resolve a URI and return a Result which can be used to write data to the URI.
void	registerScheme(String scheme, String className) Register a scheme name and its associated StylusFile class name.
void	registerScheme(String scheme, String className, String classPath) Register a scheme name and its associated StylusFile class name and classpath.
Source	resolve(String uri, String URIBase) Resolve a URI and return a Source which can be used to read data from the URI.
InputSource	resolveEntity(String publicId, String systemId) Implementation of EntityResolver.
static boolean	unlockAPI(String installID) Unlock the StylusFileFactory API.
static void	unlockObject(Object obj)

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.

unlockAPI

public static boolean unlockAPI(String installID)

Unlock the StylusFileFactory API. This must be called before the first time getFactory() is called. Note that the static convenience methods in this class (createInputStream, etc) call getFactory() internally. The API must be unlocked by calling unlockAPI before calling any of those methods as well.

Parameters:

installID - - The Installation ID provided with your license.

Returns:

true if the unlock succeeded, and the Installation ID authorizes the use of the StylusFileFactory API, otherwise false

getUnlockAPIError

public static String getUnlockAPIError()

Get the error message generated from the last call to unlockAPI. If the last call to unlockAPI return false, this method can be used to get the error message.

unlockObject

public static void unlockObject(Object obj)

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.copyFromFile(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) of the StylusFile class. 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 using it to read the converted data.

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
• Copy data with 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

createStylusFile

public StylusFile createStylusFile(String url,
                                   OutputStream os)
                            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, OutputStream) of the StylusFile class. This is useful if the StylusFile object being created is an adapter or converter which will write output to the OutputStream. The application will normally call the object's getOutputStream method and use that stream to send data to the adapter.

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 one of the registerScheme methods.

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 application can then send data to the StylusFile object returned by createStylusFile by calling either:

• StylusFile.getOutputStream() or
• StylusFile.copyFromFile(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, OutputStream) 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
• ws: class com.exln.stylus.webservice.WSFile

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. When your class is needed, StylusFileFactory will create a class loader whose class path will be taken from the system property className.classpath

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

registerScheme

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

Register a scheme name and its associated StylusFile class name and classpath. This method differs from registerScheme(String scheme, String className) by allowing the caller to specify additional classpath elements to use when loading classes for the specified scheme.

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.

classPath - Additional ';' separated elements of the classpath which will be used to load className. These pathnames will be appended after the pathnames in the system property: className.classpath

Throws:

IllegalArgumentException - if

• The parameter scheme is a built-in scheme, or
• The parameter scheme has already been registered with a different className or classPath

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.

outputStreamResolver

public Result outputStreamResolver(String uri,
                                   String URIBase)
                            throws TransformerException,
                                   IOException

Resolve a URI and return a Result which can be used to write data to the URI.

Parameters:

uri - The URI to be resolved.

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

Returns:

A Result which can be used to write data to the URI, or null if the scheme: is not registered. The Result returned is always a StreamResult. To write data to it, cast it as a StreamResult, and use getOutputStream to get the output stream. It is VERY important to close() the OutputStream, whether you actually write any data to it or not.

Throws:

TransformerException - If the URI is malformed.

IOException

createSource

public static StreamSource createSource(String uri,
                                        String URIBase,
                                        boolean useResolver)
                                 throws TransformerException

A convenience method to resolve a Stylus Studio uri and return a StreamSource. This method will (if useResolver is true) attempt to use the Stylus resolver to create a StreamSource. If that attempt fails, or useResolver is false, then this method will attempt to create a StreamSource directly from the uri.

Parameters:

uri - The URI to be resolved.

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

useResolver - Use the Stylus resolver if this is true.

Returns:

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

Throws:

TransformerException - If an error occurs.

createInputStream

public static InputStream createInputStream(String uri,
                                            String URIBase)
                                     throws IOException

A convenience method to resolve a Stylus Studio URI and return an InputStream. This method will attempt to use the Stylus resolver to create an InputStream.

Parameters:

uri - The URI to be resolved.

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

Returns:

An InputStream which can be used to read the URI data, or null if the URI could not be resolved

Throws:

IOException - If an error occurs.

createOutputStream

public static OutputStream createOutputStream(String uri,
                                              String URIBase)
                                       throws IOException

A convenience method to resolve a Stylus Studio URI and return an OutputStream. This method will attempt to use the Stylus resolver to create an OutputStream.

Parameters:

uri - The URI to be resolved.

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

Returns:

An OutputStream

Throws:

IOException - If an error occurs.

createOutputResult

public static Result createOutputResult(String uri,
                                        String URIBase)
                                 throws IOException

A convenience method to resolve a Stylus Studio URI and return a StreamResult. This method will attempt to use the Stylus resolver to create an StreamResult.

Parameters:

uri - The URI to be resolved.

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

Returns:

An OutputStream. It never return null.

Throws:

IOException - If an error occurs.

resolveEntity

public InputSource resolveEntity(String publicId,
                                 String systemId)
                          throws IOException

Implementation of EntityResolver. Attempts to resolve an external entity reference using the StylusFileFactory methods.

Specified by:

resolveEntity in interface EntityResolver

Parameters:

publicId - The public identifier of the external entity being referenced, or null if none was supplied.

systemId - The system identifier of the external entity being referenced.

Throws:

IOException