Class NodeFactory
Builders use a NodeFactory object
to construct each Node object (Element,
Text, Attribute, etc.) they add to the
tree. The default implementation simply calls the relevant
constructor, stuffs the resulting Node object in a
length one Nodes object, and returns it.
Subclassing this class allows builders to produce
instance of subclasses (for example,
HTMLElement) instead of the
base classes.
Subclasses can also filter content while building.
For example, namespaces could be added to or changed
on all elements. Comments could be deleted. Processing
instructions can be changed into elements. An
xinclude:include element could be replaced
with the content it references. All such changes must be
consistent with the usual rules of well-formedness. For
example, the makeDocType() method should not
return a list containing two DocType objects
because an XML document can have at most one document type
declaration. Nor should it return a list containing an element,
because an element cannot appear in a document prolog. However,
it could return a list containing any number of comments and
processing instructions, and not more than one DocType
object.
- Version:
- 1.3.1
- Author:
- Elliotte Rusty Harold
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoidfinishMakingDocument(Document document) Signals the end of a document.finishMakingElement(Element element) Signals the end of an element.makeAttribute(String name, String URI, String value, Attribute.Type type) Returns a newNodesobject containing an attribute in the specified namespace with the specified name and type.makeComment(String data) Returns a newNodesobject containing a comment with the specified text.makeDocType(String rootElementName, String publicID, String systemID) Returns a newNodesobject containing aDocTypeobject with the specified root element name, system ID, and public ID.makeProcessingInstruction(String target, String data) Returns a newNodesobject containing a newProcessingInstructionobject with the specified target and data.makeRootElement(String name, String namespace) Creates a new element in the specified namespace with the specified name.Returns a newNodesobject containing a text node with the specified content.Creates a newDocumentobject.startMakingElement(String name, String namespace) Creates a newElementin the specified namespace with the specified name.
-
Constructor Details
-
NodeFactory
public NodeFactory()Constructs a new node factory.
-
-
Method Details
-
makeRootElement
Creates a new element in the specified namespace with the specified name. The builder calls this method to make the root element of the document.
Subclasses may change the name, namespace, content, or other characteristics of the element returned. The default implementation merely calls
startMakingElement. However, when subclassing, it is often useful to be able to easily distinguish between the root element and a non-root element because the root element cannot be detached. Therefore, subclasses must not return null from this method. Doing so will cause aNullPointerException.- Parameters:
name- the qualified name of the elementnamespace- the namespace URI of the element- Returns:
- the new root element
-
startMakingElement
Creates a new
Elementin the specified namespace with the specified name.Subclasses may change the name, namespace, content, or other characteristics of the
Elementreturned. Subclasses may return null to indicate theElementshould not be created. However, doing so will only remove the element's start-tag and end-tag from the result tree. Any content inside the element will be attached to the element's parent by default, unless it too is filtered. To remove an entire element, return an emptyNodesobject from thefinishMakingElement()method.- Parameters:
name- the qualified name of the elementnamespace- the namespace URI of the element- Returns:
- the new element
-
finishMakingElement
Signals the end of an element. This method should return the
Nodesto be added to the tree. They need not contain theElementthat was passed to this method, though most often they will. By default theNodesreturned contain only the built element. However, subclasses may return a list containing any number of nodes, all of which will be added to the tree at the current position in the order given by the list (subject to the usual well-formedness constraints, of course. For instance, the list should not contain aDocTypeobject unless the element is the root element, and the document does not already have aDocType). All of the nodes returned must be parentless. If this method returns an empty list, then the element (including all its contents) is not included in the finished document.To process an element at a time, override this method in a subclass so that it functions as a callback. When you're done processing the
Element, return an empty list so that it will be removed from the tree and garbage collected. Be careful not to return an empty list for the root element though. That is, when the element passed to this method is the root element, the list returned must contain exactly oneElementobject. The simplest way to check this is testing ifelement.getParent() instanceof Document.Do not detach
elementor any of its ancestors while inside this method. Doing so can royally muck up the build.- Parameters:
element- the finishedElement- Returns:
- the nodes to be added to the tree
-
startMakingDocument
Creates a new
Documentobject. The root element of this document is initially set to<root xmlns="https://xom.nu/fakeRoot"/>. This is only temporary. As soon as the real root element's start-tag is read, this element is replaced by the real root. This fake root should never be exposed.The builder calls this method at the beginning of each document, before it calls any other method in this class. Thus this is a useful place to perform per-document initialization tasks.
Subclasses may change the root element, content, or other characteristics of the document returned. However, this method must not return null or the builder will throw a
ParsingException.- Returns:
- the newly created
Document
-
finishMakingDocument
Signals the end of a document. The default implementation of this method does nothing. The builder does not call this method if an exception is thrown while building a document.
- Parameters:
document- the completedDocument
-
makeAttribute
Returns a new
Nodesobject containing an attribute in the specified namespace with the specified name and type.Subclasses may change the nodes returned from this method. They may return a
Nodesobject containing any number of children and attributes which are appended and added to the current parent element. ThisNodesobject may not contain anyDocumentobjects. All of the nodes returned must be parentless. Subclasses may return an emptyNodesto indicate the attribute should not be created.- Parameters:
name- the prefixed name of the attributeURI- the namespace URIvalue- the attribute valuetype- the attribute type- Returns:
- the nodes to be added to the tree
-
makeComment
Returns a new
Nodesobject containing a comment with the specified text.Subclasses may change the content or other characteristics of the comment returned. Subclasses may change the nodes returned from this method. They may return a
Nodesobject containing any number of children and attributes which are appended and added to the current parent element. ThisNodesobject should not contain anyDocumentobjects. All of the nodes returned must be parentless. Subclasses may return an emptyNodesto indicate the comment should not be included in the finished document.- Parameters:
data- the complete text content of the comment- Returns:
- the nodes to be added to the tree
-
makeDocType
Returns a new
Nodesobject containing aDocTypeobject with the specified root element name, system ID, and public ID.Subclasses may change the root element name, public ID, system ID, or other characteristics of the
DocTypereturned. Subclasses may change the nodes returned from this method. They may return aNodesobject containing any number of comments and processing instructions which are appended to the current parent node. ThisNodesobject may not contain anyDocument,Element,Attribute, orTextobjects. All of the nodes returned must be parentless. Subclasses may return an emptyNodesto indicate theDocTypeshould not be included in the finished document.- Parameters:
rootElementName- the declared, qualified name for the root elementpublicID- the public ID of the external DTD subsetsystemID- the URL of the external DTD subset- Returns:
- the nodes to be added to the document
-
makeText
Returns a new
Nodesobject containing a text node with the specified content.Subclasses may change the content or other characteristics of the text returned. Subclasses may also change the nodes returned from this method. They may return a
Nodesobject containing any number of nodes which are added or appended to the current parent node. ThisNodesobject must not contain anyDocumentnodes. All of the nodes returned must be parentless. Subclasses may return an emptyNodesto indicate the text should not be included in the finished document.- Parameters:
data- the complete text content of the node- Returns:
- the nodes to be added to the tree
-
makeProcessingInstruction
Returns a new
Nodesobject containing a newProcessingInstructionobject with the specified target and data.Subclasses may change the target, data, or other characteristics of the
ProcessingInstructionreturned. Subclasses may change the nodes returned from this method. They may return aNodesobject containing any number of nodes which are added or appended to the current parent node. ThisNodesobject must not contain anyDocumentnodes. If the processing instruction appears in the prolog or epilog of the document, then it must also not contain anyElement,Attribute, orTextobjects. All of the nodes returned must be parentless. Subclasses may return an emptyNodesto indicate the processing instruction should not be included in the finished document.- Parameters:
target- the target of the processing instructiondata- the data of the processing instruction- Returns:
- the nodes to be added to the tree
-