com.reverseXSL.transform
Class TransformerFactory

java.lang.Object
  com.reverseXSL.transform.TransformerFactory

public final class TransformerFactory
extends java.lang.Object

A TransformerFactory is instantiated with a source of transformation meta-data, namely mapping selection meta-data as well as parsing DEFinitions and XSL transformation templates.

The distinction between a TransformerFactory and subsequent Transformer objects follows the classical java pattern.

A factory is instantiated, used to set various parameters, and then used to instantiate Transformer objects. All Transformer objects from the same factory inherit and share meta-data from the factory. The factory can be used to tune parameters that control the behaviour of Transformer objects.

Transformer objects are in turn used to execute message parsings and transformations, with the help of resources and parameters inherited from the factory.

Note that the link between the factory and Transformer objects is never broken in the present design: changes to factory parameters may affect the behaviour of Transformer objects already generated! Yet, proper practice recommends to set all factory features before instantiating the first Transformer, and using it.

See Also:

Transformer

Method Summary

static TransformerFactory	newInstance() Instantiates a Transformer Factory that will load meta-data from the software distribution jar file itself.
Transformer	newTransformer() Instantiate a new Transformer from the factory.
Transformer	newTransformer(java.util.jar.JarFile jarFile) Instantiates a Transformer with meta-data from an explicitly specified jar file.
Transformer	newTransformer(java.io.Reader myDefinition, java.io.Reader myXSLT) Instantiates a new Transformer instance from the factory, which will bypass the Mapping Selection process.
void	setExternalMappingSelectionTable(java.io.Reader r) Imposes the specified Mapping Selection Table meta-data (full replacement).
void	setExternalMappingSelectionTable(java.io.Reader r, java.lang.String path) Imposes the specified Mapping Selection Table meta-data (full replacement).
void	setInputCharSet(java.nio.charset.Charset charset) Sets the Charset used for decoding input message bytes into characters, using a java Charset object.
void	setInputCharSet(java.lang.String charset) Sets the Charset used for decoding input message bytes into characters, using a java Charset name.
void	setInputDataConversions(int specs) Sets the conversions to perform on input data at byte or character level before applying transformations in proper.
void	setOutputCharSet(java.nio.charset.Charset charset) Sets the Charset used for encoding output message characters into bytes, using a java Charset object.
void	setOutputCharSet(java.lang.String charset) Sets the Charset used for encoding output message characters into bytes, using a java Charset object.
void	setParserExceptionThresholds(int maxFatal, int maxTotal) Sets specific Parser tolerance to input message syntax errors.
void	setParserRemoveNonRepeatableNilOptionalElements(boolean bool) Would cause (if set TRUE) to remove from the output XML document all data elements with a NIL value that are optional or conditional elements, and whose matching definition indicates that the element is non repeatable (i.e.
void	setPrintableXmlIndent(java.lang.String ptrn) Sets the pattern of chars that will be repeated at each depth level to indent the printable-XML output.

Methods inherited from class java.lang.Object

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

Method Detail

newInstance

public static final TransformerFactory newInstance()

Instantiates a Transformer Factory that will load meta-data from the software distribution jar file itself.

This variant uses the classloader. It is then able to find all meta-data resources that are placed on the CLASSPATH.

Returns:

a factory instance

newTransformer

public Transformer newTransformer()
                           throws java.io.IOException,
                                  TransformerException

Instantiate a new Transformer from the factory. In this simplest-to-use version, all resources are loaded from the CLASSPATH, meaning: the mapping selection table, plus the parsing DEF, and the XSL resources, are fetched from the ClassLoader when needed.

Returns:

a Transformer instance

Throws:

java.io.IOException

TransformerException

newTransformer

public Transformer newTransformer(java.util.jar.JarFile jarFile)
                           throws java.io.IOException,
                                  TransformerException

Instantiates a Transformer with meta-data from an explicitly specified jar file.

The jar file does not need to be on the CLASSPATH and may contain alternative transformation meta-data sets. The jar must contain a Mapping Selection Table and all other dependent meta-data pieces (Parsing DEFs and XSL templates). The specified jar does not take precedence but replaces entirely the default resources, including the mapping selection table.

The method setExternalMappingSelectionTable(Reader) still allows to overrride the mapping selection table (over that which can be on the CALSSPATH, else within the explicitly specified jar).

Parameters:

jarFile - a JarFile object containing all meta-data resources

Returns:

a Transformer instance

Throws:

java.io.IOException

TransformerException

newTransformer

public Transformer newTransformer(java.io.Reader myDefinition,
                                  java.io.Reader myXSLT)
                           throws java.io.IOException

Instantiates a new Transformer instance from the factory, which will bypass the Mapping Selection process. It will always apply the parsing DEF and XSL transformation specified in argument. One or both of these arguments may be nulls in order to skip the corresponding transformation step.

Parameters:

myDefinition - a Reader on a DEF file or null

myXSLT - a Reader on an XSL file or null

Returns:

a Transformer instance

Throws:

java.io.IOException - in case of read errors from one of the Reader arguments

setExternalMappingSelectionTable

public void setExternalMappingSelectionTable(java.io.Reader r)
                                      throws java.io.IOException,
                                             TransformerException

Imposes the specified Mapping Selection Table meta-data (full replacement).

The CLASSPATH or a JAR will still be used as source for transformation resources (Parsing DEFs and XSL templates), depending upon the method of creating the Transformer.

Parameters:

r - A Reader from which the table will be loaded

Throws:

java.io.IOException

TransformerException

setExternalMappingSelectionTable

public void setExternalMappingSelectionTable(java.io.Reader r,
                                             java.lang.String path)
                                      throws java.io.IOException,
                                             TransformerException

Imposes the specified Mapping Selection Table meta-data (full replacement).

One can provide an optional path argument that will formally be added to the CLASSPATH for loading resources (Parsing DEFs and XSL templates).

Parameters:

r - A Reader from which the table will be loaded

path - if not null or empty, a directory path to be used as root location for loading associated mapping resources

Throws:

java.io.IOException

TransformerException

setInputCharSet

public void setInputCharSet(java.nio.charset.Charset charset)

Sets the Charset used for decoding input message bytes into characters, using a java Charset object. The default is UTF-8.

Parameters:

charset - a java Charset or null to reset to default UTF-8

See Also:

setInputCharSet(String)

setInputCharSet

public void setInputCharSet(java.lang.String charset)

Sets the Charset used for decoding input message bytes into characters, using a java Charset name. The default is UTF-8.

Useful character set names to consider are the legacy 7bit "US-ASCII", 8-bit collections like "ISO-8859-1" (ISO Latin Alphabet No. 1 or 2,3,4..), "EBCDIC-INT", and "EBCDIC-CP-US", multibyte sets like "Shift_JIS", and the now standard Unicode Transformation Formats "UTF-8", or "UTF-16". The full listing is available at the IANA Charset Registry (http://www.iana.org/assignments/character-sets).

Parameters:

charset - a java Charset name as String or null to reset to default UTF-8

setInputDataConversions

public void setInputDataConversions(int specs)

Sets the conversions to perform on input data at byte or character level before applying transformations in proper.

Parameters:

specs - add flag values as defined by Data constants.

See Also:

Data

setOutputCharSet

public void setOutputCharSet(java.nio.charset.Charset charset)

Sets the Charset used for encoding output message characters into bytes, using a java Charset object. The default is UTF-8.

Parameters:

charset - a java Charset or null to reset to default UTF-8

See Also:

setOutputCharSet(String)

setOutputCharSet

public void setOutputCharSet(java.lang.String charset)

Sets the Charset used for encoding output message characters into bytes, using a java Charset object. The default is UTF-8.

Useful character set names to consider are the legacy 7bit "US-ASCII", 8-bit collections like "ISO-8859-1" (ISO Latin Alphabet No. 1 or 2,3,4..), "EBCDIC-INT", and "EBCDIC-CP-US", multibyte sets like "Shift_JIS", and the now standard Unicode Transformation Formats "UTF-8", or "UTF-16". The full listing is available at the IANA Charset Registry (http://www.iana.org/assignments/character-sets).

Parameters:

charset - a java Charset name as String or null to reset to default UTF-8

setParserExceptionThresholds

public void setParserExceptionThresholds(int maxFatal,
                                         int maxTotal)

Sets specific Parser tolerance to input message syntax errors. Every element of syntax definition for a given message in a Parser DEF file is associated to a Warning or Fatal exception. These exceptions are raised whenever the corresponding syntax rule is violated by an input message; but 'raised' doesn't mean 'thrown': indeed, the Parser silently records all violations till thresholds are reached, at which time an exception will effectively be thrown. In other words, the Parser actually attempts to recover from syntax violations and continue parsing the input (e.g. skipping faulty data) util the thresholds are met. The default threshold is 10 warnings and no fatal error.

Parameters:

maxFatal - new acceptable count of syntax violations conunted as Fatal

maxTotal - new total acceptable count of syntax violations (all as warnings, or acceptable fatal + acceptable warnings)

setParserRemoveNonRepeatableNilOptionalElements

public void setParserRemoveNonRepeatableNilOptionalElements(boolean bool)

Would cause (if set TRUE) to remove from the output XML document all data elements with a NIL value that are optional or conditional elements, and whose matching definition indicates that the element is non repeatable (i.e. ACC 1), and whose minimum size requirement is >0.

This function is actually quite useful on messages based on the principle of positional data elements within 'segments' (e.g. EDIFACT, TRADACOMS, X12, etc.). Indeed, most positions (think 'slots') in such segments are occupied by optional/conditional data elements, all unique and distinguished by their relative position in the 'segment'. Every unoccupied position will yield a corresponding NIL data element in XML, that can be suppressed from the XML output if this method is set to TRUE.

NIL data elements are supressed only if they have a min/max size specification (of the kind [1..15] ) with a minimum of at least 1. Obviously, if 0 is an acceptable size for the element, there's no reason to suppress the element.

Moreover, the element must be non-repeatable otherwise there is a risk to eat-up intermediate elements within series, causing undesirable rank shifts.

The default value is TRUE.

Parameters:

bool - whether or not to Remove non-repeatable NIL optionals

setPrintableXmlIndent

public void setPrintableXmlIndent(java.lang.String ptrn)

Sets the pattern of chars that will be repeated at each depth level to indent the printable-XML output. Only applicable to Transformer.printableTransform(InputStream, StringBuffer)

Parameters:

ptrn - a pattern like " ", or "| " for increased readability (really cool!).