org.codehaus.mojo.jaxb2.schemageneration.postprocessing.javadoc

Class DomHelper

java.lang.Object

org.codehaus.mojo.jaxb2.schemageneration.postprocessing.javadoc.DomHelper

public final class DomHelper
extends Object

Helper class stashing commonly used algorithms to work with DOM documents.

Since:

2.3

Author:

Lennart Jörelid, jGuru Europe AB

Field Summary

Fields

Modifier and Type	Field and Description
static String	ANNOTATION_ELEMENT_NAME The name of the annotation element.
static List<String>	CLASS_FIELD_METHOD_ELEMENT_NAMES The names of DOM Elements corresponding to Java class Fields or Methods.
static String	DOCUMENTATION_ELEMENT_NAME The name of the documentation element.
static List<String>	ENUMERATION_FIELD_METHOD_ELEMENT_NAMES The names of DOM Elements corresponding to Java enum Fields or Methods.
static String	XSD_SCHEMA_NAMESPACE_PREFIX The namespace schema prefix for the URI http://www.w3.org/2001/XMLSchema (i.e.

Method Summary

Modifier and Type	Method and Description
static void	addXmlDocumentAnnotationTo(Node aNode, String formattedDocumentation) Adds the given formattedDocumentation within an XML documentation annotation under the supplied Node.
static ClassLocation	getClassLocation(Node aNode, Set<ClassLocation> classLocations) Retrieves the ClassLocation for the supplied aNode.
static String	getElementTagName(Node aNode) Retrieves the TagName for the supplied Node if it is an Element, and null otherwise.
static FieldLocation	getFieldLocation(Node aNode, Set<FieldLocation> fieldLocations) Retrieves a FieldLocation from the supplied Set, provided that the FieldLocation matches the supplied Node.
static <T extends FieldLocation> T	getFieldOrMethodLocationIfValid(Node aNode, Node containingClassNode, Set<? extends FieldLocation> locations) Retrieves a FieldLocation or MethodLocation from the supplied Set of Field- or MethodLocations, provided that the supplied Node has the given containing Node corresponding to a Class or an Enum.
static MethodLocation	getMethodLocation(Node aNode, Set<MethodLocation> methodLocations) Finds the MethodLocation within the given Set, which corresponds to the supplied DOM Node.
static String	getNameAttribute(Node aNode) Retrieves the value of the name attribute of the supplied Node.
static String	getValueAttribute(Node aNode) Retrieves the value of the value attribute of the supplied Node.
static String	getXPathFor(Node aNode) Retrieves the XPath for the supplied Node within its document.
static void	insertXmlDocumentationAnnotationsFor(Node aNode, SortedMap<ClassLocation,JavaDocData> classJavaDocs, SortedMap<FieldLocation,JavaDocData> fieldJavaDocs, SortedMap<MethodLocation,JavaDocData> methodJavaDocs, JavaDocRenderer renderer) Processes the supplied DOM Node, inserting XML Documentation annotations if applicable.
static boolean	isNamedElement(Node aNode) Checks if the supplied DOM Node is a DOM Element having a defined "name" attribute.

Methods inherited from class java.lang.Object

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

Field Detail

ANNOTATION_ELEMENT_NAME

public static final String ANNOTATION_ELEMENT_NAME

The name of the annotation element.

See Also:

Constant Field Values

DOCUMENTATION_ELEMENT_NAME

public static final String DOCUMENTATION_ELEMENT_NAME

The name of the documentation element.

See Also:

Constant Field Values

XSD_SCHEMA_NAMESPACE_PREFIX

public static final String XSD_SCHEMA_NAMESPACE_PREFIX

The namespace schema prefix for the URI http://www.w3.org/2001/XMLSchema (i.e. XMLConstants.W3C_XML_SCHEMA_NS_URI).

See Also:

XMLConstants.W3C_XML_SCHEMA_NS_URI, Constant Field Values

CLASS_FIELD_METHOD_ELEMENT_NAMES

public static final List<String> CLASS_FIELD_METHOD_ELEMENT_NAMES

The names of DOM Elements corresponding to Java class Fields or Methods.

ENUMERATION_FIELD_METHOD_ELEMENT_NAMES

public static final List<String> ENUMERATION_FIELD_METHOD_ELEMENT_NAMES

The names of DOM Elements corresponding to Java enum Fields or Methods.

Method Detail

getNameAttribute

public static String getNameAttribute(Node aNode)

Retrieves the value of the name attribute of the supplied Node.

Parameters:

aNode - A DOM Node.

Returns:

the value of the name attribute of the supplied Node/Element.

getValueAttribute

public static String getValueAttribute(Node aNode)

Retrieves the value of the value attribute of the supplied Node.

Parameters:

aNode - A DOM Node.

Returns:

the value of the value attribute of the supplied Node/Element.

isNamedElement

public static boolean isNamedElement(Node aNode)

Checks if the supplied DOM Node is a DOM Element having a defined "name" attribute.

Parameters:

aNode - A DOM Node.

Returns:

true if the supplied aNode is an Elemnet having a defined "name" attribute.

getElementTagName

public static String getElementTagName(Node aNode)

Retrieves the TagName for the supplied Node if it is an Element, and null otherwise.

Parameters:

aNode - A DOM Node.

Returns:

The TagName of the Node if it is an Element, and null otherwise.

addXmlDocumentAnnotationTo

public static void addXmlDocumentAnnotationTo(Node aNode,
                                              String formattedDocumentation)

Adds the given formattedDocumentation within an XML documentation annotation under the supplied Node. Only adds the documentation annotation if the formattedDocumentation is non-null and non-empty. The documentation annotation is on the form:

     
         <xs:annotation>
             <xs:documentation>(JavaDoc here, within a CDATA section)</xs:documentation>
         </xs:annotation>
     
 

Parameters:

aNode - The non-null Node to which an XML documentation annotation should be added.

formattedDocumentation - The documentation text to add.

getXPathFor

public static String getXPathFor(Node aNode)

Retrieves the XPath for the supplied Node within its document.

Parameters:

aNode - The DOM Node for which the XPath should be retrieved.

Returns:

The XPath to the supplied DOM Node.

getClassLocation

public static ClassLocation getClassLocation(Node aNode,
                                             Set<ClassLocation> classLocations)

Retrieves the ClassLocation for the supplied aNode.

Parameters:

aNode - A non-null DOM Node.

classLocations - The set of known ClassLocations, extracted from the JavaDocs.

Returns:

the ClassLocation matching the supplied Node

getMethodLocation

public static MethodLocation getMethodLocation(Node aNode,
                                               Set<MethodLocation> methodLocations)

Finds the MethodLocation within the given Set, which corresponds to the supplied DOM Node.

Parameters:

aNode - A DOM Node.

methodLocations - The Set of all found/known MethodLocation instances.

Returns:

The MethodLocation matching the supplied Node - or null if no match was found.

getFieldLocation

public static FieldLocation getFieldLocation(Node aNode,
                                             Set<FieldLocation> fieldLocations)

Retrieves a FieldLocation from the supplied Set, provided that the FieldLocation matches the supplied Node.

Parameters:

aNode - The non-null Node.

fieldLocations - The Set of known/found FieldLocation instances.

Returns:

The FieldLocation corresponding to the supplied DOM Node.

getFieldOrMethodLocationIfValid

public static <T extends FieldLocation> T getFieldOrMethodLocationIfValid(Node aNode,
                                                                          Node containingClassNode,
                                                                          Set<? extends FieldLocation> locations)

Retrieves a FieldLocation or MethodLocation from the supplied Set of Field- or MethodLocations, provided that the supplied Node has the given containing Node corresponding to a Class or an Enum.

Type Parameters:

T - The FieldLocation type.

Parameters:

aNode - A non-null DOM Node.

containingClassNode - A Non-null DOM Node corresponding to a Class or Enum.

locations - A Set containing known/found Field- and MethodLocations.

Returns:

The Matching Field- or MethodLocation.

insertXmlDocumentationAnnotationsFor

public static void insertXmlDocumentationAnnotationsFor(Node aNode,
                                                        SortedMap<ClassLocation,JavaDocData> classJavaDocs,
                                                        SortedMap<FieldLocation,JavaDocData> fieldJavaDocs,
                                                        SortedMap<MethodLocation,JavaDocData> methodJavaDocs,
                                                        JavaDocRenderer renderer)

Processes the supplied DOM Node, inserting XML Documentation annotations if applicable.

Parameters:

aNode - The DOM Node to process.

classJavaDocs - A Map relating ClassLocations to JavaDocData.

fieldJavaDocs - A Map relating FieldLocations to JavaDocData.

methodJavaDocs - A Map relating MethodLocations to JavaDocData.

renderer - A non-null JavaDocRenderer.