Release 2 (9.2)
Part Number A96616-01
 Home |
 Book List |
 Contents |
 Index |
 Master Index |
 Feedback |
| Oracle9i XML API Reference - XDK and Oracle XML DB Release 2 (9.2) Part Number A96616-01 |
|
This chapter describes the JAXP APIs contained in the oracle.xml.parser.v2 package
JXDocumentBuilder defines the APIs to obtain DOM Document instances from an XML document. Using this class, an application programmer can obtain a org.w3c.dom.Document from XML.
An instance of this class can be obtained from the DocumentBuilderFactory.newDocumentBuilder method. Once an instance of this class is obtained, XML can be parsed from a variety of input sources. These input sources are InputStreams, Files, URLs, and SAX InputSources.
Note that this class reuses several classes from the SAX API. This does not require that the implementor of the underlying DOM implementation use a SAX parser to parse XML document into a Document. It merely requires that the implementation communicate with the application using these existing APIs.
public class JXDocumentBuilder oracle.xml.jaxp.JXDocumentBuilder
Returns the associated DOM implementation object that handles this document. A DOM application may use objects from multiple implementations.
public org.w3c.dom.DOMImplementation getDOMImplementation();
Indicates whether or not this parser is configured to understand namespaces.
public boolean isNamespaceAware();
Indicates whether or not this parser is configured to validate XML documents.
public boolean isValidating();
Obtains a new instance of a DOM Document object with which to build a DOM tree.
public org.w3c.dom.Document newDocument();
Parses the content of the given input source as an XML document and return a new DOM Document object. Throws the following exceptions:
IOException if any I/O errors occurSAXException if any parse errors occurIllegalArgumentException if the InputSource is nullpublic org.w3c.dom.Document parse( org.xml.sax.InputSource is);
| Parameter | Description |
|---|---|
|
is |
InputSource containing the content to be parsed. |
Specifies the EntityResolver to resolve entities present in the XML document to be parsed. If this is set to NULL, the underlying implementation uses its own default implementation and behavior.
public void setEntityResolver( org.xml.sax.EntityResolver er);
| Parameter | Description |
|---|---|
|
er |
Entity Resolver. |
Specifies the ErrorHandler to be used to resolve entities present in the XML document to be parsed. Setting this to null will result in the underlying implementation using it's own default implementation and behavior.
public void setErrorHandler( org.xml.sax.ErrorHandler eh);
| Parameter | Description |
|---|---|
|
eh |
Error handler. |
Defines a factory API that enables applications to obtain a parser that produces DOM object trees from XML documents.
public class JXDocumentBuilderFactory oracle.xml.jaxp.JXDocumentBuilderFactory
Default constructor.
public JXDocumentBuilderFactory();
Allows the user to retrieve specific attributes on the underlying implementation; returns the value of the attribute. Throws IllegalArgumentException if the underlying implementation doesn't recognize the attribute.
public Object getAttribute( String name);
| Parameter | Description |
|---|---|
|
name |
The name of the attribute. |
Indicates whether or not the factory is configured to produce parsers which expand entity reference nodes. Always returns TRUE; currently, there is no way to prevent entity references expansions.
public boolean isExpandEntityReferences();
Indicates whether or not the factory is configured to produce parsers which ignore comments. Always returns FALSE; currently, ignoring comments is not configurable.
public boolean isIgnoringComments();
Indicates whether or not the factory is configured to produce parsers which are namespace aware. Always returns TRUE; currently, there is no way to turn of Namespaces.
public boolean isNamespaceAware();
Creates a new instance of a DocumentBuilder using the currently configured parameters. Throws ParserConfigurationException if a DocumentBuilder which satisfies the configuration requested cannot be created.
public DocumentBuilder newDocumentBuilder();
Sets specific attributes on the underlying implementation. Throws IllegalArgumentException if the underlying implementation doesn't recognize the attribute.
public void setAttribute( String name, Object value);
| Parameter | Description |
|---|---|
|
name |
The name of the attribute. |
|
value |
The value of the attribute. |
Defines the API that wraps an org.xml.sax.XMLReader implementation class. In JAXP 1.0, this class wrapped the org.xml.sax.Parser interface, however this interface was replaced by the XMLReader.
For ease of transition, this class continues to support the same name and interface as well as supporting new methods. An instance of this class can be obtained from the SAXParserFactory.newSAXParser method. Once an instance of this class is obtained, XML can be parsed from a variety of input sources. These input sources are InputStreams, Files, URLs, and SAX InputSources.
This static method creates a new factory instance based on a system property setting or uses the platform default if no property has been defined.
The system property that controls which Factory implementation to create is named "javax.xml.style.TransformFactory". This property names a class that is a concrete subclass of this abstract class. If no property is defined, a platform default will be used.
As the content is parsed by the underlying parser, methods of the given HandlerBase are called.
public class JXSAXParser oracle.xml.jaxp.JXSAXParser
Returns the value of the requested property for in the underlying implementation of org.xml.sax.XMLReader. See also org.xml.sax.XMLReader#getProperty. Throws the following exceptions:
SAXNotRecognizedException, when the underlying XMLReader does not recognize the property name.SAXNotSupportedException, when the underlying XMLReader recognizes the property name but doesn't support the property.public java.lang.Object getProperty( String name);
| Parameter | Description |
|---|---|
|
name |
The name of the property to be retrieved. |
Returns the XMLReader that is encapsulated by the implementation of this class.
public XMLReader getXMLReader();
Indicates whether or not this parser is configured to understand namespaces. Returns TRUE if the parser understands namespaces, FALSE otherwise.
public boolean isNamespaceAware();
Indicates whether or not this parser is configured to validate XML documents.
public boolean isValidating();
Sets the particular property in the underlying implementation of XMLReader. See also org.xml.sax.XMLReader#setProperty. Throws the following exceptions:
SAXNotRecognizedException, when the underlying XMLReader does not recognize the property name.SAXNotSupportedException, when the underlying XMLReader recognizes the property name but doesn't support the property.public void setProperty( String name, Object value);
| Parameter | Description |
|---|---|
|
name |
The name of the property to be set. |
|
value |
The value of the property to be set. |
Defines a factory API that enables applications to configure and obtain a SAX based parser to parse XML documents.
public class JXSAXParserFactory oracle.xml.jaxp.JXSAXParserFactory
Default constructor.
public JXSAXParserFactory();
Returns the value of the requested property for in the underlying implementation of XMLReader. See also org.xml.sax.XMLReader#getProperty. Throws the following exceptions:
SAXNotRecognizedException, when the underlying XMLReader does not recognize the property name.SAXNotSupportedException, when the underlying XMLReader recognizes the property name but doesn't support the property.public boolean getFeature( String name);
| Parameter | Description |
|---|---|
|
name |
The name of the property to be retrieved. |
Indicates whether or not the factory is configured to produce namespace aware parsers. Returns TRUE if the factory is configured for namespace aware parsers, FALSE otherwise.
public boolean isNamespaceAware();
Creates a new instance of a SAXParser using the currently configured factory parameters. Throws ParserConfigurationException if a parser which satisfies the requested configuration cannot be created.
public SAXParser newSAXParser();
Sets the particular feature in the underlying implementation of XMLReader. See also org.xml.sax.XMLReader#setFeature. Throws the following exceptions:
SAXNotRecognizedException, when the underlying XMLReader does not recognize the property name.SAXNotSupportedException, when the underlying XMLReader recognizes the property name but doesn't support the property.public void setFeature( String name, boolean value);
| Parameter | Description |
|---|---|
|
name |
The name of the feature to be set. |
|
value |
The value of the feature to be set. |
A JXSAXTransformerFactory instance can be used to create Transformer and Templates objects.
The system property that determines which Factory implementation to create is named "javax.xml.transform.TransformerFactory". This property names a concrete subclass of the TransformerFactory abstract class (in our case, it is JXSAXTransformerFactory). If the property is not defined, a platform default is be used.
This class also provides SAX-specific factory methods. It provides two types of ContentHandlers, one for creating Transformers, the other for creating Templates objects.
If an application wants to set the ErrorHandler or EntityResolver for an XMLReader used during a transformation, it should use a URIResolver to return the SAXSource which provides (with getXMLReader) a reference to the XMLReader.
public class JXSAXTransformerFactory oracle.xml.jaxp.JXSAXTransformerFactory
The default constructor.
public JXSAXTransformerFactory();
Retrieves the stylesheet specification(s) associated through the xml-stylesheet processing instruction (see http://www.w3.org/TR/xml-stylesheet/) matching the document specified in the source parameter and other parameters. Returns a Source object suitable for passing to the TransformerFactory. Note that it is possible to return several stylesheets, in which case they are applied as if they were a list of imports or cascades in a single stylesheet.
public Source getAssociatedStylesheet( Source source, String media, String title, String charset);
Allows the user to retrieve specific attributes on the underlying implementation. Returns the value of the attribute. Throws IllegalArgumentException if the underlying implementation doesn't recognize the attribute.
public java.lang.Object getAttribute( String name);
| Parameter | Description |
|---|---|
|
name |
The name of the attribute. |
Retrieves the current error event handler (which should never be NULL) for the TransformerFactory.
public ErrorListener getErrorListener();
Looks up the value of a feature. Returns the current state of the feature (TRUE or FALSE). The feature name is any absolute URI.
public boolean getFeature( String name);
| Parameter | Description |
|---|---|
|
name |
The feature name, which is an absolute URI. |
Retrieves the object used by default during the transformation to resolve URIs used in document(), xsl:import(), or xsl:include(). Returns the URIResolver that was set with setURIResolver.
public URIResolver getURIResolver();
Processes the Source into a Templates object, which is a compiled representation of the source. Returns a Templates object capable of being used for transformation purposes, never NULL. This Templates object may then be used concurrently across multiple threads. Creating a Templates object allows the TransformerFactory to do detailed performance optimization of transformation instructions, without penalizing runtime transformation. If the methods fails to construct the Templates object during the parse, it throws TransformerConfigurationException.
public Templates newTemplates( Source source);
| Parameter | Description |
|---|---|
|
source |
An object that holds a URL, input stream, and so on. |
Retrieves a TemplatesHandler object that can process SAX ContentHandler events into a Templates object. Returns a non-NULL reference to a TransformerHandler, that may be used as a ContentHandler for SAX parse events. If the TemplatesHandler cannot be created, throws a TransformerConfigurationException.
public TemplatesHandler newTemplatesHandler();
Generates a new Transformer object. Returns a Transformer object that may be used to perform a transformation in a single thread, never NULL. Care must be taken not to use this object in multiple threads running concurrently; instead, different TransformerFactories should be used concurrently by different threads. Throws TransformerConfigurationException if construction of the Templates object fails during parse. The options are described in the following table.
| Parameter | Description |
|---|---|
|
source |
An object that holds a URI, input stream, and so on. |
Generates a TransformerHandler object. Returns a non-NULL reference to a TransformerHandler, ready to transform SAX parse events. The transformation is defined as an identity (or copy) transformation, for example to copy a series of SAX parse events into a DOM tree. If the TransformerHandler cannot be created, throws TransformerConfigurationException. The options are described in the following table.
| Parameter | Description |
|---|---|
|
source |
The Source of the transformation instructions. |
|
templates |
The compiled transformation instructions. |
Creates an XMLFilter. Returns an XMLFilter object, or null if this feature is not supported. Throws TransformerConfigurationException if the TemplatesHandler cannot be created. The options are described in the following table.
| Parameter | Description |
|---|---|
|
source |
The Source of the transformation instructions. |
|
templates |
The compiled transformation instructions. |
Sets specific attributes on the underlying implementation. An attribute in this context is defined to be an option that the implementation provides.
public void setAttribute( String name, Object value);
| Parameter | Description |
|---|---|
|
name |
The name of the attribute. |
|
value |
The value of the attribute. |
Sets the error event listener for the TransformerFactory. This is used for the processing of transformation instructions, and not for the transformation itself. Throws IllegalArgumentException if listener is NULL.
public void setErrorListener( javax.xml.transform.ErrorListener listener);
| Parameter | Description |
|---|---|
|
listener |
The new error listener. |
Sets an object to use by default during the transformation to resolve URIs used in xsl:import, or xsl:include.
public void setURIResolver( javax.xml.transform.URIResolver resolver);
| Parameter | Description |
|---|---|
|
name |
An object that implements the URIResolver interface, or |
An instance of this class can transform a source tree into a result tree.
An instance of this class can be obtained with the TransformerFactory.newTransformer method. This instance may then be used to process XML from a variety of sources and write the transformation output to a variety of sinks.
An object of this class may not be used in multiple threads running concurrently. Different Transformers may be used concurrently by different threads.
A Transformer may be used multiple times. Parameters and output properties are preserved across transformations.
public class JXTransformer oracle.xml.jaxp.JXTransformer
Constructs a JXTransformer object. The options are described in the following table.
| Syntax | Description |
|---|---|
|
public JXTransformer(); |
Default constructor. |
|
oracle.xml.parser.v2.XSLStylesheet templates); |
Constructs a JXTransformer object that uses the XSLStylesheet to transform the source. |
| Parameter | Description |
|---|---|
|
templates |
An XSLStylesheet or Templates. |
Clears all parameters set with setParameter.
public void clearParameters();
Retrieves the error event handler in effect for the transformation; the error handler should never be NULL.
public javax.xml.transform.ErrorListener getErrorListener();
Retrieves a copy of the output properties for the transformation.
The properties returned should contain properties set by the user and properties set by the stylesheet. These properties are "defaulted" by default properties specified by section 16 of the XSL Transformations (XSLT) W3C Recommendation. The properties that were specifically set by the user or the stylesheet should be in the base Properties list, while the XSLT default properties that were not specifically set should be the default Properties list. Thus, getOutputProperties().getProperty() will obtain any property in that was set by setOutputProperty() , setOutputProperties() , in the stylesheet, or the default properties, while getOutputProperties().get() will only retrieve properties that were explicitly set by setOutputProperty() , setOutputProperties() , or in the stylesheet. Note that mutation of the Properties object returned will not effect the properties that the transformation contains.
If any of the argument keys are not recognized and are not namespace qualified, the property will be ignored; the behavior is not orthogonal with setOutputProperties().
public java.util.Properties getOutputProperties();
Returns string value of an output property that is in effect for the transformation, or NULL if no property was found. The property specified may be a property that was set with setOutputProperty, or it may be a property specified in the stylesheet. Throws IllegalArgumentException if the property is not supported
public String getOutputProperty( String name);
| Parameter | Description |
|---|---|
|
name |
A non-null String that specifies an output property name, which may be namespace qualified. |
Returns a parameter that was explicitly set with setParameter() or setParameters(); NULL if a parameter with the given name was not found. This method does not return a default parameter value, which cannot be determined until the node context is evaluated during the transformation process.
public Object getParameter( String name);
| Parameter | Description |
|---|---|
|
name |
Parameter name. |
Returns an object that will be used to resolve URIs used in document(), and so on. Retrieves an object that implements the URIResolver interface, or null. Throws and IllegalArgumentException if listener is null.
public javax.xml.transform.URIResolver getURIResolver();
Sets the error event listener in effect for the transformation.
public void setErrorListener(javax.xml.transform.ErrorListener listener)
| Parameter | Description |
|---|---|
|
listener |
The new error listener. |
Sets the output properties for the transformation. These properties will override properties set in the Templates with xsl:output. Throws an IllegalArgumentException if any of the argument keys are not recognized and are not namespace qualified.
If argument to this function is null, any properties previously set are removed, and the value will revert to the value defined in the templates object.
Passes a qualified property key name as a two-part string, the namespace URI enclosed in curly braces ({}), followed by the local name. If the name has a null URL, the String only contain the local name. An application can safely check for a non-null URI by testing to see if the first character of the name is a '{' character.
For example, if a URI and local name were obtained from an element defined with <xyz:foo xmlns:xyz="http://xyz.foo.com/yada/baz.html"/>, then the qualified name would be "{http://xyz.foo.com/yada/baz.html}foo". Note that no prefix is used.
public void setOutputProperties( java.util.Properties oformat);
| Parameter | Description |
|---|---|
|
oformat |
A set of output properties that will be used to override any of the same properties in affect for the transformation. |
Sets an output property that will be in effect for the transformation. Passes a qualified property name as a two-part string, the namespace URI enclosed in curly braces ({}), followed by the local name. If the name has a null URL, the String only contain the local name. An application can safely check for a non-null URI by testing to see if the first character of the name is a '{' character.
For example, if a URI and local name were obtained from an element defined with <xyz:foo xmlns:xyz="http://xyz.foo.com/yada/baz.html"/>, then the qualified name would be "{http://xyz.foo.com/yada/baz.html}foo". Note that no prefix is used.
The Properties object that was passed to setOutputProperties(Properties) won't be effected by calling this method.
Throws an IllegalArgumentException if the property is not supported, and is not qualified with a namespace.
public void setOutputProperty(java.lang.String name, java.lang.String value)
| Parameter | Description |
|---|---|
|
name |
A non-null String that specifies an output property name, which may be namespace qualified. |
|
value |
The non-null string value of the output property. |
Adds a parameter for the transformation. Passes a qualified name as a two-part string, the namespace URI enclosed in curly braces ({}), followed by the local name. If the name has a null URL, the String only contains the local name. An application can safely check for a non-null URI by testing to see if the first character of the name is a '{' character.
For example, if a URI and local name were obtained from an element defined with <xyz:foo xmlns:xyz="http://xyz.foo.com/yada/baz.html"/>, then the qualified name would be "{http://xyz.foo.com/yada/baz.html}foo". Note that no prefix is used.
public void setParameter( String name, Object value);
Sets an object that will be used to resolve URIs used in document(). If the resolver argument is null, the URIResolver value will be cleared, and the default behavior will be used. Currently, URIResolver in document() function is not supported.
public void setURIResolver( javax.xml.transform.URIResolver resolver);
| Parameter | Description |
|---|---|
|
resolver |
An object that implements the URIResolver interface, or |
Processes the source tree to the output result. Throws TransformerException if an unrecoverable error occurs during the course of the transformation
public void transform( javax.xml.transform.Source xmlSource, javax.xml.transform.Result outputTarget);
| Parameter | Description |
|---|---|
|
xmlSource |
The input for the source tree. |
|
outputTarget |
The output target. |
|
 Copyright © 2001, 2002 Oracle Corporation. All Rights Reserved. |
|