001: /* ====================================================================
002: * Tea - Copyright (c) 1997-2000 Walt Disney Internet Group
003: * ====================================================================
004: * The Tea Software License, Version 1.1
005: *
006: * Copyright (c) 2000 Walt Disney Internet Group. All rights reserved.
007: *
008: * Redistribution and use in source and binary forms, with or without
009: * modification, are permitted provided that the following conditions
010: * are met:
011: *
012: * 1. Redistributions of source code must retain the above copyright
013: * notice, this list of conditions and the following disclaimer.
014: *
015: * 2. Redistributions in binary form must reproduce the above copyright
016: * notice, this list of conditions and the following disclaimer in
017: * the documentation and/or other materials provided with the
018: * distribution.
019: *
020: * 3. The end-user documentation included with the redistribution,
021: * if any, must include the following acknowledgment:
022: * "This product includes software developed by the
023: * Walt Disney Internet Group (http://opensource.go.com/)."
024: * Alternately, this acknowledgment may appear in the software itself,
025: * if and wherever such third-party acknowledgments normally appear.
026: *
027: * 4. The names "Tea", "TeaServlet", "Kettle", "Trove" and "BeanDoc" must
028: * not be used to endorse or promote products derived from this
029: * software without prior written permission. For written
030: * permission, please contact opensource@dig.com.
031: *
032: * 5. Products derived from this software may not be called "Tea",
033: * "TeaServlet", "Kettle" or "Trove", nor may "Tea", "TeaServlet",
034: * "Kettle", "Trove" or "BeanDoc" appear in their name, without prior
035: * written permission of the Walt Disney Internet Group.
036: *
037: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
038: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
039: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
040: * DISCLAIMED. IN NO EVENT SHALL THE WALT DISNEY INTERNET GROUP OR ITS
041: * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
042: * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
043: * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
044: * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
045: * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
046: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
047: * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
048: * ====================================================================
049: *
050: * For more information about Tea, please see http://opensource.go.com/.
051: */
052:
053: package com.go.tea.runtime;
054:
055: /******************************************************************************
056: * A block of code in a template that can be passed as a substitution to
057: * another template or to a function, must implement this interface. A
058: * function that defines its last parameter as a Substitution can receive
059: * a block of code from a template. To execute it, call substitute.
060: * <p>
061: * Substitution blocks can contain internal state information which may change
062: * when the called function returns. Therefore, Substitution objects should
063: * never be saved unless explicitly detached.
064: * <p>
065: * Functions that accept a Substitution appear to extend the template language
066: * itself. Condsider the following example, which implements a simple looping
067: * function:
068: *
069: * <pre>
070: * public void loop(int count, Substitution s) throws Exception {
071: * while (--count >= 0) {
072: * s.substitute();
073: * }
074: * }
075: * </pre>
076: *
077: * The template might invoke this function as:
078: *
079: * <pre>
080: * loop (100) {
081: * "This message is printed 100 times\n"
082: * }
083: * </pre>
084: *
085: * @author Brian S O'Neill
086: * @version
087: * <!--$$Revision:--> 15 <!-- $-->, <!--$$JustDate:--> 01/05/03 <!-- $-->
088: */
089: public interface Substitution {
090: /**
091: * Causes the code substitution block to execute against its current
092: * output receiver.
093: *
094: * @throws UnsupportedOperationException if this Substitution was detached.
095: */
096: public void substitute() throws Exception;
097:
098: /**
099: * Causes the code substitution block to execute against any context.
100: *
101: * @throws ClassCastException if context is incompatible with this
102: * substitution.
103: */
104: public void substitute(Context context) throws Exception;
105:
106: /**
107: * Returns an object that uniquely identifies this substitution block.
108: */
109: public Object getIdentifier();
110:
111: /**
112: * Returns a detached substitution that can be saved and re-used. Detaching
113: * a substitution provides greater flexibilty when implementing template
114: * output caching strategies. One thread may execute the substitution while
115: * another thread may, upon timing out, output the previously cached output
116: * from this substitution.
117: * <p>
118: * When calling substitute, a context must be provided or else an
119: * UnsupportedOperationException is thrown. In order for multiple threads
120: * to safely execute this substitution, each must have its own detached
121: * instance.
122: */
123: public Substitution detach();
124: }
|