net.sf.fikin.xml
Class Xslt

java.lang.Object
  net.sf.fikin.xml.Xslt

public class Xslt
extends java.lang.Object

Makes XSLT operations easier.

Main idea is to simplify usage of JAXP interfaces in order to process XML document.

Usage:

      Xslt xsl = new Xslt( Xslt.newStreamSource( "my.xsl" ) );
      xsl.transform( Xslt.newStreamSource("my.xml") );
      xsl.transform( Xslt.newStreamSource("my.xml"), new StreamResult( "my.txt" ) );
      ...
 

Xslt has following features:

• created objects are reusable i.e. multiple transform() calls
• using JAXP Template thus operating on pre-compiled (presumably) Transformers
• provides with methods to resolve input sources from classpath, file or url sources i.e. Xslt.newStreamSource()
• has several transform() methods for better convenience
• provides with ability to specify JAXP factory if needed
• has lookup-objects support for callbacks. For explanation look bellow.

Lookup objects and callbacks:

These are POJO which one can use from the xslt via engine's propriatiry extensions. For example both Xalan and Saxon allow for calling methods of Java objects from the xslt.

By definition one can either create new java objects or call static methods of some available classes

Since instantiating of usable set of objects in xsl is rather cumberstone (and most times even inappropriate) one can try to pass along xslt callback objects. Then xslt will deal only with calling instance methods aka. callbacks and java code would deal with proper object handling.

Since xsl can accept parameters but they are of type string, one would require an infrastructure to pass along real object.

Xslt provides such in the face of exportJavaObject(Object) and lookupObject(String).

Typical schenario is:

• pass an existing objects to exportJavaObject(Object)
• pass given string key as an parameter to the xsl
• in xsl "look up" the object based on the key via lookupObject(String)

Example: This is based on Xalan which is delivered by default with JRE 1.4+

      // xsl looks like this one:
      <xsl:stylesheet
          xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
          version="1.0"
          xmlns:xslt="xalan://net.sf.fikin.xml.Xslt" 
          xmlns:my="xalan://MyPOJO" 
      >
          <xsl:param name="callbackObj" />
          <xsl:varialbe name="myPojo" select="xslt:lookupObject( $callbackObj )" />
          ...
              <xsl:value-of select="my:hello( $myPojo )" />
              ...
              <xsl:value-of select="my:toStr( $myPojo, number(@id) )" />
              ...
      </xsl:stylesheet>
      
      // POJO for lookups
      public class MyPOJO {
          public String hello() { return "Hello world!"; }
          public String toStr(int val) { return Integer.toString(val); }
      }
      
      // java code looks like:
      Xslt xsl = new Xslt( Xslt.newStreamSource( "my.xsl" ) );
      Hashtable params = new Hashtable();
      params.put( "callbackObj", xsl.exportObject( new MyPOJO() ) );
      xsl.transform();
 

Xslt guarantees the uniqueness of the keys, based on the object and the actual xslt

Xslt is backed by a weak hashmap, so that registering callback objects would not trouble the garbage collector

created on Oct 1, 2006

Since:

Version:

$Revision: 1.11 $

Author:

fiykov

Constructor Summary

Xslt(javax.xml.transform.Source xsl)
instantiate an template with xsl source

Xslt(javax.xml.transform.TransformerFactory fact, javax.xml.transform.Source xsl)
instantiate an template with xsl source

Method Summary

java.lang.String	exportJavaObject(java.lang.Object obj) if you want to thread-safe export a callback java object called from the xstl (via one or another java extension api): call this method with the object to be exported the return is a an unique key value with which you can look it up via lookupObject(String) pass the key as a normal parameter to the xslt in the xslt you have to use the java extension api available and lookup the object via lookupObject(String)
static java.lang.Object	lookupObject(java.lang.String key) lookup a previously exported java object via exportJavaObject(Object) this method is called by xslt (via xslt vendor specific java extension api)
static javax.xml.transform.stream.StreamSource	newStreamSource(java.io.File in) instantiate a new source out of a file it uses buffered input stream
static javax.xml.transform.stream.StreamSource	newStreamSource(java.io.InputStream in) instantiate a new source out of an input stream
static javax.xml.transform.stream.StreamSource	newStreamSource(java.io.Reader in) instantiate a new source out of a reader
static javax.xml.transform.stream.StreamSource	newStreamSource(java.lang.String file) instantiate a new source out of a file name
static javax.xml.transform.stream.StreamSource	newStreamSource(java.lang.String file, java.lang.Class callingCls) instantiate a new source out of a resource available in the classpath
static javax.xml.transform.stream.StreamSource	newStreamSource(java.lang.String fqnFile, java.lang.ClassLoader cl) instantiate a new source out of a resource available in the classpath when a classloader is provided, it will be used to resolve the resource.
static javax.xml.transform.stream.StreamSource	newStreamSource(java.lang.String file, java.lang.Package pkg) instantiate a new source out of a resource available in the classpath
static javax.xml.transform.stream.StreamSource	newStreamSource(java.net.URL in) instantiate a new source out of an url location it uses buffered input stream
void	setErrorListener(javax.xml.transform.ErrorListener errorListener) assign new ErrorListener
void	transform(javax.xml.transform.Source in) transform in into output output is a dummy byte array stream
void	transform(javax.xml.transform.Source in, java.util.Hashtable params) transform in into output output is a dummy byte array stream
void	transform(javax.xml.transform.Source in, javax.xml.transform.Result out) transform in into output
void	transform(javax.xml.transform.Source in, javax.xml.transform.Result out, java.util.Hashtable params) transform in into output

Methods inherited from class java.lang.Object

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

Constructor Detail

Xslt

public Xslt(javax.xml.transform.TransformerFactory fact,
            javax.xml.transform.Source xsl)
     throws javax.xml.transform.TransformerConfigurationException

instantiate an template with xsl source

Parameters:

xsl -

Throws:

javax.xml.transform.TransformerConfigurationException

Xslt

public Xslt(javax.xml.transform.Source xsl)
     throws javax.xml.transform.TransformerConfigurationException

instantiate an template with xsl source

Parameters:

xsl -

Throws:

javax.xml.transform.TransformerConfigurationException

Method Detail

setErrorListener

public void setErrorListener(javax.xml.transform.ErrorListener errorListener)

assign new ErrorListener

Parameters:

errorListener - to use in transformations

transform

public void transform(javax.xml.transform.Source in,
                      javax.xml.transform.Result out,
                      java.util.Hashtable params)
               throws javax.xml.transform.TransformerException

transform in into output

Parameters:

in -

out -

params -

Throws:

javax.xml.transform.TransformerException

transform

public void transform(javax.xml.transform.Source in,
                      javax.xml.transform.Result out)
               throws javax.xml.transform.TransformerException

transform in into output

Parameters:

in -

out -

Throws:

javax.xml.transform.TransformerException

transform

public void transform(javax.xml.transform.Source in,
                      java.util.Hashtable params)
               throws javax.xml.transform.TransformerException

transform in into output output is a dummy byte array stream

Parameters:

in -

params -

Throws:

javax.xml.transform.TransformerException

transform

public void transform(javax.xml.transform.Source in)
               throws javax.xml.transform.TransformerException

transform in into output output is a dummy byte array stream

Parameters:

in -

Throws:

javax.xml.transform.TransformerException

exportJavaObject

public java.lang.String exportJavaObject(java.lang.Object obj)

if you want to thread-safe export a callback java object called from the xstl (via one or another java extension api):

call this method with the object to be exported

the return is a an unique key value with which you can look it up via lookupObject(String)

pass the key as a normal parameter to the xslt

in the xslt you have to use the java extension api available and lookup the object via lookupObject(String)

Parameters:

obj -

Returns:

unique key idenfyfing this lookup object

lookupObject

public static java.lang.Object lookupObject(java.lang.String key)

lookup a previously exported java object via exportJavaObject(Object) this method is called by xslt (via xslt vendor specific java extension api)

Parameters:

key - is the key obtained by exportJavaObject(Object)

Returns:

found object or null

newStreamSource

public static javax.xml.transform.stream.StreamSource newStreamSource(java.io.Reader in)

instantiate a new source out of a reader

Parameters:

in - is a reader object

Returns:

a new source object

newStreamSource

public static javax.xml.transform.stream.StreamSource newStreamSource(java.io.InputStream in)

instantiate a new source out of an input stream

Parameters:

in - is an input stream

Returns:

a new source object

newStreamSource

public static javax.xml.transform.stream.StreamSource newStreamSource(java.io.File in)
                                                               throws java.io.FileNotFoundException

instantiate a new source out of a file it uses buffered input stream

Parameters:

in - the file object

Returns:

a new source object

Throws:

java.io.FileNotFoundException

newStreamSource

public static javax.xml.transform.stream.StreamSource newStreamSource(java.net.URL in)
                                                               throws java.io.IOException

instantiate a new source out of an url location it uses buffered input stream

Parameters:

in - the url of the source

Returns:

a new source object

Throws:

java.io.IOException

newStreamSource

public static javax.xml.transform.stream.StreamSource newStreamSource(java.lang.String file)
                                                               throws java.io.FileNotFoundException

instantiate a new source out of a file name

Parameters:

file - is the fully qualified file name

Returns:

a new source object

Throws:

java.io.FileNotFoundException

newStreamSource

public static javax.xml.transform.stream.StreamSource newStreamSource(java.lang.String fqnFile,
                                                                      java.lang.ClassLoader cl)
                                                               throws java.lang.NullPointerException

instantiate a new source out of a resource available in the classpath when a classloader is provided, it will be used to resolve the resource. when classloader is null, the resource is seached via system classloader first, then via current's class classloader and finally via thread's context classloader. first time the resource is located it is returned.

Parameters:

fqnFile - is the fully qualified name of the resource

cl - is the classloader to be used or null

Returns:

a new source object

Throws:

NullPoinerException - when no resource is found

java.lang.NullPointerException

newStreamSource

public static javax.xml.transform.stream.StreamSource newStreamSource(java.lang.String file,
                                                                      java.lang.Package pkg)

instantiate a new source out of a resource available in the classpath

Parameters:

file - is the resource name (only file name)

pkg - is the package (i.e. java package) where the file is

Returns:

a new source object

newStreamSource

public static javax.xml.transform.stream.StreamSource newStreamSource(java.lang.String file,
                                                                      java.lang.Class callingCls)

instantiate a new source out of a resource available in the classpath

Parameters:

file - is the resource name (only file name)

callingCls - is the class whose package the file is

Returns:

a new source object