freemarker.ext.jdom
Class NodeListModel
java.lang.Object
|
+--freemarker.ext.jdom.NodeListModel
- All Implemented Interfaces:
- TemplateCollectionModel, TemplateHashModel, TemplateMethodModel, TemplateModel, TemplateScalarModel, TemplateSequenceModel
- public class NodeListModel
- extends java.lang.Object
- implements TemplateHashModel, TemplateMethodModel, TemplateCollectionModel, TemplateSequenceModel, TemplateScalarModel
Provides a template for wrapping JDOM objects. It is capable of storing not only
a single JDOM node, but a list of JDOM nodes at once (hence the name).
Each node is an instance of any of the core JDOM node classes (except namespaces,
which are not supported at the moment), or String for representing text.
See individual method documentation for exact details on how the class works. In
short:
getAsString(java.util.Locale)
will render all contained nodes as XML fragment,
exec(List)
provides full XPath functionality implemented on top of
the werken.xpath library,
get(String)
provides node traversal, copying and filtering - somewhat
less expressive than XPath, however it does not require the external library and
it evaluates somewhat faster
TemplateCollectionModel
allows to iterate the contained node list, and
TemplateSequenceModel
allows to access the contained nodes by index.
- Version:
- 1.0
- Author:
- Attila Szegedi, szegedia@users.sourceforge.net
Constructor Summary |
NodeListModel(org.jdom.Document document)
Creates a node set template that holds a single Document node. |
NodeListModel(org.jdom.Element element)
Creates a node set template that holds a single Element node. |
NodeListModel(java.util.List nodes)
Creates a node set template that holds a list of nodes. |
NodeListModel(java.util.List nodes,
boolean copy)
Creates a node set template that holds a list of nodes. |
Method Summary |
static NodeListModel |
createNodeListModel(java.util.List list,
boolean copy)
Factory method for creating a NodeListModel that best suits the passed list. |
TemplateModel |
exec(java.util.List arguments)
Applies an XPath expression to the node set and returns the resulting node set. |
TemplateModel |
get(int i)
Retrieves the i-th element of the node set (as despite its name it really is
a list). |
TemplateModel |
get(java.lang.String key)
Provides node set traversal as well as special functions: filtering by name,
filtering by node type, shallow-copying, and duplicate removal. |
java.lang.String |
getAsString(java.util.Locale l)
This method returns the string resulting from concatenation
of string representations of its nodes. |
boolean |
isEmpty()
Returns true if this model contains no nodes. |
TemplateModelIterator |
iterator()
Retrieves a template model iterator that is used to iterate over
the elements in this collection. |
static void |
main(java.lang.String[] args)
Loads a template from a file passed as the first argument, loads an XML
document from the standard input, passes it to the template as variable
document and writes the result of template processing to
standard output. |
void |
registerNamespace(java.lang.String prefix,
java.lang.String uri)
Registers an XML namespace with this node list. |
int |
size()
|
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
NodeListModel
public NodeListModel(org.jdom.Document document)
- Creates a node set template that holds a single
Document
node.
NodeListModel
public NodeListModel(org.jdom.Element element)
- Creates a node set template that holds a single
Element
node.
NodeListModel
public NodeListModel(java.util.List nodes)
- Creates a node set template that holds a list of nodes.
- Parameters:
nodes
- the list of nodes this template should hold. The created template
will copy the passed nodes list, so changes to the passed list will not affect
the model.
NodeListModel
public NodeListModel(java.util.List nodes,
boolean copy)
- Creates a node set template that holds a list of nodes.
- Parameters:
nodes
- the list of nodes this template should hold.copy
- if true, the created template will copy the passed nodes list,
so changes to the passed list will not affect the model. If false, the model
will reference the passed list and will sense changes in it, altough no
operations on the list will be synchronized.
createNodeListModel
public static final NodeListModel createNodeListModel(java.util.List list,
boolean copy)
- Factory method for creating a NodeListModel that best suits the passed list.
- Returns:
- the singleton empty model for null or empty input list, a model backed
by a singleton collection for a single-element input list, or a generic model
backed by the passed list, or a copy of it for multiple-element input list.
isEmpty
public boolean isEmpty()
- Returns true if this model contains no nodes.
- Specified by:
isEmpty
in interface TemplateModel
- Following copied from interface:
freemarker.template.TemplateModel
- Returns:
- true if this object is empty.
getAsString
public java.lang.String getAsString(java.util.Locale l)
throws TemplateModelException
- This method returns the string resulting from concatenation
of string representations of its nodes. Each node is rendered using its XML
serialization format, while text (String) is rendered as itself. This greatly
simplifies creating XML-transformation templates, as to output a node contained
in variable x as XML fragment, you simply write ${x} in the template.
- Specified by:
getAsString
in interface TemplateScalarModel
- Parameters:
l
- unused
get
public TemplateModel get(java.lang.String key)
throws TemplateModelException
- Provides node set traversal as well as special functions: filtering by name,
filtering by node type, shallow-copying, and duplicate removal.
While not as powerful as the full XPath support built into the
exec(List)
method, it does not require the external werken.xpath
library to be present at run time. Below are listed the recognized keys.
In key descriptions, "applicable to this-and-that node type" means that if
a key is applied to a node set that contains a node of non-applicable type
a TemplateMethodModel will be thrown. However, you can use _ftype
key to explicitly filter out undesired node types prior to applying the
restricted-applicability key. Also "current nodes" means nodes contained in this
set.
- * or _children: all direct element children of current nodes (non-recursive). Applicable
to element and document nodes.
- @* or _attributes: all attributes of current nodes. Applicable to elements only.
- _content the complete content of current nodes (non-recursive).
Applicable to elements and documents.
- _text: the text of current nodes, one string per node (non-recursive).
Applicable to elements, attributes, comments, processing instructions (returns its data)
and CDATA sections. The reserved XML characters ('<' and '&') are escaped.
- _plaintext: same as _text, but does not escape any characters.
- _name: the names of current nodes, one string per node (non-recursive).
Applicable to elements, attributes, entities, processing instructions (returns its target),
doctypes (returns its public ID)
- _parent: parent elements of current nodes. Applicable to element, attribute, comment,
entity, processing instruction.
- _ancestor: all ancestors up to root element (recursive) of current nodes. Applicable
to same node types as _parent.
- _ancestorOrSelf: all ancestors of current nodes plus current nodes. Applicable
to same node types as _parent.
- _descendant: all recursive descendant element children of current nodes. Applicable to
document and element nodes.
- _descendantOrSelf: all recursive descendant element children of current nodes
plus current nodes. Applicable to document and element nodes.
- _document: all documents the current nodes belong to.
Applicable to all nodes except text.
- _doctype: doctypes of the current nodes.
Applicable to document nodes only.
- _fname: is a filter-by-name template method model. When called,
it will yield a node set that contains only those current nodes whose name
matches one of names passed as argument. Attribute names should NOT be prefixed with the
at sign (@). Applicable on all node types, however has no effect on unnamed nodes.
- _ftype: is a filter-by-type template method model. When called,
it will yield a node set that contains only those current nodes whose type matches one
of types passed as argument. You should pass a single string to this method
containing the characters of all types to keep. Valid characters are:
e (Element), a (Attribute), n (Entity), d (Document), t (DocType),
c (Comment), p (ProcessingInstruction), x (text). If the string anywhere contains
the exclamation mark (!), the filter's effect is negated.
- _type: Returns a one-character String SimpleScalar containing
the typecode of the first node in the node list. Valid characters are:
e (Element), a (Attribute), n (Entity), d (Document), t (DocType),
c (Comment), p (ProcessingInstruction), x (text). If the type of the node
is unknown, returns '?'. If the node list is empty, returns an empty string scalar.
- _unique: a copy of the current nodes that keeps only the
first occurrence of every node, eliminating duplicates. Duplicates can
occur in the node set by applying uptree-traversals _parent,
_ancestor, _ancestorOrSelf, and _document.
I.e. foo._children._parent will return a node set that has
duplicates of nodes in foo - each node will have the number of occurrences
equal to the number of its children. In these cases, use
foo._children._parent._unique to eliminate duplicates. Applicable
to all node types.
- _copy: a copy of the current node set. It is a shallow copy that
shares the underlying node list with this node set, however it has a
separate iterator, so it can be used to guarantee correct behavior of
TemplateListModel methods in multithreaded environment. However, this concern
arises only when using a shared NodeListModel instance, i.e. the one directly
bound into the TemplateModelRoot. All instances returned through
get(String)
and exec(List)
during template processing are created new, thus they
are private to the thread that processes the template and need not be copied
before they are used as a TemplateListModel. Applicable to all node types.
- _registerNamespace(prefix, uri): register a XML namespace
with the specified prefix and URI for the current node list and all node
lists that are derived from the current node list. After registering,
you can use the nodelist["prefix:localname"] or
nodelist["@prefix:localname"] syntaxes to reach elements and
attributes whose names are namespace scoped. Note that the namespace
prefix need not match the actual prefix used by the XML document itself
since namespaces are compared solely by their URI. You can also register
namespaces from Java code using the
registerNamespace(String, String)
method.
- @attributeName: named attributes of current nodes. Applicable to
elements, doctypes and processing instructions. On doctypes it supports
attributes publicId, systemId and elementName. On processing
instructions, it supports attributes target and data, as
well as any other attribute name specified in data as name="value" pair.
The attribute nodes for doctype and processing instruction are synthetic, and
as such have no parent. Note, however that @* does NOT operate on
doctypes or processing instructions.
- any other key: element children of current nodes with name matching the key.
This allows for convenience child traversal in book.chapter.title style syntax.
Note that nodeset.childname is technically equivalent to
nodeset._children._fname("childname"), but is both shorter to write
and evaluates faster. Applicable to document and element nodes.
The order of nodes in the resulting set is the order of evaluation of the key
on each node in this set from left to right. Evaluation of the key on a single
node always yields the results in "natural" order (that of the document preorder
traversal), even for uptree traversals. As a consequence, if this node set's nodes
are listed in natural order, applying any of the keys will produce a node set that
is also naturally ordered. As a special case, all node sets that are directly or
indirectly generated from a single Document or Element node through repeated
invocations of this method will be naturally ordered.
- Specified by:
get
in interface TemplateHashModel
- Parameters:
key
- a key that identifies a required set of nodes- Returns:
- a new NodeListModel that represents the requested set of nodes.
iterator
public TemplateModelIterator iterator()
- Description copied from interface:
TemplateCollectionModel
- Retrieves a template model iterator that is used to iterate over
the elements in this collection.
- Specified by:
iterator
in interface TemplateCollectionModel
get
public TemplateModel get(int i)
throws TemplateModelException
- Retrieves the i-th element of the node set (as despite its name it really is
a list).
- Specified by:
get
in interface TemplateSequenceModel
exec
public TemplateModel exec(java.util.List arguments)
throws TemplateModelException
- Applies an XPath expression to the node set and returns the resulting node set.
In order for this method to work, your application must have access
werken.xpath library classes. The
implementation does cache the parsed format of XPath expressions in a weak hash
map, keyed by the string representation of the XPath expression. As the string
object passed as the argument is usually kept in the parsed Freemarker template,
this ensures that each XPath expression is parsed only once during the lifetime
of the Freemarker template that contains it.
- Specified by:
exec
in interface TemplateMethodModel
- Parameters:
arguments
- the list of arguments. Must contain exactly one string that is
the XPath expression you wish to apply.- Returns:
- a NodeListModel representing the nodes that are the result of application
of the XPath to the current node set.
registerNamespace
public void registerNamespace(java.lang.String prefix,
java.lang.String uri)
- Registers an XML namespace with this node list. Once registered, you can
refer to the registered namespace using its prefix in the
get(String)
method from this node list and all other
node lists that are derived from this node list. Use the
nodelist["prefix:localname"] or the
nodelist["@prefix:localname"] syntax to reach elements and
attributes whose names are namespace scoped. Note that the namespace
prefix need not match the actual prefix used by the XML document itself
since namespaces are compared solely by their URI. You can also register
namespaces during template evaluation using the
nodelist._registerNamespace(prefix, uri) syntax in the template.
This mechanism is completely independent from the namespace declarations
in the XML document itself; its purpose is to give you an easy way
to refer to namespace-scoped elements in get(String)
.
main
public static void main(java.lang.String[] args)
throws java.lang.Exception
- Loads a template from a file passed as the first argument, loads an XML
document from the standard input, passes it to the template as variable
document and writes the result of template processing to
standard output.
size
public int size()
- Specified by:
size
in interface TemplateSequenceModel
- Following copied from interface:
freemarker.template.TemplateSequenceModel
- Returns:
- the number of items in the list.