net.sf.joost
Interface TransformerHandlerResolver

All Known Implementing Classes:
TransformerHandlerResolverImpl

public interface TransformerHandlerResolver

Basic interface for resolving external TransformerHandler objects.

An object that implements this interface can be called by the STX processor if it encounters a request to hand over the processing to an external TransformerHandler object.

A TransformerHandlerResolver can be registered by using the Joost specific Processor.setTransformerHandlerResolver(net.sf.joost.TransformerHandlerResolver) method, or (using JAXP) by calling TransformerFactory.setAttribute(java.lang.String, java.lang.Object) with the string TrAXConstants.KEY_TH_RESOLVER as its first argument.

Also TransformerHandlerResolver can be registered using Java1.3 services plugin mechanism. This is achieved by specifying the particular handler implementation in META-INF/services/net.sf.joost.TransformerHandlerResolver file. Joost is using Jakarta's Discovery library to locate all available plugins which provides some additional configuration options one can employ as well.

The TransformerHandler object returned by each of the resolve methods is required to accept a SAXResult as parameter in the TransformerHandler.setResult(javax.xml.transform.Result) method. The other methods TransformerHandler.setSystemId(java.lang.String), TransformerHandler.getSystemId(), and TransformerHandler.getTransformer() won't be called by Joost. Especially potential parameters for the transformation will be provided already as the third argument in each of the resolve methods, so there's no need to implement a Transformer dummy solely as means to the end of enabling Transformer.setParameter(java.lang.String, java.lang.Object).

Version:
$Revision: 1.8 $ $Date: 2009/09/22 21:13:44 $
Author:
Oliver Becker

Method Summary
 boolean available(String method)
          Determines whether a requested filter is available or not, used by the STX function filter-available.
 TransformerHandler resolve(String method, String href, String base, URIResolver uriResolver, ErrorListener errorListener, Hashtable params)
          Resolves a TransformerHandler object for an external transformation.
 TransformerHandler resolve(String method, XMLReader reader, URIResolver uriResolver, ErrorListener errorListener, Hashtable params)
          Resolves a TransformerHandler object for an external transformation.
 String[] resolves()
          Return all supported filter-method URIs Each one must return true when checked against available(String).
 

Method Detail

resolve

TransformerHandler resolve(String method,
                           String href,
                           String base,
                           URIResolver uriResolver,
                           ErrorListener errorListener,
                           Hashtable params)
                           throws SAXException
Resolves a TransformerHandler object for an external transformation. This method will be called if the filter-src attribute contains an URL, or if this attribute is missing at all.

Parameters:
method - an URI string provided in the filter-method attribute, identifying the type of the requested filter
href - the location of the source for the filter provided in the filter-src attribute (as pseudo-argument of the url(...) notation); null if the filter-src attribute is missing
base - the base URI of the transformation sheet
uriResolver - the optional URIResolver configured for Joost
errorListener - the optional ErrorListener configured for Joost
params - the set of parameters specified using stx:with-param elements, all values are Strings
Returns:
a TransformerHandler object that transforms a SAX stream, or null if the STX processor should try to resolve the handler itself
Throws:
SAXException - if an error occurs during the creation or initialization

resolve

TransformerHandler resolve(String method,
                           XMLReader reader,
                           URIResolver uriResolver,
                           ErrorListener errorListener,
                           Hashtable params)
                           throws SAXException
Resolves a TransformerHandler object for an external transformation. This method will be called if the filter-src attribute contains a buffer specification.

Parameters:
method - an URI string provided in the filter-method attribute, identifying the type of the requested filter
reader - an XMLReader object that provides the source for the transformation as a stream of SAX events (the contents of an stx:buffer). Either parse method may be used, the required parameters systemId or input respectively will be ignored by this reader.
uriResolver - the optional URIResolver configured for Joost
errorListener - the optional ErrorListener configured for Joost
params - the set of parameters specified using stx:with-param elements, all values are Strings
Returns:
a TransformerHandler object that transforms a SAX stream, or null if the STX processor should try to resolve the handler itself
Throws:
SAXException - if an error occurs during the creation or initialization

available

boolean available(String method)
Determines whether a requested filter is available or not, used by the STX function filter-available.

Parameters:
method - an URI string identifying the type of the requested filter
Returns:
true if this resolver will return a TransformerHandler object for this filter

resolves

String[] resolves()
Return all supported filter-method URIs Each one must return true when checked against available(String).

Returns:
array of supported URIs