Class NodeFactory
- Object
-
- nu.xom.NodeFactory
-
public class NodeFactory extends Object
Builders use a
NodeFactory
object to construct eachNode
object (Element
,Text
,Attribute
, etc.) they add to the tree. The default implementation simply calls the relevant constructor, stuffs the resultingNode
object in a length oneNodes
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, themakeDocType()
method should not return a list containing twoDocType
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 oneDocType
object.- Version:
- 1.1d5
- Author:
- Elliotte Rusty Harold
-
-
Constructor Summary
Constructors Constructor Description NodeFactory()
Constructs a new node factory.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
finishMakingDocument(Document document)
Signals the end of a document.Nodes
finishMakingElement(Element element)
Signals the end of an element.Nodes
makeAttribute(String name, String URI, String value, Attribute.Type type)
Returns a newNodes
object containing an attribute in the specified namespace with the specified name and type.Nodes
makeComment(String data)
Returns a newNodes
object containing a comment with the specified text.Nodes
makeDocType(String rootElementName, String publicID, String systemID)
Returns a newNodes
object containing aDocType
object with the specified root element name, system ID, and public ID.Nodes
makeProcessingInstruction(String target, String data)
Returns a newNodes
object containing a newProcessingInstruction
object with the specified target and data.Element
makeRootElement(String name, String namespace)
Creates a new element in the specified namespace with the specified name.Nodes
makeText(String data)
Returns a newNodes
object containing a text node with the specified content.Document
startMakingDocument()
Creates a newDocument
object.Element
startMakingElement(String name, String namespace)
Creates a newElement
in the specified namespace with the specified name.
-
-
-
Method Detail
-
makeRootElement
public Element makeRootElement(String name, String namespace)
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
public Element startMakingElement(String name, String namespace)
Creates a new
Element
in the specified namespace with the specified name.Subclasses may change the name, namespace, content, or other characteristics of the
Element
returned. Subclasses may return null to indicate theElement
should 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 emptyNodes
object from thefinishMakingElement()
method.- Parameters:
name
- the qualified name of the elementnamespace
- the namespace URI of the element- Returns:
- the new element
-
finishMakingElement
public Nodes finishMakingElement(Element element)
Signals the end of an element. This method should return the
Nodes
to be added to the tree. They need not contain theElement
that was passed to this method, though most often they will. By default theNodes
returned 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 aDocType
object 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 oneElement
object. The simplest way to check this is testing ifelement.getParent() instanceof Document
.Do not detach
element
or 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
public Document startMakingDocument()
Creates a new
Document
object. The root element of this document is initially set to<root xmlns=http://www.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
public void finishMakingDocument(Document document)
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
public Nodes makeAttribute(String name, String URI, String value, Attribute.Type type)
Returns a new
Nodes
object 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
Nodes
object containing any number of children and attributes which are appended and added to the current parent element. ThisNodes
object may not contain anyDocument
objects. All of the nodes returned must be parentless. Subclasses may return an emptyNodes
to 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
public Nodes makeComment(String data)
Returns a new
Nodes
object 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
Nodes
object containing any number of children and attributes which are appended and added to the current parent element. ThisNodes
object should not contain anyDocument
objects. All of the nodes returned must be parentless. Subclasses may return an emptyNodes
to 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
public Nodes makeDocType(String rootElementName, String publicID, String systemID)
Returns a new
Nodes
object containing aDocType
object 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
DocType
returned. Subclasses may change the nodes returned from this method. They may return aNodes
object containing any number of comments and processing instructions which are appended to the current parent node. ThisNodes
object may not contain anyDocument
,Element
,Attribute
, orText
objects. All of the nodes returned must be parentless. Subclasses may return an emptyNodes
to indicate theDocType
should 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
public Nodes makeText(String data)
Returns a new
Nodes
object 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
Nodes
object containing any number of nodes which are added or appended to the current parent node. ThisNodes
object must not contain anyDocument
nodes. All of the nodes returned must be parentless. Subclasses may return an emptyNodes
to 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
public Nodes makeProcessingInstruction(String target, String data)
Returns a new
Nodes
object containing a newProcessingInstruction
object with the specified target and data.Subclasses may change the target, data, or other characteristics of the
ProcessingInstruction
returned. Subclasses may change the nodes returned from this method. They may return aNodes
object containing any number of nodes which are added or appended to the current parent node. ThisNodes
object must not contain anyDocument
nodes. If the processing instruction appears in the prolog or epilog of the document, then it must also not contain anyElement
,Attribute
, orText
objects. All of the nodes returned must be parentless. Subclasses may return an emptyNodes
to 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
-
-