1 /* 2 * Copyright (c) 2003 The Visigoth Software Society. All rights 3 * reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 9 * 1. Redistributions of source code must retain the above copyright 10 * notice, this list of conditions and the following disclaimer. 11 * 12 * 2. Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in 14 * the documentation and/or other materials provided with the 15 * distribution. 16 * 17 * 3. The end-user documentation included with the redistribution, if 18 * any, must include the following acknowledgement: 19 * "This product includes software developed by the 20 * Visigoth Software Society (http://www.visigoths.org/)." 21 * Alternately, this acknowledgement may appear in the software itself, 22 * if and wherever such third-party acknowledgements normally appear. 23 * 24 * 4. Neither the name "FreeMarker", "Visigoth", nor any of the names of the 25 * project contributors may be used to endorse or promote products derived 26 * from this software without prior written permission. For written 27 * permission, please contact visigoths@visigoths.org. 28 * 29 * 5. Products derived from this software may not be called "FreeMarker" or "Visigoth" 30 * nor may "FreeMarker" or "Visigoth" appear in their names 31 * without prior written permission of the Visigoth Software Society. 32 * 33 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED 34 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 35 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 36 * DISCLAIMED. IN NO EVENT SHALL THE VISIGOTH SOFTWARE SOCIETY OR 37 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 38 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 39 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF 40 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 41 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 42 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 43 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 44 * SUCH DAMAGE. 45 * ==================================================================== 46 * 47 * This software consists of voluntary contributions made by many 48 * individuals on behalf of the Visigoth Software Society. For more 49 * information on the Visigoth Software Society, please see 50 * http://www.visigoths.org/ 51 */ 52 53 package freemarker.template; 54 55 /** 56 * Describes objects that are nodes in a tree. 57 * If you have a tree of objects, they can be recursively 58 * <em>visited</em> using the <#visit...> and <#recurse...> 59 * FTL directives. This API is largely based on the W3C Document Object Model 60 * (DOM) API. However, it is meant to be generally useful for describing 61 * any tree of objects that you wish to navigate using a recursive visitor 62 * design pattern. 63 * @since FreeMarker 2.3 64 * @author <a HREF="mailto:jon@revusky.com">Jonathan Revusky</a> 65 */ 66 67 public interface TemplateNodeModel extends TemplateModel { 68 69 /** 70 * @return the parent of this node or null, in which case 71 * this node is the root of the tree. 72 */ 73 TemplateNodeModel getParentNode() throws TemplateModelException; 74 75 /** 76 * @return a sequence containing this node's children. 77 * If the returned value is null or empty, this is essentially 78 * a leaf node. 79 */ 80 TemplateSequenceModel getChildNodes() throws TemplateModelException; 81 82 /** 83 * @return a String that is used to determine the processing 84 * routine to use. In the XML implementation, if the node 85 * is an element, it returns the element's tag name. If it 86 * is an attribute, it returns the attribute's name. It 87 * returns "@text" for text nodes, "@pi" for processing instructions, 88 * and so on. 89 */ 90 String getNodeName() throws TemplateModelException; 91 92 /** 93 * @return a String describing the <em>type</em> of node this is. 94 * In the W3C DOM, this should be "element", "text", "attribute", etc. 95 * A TemplateNodeModel implementation that models other kinds of 96 * trees could return whatever it appropriate for that application. It 97 * can be null, if you don't want to use node-types. 98 */ 99 String getNodeType() throws TemplateModelException; 100 101 102 /** 103 * @return the XML namespace URI with which this node is 104 * associated. If this TemplateNodeModel implementation is 105 * not XML-related, it will almost certainly be null. Even 106 * for XML nodes, this will often be null. 107 */ 108 String getNodeNamespace() throws TemplateModelException; 109 } 110