iaik.ixsil.util

Interface DOMUtilsInterface

All Known Implementing Classes:

DOMUtilsImpl, DOMUtilsImplApache, DOMUtilsImplBase

public interface DOMUtilsInterface

Defines the interface for all methods IXSIL relies on for DOM manipulations (that either cannot be expressed using the DOM level 2 interfaces, or that are for convenience).

Method Summary

Methods

Modifier and Type	Method and Description
boolean	checkExpandedElementName(org.w3c.dom.Element element, java.lang.String namespaceURI, java.lang.String localName) Checks if the expanded name of the specified element corresponds with the specified namespace URI and local name.
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) Creates a DOM document instance from a given stream representation of a XML document.
java.lang.String	getCharacterData(org.w3c.dom.Element parent) Returns a concatenation of all text children of the specified parent element.
org.w3c.dom.Element	getChildElementByTagNameNS(org.w3c.dom.Element parent, java.lang.String namespaceURI, java.lang.String localName, int instance) Returns the child element of the specified parent element, which matches the specified namespace URI and the specified local name.
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.
org.w3c.dom.NodeList	listToNodeList(java.util.List list) Converts a List object into a NodeList object.
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	serializeDocument(org.w3c.dom.Document doc, java.io.OutputStream documentSurface) Serializes the specified DOM document to the specified output stream.
void	serializeDocument(org.w3c.dom.Document doc, java.io.OutputStream documentSurface, java.lang.String encoding) Serializes the specified DOM document to the specified output stream using the specified character encoding.
void	serializeElement(org.w3c.dom.Element elem, java.io.OutputStream elementSurface) Serializes the specified DOM element to the specified output stream.
void	setAttribute(org.w3c.dom.Element element, java.lang.String namespaceURI, java.lang.String namespacePrefix, java.lang.String localName, java.lang.String value) Creates a DOM attribute from the specified parameters and adds it to the specified DOM element.
void	unregisterID(org.w3c.dom.Document owningDoc, java.lang.String idValue) Unregisters a candidate DOM element, which has been registerred with method registerID(org.w3c.dom.Document, org.w3c.dom.Element, java.lang.String) before, at its owning DOM document.

Method Detail

schemaValidateSignatureElement

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

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

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:

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

replaceSignatureElement

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

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.

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:

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

createDocumentFromScratch

org.w3c.dom.Document createDocumentFromScratch()

Creates a new, empty DOM document.

Returns:

the new, empty DOM document.

getDocumentTraversal

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.

Parameters:

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

Returns:

a DocumentTraversal interface for the specified DOM document.

createDocumentFromXMLInstance

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

Creates a DOM document instance from a given stream representation of a XML document.

Parameters:

xmlDocStream - The stream representation of the XML document.

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

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".

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.

Returns:

the created DOM document.

Throws:

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

getChildElementByTagNameNS

org.w3c.dom.Element getChildElementByTagNameNS(org.w3c.dom.Element parent,
                                             java.lang.String namespaceURI,
                                             java.lang.String localName,
                                             int instance)

Returns the child element of the specified parent element, which matches the specified namespace URI and the specified local name.

Parameters:

parent - The parent element bearing the requested child element. Must not be null.

namespaceURI - The namespace URI of the requested child element. May be null to indicate that the attribute should be in no namespace.

localName - The local name of the requested child element. Must not be null.

instance - A value of i will return the (i)th occurence of the requested element in the parent element. Must be greater than or equal to 1.

Returns:

The requested child element, or null if there is no such child element.

getCharacterData

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

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

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.

checkExpandedElementName

boolean checkExpandedElementName(org.w3c.dom.Element element,
                               java.lang.String namespaceURI,
                               java.lang.String localName)

Checks if the expanded name of the specified element corresponds with the specified namespace URI and local name.

Parameters:

element - The candidate element. Must not be null.

namespaceURI - The namespace URI part of the expanded name. May be null if the candidate element should be in no namespace.

localName - The local name part of the expanded name. Must not be null.

Returns:

true, if the expanded name of the specified element corresponds with the specified namespace URI and local name; false otherwise.

setAttribute

void setAttribute(org.w3c.dom.Element element,
                java.lang.String namespaceURI,
                java.lang.String namespacePrefix,
                java.lang.String localName,
                java.lang.String value)

Creates a DOM attribute from the specified parameters and adds it to the specified DOM element. If such a DOM attribute already exists, its value will be overwritten. If the value parameter equals null, the possibly existing DOM attribute will be removed from the DOM element.

Parameters:

element - The DOM element, which will become the owner of the new DOM attribute. Must not be null.

namespaceURI - The namespace URI for the attribute. May be null to indicate that the attribute should be in no namespace.

namespacePrefix - The namespace prefix for the attribute (including the final colon). Must not be null. Use an empty string to indicate that no namespace prefix should be used.

localName - The local name for the attribute. Must not be null.

value - The value for the attribute. May be null to indicate that the specified DOM attribute should be removed from the specified DOM element.

listToNodeList

org.w3c.dom.NodeList listToNodeList(java.util.List list)

Converts a List object into a NodeList object.

Parameters:

list - A List object constisting purely of Node objects.

Returns:

a NodeList containing the specified nodes as member, or an empty NodeList if the specified List equals null.

registerID

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

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.

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.

unregisterID

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

Unregisters a candidate DOM element, which has been registerred with method 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.

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.

serializeDocument

void serializeDocument(org.w3c.dom.Document doc,
                     java.io.OutputStream documentSurface)
                       throws DOMUtilsException

Serializes the specified DOM document to the specified output stream. The document is printed as-is, i. e. no pretty printing will be done. An XML declaration will be printed. Character encoding is set to UTF-8.

Parameters:

doc - The DOM document to be serialized. Must not be null.

documentSurface - The output stream where the serialization result is printed. Must not be null.

Throws:

DOMUtilsException

Since:

Entrust 7.0

serializeDocument

void serializeDocument(org.w3c.dom.Document doc,
                     java.io.OutputStream documentSurface,
                     java.lang.String encoding)
                       throws DOMUtilsException

Serializes the specified DOM document to the specified output stream using the specified character encoding. The document is printed as-is, i. e. no pretty printing will be done. An XML declaration will be printed.

Parameters:

doc - The DOM document to be serialized. Must not be null.

documentSurface - The output stream where the serialization result is printed. Must not be null.

encoding - The string that will identify the document's character encoding in the XML declaration, e.g. "UTF-8" Must not be null.

Throws:

DOMUtilsException

Since:

Entrust 7.0

serializeElement

void serializeElement(org.w3c.dom.Element elem,
                    java.io.OutputStream elementSurface)
                      throws DOMUtilsException

Serializes the specified DOM element to the specified output stream. The element is printed as-is, i. e. no pretty printing will be done.

Parameters:

elem - The DOM element to be serialized. Must not be null.

elementSurface - The output stream where the serialization result is printed. Must not be null.

Throws:

DOMUtilsException

Since:

Entrust 7.0