com.entrust.toolkit.xml.util

Class DOMUtilsImplApache

java.lang.Object

com.entrust.toolkit.xml.util.DOMUtilsImplBase

com.entrust.toolkit.xml.util.DOMUtilsImplApache

All Implemented Interfaces:

DOMUtilsInterface

public class DOMUtilsImplApache
extends DOMUtilsImplBase
implements DOMUtilsInterface

This subclass of DOMUtilsImplBase lets the Toolkit use an Apache XML parser that resides in your Java runtime, as an installed JRE extension or on the class path. You should configure the Toolkit to use this class if your application has created a DOM Document instance using an Apache parser, and you want to provide that Document to the constructor of the Toolkit's Signer or Verifier.

To ensure that the Toolkit will use the external JAXP implementation in the Apache libraries, instead of its internal implementation, set the following property in the Toolkit's XML initialization file (usually called init.properties);

DOMUtils.ImplementingClass = com.entrust.toolkit.xml.util.DOMUtilsImplApache

The Apache libraries (Xerces and Xalan) must be on the class path or in the JRE as an installed extension. Optionally, your Java environment might specify which JAXP implementation to use by setting a Java system property for JAXP; refer to the javadoc for DocumentBuilderFactory.newInstance().

As an alternative, you could use the Toolkit's internal parser. To do that, set the DOMUtils.ImplementingClass as follows;

DOMUtils.ImplementingClass = iaik.ixsil.util.DOMUtilsImpl

In that case, your application must parse the XML source by invoking DOMUtils.createDocumentFromXMLInstance(java.io.InputStream, iaik.ixsil.util.URI, int, java.lang.String, java.lang.String). The Toolkit's internal parser is based on Apache Xerces 1.4.4.

Note 1

The Toolkit uses this class internally, but your application should not invoke its methods directly. Instead, invoke methods in the class DOMUtils. Internally, the Toolkit finds an implementation based on the Java property DOMUtils.ImplementingClass in the init.properties file.

Note 2

DOMUtilsImplApache sets the parser Properties and Features specific to Apache, but it does this through the JAXP API, without using classes or methods specific to Apache parsers. Furthermore, it does not import any classes from org.apache packages, so it should work with most versions of the Apache libraries (even though the Apache parser classes are located in different Java packages for different Apache releases; for example, the DOMParser class derives from org.apache.xerces.framework.XMLParser in Xerces 1.4.4, but from org.apache.xerces.parsers.XMLParser in Xerces 2). The Toolkit has been tested with Xerces 1.4.4, Xerces 2.0.2, Xerces 2.4, Xalan 2.3.1, and Xalan 2.4. It will not work properly with Xerces 2.3; if your application must use that version, use the alternate procedure described above, setting DOMUtils.ImplementingClass to the the Toolkit's internal parser.

See Also:

DOMUtils, Signer(Document signatureDocOM, URI signatureDocBaseURI, Position signaturePosition), Verifier(Document signatureDocOM, URI signatureDocBaseURI, String signatureSelectorXPath, String additionalNSPrefixes)

Nested Class Summary

Nested classes/interfaces inherited from class com.entrust.toolkit.xml.util.DOMUtilsImplBase

DOMUtilsImplBase.NodeListImpl

Constructor Summary

Constructors

Constructor and Description
DOMUtilsImplApache()

Method Summary

Modifier and Type	Method and Description
org.w3c.dom.Document	createDocumentFromScratch() Creates a new, empty DOM document.
org.w3c.dom.Document	createDocumentFromXMLInstance(java.io.InputStream xmlDocStream, URI xmlDocBaseURI, int validate, java.lang.String noNamespaceSchemaLocation, java.lang.String schemaLocations) The DOM parser is configured not to report any Warnings, Errors or FatalErrors.
java.lang.String	getCharacterData(org.w3c.dom.Element parent) Returns a concatenation of all text children of the specified parent element.
org.w3c.dom.traversal.DocumentTraversal	getDocumentTraversal(org.w3c.dom.Document doc) Gets a DOM level 2 DocumentTraversal interface, which allows the creation of DOM level 2 NodeIterator and TreeWalker interfaces, for the specified DOM document.
void	registerID(org.w3c.dom.Document owningDoc, org.w3c.dom.Element candidate, java.lang.String idValue) Registers a candidate DOM element with the value of its ID attribute at its owning DOM document.
void	replaceSignatureElement(org.w3c.dom.Element oldSigElem, org.w3c.dom.Element newSigElem) Replaces an old signature element, which is part of document A, with a new signature element, which is part of document B.
org.w3c.dom.Element	schemaValidateSignatureElement(org.w3c.dom.Element signatureDOMElem, java.lang.String additionalNoNamespaceSchemaLocation, java.lang.String additionalSchemaLocations) Validates a specified DOM element representing a XML signature against the signature schema specified in the IXSIL init properties.
void	unregisterID(org.w3c.dom.Document owningDoc, java.lang.String idValue) Unregisters a candidate DOM element, which has been registerred with method DOMUtilsInterface.registerID(org.w3c.dom.Document, org.w3c.dom.Element, java.lang.String) before, at its owning DOM document.

Methods inherited from class com.entrust.toolkit.xml.util.DOMUtilsImplBase

checkExpandedElementName, getChildElementByTagNameNS, getNamespaceOfElement, listToNodeList, serializeDocument, serializeDocument, serializeElement, setAttribute

Methods inherited from class java.lang.Object

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

Methods inherited from interface iaik.ixsil.util.DOMUtilsInterface

checkExpandedElementName, getChildElementByTagNameNS, listToNodeList, serializeDocument, serializeDocument, serializeElement, setAttribute

Constructor Detail

DOMUtilsImplApache

public DOMUtilsImplApache()

Method Detail

schemaValidateSignatureElement

public org.w3c.dom.Element schemaValidateSignatureElement(org.w3c.dom.Element signatureDOMElem,
                                                          java.lang.String additionalNoNamespaceSchemaLocation,
                                                          java.lang.String additionalSchemaLocations)
                                                   throws DOMUtilsException

Description copied from interface: DOMUtilsInterface

Validates a specified DOM element representing a XML signature against the signature schema specified in the IXSIL init properties.

Specified by:

schemaValidateSignatureElement in interface DOMUtilsInterface

Specified by:

schemaValidateSignatureElement in class DOMUtilsImplBase

Parameters:

signatureDOMElem - The signature DOM element to be schema validated. Must not be null .

additionalNoNamespaceSchemaLocation - Provides an additional schema apart from the XMLDSIG schema for elements in the no-namespace. Such a schema can be pro- vided for the content of Object or SignatureProperty elements. The parameter contains the location URI for such a schema. May be null .

additionalSchemaLocations - Provides additional schemas apart from the XMLDSIG schema to be used for validation. Such schemas can be provided for the content of Object or SignatureProperty elements. Must either be null or conform to the following rules:

                                    additionalSchemas ::= additionalSchema (space additionalSchema)*
                                    additionalSchema ::= schemaNamespaceURI space schemaLocationURI
                                  

For example, "http://foo.org/mySchema http://repository.foo.org/mySchema.xsd".

Returns:

the validated signature DOM element. If this element or descending elements have ID attributes, the returned element's implementation must provide marks for such special elements. The marks are evaluated by other methods of this interface!

Throws:

DOMUtilsException - if the validation fails for some reason.

See Also:

DOMUtilsInterface.schemaValidateSignatureElement(org.w3c.dom.Element, java.lang.String, java.lang.String)

replaceSignatureElement

public void replaceSignatureElement(org.w3c.dom.Element oldSigElem,
                                    org.w3c.dom.Element newSigElem)
                             throws DOMUtilsException

Description copied from interface: DOMUtilsInterface

Replaces an old signature element, which is part of document A, with a new signature element, which is part of document B. The method must also take into account marks made by the underlying document implementation, regarding elements of the document, which have an ID attribute declared.

Specified by:

replaceSignatureElement in interface DOMUtilsInterface

Specified by:

replaceSignatureElement in class DOMUtilsImplBase

Parameters:

oldSigElem - The old Signature DOM element which should be replaced. Must not be null .

newSigElem - The new Signature DOM element which should replace the old one. Must not be null.

Throws:

DOMUtilsException - if the transfer fails for some reason.

See Also:

DOMUtilsInterface.replaceSignatureElement(org.w3c.dom.Element, org.w3c.dom.Element)

createDocumentFromScratch

public org.w3c.dom.Document createDocumentFromScratch()

Description copied from interface: DOMUtilsInterface

Creates a new, empty DOM document.

Specified by:

createDocumentFromScratch in interface DOMUtilsInterface

Specified by:

createDocumentFromScratch in class DOMUtilsImplBase

Returns:

the new, empty DOM document.

See Also:

DOMUtilsInterface.createDocumentFromScratch()

getDocumentTraversal

public org.w3c.dom.traversal.DocumentTraversal getDocumentTraversal(org.w3c.dom.Document doc)

Description copied from interface: DOMUtilsInterface

Gets a DOM level 2 DocumentTraversal interface, which allows the creation of DOM level 2 NodeIterator and TreeWalker interfaces, for the specified DOM document.

Specified by:

getDocumentTraversal in interface DOMUtilsInterface

Specified by:

getDocumentTraversal in class DOMUtilsImplBase

Parameters:

doc - The DOM document, for which a DocumentTraversal should be returned.

Returns:

a DocumentTraversal interface for the specified DOM document.

See Also:

DOMUtilsInterface.getDocumentTraversal(org.w3c.dom.Document)

createDocumentFromXMLInstance

public org.w3c.dom.Document createDocumentFromXMLInstance(java.io.InputStream xmlDocStream,
                                                          URI xmlDocBaseURI,
                                                          int validate,
                                                          java.lang.String noNamespaceSchemaLocation,
                                                          java.lang.String schemaLocations)
                                                   throws DOMUtilsException

The DOM parser is configured not to report any Warnings, Errors or FatalErrors. An instance of the class DOMUtilsErrorHandler is registered at the parser. This error handler treats Warnings, Errors and FatalErrors as specified by corresponding IXSIL properties.

Specified by:

createDocumentFromXMLInstance in interface DOMUtilsInterface

Specified by:

createDocumentFromXMLInstance in class DOMUtilsImplBase

Parameters:

xmlDocStream - The stream representation of the XML document.

xmlDocBaseURI - Holds the base URI for the XML document used to resolve relative URIs.

validate - Determines wheter the document should be validated or not. Please see the constants DOMUtils.VALIDATION_YES_, DOMUtils.VALIDATION_NO_, DOMUtils.VALIDATION_DYNAMIC_ for further information.

noNamespaceSchemaLocation - This URI string can be used to provide a Schema for the no-namespace in cases where the DOM document should be created by a validating parser (see also parameter validate). May be null . Valid example: "http://repository.foo.org/mySchema.xsd".

schemaLocations - This parameter can be used to provide schemas for various namespaces in cases where the DOM document should be created by a validating parser (see also parameter validate). Must either be null or conform to the following rules:

                           additionalSchemas ::= additionalSchema (space additionalSchema)*
                           additionalSchema ::= schemaNamespaceURI space schemaLocationURI
                         

For example, "http://foo.org/mySchema http://repository.foo.org/mySchema.xsd".

Returns:

the created DOM document.

Throws:

DOMUtilsException - if creating the DOM document failed for any reason.

See Also:

DOMUtilsInterface.createDocumentFromXMLInstance(java.io.InputStream, iaik.ixsil.util.URI, int, java.lang.String, java.lang.String)

registerID

public void registerID(org.w3c.dom.Document owningDoc,
                       org.w3c.dom.Element candidate,
                       java.lang.String idValue)
                throws DOMUtilsException

Description copied from interface: DOMUtilsInterface

Registers a candidate DOM element with the value of its ID attribute at its owning DOM document. After this registration, the DOM element can be queried at its owning DOM document using the DOM interface method Document.getElementById(java.lang.String). If a DOM element is already registerred under the specified ID value, this method will have no effect.

Specified by:

registerID in interface DOMUtilsInterface

Specified by:

registerID in class DOMUtilsImplBase

Parameters:

owningDoc - The DOM document which owns the candidate DOM element. Must not be null.

candidate - The candidate DOM element to be registerred. Must not be null.

idValue - The value of the candidate's ID attribute. Must not be null.

Throws:

DOMUtilsException - if registration fails for any reason.

See Also:

DOMUtilsInterface.registerID(org.w3c.dom.Document, org.w3c.dom.Element, java.lang.String)

unregisterID

public void unregisterID(org.w3c.dom.Document owningDoc,
                         java.lang.String idValue)
                  throws DOMUtilsException

Description copied from interface: DOMUtilsInterface

Unregisters a candidate DOM element, which has been registerred with method DOMUtilsInterface.registerID(org.w3c.dom.Document, org.w3c.dom.Element, java.lang.String) before, at its owning DOM document. If no DOM element is registerred under the specified ID value at the DOM document, this method will have no effect.

Specified by:

unregisterID in interface DOMUtilsInterface

Specified by:

unregisterID in class DOMUtilsImplBase

Parameters:

owningDoc - The DOM document which owns the candidate DOM element. Must not be null.

idValue - The value of the candidate's ID attribute. Must not be null.

Throws:

DOMUtilsException - if undoing the registration fails for any reason.

See Also:

DOMUtilsInterface.unregisterID(org.w3c.dom.Document, java.lang.String)

getCharacterData

public java.lang.String getCharacterData(org.w3c.dom.Element parent)

Description copied from interface: DOMUtilsInterface

Returns a concatenation of all text children of the specified parent element.

Specified by:

getCharacterData in interface DOMUtilsInterface

Parameters:

parent - The parent element.

Returns:

a string representing the concatenation of all text children's values, or null, if the element does not contain any text children or if all text children represent text with zero length.