org.jasig.portal.utils
Class XSLT

java.lang.Object
  extended by org.jasig.portal.utils.XSLT
Direct Known Subclasses:
LocaleAwareXSLT

public class XSLT
extends java.lang.Object

This utility provides methods for transforming XML documents via XSLT. It takes advantage of Xalan's ability to pre-compile stylehseets into StylesheetRoot objects. The first time a transform is requested, a stylesheet is compiled and cached.

None of the method signatures in this class should contain classes specific to a particular XSLT engine, e.g. Xalan, or XML parser, e.g. Xerces.

The constructor for XSLT takes an instance of whatever class is requesting the transformation. XSLT uses this instance to locate resources relative to the classpath.

Typical usage:

 XSLT xslt = new XSLT(this);
 xslt.setXML("myXMLDoc.xml");
 xslt.setSSL("myChannel.ssl", "aTitle", runtimeData.getBrowserInfo());
 xslt.setTarget(out);
 xslt.setStylesheetParameter("param1Name", "param1Value");
 xslt.setStylesheetParameter("param2Name", "param2Value");
 xslt.transform();
 

Version:
$Revision: 1.57.2.1 $
Author:
Ken Weiner, kweiner@unicon.net

Field Summary
protected  java.lang.Object caller
           
protected  java.util.ResourceBundle l18n
           
private static org.apache.commons.logging.Log log
           
protected static java.lang.String mediaProps
           
private static javax.xml.transform.sax.SAXTransformerFactory saxTFactory
           
protected  java.util.HashMap stylesheetParams
           
protected static java.util.Hashtable stylesheetRootCache
           
protected static boolean stylesheetRootCacheEnabled
           
protected static java.util.Hashtable stylesheetSetCache
           
protected static boolean stylesheetSetCacheEnabled
           
protected  javax.xml.transform.Result xmlResult
           
protected  javax.xml.transform.Source xmlSource
           
protected  java.lang.String xslURI
           
 
Constructor Summary
XSLT(java.lang.Object instance)
          Constructs an XSLT object.
 
Method Summary
protected static void addLocalization(org.w3c.dom.Document xsl, java.util.ResourceBundle localization)
          Writes a set of key/value pairs from a resourcebundle as global variables in an xsl stylesheet
protected static java.lang.String escape(java.lang.String s)
          Escape problem characters which will be inserted into XSL
static javax.xml.transform.sax.SAXTransformerFactory getSAXTFactory()
           
static int getStylesheetCacheSize()
          Get the number of stylesheets in the stylesheet root cache.
static StylesheetSet getStylesheetSet(java.lang.String stylesheetListURI)
          This method caches compiled stylesheet set objects, keyed by the stylesheet list's URI.
static java.lang.String getStylesheetURI(java.lang.String sslUri, BrowserInfo browserInfo)
          Returns a stylesheet URI exactly as it appears in a stylesheet list file.
static java.lang.String getStylesheetURI(java.lang.String sslUri, java.lang.String title, BrowserInfo browserInfo)
          Returns a stylesheet URI exactly as it appears in a stylesheet list file.
static javax.xml.transform.Templates getTemplates(java.lang.String stylesheetURI)
          This method caches compiled stylesheet objects, keyed by the stylesheet's URI.
static javax.xml.transform.Templates getTemplates(java.lang.String stylesheetURI, java.util.ResourceBundle l18n)
          This method caches compiled stylesheet objects, keyed by the stylesheet's URI and locale.
static XSLT getTransformer(java.lang.Object instance)
          Factory method that produces an XSLT transformer utility.
static XSLT getTransformer(java.lang.Object instance, java.util.Locale[] locales)
          Factory method that produces an XSLT transformer utility with a capability of choosing a stylesheet depending on a list of locales.
static javax.xml.transform.Transformer getTransformer(java.lang.String stylesheetURI)
          This method returns a Transformer for a given stylesheet.
static javax.xml.transform.Transformer getTransformer(java.lang.String stylesheetURI, java.util.ResourceBundle l18n)
          This method returns a localized Transformer for a given stylesheet.
static javax.xml.transform.sax.TransformerHandler getTransformerHandler(java.lang.String stylesheetURI)
          This method returns a TransformerHandler for a given stylesheet.
static javax.xml.transform.sax.TransformerHandler getTransformerHandler(java.lang.String stylesheetURI, java.util.Locale[] locales, java.lang.Object caller)
          This method returns a localized TransformerHandler for a given stylesheet.
static void purgeStylesheetCache()
          Purge the cache of stylesheet roots and stylesheet sets.
 void setResourceBundle(java.util.ResourceBundle bundle)
           
 void setStylesheetParameter(java.lang.String name, java.lang.String value)
          Sets all the stylesheet parameters at once.
 void setStylesheetParameters(java.util.HashMap stylesheetParameters)
          Sets all the stylesheet parameters at once.
 void setStylesheetParameters(java.util.Hashtable stylesheetParameters)
          Sets all the stylesheet parameters at once.
private static void setStylesheetParams(javax.xml.transform.Transformer transformer, java.util.HashMap stylesheetParams)
          Extracts name/value pairs from a Hashtable and uses them to create stylesheet parameters
private static void setStylesheetParams(javax.xml.transform.Transformer transformer, java.util.Hashtable stylesheetParams)
          Deprecated. replaced by setStylesheetParams(Transformer, HashMap)
 void setTarget(org.xml.sax.ContentHandler contentHandler)
          Configures the xslt target.
 void setTarget(org.w3c.dom.Node node)
          Configures the xslt target.
 void setTarget(java.io.OutputStream os)
          Configures the xslt target.
 void setXML(java.io.File file)
          Configures the xml source.
 void setXML(java.io.InputStream is)
          Configures the xml source.
 void setXML(org.w3c.dom.Node xml)
          Configures the xml source.
 void setXML(java.lang.String xml)
          Configures the xml source.
 void setXSL(java.lang.String xslUri)
          Configures the xsl source.
 void setXSL(java.lang.String sslUri, BrowserInfo browserInfo)
          Configures the xsl source by choosing the appropriate stylesheet from the provided stylesheet list file.
 void setXSL(java.lang.String sslUri, java.lang.String stylesheetTitle, BrowserInfo browserInfo)
          Configures the xsl source by choosing the appropriate stylesheet from the provided stylesheet list file.
 java.lang.String toString()
           
 void transform()
          Performs a transformation.
static void transform(javax.xml.transform.Source xmlSource, javax.xml.transform.Result xmlResult, java.util.Hashtable stylesheetParams, java.lang.String xslURI)
          Performs an XSL transformation.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

log

private static final org.apache.commons.logging.Log log

stylesheetRootCacheEnabled

protected static boolean stylesheetRootCacheEnabled

stylesheetSetCacheEnabled

protected static boolean stylesheetSetCacheEnabled

mediaProps

protected static final java.lang.String mediaProps
See Also:
Constant Field Values

stylesheetRootCache

protected static final java.util.Hashtable stylesheetRootCache

stylesheetSetCache

protected static final java.util.Hashtable stylesheetSetCache

saxTFactory

private static javax.xml.transform.sax.SAXTransformerFactory saxTFactory

caller

protected java.lang.Object caller

xmlSource

protected javax.xml.transform.Source xmlSource

xmlResult

protected javax.xml.transform.Result xmlResult

stylesheetParams

protected java.util.HashMap stylesheetParams

xslURI

protected java.lang.String xslURI

l18n

protected java.util.ResourceBundle l18n
Constructor Detail

XSLT

public XSLT(java.lang.Object instance)
Constructs an XSLT object. This contructor should be declared protected, but it will remain public for a while until most client code is changed to use the getTransformer() methods. Please avoid using this constructor!

Parameters:
instance - the client of this utility
Method Detail

getTransformer

public static XSLT getTransformer(java.lang.Object instance)
Factory method that produces an XSLT transformer utility.

Parameters:
instance - the client of this utility
Returns:
a transformer utility
Since:
uPortal 2.2

getTransformer

public static XSLT getTransformer(java.lang.Object instance,
                                  java.util.Locale[] locales)
Factory method that produces an XSLT transformer utility with a capability of choosing a stylesheet depending on a list of locales.

Parameters:
instance - the client of this utility
Returns:
a locale-aware transformer utility
Since:
uPortal 2.2

getSAXTFactory

public static javax.xml.transform.sax.SAXTransformerFactory getSAXTFactory()

setXML

public void setXML(java.lang.String xml)
Configures the xml source.

Parameters:
xml - a string representing the xml document

setXML

public void setXML(org.w3c.dom.Node xml)
Configures the xml source.

Parameters:
xml - a node representing the xml document

setXML

public void setXML(java.io.InputStream is)
Configures the xml source.

Parameters:
is - an input stream to the serialized xml source

setXML

public void setXML(java.io.File file)
Configures the xml source.

Parameters:
file - a File object representing the xml source

setXSL

public void setXSL(java.lang.String xslUri)
            throws PortalException
Configures the xsl source.

Parameters:
xslUri - the URL of an XSLT stylesheet
Throws:
PortalException

setXSL

public void setXSL(java.lang.String sslUri,
                   java.lang.String stylesheetTitle,
                   BrowserInfo browserInfo)
            throws PortalException
Configures the xsl source by choosing the appropriate stylesheet from the provided stylesheet list file.

Parameters:
sslUri - the URL of the stylesheet list file
stylesheetTitle - the title of a stylesheet within the stylesheet list file
browserInfo - the browser info object
Throws:
PortalException

setXSL

public void setXSL(java.lang.String sslUri,
                   BrowserInfo browserInfo)
            throws PortalException
Configures the xsl source by choosing the appropriate stylesheet from the provided stylesheet list file.

Parameters:
sslUri - the URL of the stylesheet list file
browserInfo - the browser info object
Throws:
PortalException

setTarget

public void setTarget(org.xml.sax.ContentHandler contentHandler)
Configures the xslt target.

Parameters:
contentHandler - the content handler

setTarget

public void setTarget(java.io.OutputStream os)
Configures the xslt target.

Parameters:
os - output stream

setTarget

public void setTarget(org.w3c.dom.Node node)
Configures the xslt target.

Parameters:
node - target node

setStylesheetParameters

public void setStylesheetParameters(java.util.Hashtable stylesheetParameters)
Sets all the stylesheet parameters at once.

Parameters:
stylesheetParameters - a Hashtable of stylesheet parameters

setStylesheetParameters

public void setStylesheetParameters(java.util.HashMap stylesheetParameters)
Sets all the stylesheet parameters at once.

Parameters:
stylesheetParameters - a HashMap of stylesheet parameters

setStylesheetParameter

public void setStylesheetParameter(java.lang.String name,
                                   java.lang.String value)
Sets all the stylesheet parameters at once.

Parameters:
name - the name of the stylesheet parameter
value - the value of the stylesheet parameter

transform

public void transform()
               throws PortalException
Performs a transformation. Assumes that the XML, XSL, and result targets have already been set.

Throws:
PortalException

transform

public static void transform(javax.xml.transform.Source xmlSource,
                             javax.xml.transform.Result xmlResult,
                             java.util.Hashtable stylesheetParams,
                             java.lang.String xslURI)
                      throws PortalException
Performs an XSL transformation. Accepts stylesheet parameters (key, value pairs) stored in a Hashtable.

Parameters:
xmlSource - the source to be transformedn
xmlResult - the result to be populated
stylesheetParams - a Hashtable of key/value pairs or null if no parameters
xslURI - the uri of the stylesheet to be used
Throws:
PortalException - if something goes wrong

setStylesheetParams

private static void setStylesheetParams(javax.xml.transform.Transformer transformer,
                                        java.util.Hashtable stylesheetParams)
Deprecated. replaced by setStylesheetParams(Transformer, HashMap)

Extracts name/value pairs from a Hashtable and uses them to create stylesheet parameters

Parameters:
transformer - the XSLT processor
stylesheetParams - name/value pairs used as stylesheet parameters

setStylesheetParams

private static void setStylesheetParams(javax.xml.transform.Transformer transformer,
                                        java.util.HashMap stylesheetParams)
Extracts name/value pairs from a Hashtable and uses them to create stylesheet parameters

Parameters:
transformer - the XSLT processor
stylesheetParams - name/value pairs used as stylesheet parameters

setResourceBundle

public void setResourceBundle(java.util.ResourceBundle bundle)

getTemplates

public static javax.xml.transform.Templates getTemplates(java.lang.String stylesheetURI,
                                                         java.util.ResourceBundle l18n)
                                                  throws org.xml.sax.SAXException,
                                                         PortalException,
                                                         javax.xml.transform.TransformerConfigurationException
This method caches compiled stylesheet objects, keyed by the stylesheet's URI and locale.

Parameters:
stylesheetURI - the URI of the XSLT stylesheet
l18n - the localized strings to add to the xsl
Returns:
the StlyesheetRoot object
Throws:
org.xml.sax.SAXException
PortalException
javax.xml.transform.TransformerConfigurationException

getTemplates

public static javax.xml.transform.Templates getTemplates(java.lang.String stylesheetURI)
                                                  throws org.xml.sax.SAXException,
                                                         PortalException
This method caches compiled stylesheet objects, keyed by the stylesheet's URI.

Parameters:
stylesheetURI - the URI of the XSLT stylesheet
Returns:
the StlyesheetRoot object
Throws:
org.xml.sax.SAXException
PortalException

getTransformer

public static javax.xml.transform.Transformer getTransformer(java.lang.String stylesheetURI,
                                                             java.util.ResourceBundle l18n)
                                                      throws org.xml.sax.SAXException,
                                                             PortalException
This method returns a localized Transformer for a given stylesheet.

Parameters:
stylesheetURI - the URI of the XSLT stylesheet
Returns:
Transformer
Throws:
org.xml.sax.SAXException
PortalException

getTransformer

public static javax.xml.transform.Transformer getTransformer(java.lang.String stylesheetURI)
                                                      throws org.xml.sax.SAXException,
                                                             PortalException
This method returns a Transformer for a given stylesheet.

Parameters:
stylesheetURI - the URI of the XSLT stylesheet
Returns:
Transformer
Throws:
org.xml.sax.SAXException
PortalException

getTransformerHandler

public static javax.xml.transform.sax.TransformerHandler getTransformerHandler(java.lang.String stylesheetURI)
                                                                        throws org.xml.sax.SAXException,
                                                                               PortalException
This method returns a TransformerHandler for a given stylesheet.

Parameters:
stylesheetURI - the URI of the XSLT stylesheet
Returns:
Transformer
Throws:
org.xml.sax.SAXException
PortalException

getTransformerHandler

public static javax.xml.transform.sax.TransformerHandler getTransformerHandler(java.lang.String stylesheetURI,
                                                                               java.util.Locale[] locales,
                                                                               java.lang.Object caller)
                                                                        throws org.xml.sax.SAXException,
                                                                               PortalException
This method returns a localized TransformerHandler for a given stylesheet.

Parameters:
stylesheetURI - the URI of the XSLT stylesheet
locales - the list of locales
caller - the calling class
Returns:
Transformer
Throws:
org.xml.sax.SAXException
PortalException

getStylesheetSet

public static StylesheetSet getStylesheetSet(java.lang.String stylesheetListURI)
                                      throws PortalException
This method caches compiled stylesheet set objects, keyed by the stylesheet list's URI.

Parameters:
stylesheetListURI - the URI of the XSLT stylesheet list file (.ssl)
Returns:
the StlyesheetSet object
Throws:
PortalException

getStylesheetURI

public static java.lang.String getStylesheetURI(java.lang.String sslUri,
                                                BrowserInfo browserInfo)
                                         throws PortalException
Returns a stylesheet URI exactly as it appears in a stylesheet list file.

Parameters:
sslUri - the stylesheet list file URI
browserInfo - the browser information
Returns:
the stylesheet URI as a string
Throws:
PortalException

getStylesheetURI

public static java.lang.String getStylesheetURI(java.lang.String sslUri,
                                                java.lang.String title,
                                                BrowserInfo browserInfo)
                                         throws PortalException
Returns a stylesheet URI exactly as it appears in a stylesheet list file.

Parameters:
sslUri - the stylesheet list file URI
title - the stylesheet title
browserInfo - the browser information
Returns:
the stylesheet URI as a string
Throws:
PortalException

addLocalization

protected static void addLocalization(org.w3c.dom.Document xsl,
                                      java.util.ResourceBundle localization)
Writes a set of key/value pairs from a resourcebundle as global variables in an xsl stylesheet

Parameters:
xsl - the xsl stylesheet as a DOM document
localization - the resource bundle of key/value pairs to be written to xsl variables

escape

protected static java.lang.String escape(java.lang.String s)
Escape problem characters which will be inserted into XSL

Parameters:
s - the string to escape

purgeStylesheetCache

public static void purgeStylesheetCache()
Purge the cache of stylesheet roots and stylesheet sets.


getStylesheetCacheSize

public static int getStylesheetCacheSize()
Get the number of stylesheets in the stylesheet root cache.

Returns:
the number of stylesheets in the stylesheet root cache.

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object