com.exln.stylus.io
Class StylusFileHelpers

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

public class StylusFileHelpers

extends Object

A collection of static helpers for use with the Stylus Studio custom file system interfaces StylusFile and StylusFileSystem and the class StylusFileFactory.

These items are useful for custom file system implementers as well as Java application developers using the custom file systems.

Method Summary

static void	copyFromFile(StylusFile outputStylusFile, String fileName) Perform the copyFromFile function of the StylusFile interface.
static void	copyFromStream(StylusFile outputStylusFile, InputStream inStream) Copy data from an InputStream object to a StylusFile object.
static void	copyToFile(StylusFile inputStylusFile, String fileName) Perform the copyToFile function of the StylusFile interface.
static void	copyToStream(StylusFile inputStylusFile, OutputStream outStream) Copy data from a StylusFile object to a Stream object.
static IOException	createIOException(Throwable t) Convert an exception into an IOException.
static XMLReader	createXMLReader() Create an XMLReader implementation instance.
static void	doCopy(InputStream is, OutputStream os) Copy data from an InputStream to an OutputStream using a 64K buffer.
static boolean	doINFO() Return whether the INFO method will generate any output.
static boolean	doTRACE() Return whether the TRACE method will generate any output.
static String	getBinDir() Get the name of the directory containing CustomFileSystem.jar.
static Logger	getLogger() Get the StylusFileHelpers.Logger object.
static String	getResolvedPathname(String uri, String baseURI) Resolve a uri and a baseURI to form a local filesystem pathname.
static String	getResolvedURI(String uri, String baseURI) Convenience routine to resolve a uri with a baseURI using the java URI class.
static String	getRootDir() Get the Stylus Studio installation directory (rootdir).
static boolean	isLocalFile(String uri, String baseURI) Return whether the parameter represents a local file system file or directory.
static String	resolve(String uri, String baseURI) Resolve a URI with a base URI.
static String	stripFile(String path) Remove a file:/// prefix from a URL to create a pathname.

Methods inherited from class java.lang.Object

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

Method Detail

getLogger

public static Logger getLogger()

Get the StylusFileHelpers.Logger object.

Logging Facilities within Stylus Studio Custom File Systems
This section describes Stylus Studio's support for the Java logging mechanism in its custom file systems.
Any custom file system can write log messages using the Logger returned by this method. When a custom file system is used inside Stylus Studio, the log messages are displayed in the Stylus Studio Output Window. When a custom file system is used in a standalone Java program (using StylusFileFactory), the log messages are be written to stdout with System.out.println(). The command line utilities StylusXslt, StylusXql, StylusDiff, and XmlValidator do not support logging. Any calls to write messages using this logger will be ignored.

There is at most one instance of this class, created by the first call to getLogger(). Once you have the Logger object, you can use it to write log messages, or change the filtering Level for all subsequent messages.

Each message to be logged has a Level associated with it. Two levels are of particular interest:

• Level.INFO messages are general information that a user might want to see. You write these messages by calling the Logger.info(String) method.
• Level.FINE messages are tracing messages that are useful during debugging, but the end user does not normally want to see. You write these messages by calling the Logger.fine(String) method.

For details on writing log messages, see Logger and Level.

The Logger has a filtering level associated with it. Any message whose level is lower than the current filtering level is ignored. The filtering level is set in two ways:

1. System properties can be used to set the initial filtering level when the Logger is constructed.
   • TRACE sets the initial filtering level to Level.FINE (fine and info messages appear)
   • NOINFO sets the initial filtering level to Level.OFF (no message appear)
   If neither is present, the initial filtering level is Level.INFO (only info messages appear)
2. A Java class can change the filtering level at any time by calling the Logger.setLevel(java.util.logging.Level) method. The new level remains in effect until setLevel is called again by any class.

This is typical code inside a custom file system which writes a tracing message:

	...
  private static boolean doTRACE = StylusFileHelpers.doTRACE();
	private static void TRACE(String msg) {
		StylusFileHelpers.getLogger().fine(msg);
	}
	...
	void mymethod() {
		if (doTRACE) TRACE("mymethod called");
	...
	}
 

This code could be used in a Java application to suppress all logging messages:

	StylusFileHelpers.getLogger().setLevel(java.util.logging.Level.OFF);
 

although it might be preferable to start the JVM with the parameter -DNOINFO.

doTRACE

public static boolean doTRACE()

Return whether the TRACE method will generate any output. If TRACE is defined as recommended for getLogger(), then the simplest way to write a tracing message is with:

 TRACE("my message");
 

Since tracing is usually off, this generates unnecessary overhead, especially if the parameter to TRACE() is expensive to evaluate. This technique should, therefore, be modified to improve performance. The recommended technique is:

	static boolean doTRACE = StylusFileHelpers.doTRACE();
  ...
  void mymethod() {
		if (doTRACE) TRACE("mymethod called");
	...
	}
  ...
 

Returns:

A boolean value indicating whether TRACE output will actually be written to the log file.

doINFO

public static boolean doINFO()

Return whether the INFO method will generate any output. If INFO is defined as:

	static void INFO(String s)  { StylusFileHelpers.getLogger().info(s); }

then the simplest way to write a tracing message is with:

 INFO("my message");
 

If INFO is usually turned off, then this technique should be modified to improve performance. The recommended technique is:

	static boolean doINFO = StylusFileHelpers.doINFO();
  ...
  void mymethod() {
		if (doINFO) INFO("mymethod called");
	...
	}
  ...



Returns:
A boolean value indicating whether INFO output will actually
 be written to the log file.

copyToFile

public static void copyToFile(StylusFile inputStylusFile,
                              String fileName)
                       throws IOException

Perform the copyToFile function of the StylusFile interface. This method implements StylusFile.copyToFile, using the StylusFile.getInputStream method.
All implementors of StylusFile subclasses are encouraged to use this method as follows:

	public class myclass implements StylusFile {
	...
	public void copyToFile(String outputName) throws IOException {
		StylusFileHelpers.copyToFile(this, outputName);
	}
	...
 

Parameters:

inputStylusFile - The StylusFile object whose data should be copied to a file.

fileName - The name of the output file which will be created.

Throws:

IOException

copyToStream

public static void copyToStream(StylusFile inputStylusFile,
                                OutputStream outStream)
                         throws IOException

Copy data from a StylusFile object to a Stream object. This method uses the StylusFile.getInputStream method to get an InputStream, then copies all the data from that InputStream to the parameter OutputStream.

This method can be used to copy data from one StylusFile object to another as follows:

	...
	StylusFileHelpers.copyToStream(stylusFileIn, stylusFileOut.getOutputStream());
	...
 

Parameters:

inputStylusFile - The StylusFile object whose data should be copied.

outStream - The output stream to which the data will be copied.

Throws:

IOException

copyFromFile

public static void copyFromFile(StylusFile outputStylusFile,
                                String fileName)
                         throws IOException

Perform the copyFromFile function of the StylusFile interface. This method implements StylusFile.copyFromFile, using the StylusFile.getOutputStream method.
All implementors of StylusFile subclasses are encouraged to use this method as follows:

	public class myclass implements StylusFile {
	...
	public void copyFromFile(String inputName) throws IOException {
		StylusFileHelpers.copyFromFile(this, inputName);
	}
	...
 

Parameters:

outputStylusFile - The StylusFile object to which data should be copied.

fileName - The name of the input file which will be copied.

Throws:

IOException

copyFromStream

public static void copyFromStream(StylusFile outputStylusFile,
                                  InputStream inStream)
                           throws IOException

Copy data from an InputStream object to a StylusFile object. This method uses the StylusFile.getOutputStream method to get an OutputStream, then copies all the data from the parameter inputStream to that OutputStream.

This method can be used to copy data from one StylusFile object to another as follows:

	...
	StylusFileHelpers.copyFromStream(stylusFileOut, stylusFileIn.getInputStream());
	...
 

Parameters:

outputStylusFile - The StylusFile object to which data should be copied.

inStream - The input stream from which the data will be copied.

Throws:

IOException

doCopy

public static void doCopy(InputStream is,
                          OutputStream os)
                   throws IOException

Copy data from an InputStream to an OutputStream using a 64K buffer. This method does not close either Stream.

Parameters:

is - The InputStream.

os - The OutputStream

Throws:

IOException

createIOException

public static IOException createIOException(Throwable t)

Convert an exception into an IOException. Several of the methods in the StylusFile interface are declared with "throws IOException". When some other exception occurs which should be passed to the caller, it must be converted to an IOException. This method does that, while preserving the stack trace from the original exception.

Parameters:

t - The Throwable object which is to be converted to an IOException.

Returns:

The IOException.

stripFile

public static String stripFile(String path)

Remove a file:/// prefix from a URL to create a pathname. This removes file: file:/ file://, etc to leave a valid pathname. It also converts all \ characters to / and converts %20 escapes to blanks. If the path argument is a URI with a protocol other than file:, then this method will pretty much destroy the URL.

Parameters:

path - the String from which the file: prefix should be stripped.

Returns:

The resulting String pathname.

isLocalFile

public static boolean isLocalFile(String uri,
                                  String baseURI)

Return whether the parameter represents a local file system file or directory. This method examines the parameters to determine whether they could represent a local file. There is no check to determine whether the file actually exists or whether the path to the file exists.

Parameters:

uri - The URI to be checked

baseURI - If the uri parameter is relative, it will be taken as relative to this base.

Returns:

true if the parameters represent a local file system file or

getResolvedPathname

public static String getResolvedPathname(String uri,
                                         String baseURI)

Resolve a uri and a baseURI to form a local filesystem pathname. The resulting pathname will have all \ characters converted to /, and all %20 escapes converted to blanks.

Parameters:

uri - The URI to be resolved.

baseURI - If the uri parameter is relative, it will be taken as relative to this base.

Returns:

The resolved pathname (without any file: prefix), or null if the resolved URI does not belong to the file: protocol.

getResolvedURI

public static String getResolvedURI(String uri,
                                    String baseURI)

Convenience routine to resolve a uri with a baseURI using the java URI class. This routine wraps a call to URI.resolve(java.lang.String) to resolve a uri string relative to a base URI.

Parameters:

uri - The uri string to be resolved.

baseURI - The base URI to resolve with.

Returns:

The resolved uri if it was successful, otherwise the original uri.

resolve

public static String resolve(String uri,
                             String baseURI)

Resolve a URI with a base URI. If the combination of the two parameters could represent a local file system file, then the returned string is a legal path name suitable for use with java classes such as java.io.File. Otherwise, it is presumed to be a URI, and the returned string will (if possible) contain a protocol prefix, and blank characters will be escaped with %20.

Parameters:

uri - The URI to be resolved

baseURI - The base URI to resolve uri with.

Returns:

The resolved string.

getBinDir

public static String getBinDir()

Get the name of the directory containing CustomFileSystem.jar. If the user has set the system property "com.stylusstudio.bindir" AND it contains a valid directory name which contains CustomFileSystem.jar, then that name will be returned. Otherwise, this method will use ClassLoader.getResource to find the correct directory.

Returns:

The name of the directory containing CustomFileSystem.jar.

getRootDir

public static String getRootDir()

Get the Stylus Studio installation directory (rootdir). If the user has set the system property "com.stylusstudio.rootdir" AND it contains a valid directory name which contains bin/CustomFileSystem.jar, then that name will be returned. Otherwise, this method will use ClassLoader.getResource to find the correct directory.

Returns:

The name of the Stylus Studio installation directory.

createXMLReader

public static XMLReader createXMLReader()
                                 throws SAXException

Create an XMLReader implementation instance. This job should be performed by XMLReaderFactory.createXMLReader(), but under Java 1.4, that method is not sufficiently smart. This method tries to use XMLReaderFactory.createXMLReader, but if that fails, it then tries to load the following classes:

• The class name in the system property org.xml.sax.driver
• org.apache.crimson.parser.XMLReaderImpl
• org.apache.xerces.parsers.SAXParser

Returns:

An instance of an XMLReader.

Throws:

SAXException