org.inria.ns.reflex.processor.xcl
Class TransformAction

java.lang.Object
  extended by org.inria.ns.reflex.processor.core.AbstractAction
      extended by org.inria.ns.reflex.processor.core.AbstractSetAction
          extended by org.inria.ns.reflex.processor.xcl.TransformAction
All Implemented Interfaces:
Computable, Executable, Presentable, NamespaceContextFactory

public class TransformAction
extends AbstractSetAction

The primary usage of the <xcl:transform> element is to perform an XSLT transformation to the document specified in the source attribute, with the stylesheet specified in the stylesheet attribute.

It can handle all combinations of XML/DOM/SAX to XML/DOM/SAX with or without a stylesheet and with or without a serializer (SVG to PNG, XSLFO to PDF...); DOM and SAX output styles are not relevant when a serializer is involved; the serializer write to an output stream that can be an URL of any type supported (file, http, ftp...). Output in DOM or SAX can be plugged to a next transformer. Supported stylesheets are: XSLT, pre-compiled stylesheets (classes instance of Transformer) or even SAX filters (classes that extends XMLFilterImpl with a zero-argument constructor). Classes can be referred with the "res" URI scheme.

<xcl:transform
          source="file:///path/to/doc.xml"
          output="file:///path/to/doc.html"
          stylesheet="file:///path/to/html.xslt"
>
      <xcl:param name="date" value="{$today}">
      <xcl:param name="captain-age" value="{$captain-age}">
      <!--overrides the encoding specified in the stylesheet-->
      <xcl:param name="xsl:encoding" value="iso-8859-1"
                         xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
</xcl:transform>

Notice that the name of a parameter may be a qualified name, thus <xcl:param name="foo:captain-age" value="{$captain-age}" xmlns:foo="http://www.foo.com"> will be set to the stylesheet variable that has the same local-name and namespace-uri; unqualified names are not bound to a namespace URI. Parameter names bound to the XSLT namespace override the output properties specified in the stylesheet.

URI resolution

URIs are resolved with the catalog in use by the processor instance. See URIReferenceResolver.

Error handling

See XMLError.

Optional parameters

Parameters may be set conditionnally (subactions can be used), like this :

<xcl:transform
          name="result"
          source="{$xml}"
          stylesheet="{$xslt}"
>
      <xcl:param name="date" value="{$today}">
      <xcl:if test="{$captain-age}">
          <xcl:then><!--set the parameter only if it exists-->
              <xcl:param name="captain-age" value="{$captain-age}">
          </xcl:then>
      </xcl:if>
</xcl:transform>

Serialization

If the transformation is intended to produce a byte stream (a file), the MIME type can be specified to activate a serializer:

<xcl:transform
          source="file:///path/to/sales.xml;"
          output="file:///path/to/sales-svg.jpeg"
          stylesheet="file:///path/to/svg.xslt"
          mime-type="image/jpeg"
 />

Here, the XML source is transformed with XSLT to SVG, then serialized to JPG.

If the XML source is already in SVG, then stylesheet can be omitted:

<xcl:transform
          source="file:///path/to/sales.svg;"
          output="file:///path/to/sales-svg.jpeg"
          mime-type="image/jpeg"
 />

The serializers available in RefleX are specified for each MIME type supported in META-INF/services/org.inria.ns.reflex.xml.SerializerFactory/

The serializers specified in the RefleX JAR are the fallback ones, and if another JAR file overwrite existing definitions in its own META-INF/services/..., they will be preferred. Custom serializers can be also added as well, by adding the relevant MIME type to the path.

Serializers also accept parameters if their name are in the relevant namespace URI. Refer to the documentation of the serializer.

Compiled stylesheets

XSLT stylesheet can be compiled to Java bytecode; RefleX provides a tool for that purpose (Compile) that can be used at designed time.

Instead of parsing a stylesheet, the target class can be referred in place of the stylesheet reference thanks to the "res:" URI scheme that is used for classes and resources to lookup in the JAR known by the JVM :

<xcl:transform
          name="result"
          source="{$xml}"
          stylesheet="res:org.acme.MyTemplates"
 />

Ensure that the relevant class is reachable by the JVM (set it to the classpath or put in the WEB-INF/lib directory for Web applications)

Note that the "res:" URI scheme can also be used to refer a non-compiled stylesheet (XSLT):

<xcl:transform
          name="result"
          source="{$xml}"
          stylesheet="res:///org/acme/resources/stylesheet.xslt"
 />

When the URI is opaque (doesn't start with res://), it denotes a class name that must be an implementation of the Templates interface; when the URI is hierarchic (do start with res://), it denotes a path to a resource within the JAR known by the JVM.

SAX filters

Similarly to compiled stylesheet, SAX filters are also supported; classes must extends XMLFilterImpl and have a zero-argument constructor.

<xcl:transform
          name="result"
          source="{$xml}"
          stylesheet="res:org.acme.MyXMLFilterImpl"
 />

Author:
Philippe Poulard
See Also:
ParseStylesheetAction, SetParameterAction, URIReferenceResolver, SerializerFactory, Templates, Compile, XMLFilterImpl

Nested Class Summary
 
Nested classes/interfaces inherited from class org.inria.ns.reflex.processor.core.AbstractAction
AbstractAction.ParameterAdapter, AbstractAction.UselessAction
 
Field Summary
 
Fields inherited from class org.inria.ns.reflex.processor.core.AbstractSetAction
NO_VALUE
 
Fields inherited from class org.inria.ns.reflex.processor.core.AbstractAction
actions, parent, processorInstance
 
Constructor Summary
TransformAction(Expression source, Expression stylesheet, EvaluableExpression style, EvaluableExpression mimeType, Expression outputFile, Element element, AbstractAction parent)
          Create a new instance of TransformAction.
 
Method Summary
 Object getComputedValue(DataSet dataSet)
          Return the computed value of the property, by transforming an XML source with an XSLT stylesheet, and enventually serializing the result with a custom serializer if a MIME type was specified (SVG to PNG, FO to PDF, etc).
 void setParameters(Transformer transformer, Serializer serializer, DataSet dataSet)
          Set the parameters of the subactions -if any- to the serializer and the transformer.
static AbstractAction unmarshal(AbstractAction parent, Element element)
          XML unmarshaller for TransformAction.
 
Methods inherited from class org.inria.ns.reflex.processor.core.AbstractSetAction
addProperty, getComputedName, getName, getValue, runAction, scope, unmarshalScope
 
Methods inherited from class org.inria.ns.reflex.processor.core.AbstractAction
addAction, addFallbackAction, createContext, getCanonicalPath, getFallbackAction, getLocalFallbackAction, getLogger, getNamespaceContext, getNode, getParent, recover, recover, removeFallbackAction, reorganize, run, runActions, toPrettyString, toPrettyString, toString
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

TransformAction

public TransformAction(Expression source,
                       Expression stylesheet,
                       EvaluableExpression style,
                       EvaluableExpression mimeType,
                       Expression outputFile,
                       Element element,
                       AbstractAction parent)
                throws XMLException
Create a new instance of TransformAction.

Parameters:
source - The source of the xml document to transform, that will be the value of the property, as an Expression. null indicates to use the current object.
stylesheet - The stylesheet used to perform the transformation, as an expression, or null for the identity transformer.
style - The style of the output expected : tree (DOM), stream (SAX), or xml.
mimeType - The optional MIME type, if the output is a stream.
outputFile - The file target of the output STREAM.
element - The element from which the action has been unmarshalled. Used for namespace prefix resolution when performing XPath expressions.
parent - The action depending from.
Throws:
XMLException
Method Detail

unmarshal

public static AbstractAction unmarshal(AbstractAction parent,
                                       Element element)
                                throws XMLException
XML unmarshaller for TransformAction.

Parameters:
parent - The action depending from.
element - The XML element to unmarshall.
Returns:
The TransformAction created.
Throws:
XMLException - When the element and its content is not those expected.

getComputedValue

public Object getComputedValue(DataSet dataSet)
                        throws ExecutionException,
                               XPathException
Return the computed value of the property, by transforming an XML source with an XSLT stylesheet, and enventually serializing the result with a custom serializer if a MIME type was specified (SVG to PNG, FO to PDF, etc).

Specified by:
getComputedValue in interface Computable
Specified by:
getComputedValue in class AbstractSetAction
Parameters:
dataSet - The set of datas used when the name is computed.
Returns:
The computed value of the property.
Throws:
ExecutionException - If the computation can't be performed.
XPathException

setParameters

public void setParameters(Transformer transformer,
                          Serializer serializer,
                          DataSet dataSet)
                   throws XPathException,
                          ExecutionException
Set the parameters of the subactions -if any- to the serializer and the transformer.

Each parameter can be set with <xcl:param> and is applied to the component that recognize it, in this order:

Note: setting a MIME type to the transformer engine with a parameter won't change or set the serializer; use the mime-type attribute of <xcl:stylesheet> for that purpose.

Parameters:
transformer - The transformer that accept parameters, can be null.
serializer - The serializer that accept parameters, can be null.
dataSet - The set of datas to use while performing subactions.
Throws:
XPathException - If an invalid XPath expression is encountered.
ExecutionException - If a subaction can't be performed.
See Also:
Serializer.acceptAttribute(QName)