com.stylusstudio.converter
Interface Conversion

All Superinterfaces:

ErrorHandler, ErrorListener

All Known Subinterfaces:

SAXConversion

public interface Conversion

extends ErrorHandler, ErrorListener

A Conversion object contains all the information needed during an ongoing conversion.

A conversion is initiated by creating a Converter object and then calling Converter.convert. The convert method returns a Conversion which actually controls the conversion process. In some cases, the conversion has already completed when Converter.convert returns the Conversion object; the Conversion object represents a completed conversion.

When the convert source is a OutputStreamSource, a WriterSource, or a SAXSource, the conversion will not be complete and system resources will not be released until all data has been delivered or the conversion has been cancelled. The application can

• query the status of the conversion with isFinished(),
• report errors using the ErrorHandler or ErrorListener interfaces
• cancel the conversion with cancel(),
• finish the conversion by closing the OutputStream, Writer, or by calling EndDocument().

A Conversion object implements ErrorHandler and ErrorListener as follows:

• fatalError is treated the same as cancel(Exception)
• warning and error: If the conversion was created with Converter.convert(Source, Result, ErrorListener), then warnings and errors are reported to the ErrorListener given on the convert call. Otherwise, they are written to System.err and processing continues.

Method Summary

void	cancel() Attempt to cancel a Conversion.
void	cancel(Exception e) Attempt to cancel a Conversion.
boolean	isFinished() Return whether the Conversion has finished.

Methods inherited from interface org.xml.sax.ErrorHandler

error, fatalError, warning

Methods inherited from interface javax.xml.transform.ErrorListener

error, fatalError, warning

Method Detail

isFinished

public boolean isFinished()

Return whether the Conversion has finished. If the Source object supplied to convert was an OutputStreamSource, a WriterSource, or a SAXSource, then the conversion cannot finish until the application has delivered all the data. isFinished() returns false until all the data has been delivered, after which it returns true.
For all other sources, the conversion finishes before convert returns the Conversion object and isFinished() always returns true.

Returns:

true if the conversion has finished; otherwise it returns false.

cancel

public void cancel()

Attempt to cancel a Conversion. If the conversion has already finished, this call has no effect. Otherwise, this cancels the conversion and releases system resources such as open file handles.
This method is useful if the conversion source is a SAXSource, OutputStreamSource, or a WriterSource, and the application cannot or does not want to close the source normally. In this case, the application should call cancel() to make sure system resources are released. In addition to cancelling the Conversion, this method attempts to throw a ConverterException to the conversion data source and conversion data consumer.

cancel

public void cancel(Exception e)

Attempt to cancel a Conversion. This method performs the same actions as cancel(). The Exception e is wrapped as a ConversionException or an IOException as needed and thrown to the conversion data source and conversion data consumer.