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	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 Logger	getLogger() Get the StylusFileHelpers.Logger object.

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 void TRACE(String msg) {
		StylusFileHelpers.getLogger().fine(msg);
	}
	...
	void mymethod() {
		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.

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 name of the output stream to which the data will be copied.

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.