freemarker.ext.jdom
Class NodeListModel

java.lang.Object
  freemarker.ext.jdom.NodeListModel

All Implemented Interfaces:

TemplateHashModel, TemplateIndexedModel, TemplateListModel2, TemplateMethodModel, TemplateModel, TemplateObjectModel, TemplateScalarModel, java.io.Serializable

public class NodeListModel
extends java.lang.Object
implements TemplateHashModel, TemplateMethodModel, TemplateIndexedModel, TemplateListModel2, TemplateScalarModel, TemplateObjectModel, java.io.Serializable

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() will render all contained nodes as XML fragment,
• exec(List) provides full XPath functionality implemented on top of the Jaxen 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.
• TemplateListModel2 methods simply iterate over the contained node list.

Finally, TemplateObjectModel is implemented so that operations on the node list can be performed directly.

Version:

$Id: NodeListModel.java 1159 2013-04-20 05:53:37Z run2000 $

Author:

Attila Szegedi, szegedia@users.sourceforge.net

See Also:

Serialized Form

Field Summary

static TemplateScalarModel

EMPTY_SCALAR A singleton empty scalar.

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<java.lang.String> arguments) Applies an XPath expression to the node set and returns the resulting node set.
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.Object	getAsObject() Return the underlying object to the reflection mechanism in the freemarker.ext.beans package.
java.lang.String	getAsString() This method returns the string resulting from concatenation of string representations of its nodes.
TemplateModel	getAtIndex(long i) Retrieves the i-th element of the node list.
boolean	isEmpty() Returns true if this model contains no nodes.
static void	main(java.lang.String[] args) Loads a template from a file passed as the first argument, loads an XML document from either the second argument or standard input, passes it to the template 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.
void	releaseIterator(TemplateIteratorModel iterator) Returns the used iterator to the list model.
TemplateIteratorModel	templateIterator() Retrieves an iterator to iterate over this list.

Methods inherited from class java.lang.Object

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

Field Detail

EMPTY_SCALAR

public static final TemplateScalarModel EMPTY_SCALAR

A singleton empty scalar. It is an instance of EmptyScalar.

Constructor Detail

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.

Method Detail

createNodeListModel

public static 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

Returns:

true if this object is empty, otherwise false

getAsString

public java.lang.String getAsString()
                             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

Returns:

the String value of this scalar.

Throws:

TemplateModelException

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 Jaxen 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.
• _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.

Throws:

TemplateModelException - there was a problem getting the value for the given key

getAtIndex

public TemplateModel getAtIndex(long i)
                         throws TemplateModelException

Retrieves the i-th element of the node list.

Specified by:

getAtIndex in interface TemplateIndexedModel

Parameters:

i - the index of the underlying value we're interested in

Returns:

a TemplateModel representing the value for the given index

Throws:

TemplateModelException - the value could not be determined, possibly due to an index out-of-bounds, or an otherwise undefined value

templateIterator

public TemplateIteratorModel templateIterator()
                                       throws TemplateModelException

Retrieves an iterator to iterate over this list.

Specified by:

templateIterator in interface TemplateListModel2

Returns:

an iterator to iterate over the current list.

Throws:

TemplateModelException - the next item in the list can't be retrieved, or no next item exists.

releaseIterator

public void releaseIterator(TemplateIteratorModel iterator)

Returns the used iterator to the list model.

Specified by:

releaseIterator in interface TemplateListModel2

Parameters:

iterator - the iterator to be returned to the object pool, if any

exec

public TemplateModel exec(java.util.List<java.lang.String> 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 Jaxen 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 FM-Classic template, this ensures that each XPath expression is parsed only once during the lifetime of the FM-Classic 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.

Throws:

TemplateModelException

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).

getAsObject

public java.lang.Object getAsObject()
                             throws TemplateModelException

Return the underlying object to the reflection mechanism in the freemarker.ext.beans package. Any variables, methods or properties can be called directly via reflection.

Specified by:

getAsObject in interface TemplateObjectModel

Returns:

the underlying object for this template model

Throws:

TemplateModelException - the object could not be returned

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 either the second argument or standard input, passes it to the template and writes the result of template processing to standard output.

Special variables are used within template processing to provide access to the XML document and related functions. These are:

• document -- the root of the XML document
• methods -- method models provided by the Methods model
• transforms -- transform models provided by the Transforms model

Parameters:

args - command-line arguments. The first argument should be the template to be processed, the second argument should be the XML document

Throws:

java.lang.Exception