com.ddtek.xmlconverter
Interface Converter

All Known Subinterfaces:

ConvertFromXML, ConvertToXML

public interface Converter

Instances of this class perform conversion from XML to non-XML, and vice versa.

Instances are created using several static methods in the class ConverterFactory.
The actual conversion is then started with the method convert.
Certain policies can be set by the application in the Configuration object.
Instances of this class are thread safe: an application can use the same Converter object to do multiple conversions simultaneously in different threads.

Method Summary

Conversion	analyze(Source source, Result result) Test whether a conversion would succeed and create an XML document which contains the results of the test.
Conversion	convert(Source source, Result result) Start the conversion and (possibly) wait for completion.
Conversion	convert(Source dataSource, Result result, Source reportSource) Start the conversion using both the source data and an analyze report input, and (possibly) wait for completion.
Configuration	getConfiguration() Get the Configuration object for this Converter.
ErrorHandler	getErrorHandler() Get the ErrorHandler previously set with setErrorHandler.
ErrorListener	getErrorListener() Get the ErrorListener previously set with setErrorListener.
OutputStream	getOutputStream(Result result) Get a OutputStream to write the input data to.This method does not start the conversion, that occurs when the application writes the input data to, and closes the OutputStream.
void	setErrorHandler(ErrorHandler handler) Set an ErrorHandler to which errors should be reported by the converter.
void	setErrorListener(ErrorListener listener) Set an ErrorListener to which errors should be reported by the converter.

Method Detail

convert

Conversion convert(Source source,
                   Result result)
                   throws ConverterException

Start the conversion and (possibly) wait for completion.
It is important to note that after this method returns, the conversion might not yet be complete, however it is safe to immediately call convert again on the same Converter object.

If the application is pushing data into the Converter (using OutputStreamSource, WriterSource, or SAXSource), then the conversion will not be finished until all data has been delivered and the appropriate end-of-data indication has been delivered.

Parameters:

source - is an instance of Source.

The following source classes are supported for conversion to XML.

• StreamSource
• OutputStreamSource
• WriterSource

In addition to the above, the following source classes are supported for conversion from XML.

• DOMSource
• SAXSource
• XMLStreamReaderSource
• XMLStreamWriterSource

result - is an instance of Result.

The following result classes are supported for conversion from XML.

• StreamResult
• OutputResult
• InputStreamResult
• ReaderResult

In addition to the above, the following result classes are supported for conversion to XML.

• XMLStreamReaderResult
• XMLStreamWriterResult
• DOMResult
• SAXResult

Returns:

The Conversion object that represents the conversion. The application can ignore this return value if it desires, however the application can use the returned Conversion object to gain additional control over the conversion process. If the source object is a SAXSource, then the object returned by convert is a ContentHandler. The application can then send the data to the converter by calling the appropriate methods in the ContentHandler;

Throws:

ConverterException

convert

Conversion convert(Source dataSource,
                   Result result,
                   Source reportSource)
                   throws ConverterException

Start the conversion using both the source data and an analyze report input, and (possibly) wait for completion.
It is important to note that after this method returns, the conversion might not yet be complete, however it is safe to immediately call convert again on the same Converter object.

This method is to be used in conjunction with the analyze(Source, Result) method. The analyze(Source, Result) method reads its Source data and generates an XML report describing all the interchanges, groups and messages in the input document. This method uses both the source data and the analyze report to generate an output file containing all the interchanges, groups and messages which could be converted without errors. The converter omits all the erroneous parts of the data.

Parameters:

dataSource - See the source parameter of the convert(Source, Result) method.

result - See the result parameter of the convert(Source, Result) method.

reportSource - This Source object contains the analyze report generated by the analyze(Source, Result) method.

Returns:

The Conversion object that represents the conversion. The application can ignore this return value if it desires, however the application can use the returned Conversion object to gain additional control over the conversion process. If the source object is a SAXSource, then the object returned by convert is a ContentHandler. The application can then send the data to the converter by calling the appropriate methods in the ContentHandler;

Throws:

ConverterException

analyze

Conversion analyze(Source source,
                   Result result)
                   throws ConverterException

Test whether a conversion would succeed and create an XML document which contains the results of the test.
It is important to note that after this method returns, the analysis might not yet be complete.

The result document is an XML file containing a list of all the interchanges, groups, and messages in the input document. It indicates which could be successfully converted, and identifies the errors for those which could not.

Parameters:

source - See the source parameter of the convert(Source, Result) method.

result - is an instance of Result. The analyze report will be written to the result object.

The following result classes are supported.

• StreamResult
• OutputResult
• InputStreamResult
• ReaderResult
• XMLStreamReaderResult
• XMLStreamWriterResult
• DOMResult
• SAXResult

Throws:

ConverterException

getOutputStream

OutputStream getOutputStream(Result result)
                             throws ConverterException

Get a OutputStream to write the input data to.This method does not start the conversion, that occurs when the application writes the input data to, and closes the OutputStream.

Parameters:

result - A Result object specifying where the converted data should be written.

Returns:

A OutputStream.

Throws:

ConverterException - if an error occurs

getConfiguration

Configuration getConfiguration()

Get the Configuration object for this Converter. The caller can modify the returned Configuration object. Any changes affect subsequent conversions done with this Converter object.

Returns:

The Converter's Configuration object.

setErrorListener

void setErrorListener(ErrorListener listener)

Set an ErrorListener to which errors should be reported by the converter. Calling this method will replace any previously set ErrorHandler or ErrorListener.

getErrorListener

ErrorListener getErrorListener()

Get the ErrorListener previously set with setErrorListener.

setErrorHandler

void setErrorHandler(ErrorHandler handler)

Set an ErrorHandler to which errors should be reported by the converter. Calling this method will replace any previously set ErrorHandler or ErrorListener.

getErrorHandler

ErrorHandler getErrorHandler()

Get the ErrorHandler previously set with setErrorHandler.