4
XSLT Processing for Java

Using the transformation specified by the XSLT stylesheet, the XSLT processor can converts an XML document into another text format.

This chapter contains these sections:

• oraxsl Class
• XPathException Class
• XSLException Class
• XSLExtensionElement Class
• XSLProcessor Class
• XSLStylesheet Class
• XSLTContext Class

---

oraxsl Class

---

Description of oraxsl

The oraxsl class provides a command-line interface to applying stylesheets on multiple XML documents. It accepts a number of command-line options that dictate how it should behave.

---

Syntax of oraxsl

public class oraxsl extends java.lang.Object
 
java.lang.Object
  |
  +--oracle.xml.parser.v2.oraxsl

---

Usage of oraxsl

java oraxsl options* source? stylesheet? result?

Table 4-1 Command-line options of oraxsl  

command	description
-w	Show warnings
-e <error log>	A file to write errors to
-l <xml file list>	List of files to transform
-d <directory>	Directory with files to transform
-x <source extension>	Extensions to exclude
-i <source extension>	Extensions to include
-s <stylesheet>	Stylesheet to use
-r <result extension>	Extension to use for results
-o <result extension>	Directory to place results
-p <param list>	List of Params
-t <# of threads>	Number of threads to use
-v	Verbose mode

---

Methods of oraxsl

Table 4-2 Summary of Methods of oraxsl

Method	Description
oraxsl()	Class constructor.
main()	Invokes the oraxsl driver

oraxsl()

Description

Class constructor.

Syntax

public  oraxsl();

main()

Description

Invokes the oraxsl driver.

Syntax

public static void main( String[] args);

Parameter	Description
args	Command line arguments.

---

XPathException Class

---

Description of XPathException

Indicates that an exception occurred during XPath processing.

---

Syntax of XPathException

public class XPathException extends oracle.xml.parser.v2.XSLException
 
java.lang.Object
  |
  +--java.lang.Throwable
        |
        +--java.lang.Exception
              |
              +--oracle.xml.util.XMLException
                    |
                    +--oracle.xml.parser.v2.XSLException
                          |
                          +--oracle.xml.parser.v2.XPathException

---

Implemented Interfaces of XPathException

java.io.Serializable

---

Methods of XPathException

Table 4-3 Summary of Methods of XPathException

Method	Description
getErrorID()	Retrieves error id.
getMessage()	Retrieves error message.

getErrorID()

Description

Retrieves error id.

Syntax

public int getErrorID();

getMessage()

Description

Retrieves error message. The options are described in the following table.

Syntax	Description
public String getMessage();	Constructs error message from error id and error params. Overrides getMessage() in class java.lang.Throwable.
public String getMessage( XMLError err);	Gets localized message based on the XMLError sent as parameter.

Parameter	Description
err	XMLError class used to get the error message.

---

XSLException Class

---

Description of XSLException

Indicates that an exception occurred during XSL transformation.

Syntax of XSLException

public class XSLException extends oracle.xml.util.XMLException
 
java.lang.Object
  |
  +--java.lang.Throwable
        |
        +--java.lang.Exception
              |
              +--oracle.xml.util.XMLException
                    |
                    +--oracle.xml.parser.v2.XSLException

---

Direct Subclasses of XSLException

XPathException

---

Implemented Interfaces of XSLException

java.io.Serializable

---

Methods of XSLException

XSLException()

Description

Generates a new XSL exception.

Syntax

public  XSLException( String mesg);

---

XSLExtensionElement Class

---

Description of XSLExtensionElement

Base element for extension elements

---

Syntax of XSLExtensionElement

public class XSLExtensionElement
 
oracle.xml.parser.v2.XSLExtensionElement

---

Methods of XSLExtensionElement

Table 4-4 Summary of Methods of XSLExtensionElement  

Method	Description
XSLExtensionElement()	Default constructor.
getAttributeTemplateValue()	Retrieves an attribute value as template.
getAttributeValue()	Retrieves an attribute value.
getChildNodes()	Retrieves the childNodes of the extension elements.
processAction()	Executes the body of the extension elements.
processContent()	Processes contents of the extension element.

XSLExtensionElement()

Description

Default constructor.

Syntax

public  XSLExtensionElement();

getAttributeTemplateValue()

Description

Retrieves an attribute value as template.

Syntax

protected final String getAttributeTemplateValue(   XSLTContext context,
          String namespace,
          String name);

Parameter	Description
context	XSLT Context.
namespace	Namespace of the attribute.
name	Name of the attribute.

getAttributeValue()

Description

Retrieves the value of an attribute.

Syntax

protected final String getAttributeValue( String namespace,
                                          String name);

Parameter	Description
namespace	Namespace of the attribute
name	Name of the attribute

getChildNodes()

Description

Retrieves the childNodes of the extension elements as a nodelist.

Syntax

protected final java.util.Vector getChildNodes();

processAction()

Description

Executes the body of the extension elements.

Syntax

public void processAction( XSLTContext context);

Parameter	Description
context	XSLT Context.

processContent()

Description

Processes contents of the extension element.

Syntax

protected final void processContent(XSLTContext context);

Parameter	Description
context	XSLTContext.

---

XSLProcessor Class

---

Description of XSLProcessor

This class provides methods to transform an input XML document using a previously constructed XSLStylesheet. The transformation effected is as specified by the XSLT 1.0 specification.

---

Syntax of XSLProcessor

public class XSLProcessor
 
oracle.xml.parser.v2.XSLProcessor

---

Methods of XSLProcessor

Table 4-5 Summary of Methods of XSLProcessor  

Method	Description
XSLProcessor()	Default constructor.
getParam()	Retrieves the value of top-level stylesheet parameter.
newXSLStylesheet()	Constructs an XSLStylesheet.
processXSL()	Transforms input XML document.
removeParam()	Removes the value of a top-level stylesheet parameter.
resetParams()	Resets all the params set.
setBaseURL()	Sets base url to resolve include/import hrefs.
setEntityResolver()	Sets entity resolver to resolve include/import hrefs.
setErrorStream()	Creates an output stream for the output of warnings.
setLocale()	Sets the locale for error reporting.
setParam()	Sets the value of a top-level stylesheet parameter.
showWarnings()	Sets the overriding XSLOutput object.

XSLProcessor()

Description

Default constructor.

Syntax

public  XSLProcessor();

getParam()

Description

Retrieves the value of top-level stylesheet parameter.

Syntax

public Object getParam( String uri,
                        String name);

Parameter	Description
uri	Namespace URI of the parameter.
name	Local name of the parameter.

newXSLStylesheet()

Description

Constructs and returns a new XSLStylesheet. Throws an XSLException. The options are described in the following table.

Syntax	Description
public XSLStylesheet newXSLStylesheet( InputStream xsl);	Constructs an XSLStylesheet using the given Inputstream XSL.
public XSLStylesheet newXSLStylesheet( Reader xsl);	Constructs an XSLStylesheet using the given Reader.
public XSLStylesheet newXSLStylesheet( java.net.URL xsl);	Constructs an XSLStylesheet using the given URL.
public XSLStylesheet newXSLStylesheet( XMLDocument xsl);	Constructs an XSLStylesheet using the given XMLDocument.

Parameter	Description
xsl	XSL input.

processXSL()

Description

Transforms the input XML document. Throws an XSLException on error. The options are described in the following table.

Syntax	Description
public XMLDocumentFragment processXSL( XSLStylesheet xsl, InputStream xml, URL ref);	Transforms input XML document using given InputStream and stylesheet. Returns an XMLDocumentFragment.
public XMLDocumentFragment processXSL( XSLStylesheet xsl, Reader xml, URL ref);	Transforms input XML document using given Reader and stylesheet. Returns an XMLDocumentFragment.
public XMLDocumentFragment processXSL( XSLStylesheet xsl, URL xml, URL ref);	Transforms input XML document using given URL and stylesheet. Returns an XMLDocumentFragment.
public XMLDocumentFragment processXSL( XSLStylesheet xsl, XMLDocument xml);	Transforms input XML document using given XMLDocument and stylesheet. Returns an XMLDocumentFragment.
public void processXSL( XSLStylesheet xsl, XMLDocument xml, org.xml.sax.ContentHandler handler);	Transforms input XML document using given XMLDocument, stylesheet and content handler.
public XMLDocumentFragment processXSL( XSLStylesheet xsl, XMLDocumentFragment xml);	Transforms input XML document using given XMLDocumentFragment and stylesheet. Returns an XMLDocumentFragment.
public void processXSL( XSLStylesheet xsl, XMLDocumentFragment xml, OutputStream os);	Transforms input XML using given XMLDocumentFragment, stylesheet and output stream.
public void processXSL( XSLStylesheet xsl, XMLDocumentFragment xml, printWriter pw);	Transforms input XML using given XMLDocumentFragment, stylesheet and print writer.
public void processXSL( XSLStylesheet xsl, XMLDocumentFragment xml, XMLDocumentHandler handlerXML);	Transforms input XML document using given XMLDocumentFragment, stylesheet and XML Document handler. As the result of XSLT is a document fragment, the following functions in XMLDocumentHandler will not be called: - setDocumentLocator, startDocument, endDocument, - setDoctype, endDoctype, setXMLDecl, setTextDecl
public void processXSL( XSLStylesheet xsl, XMLDocument xml, OutputStream out);	Transforms input XML document using given XMLDocument, stylesheet and output stream.
public void processXSL( XSLStylesheet xsl, XMLDocument xml, java.io.PrintWriter pw);	Transforms input XML document using given XMLDocument, stylesheet and print writer.
public void processXSL( XSLStylesheet xsl, XMLDocument xml, XMLDocumentHandler handlerXML);	Transforms input XML document using given XMLDocument, stylesheet and XML document handler. The output of the transformation is reported through XMLDocumentHandler. As the result of XSLT is a document fragment, the following functions in XMLDocumentHandler will not be called: - setDocumentLocator, startDocument, endDocument, - setDoctype, endDoctype, setXMLDecl, setTextDecl
public XMLDocumentFragment processXSL( XSLStylesheet xsl, XMLElement inp);	Transforms input XML document using given XMLElement and stylesheet. Returns an XMLDocumentFragment.
public void processXSL( XSLStylesheet xsl, XMLElement inp, org.xml.sax.ContentHandler handler);	Transforms input XML document using given XMLElement, stylesheet and content handler. The output of the transformation is reported through ContentHandler. As the result of XSLT is a document fragment, the following functions in ContentHandler will not be called: - setDocumentLocator, startDocument, endDocument,
public void processXSL( XSLStylesheet xsl, XMLElement xml, OutputStream out);	Transforms input XML using given XMLElement, stylesheet and output stream.
public void processXSL( XSLStylesheet xsl, XMLElement xml, PrintWriter pw);	Transform input XML using given XMLElement, stylesheet and print writer.
public void processXSL( XSLStylesheet xsl, XMLElement xml, XMLDocumentHandler handlerXML);	Transform input XML document using given XMLElement, stylesheet and document handler. As the result of XSLT is a document fragment, the following functions in XMLDocumentHandler will not be called: - setDocumentLocator, startDocument, endDocument, - setDoctype, endDoctype, setXMLDecl, setTextDecl

Parameter	Description
xsl	XSLStylesheet to be used for transformation.
xml	XML input to be transformed.
ref	Reference URL to resolve external entities in input xml file.
handler	Content handler.
out	Output stream to which the result is printed.
pw	PrintWriter to which the result is printed.
handlerXML	XMLDocument handler.

removeParam()

Description

Removes the value of a top-level stylesheet parameter. Throws an XSLException on error.

Syntax

public void removeParam( String uri,
                         String name);

Parameter	Description
uri	URI of parameter.
name	parameter name.

resetParams()

Description

Resets all the params set. Throws an XSLException on error.

Syntax

public void resetParams();

setBaseURL()

Description

Sets base url to resolve include/import hrefs. EntityResolver if set is used before using the base url. See also setEntityResolver().

Syntax

public void setBaseURL(java.net.URL url);

Parameter	Description
url	Base URL to be set.

setEntityResolver()

Description

Sets entity resolver to resolve include/import hrefs. If not set, base url (if set) is used.

Syntax

public void setEntityResolver( org.xml.sax.EntityResolver eResolver);

Parameter	Description
eResolver	Entity resolver

setErrorStream()

Description

Creates an output stream for the output of warnings. If an output stream for warnings is not specified, the processor will not output any warnings.

Syntax

public final void setErrorStream(java.io.OutputStream out);

Parameter	Description
out	The output stream to use for errors and warnings.

setLocale()

Description

Applications can use this to set the locale for error reporting.

Syntax

public void setLocale( java.util.Locale locale);

Parameter	Description
locale	Locale to set.

setParam()

Description

Sets the value of a top-level stylesheet parameter. The parameter value is expected to be a valid XPath expression (note that string literal values would therefore have to be explicitly quoted). The param functions CANNOT be used along with param functions in XSLStylesheet. If the param functions in XSLProcessor are used, any parameters set using XSLStylesheet functions will be ignored. Throws an XSLException on error.

Syntax

public void setParam( String uri,
                      String name,
                      Object value);

Parameter	Description
uri	URI of parameter.
name	Parameter name.
value	Parameter value; Strings are treated as XPath Expr for backward compatibility).

showWarnings()

Description

Switch to determine whether to output warnings.

Syntax

public final void showWarnings( boolean flag);

Parameter	Description
flag	Determines if warning should be shown; default: warnings not output.

---

XSLStylesheet Class

---

Description of XSLStylesheet

The class holds XSL stylesheet information such as templates, keys, variables, and attribute sets. The same stylesheet, once constructed, can be used to transform multiple XML documents.

---

Syntax of XSLStylesheet

public class XSLStylesheet
 
oracle.xml.parser.v2.XSLStylesheet

---

Fields of XSLStylesheet

Table 4-6 Fields of XSLStylesheet

Field	Syntax	Description
output	public oracle.xml.parser.v2.XSLOutput output	Output

---

Methods of XSLStylesheet

Table 4-7 Summary of Methods of XSLStylesheet  

Method	Description
getDecimalFormat()	Returns the decimal format symbols specified in the stylesheet
getOutputEncoding()	Returns the value of the encoding specified in xsl:output
getOutputMediaType()	Returns the value of the media-type specified in xsl:output
getOutputProperties()	Returns the output properties specified in xsl:output as java.util.Properties.
newTransformer()	Returns a JAXP Transformer object that uses this stylesheet for transformation.
getContextNode()	Removes the value of a top-level stylesheet parameter.
getContextPosition()	Resets all the params set.
getContextPosition()	Sets the value of a top-level stylesheet parameter.

getDecimalFormat()

Description

Returns the decimal format symbols specified in the stylesheet.

Syntax

public java.text.DecimalFormatSymbols getDecimalFormat( NSName nsname);

Parameter	Description
nsname	Qualified name from xsl decimal-format.

getOutputEncoding()

Description

Returns the value of the encoding specified in xsl:output.

Syntax

public String getOutputEncoding();

getOutputMediaType()

Description

Returns the value of the media-type specified in xsl:output.

Syntax

public jString getOutputMediaType();

getOutputProperties()

Description

Returns the output properties specified in xsl:output as java.util.Properties.

Syntax

public java.util.Properties getOutputProperties();

newTransformer()

Description

Returns a JAXP Transformer object that uses this stylesheet for transformation.

Syntax

public javax.xml.transform.Transformer newTransformer();

---

XSLTContext Class

---

Description of XSLTContext

Class for Xpath processing Context.

---

Syntax of XSLTContext

public class XSLTContext extends java.lang.Object
 
java.lang.Object
  |
  +--oracle.xml.parser.v2.XSLTContext

---

Methods of XSLTContext

Table 4-8 Summary of Methods of XSLTContext

Method	Description
getContextNode()	Returns the current context node.
getContextPosition()	Returns the current context node position.
getContextSize()	Returns the current context size.
getError()	Returns the XMLError instance for reporting errors.
getVariable()	Returns variable at the given stack offset.
reportCharacters()	Reports characters to the current output handler.
reportNode()	Reports an XMLNode to the current output handler.
setError()	Sets the XMLError.

getContextNode()

Description

Returns the current context node.

Syntax

public XMLNode getContextNode();

getContextPosition()

Description

Returns the current context node position.

Syntax

public int getContextPosition();

getContextSize()

Description

Returns the current context size.

Syntax

public int getContextSize();

getError()

Description

Returns the XMLError instance for reporting errors.

Syntax

public XMLError getError();

getVariable()

Description

Returns variable at the given stack offset.

Syntax

public getVariable( NSName name,
                    int offset);

Parameter	Description
name	name of the variable
offset	offset of the variable

reportCharacters()

Description

Reports characters to the current output handler.

Syntax

public void reportCharacters( String data,
                              boolean disableoutesc);

Parameter	Description
chars	String to be printed
disableoutesc	Boolean to disable or enable escaping of characters as defined in the W3C.org XML 1.0 specification. TRUE means disabled, FALSE means enabled.

reportNode()

Description

Reports a XMLNode to the current output handler.

Syntax

public void reportNode( XMLNode node);

Parameter	Description
node	Node to be output.

setError()

Description

Sets the XMLError.

Syntax

public void setError(XMLError err);

Parameter	Description
err	Instance of XMLError.