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.

    @Deprecated
    public class NodeListModel
    extends 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.

### Field Summary

### Fields inherited from interface freemarker.template.TemplateScalarModel

`EMPTY_STRING`

### Fields inherited from interface freemarker.template.TemplateModel

`NOTHING`

### Constructor Summary

Constructors
Constructor and Description
`NodeListModel(Object nodes)` Deprecated. Creates a new NodeListModel, wrapping the passed nodes.

### Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
`Object` `exec(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(String key)` Deprecated. Returns a new NodeListModel containing the nodes that result from applying an operator to this model's nodes.
`String` `getAsString()` Deprecated. Returns the string representation of the wrapped nodes.
`TemplateSequenceModel` `getChildNodes()` Deprecated.
`String` `getNodeName()` Deprecated.
`String` `getNodeNamespace()` Deprecated.
`String` `getNodeType()` Deprecated.
`TemplateNodeModel` `getParentNode()` Deprecated.
`boolean` `isEmpty()` Deprecated. Returns true if this NodeListModel contains no nodes.
`void` `registerNamespace(String prefix, 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(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 `ClassCastException`s when it encounters mixed objects.
Throws:
  `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 Object exec(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 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, unless the default value for that case was also specified in the template.
See Also:
  `TemplateSequenceModel.get(int)`

#### get

    public TemplateModel get(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(String prefix,
                                  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 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 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 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`