Package freemarker.ext.xml

Class NodeListModel

java.lang.Object
freemarker.ext.xml.NodeListModel
All Implemented Interfaces:
TemplateHashModel, TemplateMethodModel, TemplateModel, TemplateNodeModel, TemplateScalarModel, TemplateSequenceModel
@Deprecated public class NodeListModel extends Object implements TemplateHashModel, TemplateMethodModel, TemplateScalarModel, TemplateSequenceModel, TemplateNodeModel
Deprecated.
Use NodeModel instead.

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.

  • Constructor Details

    • 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 ClassCastExceptions when it encounters mixed objects.
      Throws:
      IllegalArgumentException - if you pass null

  • Method Details

    • 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:
      XML node hash keys
      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.
      _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"] syntax (or nodelist.prefix\:localname, or nodelist.@prefix\:localname) 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. Also note that if you do doc.elem1._registerNamespace(...), and then later you use doc.elem1 again, it will not have the prefix registered, because each time you use doc.elem1, it gives a completely new object. In this example, you certainly should have used doc._registerNamespace(...).
      _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