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 * <p>An extended hash interface with a couple of extra hooks. If a class 57 * implements this interface, then the built-in operators <code>?size</code>, 58 * <code>?keys</code>, and <code>?values</code> can be applied to its 59 * instances in the template.</p> 60 * 61 * <p>As of version 2.2.2, the engine will automatically wrap the 62 * collections returned by <code>keys</code> and <code>values</code> to 63 * present them as sequences to the template. For performance, you may 64 * wish to return objects that implement both TemplateCollectionModel 65 * and {@link TemplateSequenceModel}. Note that the wrapping to sequence happens 66 * on demand; if the template does not try to use the variable returned by 67 * <code>?keys</code> or <code>?values</code> as sequence (<code>theKeys?size</code>, or <code>theKeys[x]</code>, 68 * or <code>theKeys?sort</code>, etc.), just iterates over the variable 69 * (<code><#list foo?keys as k>...</code>), then no wrapping to 70 * sequence will happen, thus there will be no overhead. 71 * 72 * @author <a HREF="mailto:jon@revusky.com">Jonathan Revusky</a> 73 * @see SimpleHash 74 * @version $Id: TemplateHashModelEx.java,v 1.13 2003/06/08 00:58:15 herbyderby Exp $ 75 */ 76 public interface TemplateHashModelEx extends TemplateHashModel { 77 78 /** 79 * @return the number of key/value mappings in the hash. 80 */ 81 int size() throws TemplateModelException; 82 83 /** 84 * @return a collection containing the keys in the hash. Every element of 85 * the returned collection must implement the {@link TemplateScalarModel} 86 * (as the keys of hashes are always strings). 87 */ 88 TemplateCollectionModel keys() throws TemplateModelException; 89 90 /** 91 * @return a collection containing the values in the hash. 92 */ 93 TemplateCollectionModel values() throws TemplateModelException; 94 } 95