The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
XML-STX-0.43
River stage zero No dependents
++
/ doc::TrAXref

TrAX-like API for XML::STX

Transformation API for XML (TrAX) is a generic Java API for performing a transformation from source to a result. See the links below for more details:

Apache TrAX Page
Java 2 SDK SE TrAX Reference

This document describes a simple TrAX-like Perl API that has been developed for purposes of XML::STX transformation engine.

Objects

General rules and conventions: There are no set/get methods to access to properties. All properties can be passed to new() and set directly in the object. Objects and properties are all mixed case with initial upper-case. Method names have been converted to lower-case with underscores.

TransformerFactory
Templates
Transformer
SAXSource
SAXResult
URIResolver
ErrorListener

TransformerFactory

A factory for Templates objects, a direct factory for Transformer objects. Can also serve as factory for other objects (e.g. SAXSource, SAXResult). This class is used as a base class for the processor.

METHODS:

new_templates(SAXSource) as Templates

Returns a new instance of Templates. The source can also be provided as InputSource or uri, which is turned into SAXSource object automatically using a default XML reader.

new_transformer(SAXSource) as Transformer

Returns a new instance of Transformer. The source can also be provided as InputSource or uri, which is turned into SAXSource object automatically using a default XML reader.

This is a shortcut method that provides a default transformation context for a Templates object directly.

new_source(uri, XMLReader?) as SAXSource

Returns a new instance of SAXSource. The second argument is optional; an instance of XML reader is created automatically if it's missing.

new_result(Handler?) as SAXResult

Returns a new instance of SAXResult. The argument is optional; an instance of handler is created automatically if it's missing.

PROPERTIES:

ErrorListener as ErrorListener

Error listener that is in use when parsing templates.

URIResolver as URIResolver

URI resolver that is in use when parsing templates.

Templates

A runtime representation of the transformation instructions. A data bag for transformation instructions; act as a factory for Transformers.

METHODS:

new_transformer( ) as Transformer

Returns a new instance of Transformer.

Transformer

An execution context for transformations, it serves as an interface for performing the transformation.

METHODS:

transform(SAXSource, SAXResult?) as result

Performs the transformation. The source can also be provided as InputSource or uri, which is turned into SAXSource object automatically using a default XML reader. The second argument is optional; an instance of SAXResult is created automatically if it's missing.

clear_parameters( )

Clears all parameters set for this transformer.

PROPERTIES:

Parameters as hashref

Parameters is a hash keyed by parameter names in JClark's namespace notation. The keys are of the form {NamespaceURI}LocalName. If a parameter has no NamespaceURI, then it is simply LocalName. Values of the hash are scalar values of parameters.

ErrorListener as ErrorListener

Error listener that is in use during the transformation.

URIResolver as URIResolver

URI resolver that is in use during the transformation.

SAXSource

A data holder for SAX input streams.

This object implements an interface called Source representing multiple types of input. Other implementations include DOMSource and StreamSource, none of them implemented by XML::STX.

PROPERTIES:

SystemId as uri

System identifier for the source (optional).

XMLReader as XMLReader

XML reader for the source.

InputSource as InputSource

SAX InputSource for the source.

SAXResult

A data holder for SAX output streams.

This object implements an interface called Result representing multiple types of output. Other implementations include DOMResult and StreamResult, none of them implemented by XML::STX.

PROPERTIES:

SystemId as uri

System identifier for the result (optional).

Handler as Handler

Content handler for the result.

URIResolver

An object that can be called by the processor to turn URIs used in transformations into SAXSource objects.

METHODS:

resolve(uri, uri) as SAXSource

Parameters are URI to be resolved and optional base URI. The function returns a SAXSource object or undef if the URI cannot be resolved.

PROPERTIES:

Sources as hashref

Sources is a hash keyed by URIs. Values of the hash are SAXSource objects. These URI-Source pairs are used when trying to resolve an input URI before standard resolution mechanisms take place.

Results as hashref

Results is a hash keyed by URIs. Values of the hash are SAXResult objects. These URI-Result pairs are used when trying to resolve an output URI before standard resolution mechanisms take place.

ErrorListener

This interface is used by TransformerFactory and Transformer to report all errors and warnings. The ErrorListener property of these objects is used to register an instance of this object.

METHODS:

warning(Exception)

Receives notification of a warning.

error(Exception)

Receives notification of a recoverable error.

fatal_error(Exception)

Receives notification of a non-recoverable error.

Other definitions

Some terms referred in this document are defined in Perl SAX. These terms include:

XMLReader

An implementation of Parser interface.

See Perl SAX 2.0 Binding.

The default XML reader is chosen from compliant SAX2 parsers installed in system; XML::SAX::PurePerl being the fall-back.

InputSource

A hash representing input source.

See Advanced SAX.

Handler

A content handler.

See Advanced SAX.

The default handler is chosen from compliant SAX2 writers installed in system; XML::STX::Writer being the fall-back.

Exception

A (blessed) hash representing a Perl exception.

See Perl SAX 2.0 Binding.

$Id: TrAXref.pod,v 1.9 2003/05/29 08:42:04 cvspetr Exp $