freemarker.ext.xml

Class NodeListModel

Implemented Interfaces:
TemplateHashModel, TemplateMethodModel, TemplateModel, TemplateNodeModel, TemplateScalarModel, TemplateSequenceModel

public class NodeListModel
extends java.lang.Object
implements TemplateHashModel, TemplateMethodModel, TemplateScalarModel, TemplateSequenceModel, TemplateNodeModel

A data model adapter for three widespread XML document object model representations: W3C DOM, dom4j, and JDOM. The adapter automatically recognizes the used XML object model and provides a unified interface for it toward the template. The model provides access to all XML InfoSet features of the XML document and includes XPath support if it has access to the XPath- evaluator library Jaxen. The model's philosophy (which closely follows that of XML InfoSet and XPath) is as follows: it always wraps a list of XML nodes (the "nodelist"). The list can be empty, can have a single element, or can have multiple elements. Every operation applied to the model is applied to all nodes in its nodelist. You usually start with a single- element nodelist, usually the root element node or the document node of the XML tree. Additionally, the nodes can contain String objects as a result of certain evaluations (getting the names of elements, values of attributes, etc.)

Implementation note: If you are using W3C DOM documents built by the Crimson XML parser (or you are using the built-in JDK 1.4 XML parser, which is essentially Crimson), make sure you call setNamespaceAware(true) on the javax.xml.parsers.DocumentBuilderFactory instance used for document building even when your documents don't use XML namespaces. Failing to do so, you will experience incorrect behavior when using the documents wrapped with this model.

Version:
$Id: NodeListModel.java,v 1.15 2004/01/06 17:06:43 szegedia Exp $
Author:
Attila Szegedi

Fields inherited from interface freemarker.template.TemplateModel

NOTHING

Fields inherited from interface freemarker.template.TemplateScalarModel

EMPTY_STRING

Constructor Summary

NodeListModel(Object nodes)
Creates a new NodeListModel, wrapping the passed nodes.

Method Summary

Object
exec(List arguments)
Evaluates an XPath expression on XML nodes in this model.
TemplateModel
get(String key)
Returns a new NodeListModel containing the nodes that result from applying an operator to this model's nodes.
TemplateModel
get(int index)
Selects a single node from this model's nodelist by its list index and returns a new NodeListModel containing that single node.
String
getAsString()
Returns the string representation of the wrapped nodes.
TemplateSequenceModel
getChildNodes()
String
getNodeName()
String
getNodeNamespace()
String
getNodeType()
TemplateNodeModel
getParentNode()
boolean
isEmpty()
Returns true if this NodeListModel contains no nodes.
void
registerNamespace(String prefix, String uri)
Registers a namespace prefix-URI pair for subsequent use in get(String) as well as for use in XPath expressions.
int
size()
Returns the number of nodes in this model's nodelist.

Constructor Details

NodeListModel

public NodeListModel(Object nodes)
Creates a new NodeListModel, wrapping the passed nodes.
Parameters:
nodes - you can pass it a single XML node from any supported document model, or a Java collection containing any number of nodes. Passing null is prohibited. To create an empty model, pass it an empty collection. If a collection is passed, all passed nodes must belong to the same XML object model, i.e. you can't mix JDOM and dom4j in a single instance of NodeListModel. The model itself doesn't check for this condition, as it can be time consuming, but will throw spurious ClassCastExceptions when it encounters mixed objects.

Method Details

exec

public Object exec(List arguments)
            throws TemplateModelException
Evaluates an XPath expression on XML nodes in this model.
Specified by:
exec in interface TemplateMethodModel
Parameters:
arguments - the arguments to the method invocation. Expectes exactly one argument - the XPath expression.
Returns:
a new NodeListModel with nodes selected by applying the XPath expression to this model's nodelist.

get

public TemplateModel get(String key)
            throws TemplateModelException
Returns a new NodeListModel containing the nodes that result from applying an operator to this model's nodes.
Specified by:
get in interface TemplateHashModel
Parameters:
key - the operator to apply to nodes. Available operators are:
Key nameEvaluates to
* or _childrenall direct element children of current nodes (non-recursive). Applicable to element and document nodes.
@* or _attributesall attributes of current nodes. Applicable to elements only.
@attributeNamenamed 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 on dom4j or JDOM models. 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.
_ancestorall ancestors up to root element (recursive) of current nodes. Applicable to same node types as _parent.
_ancestorOrSelfall ancestors of current nodes plus current nodes. Applicable to same node types as _parent.
_cnamethe canonical names of current nodes (namespace URI + local name), one string per node (non-recursive). Applicable to elements and attributes
_contentthe complete content of current nodes, including children elements, text, entity references, and processing instructions (non-recursive). Applicable to elements and documents.
_descendantall recursive descendant element children of current nodes. Applicable to document and element nodes.
_descendantOrSelfall recursive descendant element children of current nodes plus current nodes. Applicable to document and element nodes.
_documentall documents the current nodes belong to. Applicable to all nodes except text.
_doctypedoctypes of the current nodes. Applicable to document nodes only.
_filterTypeis a filter-by-type template method model. When called, it will yield a node list that contains only those current nodes whose type matches one of types passed as argument. You can pass as many string arguments as you want, each representing one of the types to select: "attribute", "cdata", "comment", "document", "documentType", "element", "entity", "entityReference", "namespace", "processingInstruction", or "text".
_namethe names of current nodes, one string per node (non-recursive). Applicable to elements and attributes (returns their local names), entity references, processing instructions (returns its target), doctypes (returns its public ID)
_nsprefixthe namespace prefixes of current nodes, one string per node (non-recursive). Applicable to elements and attributes
_nsurithe namespace URIs of current nodes, one string per node (non-recursive). Applicable to elements and attributes
_parentparent elements of current nodes. Applicable to element, attribute, comment, entity, processing instruction.
_qnamethe qualified names of current nodes in [namespacePrefix:]localName form, one string per node (non-recursive). Applicable to elements and attributes
_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.
_textthe 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 NOT escaped.
_typeReturns a string describing the type of nodes, one string per node. The returned values are "attribute", "cdata", "comment", "document", "documentType", "element", "entity", "entityReference", "namespace", "processingInstruction", "text", or "unknown".
_uniquea copy of the current nodes that keeps only the first occurrence of every node, eliminating duplicates. Duplicates can occur in the node list by applying uptree-traversals _parent, _ancestor, _ancestorOrSelf, and _document on a node list with multiple elements. I.e. foo._children._parent will return a node list 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.
any other keyelement children of current nodes with name matching the key. This allows for convenience child traversal in book.chapter.title style syntax. Applicable to document and element nodes.
Returns:
a new NodeListModel containing the nodes that result from applying the operator to this model's nodes.

get

public TemplateModel get(int index)
Selects a single node from this model's nodelist by its list index and returns a new NodeListModel containing that single node.
Specified by:
get in interface TemplateSequenceModel
Parameters:
index - the ordinal number of the selected node

getAsString

public String getAsString()
            throws TemplateModelException
Returns the string representation of the wrapped nodes. String objects in the nodelist are rendered as-is (with no XML escaping applied). All other nodes are rendered in the default XML serialization format ("plain XML"). This makes the model quite suited for use as an XML-transformation tool.
Specified by:
getAsString in interface TemplateScalarModel
Returns:
the string representation of the wrapped nodes. String objects in the nodelist are rendered as-is (with no XML escaping applied). All other nodes are rendered in the default XML serialization format ("plain XML").

getChildNodes

public TemplateSequenceModel getChildNodes()
            throws TemplateModelException
Specified by:
getChildNodes in interface TemplateNodeModel

getNodeName

public String getNodeName()
            throws TemplateModelException
Specified by:
getNodeName in interface TemplateNodeModel

getNodeNamespace

public String getNodeNamespace()
            throws TemplateModelException
Specified by:
getNodeNamespace in interface TemplateNodeModel

getNodeType

public String getNodeType()
            throws TemplateModelException
Specified by:
getNodeType in interface TemplateNodeModel

getParentNode

public TemplateNodeModel getParentNode()
            throws TemplateModelException
Specified by:
getParentNode in interface TemplateNodeModel

isEmpty

public boolean isEmpty()
Returns true if this NodeListModel contains no nodes.
Specified by:
isEmpty in interface TemplateHashModel

registerNamespace

public void registerNamespace(String prefix,
                              String uri)
Parameters:
prefix - the namespace prefix to use for the namespace
uri - the namespace URI that identifies the namespace.

size

public int size()
Returns the number of nodes in this model's nodelist.
Specified by:
size in interface TemplateSequenceModel