freemarker.ext.xml
Class NodeListModel

java.lang.Object
  freemarker.ext.xml.NodeListModel

All Implemented Interfaces:

TemplateHashModel, TemplateMethodModel, TemplateModel, TemplateNodeModel, TemplateScalarModel, TemplateSequenceModel

Deprecated. Use NodeModel instead.

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

Field Summary

Fields inherited from interface freemarker.template.TemplateScalarModel

EMPTY_STRING

Fields inherited from interface freemarker.template.TemplateModel

NOTHING

Constructor Summary

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

Method Summary

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

Methods inherited from class java.lang.Object

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

Constructor Detail

NodeListModel

public NodeListModel(java.lang.Object nodes)

Deprecated.

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.

Throws:

java.lang.IllegalArgumentException - if you pass null

Method Detail

size

public int size()

Deprecated.

Returns the number of nodes in this model's nodelist.

Specified by:

size in interface TemplateSequenceModel

Returns:

the number of items in the list.

See Also:

TemplateSequenceModel.size()

exec

public java.lang.Object exec(java.util.List arguments)
                      throws TemplateModelException

Deprecated.

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.

Throws:

TemplateModelException

See Also:

TemplateMethodModel.exec(List)

getAsString

public java.lang.String getAsString()
                             throws TemplateModelException

Deprecated.

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

Throws:

TemplateModelException

See Also:

TemplateScalarModel.getAsString()

get

public TemplateModel get(int index)

Deprecated.

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

Returns:

the item at the specified index, or null if the index is out of bounds. Note that a null value is interpreted by FreeMarker as "variable does not exist", and accessing a missing variables is usually considered as an error in the FreeMarker Template Language, so the usage of a bad index will not remain hidden.

See Also:

TemplateSequenceModel.get(int)

get

public TemplateModel get(java.lang.String key)
                  throws TemplateModelException

Deprecated.

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 name	Evaluates to
* 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.
@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 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.
_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.
_cname	the canonical names of current nodes (namespace URI + local name), one string per node (non-recursive). Applicable to elements and attributes
_content	the complete content of current nodes, including children elements, text, entity references, and processing instructions (non-recursive). Applicable to elements and documents.
_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.
_filterType	is 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".
_name	the 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)
_nsprefix	the namespace prefixes of current nodes, one string per node (non-recursive). Applicable to elements and attributes
_nsuri	the namespace URIs of current nodes, one string per node (non-recursive). Applicable to elements and attributes
_parent	parent elements of current nodes. Applicable to element, attribute, comment, entity, processing instruction.
_qname	the 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.
_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 NOT escaped.
_type	Returns 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".
_unique	a 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 key	element 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.

Throws:

TemplateModelException

See Also:

TemplateHashModel.get(String)

isEmpty

public boolean isEmpty()

Deprecated.

Returns true if this NodeListModel contains no nodes.

Specified by:

isEmpty in interface TemplateHashModel

See Also:

TemplateHashModel.isEmpty()

registerNamespace

public void registerNamespace(java.lang.String prefix,
                              java.lang.String uri)

Deprecated.

Registers a namespace prefix-URI pair for subsequent use in get(String) as well as for use in XPath expressions.

Parameters:

prefix - the namespace prefix to use for the namespace

uri - the namespace URI that identifies the namespace.

getChildNodes

public TemplateSequenceModel getChildNodes()
                                    throws TemplateModelException

Deprecated.

Specified by:

getChildNodes in interface TemplateNodeModel

Returns:

a sequence containing this node's children. If the returned value is null or empty, this is essentially a leaf node.

Throws:

TemplateModelException

getNodeName

public java.lang.String getNodeName()
                             throws TemplateModelException

Deprecated.

Specified by:

getNodeName in interface TemplateNodeModel

Returns:

a String that is used to determine the processing routine to use. In the XML implementation, if the node is an element, it returns the element's tag name. If it is an attribute, it returns the attribute's name. It returns "@text" for text nodes, "@pi" for processing instructions, and so on.

Throws:

TemplateModelException

getNodeNamespace

public java.lang.String getNodeNamespace()
                                  throws TemplateModelException

Deprecated.

Specified by:

getNodeNamespace in interface TemplateNodeModel

Returns:

the XML namespace URI with which this node is associated. If this TemplateNodeModel implementation is not XML-related, it will almost certainly be null. Even for XML nodes, this will often be null.

Throws:

TemplateModelException

getNodeType

public java.lang.String getNodeType()
                             throws TemplateModelException

Deprecated.

Specified by:

getNodeType in interface TemplateNodeModel

Returns:

a String describing the type of node this is. In the W3C DOM, this should be "element", "text", "attribute", etc. A TemplateNodeModel implementation that models other kinds of trees could return whatever it appropriate for that application. It can be null, if you don't want to use node-types.

Throws:

TemplateModelException

getParentNode

public TemplateNodeModel getParentNode()
                                throws TemplateModelException

Deprecated.

Specified by:

getParentNode in interface TemplateNodeModel

Returns:

the parent of this node or null, in which case this node is the root of the tree.

Throws:

TemplateModelException