=head1 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:

=for html <a href="http://xml.apache.org/xalan-j/trax.html">Apache TrAX Page</a><br>

=for html <a href="http://java.sun.com/j2se/1.4.1/docs/api/javax/xml/transform/package-summary.html"> Java 2 SDK SE TrAX Reference</a>

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

=head2 Objects

B<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. 

=over

=item L<TransformerFactory|transformerfactory>

=item L<Templates|templates>

=item L<Transformer|transformer>

=item L<SAXSource|saxsource>

=item L<SAXResult|saxresult>

=item L<URIResolver|uriresolver>

=item L<ErrorListener|errorlistener>

=back

=head2 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:

=over

=item new_templates(L<SAXSource|saxsource>) as L<Templates|templates>

Returns a new instance of Templates. 
The source can also be provided as L<InputSource|inputsource> or I<uri>, 
which is turned into L<SAXSource|saxsource> object automatically
using a default L<XML reader|xmlreader>.

=item new_transformer(L<SAXSource|saxsource>) as L<Transformer|transformer>

Returns a new instance of Transformer.
The source can also be provided as L<InputSource|inputsource> or I<uri>, 
which is turned into L<SAXSource|saxsource> object automatically
using a default L<XML reader|xmlreader>.

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

=item new_source(I<uri>, L<XMLReader|xmlreader>?) as L<SAXSource|saxsource>

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

=item new_result(L<Handler|handler>?) as L<SAXResult|saxresult>

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

=back

PROPERTIES:

=over

=item ErrorListener as L<ErrorListener|errorlistener>

Error listener that is in use when parsing templates.

=item URIResolver as L<URIResolver|uriresolver>

URI resolver that is in use when parsing templates.

=back

=head2 Templates

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

METHODS:

=over

=item new_transformer( ) as L<Transformer|transformer>

Returns a new instance of Transformer.

=back

=head2 Transformer

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

METHODS:

=over

=item transform(L<SAXSource|saxsource>, L<SAXResult|saxresult>?) as I<result>

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

=item clear_parameters( )

Clears all parameters set for this transformer.

=back

PROPERTIES:

=over

=item Parameters as I<hashref>

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

=item ErrorListener as L<ErrorListener|errorlistener>

Error listener that is in use during the transformation.

=item URIResolver as L<URIResolver|uriresolver>

URI resolver that is in use during the transformation.

=back

=head2 SAXSource

A data holder for SAX input streams. 

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

PROPERTIES:

=over

=item SystemId as I<uri>

System identifier for the source (optional).

=item XMLReader as L<XMLReader|xmlreader>

XML reader for the source.

=item InputSource as L<InputSource|inputsource>

SAX InputSource for the source.

=back

=head2 SAXResult

A data holder for SAX output streams.

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

PROPERTIES:

=over

=item SystemId as I<uri>

System identifier for the result (optional).

=item Handler as L<Handler|handler>

Content handler for the result.

=back

=head2 URIResolver

An object that can be called by the processor to turn URIs used in 
transformations into L<SAXSource|saxsource> objects.

METHODS:

=over

=item resolve(I<uri>, I<uri>) as L<SAXSource|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.

=back

PROPERTIES:

=over

=item Sources as I<hashref>

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

=item Results as I<hashref>

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

=back

=head2 ErrorListener

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

METHODS:

=over

=item warning(L<Exception|exception>)

Receives notification of a warning.

=item error(L<Exception|exception>)

Receives notification of a recoverable error.

=item fatal_error(L<Exception|exception>)

Receives notification of a non-recoverable error.

=back

=head2 Other definitions

=for html Some terms referred in this document are defined in <a href="http://perl-xml.sourceforge.net/sax/">Perl SAX</a>. These terms include:

=head3 XMLReader

An implementation of Parser interface.

=for html See <a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/perl-xml/libxml-perl/doc/sax-2.0.html">Perl SAX 2.0 Binding</a>.

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

=head3 InputSource

A hash representing input source.

=for html See <a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/perl-xml/libxml-perl/doc/sax-2.0-adv.html#InputSources">Advanced SAX</a>.

=head3 Handler

A content handler.

=for html See <a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/perl-xml/libxml-perl/doc/sax-2.0-adv.html#Handlers">Advanced SAX</a>.

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

=head3 Exception

A (blessed) hash representing a Perl exception.

=for html See <a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/perl-xml/libxml-perl/doc/sax-2.0.html#Exceptions">Perl SAX 2.0 Binding</a>.

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

=cut
