/* Copyright 2002-2005, 2019 Elliotte Rusty Harold
This library is free software; you can redistribute it and/or modify
it under the terms of version 2.1 of the GNU Lesser General Public
License as published by the Free Software Foundation.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the
Free Software Foundation, Inc., 59 Temple Place, Suite 330,
Boston, MA 02111-1307 USA
You can contact Elliotte Rusty Harold by sending e-mail to
elharo@ibiblio.org. Please include the word "XOM" in the
subject line. The XOM home page is located at http://www.xom.nu/
*/
package nu.xom;
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.
Author: Elliotte Rusty Harold Version: 1.3.1
/**
* <p>
* Builders use a <code>NodeFactory</code> object
* to construct each <code>Node</code> object (<code>Element</code>,
* <code>Text</code>, <code>Attribute</code>, etc.) they add to the
* tree. The default implementation simply calls the relevant
* constructor, stuffs the resulting <code>Node</code> object in a
* length one <code>Nodes</code> object, and returns it.
* </p>
*
* <p>
* Subclassing this class allows builders to produce
* instance of subclasses (for example,
* <code>HTMLElement</code>) instead of the
* base classes.
* </p>
*
* <p>
* 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
* <code>xinclude:include</code> 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 <code>makeDocType()</code> method should not
* return a list containing two <code>DocType</code> 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 <code>DocType</code>
* object.
* </p>
*
* @author Elliotte Rusty Harold
* @version 1.3.1
*
*/
public class NodeFactory {
Constructs a new node factory.
/**
* <p>
* Constructs a new node factory.
* </p>
*
*/
public NodeFactory() {}
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 a
NullPointerException
.
Params: - name – the qualified name of the element
- namespace – the namespace URI of the element
Returns: the new root element
/**
* <p>
* 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.
* </p>
*
* <p>
* Subclasses may change the name, namespace, content, or other
* characteristics of the element returned.
* The default implementation merely calls
* <code>startMakingElement</code>. 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 a
* <code>NullPointerException</code>.
* </p>
*
* @param name the qualified name of the element
* @param namespace the namespace URI of the element
*
* @return the new root element
*/
public Element makeRootElement(String name, String namespace) {
return startMakingElement(name, 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 the
Element
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 empty
Nodes
object from the
finishMakingElement()
method.
Params: - name – the qualified name of the element
- namespace – the namespace URI of the element
Returns: the new element
/**
* <p>
* Creates a new <code>Element</code> in the specified namespace
* with the specified name.
* </p>
*
* <p>
* Subclasses may change the name, namespace, content, or other
* characteristics of the <code>Element</code> returned.
* Subclasses may return null to indicate the
* <code>Element</code> 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 empty
* <code>Nodes</code> object from the
* <code>finishMakingElement()</code> method.
* </p>
*
* @param name the qualified name of the element
* @param namespace the namespace URI of the element
*
* @return the new element
*/
public Element startMakingElement(String name, String namespace) {
return new Element(name, namespace);
}
Signals the end of an element. This method should return
the Nodes
to be added to the tree.
They need not contain the Element
that
was passed to this method, though most often they will.
By default the Nodes
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 a
DocType
object unless the element is the root
element, and the document does not already have a
DocType
). 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 one
Element
object. The simplest way to check this
is testing if element.getParent() instanceof
Document
.
Do not detach element
or any of its ancestors
while inside this method. Doing so can royally muck up the
build.
Params: - element – the finished
Element
Returns: the nodes to be added to the tree
/**
* <p>
* Signals the end of an element. This method should return
* the <code>Nodes</code> to be added to the tree.
* They need not contain the <code>Element</code> that
* was passed to this method, though most often they will.
* By default the <code>Nodes</code> 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 a
* <code>DocType</code> object unless the element is the root
* element, and the document does not already have a
* <code>DocType</code>). 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.
* </p>
*
* <p>
* 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 <code>Element</code>, 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 one
* <code>Element</code> object. The simplest way to check this
* is testing if <code>element.getParent() instanceof
* Document</code>.
* </p>
*
* <p>
* Do not detach <code>element</code> or any of its ancestors
* while inside this method. Doing so can royally muck up the
* build.
* </p>
*
* @param element the finished <code>Element</code>
*
* @return the nodes to be added to the tree
*
*/
public Nodes finishMakingElement(Element element) {
return new Nodes(element);
}
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
/**
* <p>
* Creates a new <code>Document</code> object.
* The root element of this document is initially set to
* <code><root xmlns="http://www.xom.nu/fakeRoot"/></code>.
* 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.
* </p>
*
* <p>
* 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.
* </p>
*
* <p>
* 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 <code>ParsingException</code>.
* </p>
*
* @return the newly created <code>Document</code>
*/
public Document startMakingDocument() {
return new Document(
Element.build("root", "http://www.xom.nu/fakeRoot", "root")
);
}
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.
Params: - document – the completed
Document
/**
* <p>
* 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.
* </p>
*
* @param document the completed <code>Document</code>
*/
public void finishMakingDocument(Document document) {}
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. This Nodes
object may not contain any Document
objects.
All of the nodes returned must be parentless.
Subclasses may return an empty Nodes
to indicate
the attribute should not be created.
Params: - name – the prefixed name of the attribute
- URI – the namespace URI
- value – the attribute value
- type – the attribute type
Returns: the nodes to be added to the tree
/**
* <p>
* Returns a new <code>Nodes</code> object containing an
* attribute in the specified namespace
* with the specified name and type.
* </p>
*
* <p>
* Subclasses may change the nodes returned from this method.
* They may return a <code>Nodes</code> object containing any
* number of children and attributes which are appended and
* added to the current parent element. This <code>Nodes</code>
* object may not contain any <code>Document</code> objects.
* All of the nodes returned must be parentless.
* Subclasses may return an empty <code>Nodes</code> to indicate
* the attribute should not be created.
* </p>
*
* @param name the prefixed name of the attribute
* @param URI the namespace URI
* @param value the attribute value
* @param type the attribute type
*
* @return the nodes to be added to the tree
*/
public Nodes makeAttribute(String name, String URI,
String value, Attribute.Type type) {
return new Nodes(new Attribute(name, URI, value, type));
}
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. This Nodes
object should not contain any Document
objects.
All of the nodes returned must be parentless.
Subclasses may return an empty Nodes
to indicate
the comment should not be included in the
finished document.
Params: - data – the complete text content of the comment
Returns: the nodes to be added to the tree
/**
* <p>
* Returns a new <code>Nodes</code> object containing a
* comment with the specified text.
* </p>
*
* <p>
* 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 <code>Nodes</code> object containing any
* number of children and attributes which are appended and
* added to the current parent element. This <code>Nodes</code>
* object should not contain any <code>Document</code> objects.
* All of the nodes returned must be parentless.
* Subclasses may return an empty <code>Nodes</code> to indicate
* the comment should not be included in the
* finished document.
* </p>
*
* @param data the complete text content of the comment
*
* @return the nodes to be added to the tree
*/
public Nodes makeComment(String data) {
return new Nodes(new Comment(data));
}
Returns a new Nodes
object containing a
DocType
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 a Nodes
object containing
any number of comments and processing instructions which are
appended to the current parent node. This Nodes
object may not contain any Document
,
Element
, Attribute
, or
Text
objects. All of the nodes returned must be
parentless. Subclasses may return an empty Nodes
to
indicate the DocType
should not be included in the
finished document.
Params: - rootElementName – the declared, qualified name
for the root element
- publicID – the public ID of the external DTD subset
- systemID – the URL of the external DTD subset
Returns: the nodes to be added to the document
/**
* <p>
* Returns a new <code>Nodes</code> object containing a
* <code>DocType</code> object with the specified root element
* name, system ID, and public ID.
* </p>
*
* <p>
* Subclasses may change the root element name, public ID,
* system ID, or other characteristics of the <code>DocType</code>
* returned. Subclasses may change the nodes returned from this
* method. They may return a <code>Nodes</code> object containing
* any number of comments and processing instructions which are
* appended to the current parent node. This <code>Nodes</code>
* object may not contain any <code>Document</code>,
* <code>Element</code>, <code>Attribute</code>, or
* <code>Text</code> objects. All of the nodes returned must be
* parentless. Subclasses may return an empty <code>Nodes</code> to
* indicate the <code>DocType</code> should not be included in the
* finished document.
* </p>
*
* @param rootElementName the declared, qualified name
* for the root element
* @param publicID the public ID of the external DTD subset
* @param systemID the URL of the external DTD subset
*
* @return the nodes to be added to the document
*/
public Nodes makeDocType(String rootElementName,
String publicID, String systemID) {
return new Nodes(new DocType(rootElementName, publicID, systemID));
}
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. This Nodes
object must not contain any Document
nodes. All of
the nodes returned must be parentless. Subclasses may return an
empty Nodes
to indicate the text should not be
included in the finished document.
Params: - data – the complete text content of the node
Returns: the nodes to be added to the tree
/**
* <p>
* Returns a new <code>Nodes</code> object containing a
* text node with the specified content.
* </p>
*
* <p>
* 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 <code>Nodes</code>
* object containing any number of nodes which are added or
* appended to the current parent node. This <code>Nodes</code>
* object must not contain any <code>Document</code> nodes. All of
* the nodes returned must be parentless. Subclasses may return an
* empty <code>Nodes</code> to indicate the text should not be
* included in the finished document.
* </p>
*
* @param data the complete text content of the node
*
* @return the nodes to be added to the tree
*/
public Nodes makeText(String data) {
return new Nodes(new Text(data));
}
Returns a new Nodes
object containing a
CDATASection
node with the specified content.
Params: - data – the complete text content of the node
Returns: the nodes to be added to the tree
/**
* <p>
* Returns a new <code>Nodes</code> object containing a
* <code>CDATASection</code> node with the specified content.
* </p>
*
* @param data the complete text content of the node
*
* @return the nodes to be added to the tree
*/
Nodes makeCDATASection(String data) {
return makeText(data);
}
Returns a new Nodes
object containing a
new ProcessingInstruction
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 a Nodes
object containing
any number of nodes which are added or
appended to the current parent node. This Nodes
object must not contain any Document
nodes.
If the processing instruction appears in the prolog or epilog
of the document, then it must also not contain any
Element
, Attribute
, or
Text
objects.
All of the nodes returned must be parentless. Subclasses
may return an empty Nodes
to indicate the
processing instruction should not be included in the
finished document.
Params: - target – the target of the processing instruction
- data – the data of the processing instruction
Returns: the nodes to be added to the tree
/**
* <p>
* Returns a new <code>Nodes</code> object containing a
* new <code>ProcessingInstruction</code> object with
* the specified target and data.
* </p>
*
* <p>
* Subclasses may change the target, data, or other
* characteristics of the <code>ProcessingInstruction</code>
* returned. Subclasses may change the nodes returned from this
* method. They may return a <code>Nodes</code> object containing
* any number of nodes which are added or
* appended to the current parent node. This <code>Nodes</code>
* object must not contain any <code>Document</code> nodes.
* If the processing instruction appears in the prolog or epilog
* of the document, then it must also not contain any
* <code>Element</code>, <code>Attribute</code>, or
* <code>Text</code> objects.
* All of the nodes returned must be parentless. Subclasses
* may return an empty <code>Nodes</code> to indicate the
* processing instruction should not be included in the
* finished document.
* </p>
*
* @param target the target of the processing instruction
* @param data the data of the processing instruction
*
* @return the nodes to be added to the tree
*/
public Nodes makeProcessingInstruction(
String target, String data) {
return new Nodes(new ProcessingInstruction(target, data));
}
void addAttribute(Element element, Attribute attribute) {
element.addAttribute(attribute);
}
void insertChild(Element element, Node child, int position) {
element.insertChild(child, position);
}
}