0001: /*
0002: * Copyright 2001-2007 Geert Bevin <gbevin[remove] at uwyn dot com>
0003: * Distributed under the terms of either:
0004: * - the common development and distribution license (CDDL), v1.0; or
0005: * - the GNU Lesser General Public License, v2.1 or later
0006: * $Id: Template.java 3643 2007-01-12 15:29:45Z gbevin $
0007: */
0008: package com.uwyn.rife.template;
0009:
0010: import java.io.IOException;
0011: import java.io.OutputStream;
0012: import java.net.URL;
0013: import java.text.NumberFormat;
0014: import java.util.Collection;
0015: import java.util.List;
0016: import java.util.Map;
0017: import java.util.ResourceBundle;
0018:
0019: import com.uwyn.rife.config.Config;
0020: import com.uwyn.rife.template.exceptions.TemplateException;
0021:
0022: /**
0023: * A template is used to construct, manipulate and produce text content.
0024: * <p>Templates can be used for a variety of text types, including XHTML,
0025: * plain text, XML, SQL and even Java source. Each template type has similar
0026: * features, the biggest difference is the syntax of the invisible tag which
0027: * takes the form of a comment in the corresponding language (<code><!--
0028: * --> </code>for XHTML and XML, <code>/* -* /</code> for Java and SQL,
0029: * ...).
0030: * <h2>Using templates</h2>
0031: * <p>Templates are most commonly used to produce web pages, which is why a
0032: * method like {@link com.uwyn.rife.engine.Element#getXhtmlTemplate(String)} is used. By obtaining
0033: * a template instance from the active {@link com.uwyn.rife.engine.Element}, features that are
0034: * related to the web engine are added. To print a template for page output,
0035: * {@link com.uwyn.rife.engine.Element#print(Template)} is usually used. However, the content of
0036: * any template instance can be retrieved with the {@link #getContent} method
0037: * which produces a regular <code>String</code> that is usable anywhere.
0038: * <h2>Components of a template</h2>
0039: * <p>Templates are controlled by external code (usually a {@linkplain
0040: * com.uwyn.rife.engine.ElementSupport RIFE element}), but communication is bidirectional between a
0041: * template and the logic that controls it. A template can provide content to
0042: * the controller through <em>blocks</em>, and the controller can insert or
0043: * replace text in the template through <em>template values</em>. The
0044: * controller can also provide the template with <em>expression variables</em>
0045: * and <em>resource bundles</em>.
0046: * <h3>Values</h3>
0047: * <p>A value is the simplest concept in a template. It is the placeholder for
0048: * text somewhere in a block or in the page itself. In a HTML template, a
0049: * value called "<code>name</code>" is created using a declaration like:
0050: * <pre><code><!--!V 'name'/--></code></pre>
0051: * <p>The controller can then fill this value with any of the {@link
0052: * #setValue(String, String) setValue} and {@link #appendValue(String, String)
0053: * appendValue} methods.
0054: * <p>Values are mainly a one-way communication channel from the logic to the
0055: * template. However, values may contain a default value which can be
0056: * {@linkplain #getDefaultValue read} by the controller:
0057: * <pre><!--V 'name'-->Some default<!--/V--></pre>
0058: * <p>Values are automatically filled in many ways aside from calling {@link
0059: * #setValue} and {@link #appendValue} directly. We will discuss this later.
0060: * <h3>Blocks</h3>
0061: * <p>Blocks represent the other direction of communication between a
0062: * controller and a template. A HTML template can define a block called "<code>greeting</code>"
0063: * like this:
0064: * <pre><!--B 'greeting'-->Welcome, <!--V 'name'/--><!--/B--></pre>
0065: * <p>The literal text in the block is not accessible by the controller. It is
0066: * evaluated when the block is used. For example by {@linkplain #getBlock
0067: * reading it from the controller}, {@linkplain #setBlock assigning it to a
0068: * value} or {@linkplain #appendBlock appending it to a value} in the template
0069: * itself. The evaluation is based on the values that are currently present in
0070: * the template. If a block contains a value that hasn't been set yet, the
0071: * value placeholder will be remembered, unpopulated. It will be evaluated
0072: * against another value context the next time the content of the block is
0073: * used.
0074: * <p>As soon as value placeholders exist when a block is used, they are
0075: * captured from the template and replaced with their available content. They
0076: * will become immutable in the result of the operation that used the block.
0077: * This means that repeated calls to {@link #appendBlock} can append a block
0078: * to a value multiple times with different values each time. This feature
0079: * allows blocks to be used for producing repeating constructs such as tables,
0080: * using a pattern like this:
0081: * <pre>template.removeValue("people", "");
0082: *Iterator it = people.iterator();
0083: *while (it.hasNext()) {
0084: * Person person = (Person)it.next();
0085: * template.setValue("name", person.getName());
0086: * template.setValue("age", person.getAge());
0087: * template.appendBlock("people", "person");
0088: *}</pre>
0089: * <p>Nested loops and corresponding nested blocks may be used to produce more
0090: * complex constructs.
0091: * <h3>Expressions</h3>
0092: * <p>Templates may contain small boolean expressions that are written in JVM
0093: * scripting languages like OGNL, Groovy, or Janino. These expressions will be
0094: * automatically evaluated and allow certain blocks to be assigned
0095: * automatically to a value according to the scripted conditions. The
0096: * controller does not execute the scripts itself, but it may provide
0097: * variables to which the scripts have access, using the {@link
0098: * #setExpressionVar setExpressionVar} method. For example, if a template
0099: * contains:
0100: * <pre><!--V 'GROOVY:welcome'--><!--/V-->
0101: *<!--V 'GROOVY:welcome:[[ showWelcome ]]'-->Welcome,
0102: *<!--V 'name'/--><!--/V--></pre>
0103: * <p>A controller could decide whether the welcome block should be shown
0104: * using:
0105: * <pre>template.setExpressionVar("showWelcome", person != null);</pre>
0106: * <p>Apart from the expression variables, each expression is evaluated
0107: * against a current root object whose methods and properties you can access
0108: * using the regular scripting language syntax. This root object is by default
0109: * the template instance that you are processing.
0110: * <p>To make it easy to write expressions against commonly used contexts,
0111: * RIFE also provides specialized scripted tags that set different root
0112: * objects. Currently the <code>language:ROLEUSER</code> and
0113: * <code>language:CONFIG</code> tags are provided.
0114: * <h3>Localization</h3>
0115: * <p>It's possible to easily localize templates through the standard {@link
0116: * ResourceBundle} mechanism that is available in Java. The strings that are
0117: * localized are automatically filtered and replace values tags. The format
0118: * for localized values is:
0119: * <pre><!--V 'L10N:key'-->default value<!--/V--></pre>
0120: * <p>Of course, before replacement, the template instance has to know where
0121: * to look for the key. Therefore, the {@link
0122: * #addResourceBundle(ResourceBundle)} method needs to be called to make the
0123: * template aware of it.
0124: * <p>For example, consider the following resource bundles:
0125: * <p><b>text_nl.properties</b>
0126: * <pre>hello = Hallo</pre>
0127: * <p><b>text_fr.properties</b>
0128: * <pre>hello = Bonjour</pre>
0129: * <p>and the following template:
0130: * <pre>Hey mister, I said: <!--V 'L10N:hello'/-->!"</pre>
0131: * <p>The following Java code:
0132: * <pre>Template template_html = TemplateFactory.HTML.get("text");
0133: *ResourceBundle bundle = Localization.getResourceBundle("text", "fr");
0134: *template_html.addResourceBundle(bundle);
0135: *System.out.println(template.getContent());</pre>
0136: * <p>will output:
0137: * <pre>Hey mister, I said: "Bonjour!"</pre>
0138: * <p>Just replacing the second line with the following:
0139: * <pre>...
0140: *ResourceBundle bundle = Localization.getResourceBundle("text", "nl");
0141: *...</pre>
0142: * <p>will output:
0143: * <pre>Hey mister, I said: "Hallo!"</pre>
0144: * <p>Very often, resourcebundle are used for the whole application.
0145: * Therefore, application-wide default resource bundles can be specified for
0146: * each template type through the {@link com.uwyn.rife.config RIFE
0147: * configuration}, for example:
0148: * <pre><list name="TEMPLATE_DEFAULT_RESOURCEBUNDLES_ENGINEHTML">
0149: * <item>l10n/graphics</item>
0150: * <item>l10n/text</item>
0151: * <item>l10n/descriptions</item>
0152: *</list></pre>
0153: * <p>This will automatically add these resourcebundles to any template
0154: * instance of the corresponding type, calling {@link
0155: * #addResourceBundle(ResourceBundle)} is thus not needed anymore and
0156: * localization will happen without any intervention from the controller.
0157: * <p>While resource bundles offer a good method to isolate localized text
0158: * snippets, it's sometimes interesting to be able to conditionally display
0159: * parts of templates with lots of markup. For this purpose, resource bundles
0160: * are actually awkward to use. Templates are therefore able to set blocks
0161: * automatically to values, according to the default localization language (<code>L10N_DEFAULT_LANGUAGE</code>
0162: * configuration parameter). This can be done with the <code><!--B
0163: * 'LANG:id:language'--></code> block syntax.
0164: * <p>For example:
0165: * <pre><!--V 'LANG:value1'-->default<!--/V--> [!V 'LANG:value2'/]
0166: *<!--B 'LANG:value1:nl'-->ja ja<!--/B-->
0167: *[!B 'LANG:value2:fr']oui oui[!/B]
0168: *[!B 'LANG:value2:en ']yes yes[!/B]</pre>
0169: * <p>will display this when the default language is '<code>en</code>':
0170: * <pre>default yes yes</pre>
0171: * <p>or this when the default language is '<code>fr</code>':
0172: * <pre>default oui oui</pre>
0173: * <p>or this when the default language is '<code>nl</code>':
0174: * <pre>ja ja [!V 'LANG:value2'/]</pre>
0175: * <h3>Value renderers</h3>
0176: * <p>Besides the main manipulation logic of a template, value content needs
0177: * to be sometimes created that is solely presentation related. This doesn't
0178: * actually have its place in elements and sometimes even creates a burden.
0179: * For these purposes, we created the {@link ValueRenderer} interface. Classes
0180: * that implement this interface can be specified in any template like this:
0181: * <pre><!--V 'RENDER:pakkage.classname'/--></pre>
0182: * <p>An instance of the class will be created and the {@link
0183: * ValueRenderer#render} method will be called if the value hasn't been set
0184: * yet. This has as side-effect that if you have several occurances of this
0185: * value ID, they will all have the same renderer value and the renderer will
0186: * only be called once.
0187: * <p>If you need to have different results of the same renderer, you need to
0188: * use a differentiator, like this:
0189: * <pre><!--V 'RENDER:pakkage.classname:differentiator'/--></pre>
0190: * <h3>Encoding</h3>
0191: * <p>Templates automatically encode values to the appropriate format (HTML,
0192: * XHTML, etc.) when using forms, {@linkplain #evaluateConfigTags
0193: * configuration tags}, localization tags, and when {@linkplain
0194: * #setBean(Object, String, boolean) setting values from bean properties}.
0195: * However, in many cases it is necessary to encode values manually, to
0196: * prevent malicious content from being inserted into your site, or simply to
0197: * display text correctly if it may contain illegal characters (like
0198: * <code><</code> in HTML). You can encode text using the template's
0199: * encoder after calling the {@link #getEncoder} method.
0200: * <h2>Other features</h2>
0201: * <p>Templates are powerful and some features are not described here. The <a
0202: * href="http://rifers.org/wiki/display/RIFE/Templates">Templates</a> wiki
0203: * page describes several other features, including filtered values,
0204: * alternative means of localization, and other forms of templates.
0205: *
0206: * @author Keith Lea <keith[remove] at cs dot oswego dot edu>
0207: * @author Geert Bevin (gbevin[remove] at uwyn dot com)
0208: * @version $Revision: 3643 $
0209: * @since 1.0
0210: */
0211: public interface Template extends Cloneable {
0212: /**
0213: * Appends the content of a block to a value. The values used by the block
0214: * will be captured when this method is called, so any future changes to
0215: * template values will not affect text which was appended when this
0216: * method is called.
0217: *
0218: * @param valueId the ID of the value
0219: * @param blockId the ID of the block
0220: * @exception TemplateException when the <code>valueId</code> or
0221: * <code>blockId</code> aren't known
0222: * @see #setBlock
0223: * @see #getBlock
0224: * @see #getContent
0225: * @see #hasBlock
0226: * @since 1.0
0227: */
0228: public void appendBlock(String valueId, String blockId)
0229: throws TemplateException;
0230:
0231: /**
0232: * Replaces the specified value with the content of the specified block.
0233: * The values used by the block will be captured when this method is
0234: * called, so any future changes to template values will not affect the
0235: * specified value text.
0236: *
0237: * @param valueId the ID of the value
0238: * @param blockId the ID of the block
0239: * @exception TemplateException when the <code>valueId</code> or
0240: * <code>blockId</code> aren't known
0241: * @see #appendBlock
0242: * @see #getBlock
0243: * @see #getContent
0244: * @see #hasBlock
0245: * @since 1.0
0246: */
0247: public void setBlock(String valueId, String blockId)
0248: throws TemplateException;
0249:
0250: /**
0251: * Returns the evaluated content of the specified block as a text.
0252: *
0253: * @param id the ID of the block in the template
0254: * @return the evaluated textual content of the specified block
0255: * @exception TemplateException when the block ID isn't known
0256: * @see #appendBlock
0257: * @see #setBlock
0258: * @see #getContent
0259: * @see #hasBlock
0260: * @since 1.0
0261: */
0262: public String getBlock(String id) throws TemplateException;
0263:
0264: /**
0265: * Returns the entire content of the template and finalize all non
0266: * evaluated values. The content is the root block with has an empty
0267: * string as identifier.
0268: * <p>Values without content will either use their default value if it has
0269: * been provided, or the tag that was used to declare the value will be
0270: * output as-is.
0271: * <p>All specialized tags will also be evaluated (resourcebundle
0272: * localization, block localization, value renderers, expressions, ...).
0273: *
0274: * @return the entire textual content of the template
0275: * @exception TemplateException when an error occurred during the
0276: * processing of the specialized tags
0277: * @see #appendBlock
0278: * @see #setBlock
0279: * @see #getBlock
0280: * @see #hasBlock
0281: * @since 1.0
0282: */
0283: public String getContent() throws TemplateException;
0284:
0285: /**
0286: * Writes the {@linkplain #getBlock(String) evaluated contents} of the
0287: * specified block to the given output stream, using <code>UTF-8</code>
0288: * encoding.
0289: *
0290: * @param id the ID of the block
0291: * @param out the stream to write to
0292: * @exception IOException when errors occur during the manipulation of the
0293: * output stream
0294: * @exception TemplateException when the block ID isn't known
0295: * @see #writeContent(OutputStream)
0296: * @see #writeContent(OutputStream, String)
0297: * @see #write
0298: * @since 1.0
0299: */
0300: public void writeBlock(String id, OutputStream out)
0301: throws IOException, TemplateException;
0302:
0303: /**
0304: * Writes the {@linkplain #getContent() complete evaluated template
0305: * content} to the given stream, using UTF-8 encoding.
0306: *
0307: * @param out the stream to which the template contents should be written
0308: * @exception IOException when errors occur during the manipulation of the
0309: * output stream
0310: * @exception TemplateException when an error occurs during the template
0311: * content evaluation
0312: * @see #writeBlock
0313: * @see #writeContent(OutputStream, String)
0314: * @see #write
0315: * @since 1.0
0316: */
0317: public void writeContent(OutputStream out) throws IOException,
0318: TemplateException;
0319:
0320: /**
0321: * Writes the {@linkplain #getContent() complete evaluated template
0322: * content} to the given stream, using the specified charset for encoding.
0323: *
0324: * @param out the stream to which the template contents should be written
0325: * @param charsetName the name of the charset to use
0326: * @exception IOException when errors occur during the manipulation of the
0327: * output stream; or
0328: * <p>when the character set isn't valid
0329: * @exception TemplateException when an error occurs during the template
0330: * content evaluation
0331: * @see #writeBlock
0332: * @see #writeContent(OutputStream)
0333: * @see #write
0334: * @since 1.0
0335: */
0336:
0337: public void writeContent(OutputStream out, String charsetName)
0338: throws IOException, TemplateException;
0339:
0340: /**
0341: * This method is a shorthand for {@link #writeContent(OutputStream)}.
0342: *
0343: * @param out the stream to which the template contents should be written
0344: * @exception IOException when errors occur during the manipulation of the
0345: * output stream; or
0346: * <p>when the character set isn't valid
0347: * @exception TemplateException when an error occurs during the template
0348: * content evaluation
0349: * @see #writeBlock
0350: * @see #writeContent(OutputStream)
0351: * @see #writeContent(OutputStream, String)
0352: * @since 1.0
0353: */
0354: public void write(OutputStream out) throws IOException,
0355: TemplateException;
0356:
0357: /**
0358: * Returns the content of the specified block as a list with all the
0359: * individual parts.
0360: * <p>This list is the internal representation of all content with
0361: * placeholders for the values that aren't filled in yet. This structure
0362: * is mainly used internally by the framework. The list structure also
0363: * makes it possible to optimize performance and memory usage.
0364: *
0365: * @param id the ID of a block in this template
0366: * @return a list of the contents of the specified block
0367: * @exception TemplateException if no such block exists; or
0368: * <p>if an error occurred during the retrieval
0369: * @see #getDeferredContent
0370: * @since 1.0
0371: */
0372: public List<CharSequence> getDeferredBlock(String id)
0373: throws TemplateException;
0374:
0375: /**
0376: * Returns the content of this template as a list with all the individual
0377: * parts.
0378: * <p>This list is the internal representation of all content with
0379: * placeholders for the values that aren't filled in yet. This structure
0380: * is mainly used internally by the framework. The list structure also
0381: * makes it possible to optimize performance and memory usage.
0382: *
0383: * @return a list of the contents of this template
0384: * @exception TemplateException if an error occurred during the retrieval
0385: * @see #getDeferredBlock
0386: * @since 1.0
0387: */
0388: public List<CharSequence> getDeferredContent()
0389: throws TemplateException;
0390:
0391: /**
0392: * Returns an anonymous value that can be used to construct complex
0393: * content for use within this template. See {@link InternalValue} for
0394: * details.
0395: * <p>The returned internal value is tied closely to the template it was
0396: * obtained from, methods like {@link InternalValue#appendBlock(String)
0397: * InternalValue.appendBlock} reference blocks within this template.
0398: *
0399: * @return a new internal value instance for constructing more complex
0400: * parts of this template
0401: * @see InternalValue
0402: * @since 1.0
0403: */
0404: public InternalValue createInternalValue();
0405:
0406: /**
0407: * Sets the specified value in this template to content that's structured
0408: * in the internal format.
0409: *
0410: * @param id the ID of the value in this template
0411: * @param deferredContent content in the internal format
0412: * @exception TemplateException if the specified value ID does not exist
0413: * in this template
0414: * @see #appendValue
0415: * @see #isValueSet
0416: * @see #removeValue
0417: * @see #removeValues
0418: * @see #blankValue
0419: * @see #hasValueId
0420: * @since 1.0
0421: */
0422: public void setValue(String id, List<CharSequence> deferredContent)
0423: throws TemplateException;
0424:
0425: /**
0426: * Sets the specified value in this template to the value of the given
0427: * {@linkplain #createInternalValue() internal value}.
0428: *
0429: * @param id the ID of the value in this template
0430: * @param internalValue an internal value, <code>null</code> set the value
0431: * content to blank content
0432: * @exception TemplateException if the specified value ID does not exist
0433: * in this template
0434: * @see #appendValue
0435: * @see #isValueSet
0436: * @see #removeValue
0437: * @see #removeValues
0438: * @see #blankValue
0439: * @see #hasValueId
0440: * @since 1.0
0441: */
0442: public void setValue(String id, InternalValue internalValue)
0443: throws TemplateException;
0444:
0445: /**
0446: * Sets the specified value in this template to the result of calling
0447: * {@link String#valueOf(Object) String.valueOf} on the given
0448: * <code>value</code>.
0449: *
0450: * @param id the ID of the value in this template
0451: * @param value an object
0452: * @exception TemplateException if the specified value ID does not exist
0453: * in this template
0454: * @see #appendValue
0455: * @see #isValueSet
0456: * @see #removeValue
0457: * @see #removeValues
0458: * @see #blankValue
0459: * @see #hasValueId
0460: * @since 1.0
0461: */
0462: public void setValue(String id, Object value)
0463: throws TemplateException;
0464:
0465: /**
0466: * Sets the specified value in this template to <code>true</code> or
0467: * <code>false</code> depending on the given <code>value</code>.
0468: *
0469: * @param id the ID of the value in this template
0470: * @param value a boolean value
0471: * @exception TemplateException if the specified value ID does not exist
0472: * in this template
0473: * @see #appendValue
0474: * @see #isValueSet
0475: * @see #removeValue
0476: * @see #removeValues
0477: * @see #blankValue
0478: * @see #hasValueId
0479: * @since 1.0
0480: */
0481: public void setValue(String id, boolean value)
0482: throws TemplateException;
0483:
0484: /**
0485: * Sets the specified value in this template to the single specified
0486: * character.
0487: *
0488: * @param id the ID of the value in this template
0489: * @param value a character
0490: * @exception TemplateException if the specified value ID does not exist
0491: * in this template
0492: * @see #appendValue
0493: * @see #isValueSet
0494: * @see #removeValue
0495: * @see #removeValues
0496: * @see #blankValue
0497: * @see #hasValueId
0498: * @since 1.0
0499: */
0500: public void setValue(String id, char value)
0501: throws TemplateException;
0502:
0503: /**
0504: * Sets the specified value in this template to the given characters. The
0505: * given value must not be <code>null</code>.
0506: *
0507: * @param id the ID of the value in this template
0508: * @param value a string of characters
0509: * @exception TemplateException if the specified value ID does not exist
0510: * in this template
0511: * @see #appendValue
0512: * @see #isValueSet
0513: * @see #removeValue
0514: * @see #removeValues
0515: * @see #blankValue
0516: * @see #hasValueId
0517: * @since 1.0
0518: */
0519: public void setValue(String id, char[] value)
0520: throws TemplateException;
0521:
0522: /**
0523: * Sets the specified value in this template to the specified range of the
0524: * given character string. The specified number of bytes from
0525: * <code>value</code> will be used, starting at the character specified by
0526: * <code>offset</code>.
0527: *
0528: * @param id the ID of the value in this template
0529: * @param value a character string
0530: * @param offset the index in <code>value</code> of the first character to
0531: * use
0532: * @param count the number of characters to use
0533: * @exception TemplateException if the specified value ID does not exist
0534: * in this template
0535: * @see #appendValue
0536: * @see #isValueSet
0537: * @see #removeValue
0538: * @see #removeValues
0539: * @see #blankValue
0540: * @see #hasValueId
0541: * @since 1.0
0542: */
0543: public void setValue(String id, char[] value, int offset, int count)
0544: throws TemplateException;
0545:
0546: /**
0547: * Sets the specified value in this template to the given double precision
0548: * floating point value. This method uses the {@linkplain
0549: * String#valueOf(double) String.valueOf} method to print the given value,
0550: * which probably prints more digits than you like. You probably want
0551: * {@link String#format String.format} or {@link NumberFormat} instead.
0552: *
0553: * @param id the ID of the value in this template
0554: * @param value a floating point value
0555: * @exception TemplateException if the specified value ID does not exist
0556: * in this template
0557: * @see #appendValue
0558: * @see #isValueSet
0559: * @see #removeValue
0560: *
0561: * @see #blankValue
0562: * @see #hasValueId
0563: * @since 1.0
0564: */
0565: public void setValue(String id, double value)
0566: throws TemplateException;
0567:
0568: /**
0569: * Sets the specified value in this template to the given floating point
0570: * value. This method uses the {@linkplain String#valueOf(float)
0571: * String.valueOf} method to print the given value, which probably prints
0572: * more digits than you like. You probably want {@link String#format
0573: * String.format} or {@link NumberFormat} instead.
0574: *
0575: * @param id the ID of the value in this template
0576: * @param value a floating point value
0577: * @exception TemplateException if the specified value ID does not exist
0578: * in this template
0579: * @see #appendValue
0580: * @see #isValueSet
0581: * @see #removeValue
0582: * @see #blankValue
0583: * @see #hasValueId
0584: * @since 1.0
0585: */
0586: public void setValue(String id, float value)
0587: throws TemplateException;
0588:
0589: /**
0590: * Sets the specified value in this template to the given integer.
0591: *
0592: * @param id the ID of the value in this template
0593: * @param value an integer
0594: * @exception TemplateException if the specified value does not exist in
0595: * this template
0596: * @see #appendValue
0597: * @see #isValueSet
0598: * @see #removeValue
0599: * @see #removeValues
0600: * @see #blankValue
0601: * @see #hasValueId
0602: * @since 1.0
0603: */
0604: public void setValue(String id, int value) throws TemplateException;
0605:
0606: /**
0607: * Sets the specified value in this template to the given long.
0608: *
0609: * @param id the ID of the value in this template
0610: * @param value a long
0611: * @exception TemplateException if the specified value ID does not exist
0612: * in this template
0613: * @see #appendValue
0614: * @see #isValueSet
0615: * @see #removeValue
0616: * @see #removeValues
0617: * @see #blankValue
0618: * @see #hasValueId
0619: * @since 1.0
0620: */
0621: public void setValue(String id, long value)
0622: throws TemplateException;
0623:
0624: /**
0625: * Sets the specified value in this template to the given string, or an
0626: * empty string if <code>value</code> is <code>null</code>.
0627: *
0628: * @param id the ID of the value in this template
0629: * @param value a string, or <code>null</code>
0630: * @exception TemplateException if the specified value ID does not exist
0631: * in this template
0632: * @see #appendValue
0633: * @see #isValueSet
0634: * @see #removeValue
0635: * @see #removeValues
0636: * @see #blankValue
0637: * @see #hasValueId
0638: * @since 1.0
0639: */
0640: public void setValue(String id, String value)
0641: throws TemplateException;
0642:
0643: /**
0644: * Sets the specified value in this template to the given character sequence,
0645: * or an empty character sequence if <code>value</code> is <code>null</code>.
0646: *
0647: * @param id the ID of the value in this template
0648: * @param value a character sequence, or <code>null</code>
0649: * @exception TemplateException if the specified value ID does not exist
0650: * in this template
0651: * @see #appendValue
0652: * @see #isValueSet
0653: * @see #removeValue
0654: * @see #removeValues
0655: * @see #blankValue
0656: * @see #hasValueId
0657: * @since 1.5
0658: */
0659: public void setValue(String id, CharSequence value)
0660: throws TemplateException;
0661:
0662: /**
0663: * Sets the specified value in this template to the current {@linkplain
0664: * #getContent() content} of the given template. The given template's
0665: * value will be evaluated immediately, instead of being stored to be
0666: * evaluated later.
0667: * <p>If the given template is <code>null</code>, the specified value will
0668: * be set to an empty string.
0669: *
0670: * @param id the ID of the value in this template
0671: * @param template a template
0672: * @exception TemplateException if the specified value ID does not exist
0673: * in this template; or
0674: * <p>if an error occurred during the evaluation of the template parameter
0675: * @see #appendValue
0676: * @see #isValueSet
0677: * @see #removeValue
0678: * @see #removeValues
0679: * @see #blankValue
0680: * @see #hasValueId
0681: * @since 1.0
0682: */
0683: public void setValue(String id, Template template)
0684: throws TemplateException;
0685:
0686: /**
0687: * Sets all values in this template whose identifiers match names of
0688: * properties in the given bean.
0689: * <p>For example, given a class:
0690: * <pre>
0691: * class Person {
0692: * private String first;
0693: * private String last;
0694: *
0695: * public String getFirstName() { return first; }
0696: * public void setFirstName(String name) { this.first = name; }
0697: *
0698: * public String getLastName() { return last; }
0699: * public void setLastName(String name) { this.last = name; }
0700: * </pre>
0701: * <p>And given a template:
0702: * <pre>
0703: * Hello <!--V 'firstName'/--> <!--V 'lastName'/-->.
0704: * </pre>
0705: * <p>Calling this method with an instance of Person where
0706: * <code>first</code> was "Jim" and <code>last</code> was "James", would
0707: * produce:
0708: * <pre>Hello Jim James.</pre>
0709: * <p>Calling this method is equivalent to calling {@link
0710: * #setValue(String, String) setValue} individually for each property of
0711: * the bean.
0712: * <p>This method uses this template's {@linkplain #getEncoder encoder} to
0713: * encode the bean properties before setting the values. To prevent this,
0714: * use {@linkplain #setBean(Object, String, boolean) the other form of
0715: * setBean}.
0716: * <p>Only <em>bean properties</em> will be considered for insertion in
0717: * the template. This means only properties with a <em>getter and a setter</em>
0718: * will be considered.
0719: *
0720: * @param bean a bean whose properties will be used to fill in values in
0721: * the template
0722: * @exception TemplateException if this template has no bean handling
0723: * capability; or
0724: * <p>an error occurred during the introspection of the bean
0725: * @see #removeBean
0726: * @since 1.0
0727: */
0728: public void setBean(Object bean) throws TemplateException;
0729:
0730: /**
0731: * Sets all values in this template whose names match names of properties
0732: * in the given bean, preceded by the given prefix.
0733: * <p>For example, given a class:
0734: * <pre>
0735: * class Person {
0736: * private String first;
0737: * private String last;
0738: *
0739: * public String getFirstName() { return first; }
0740: * public void setFirstName(String name) { this.first = name; }
0741: *
0742: * public String getLastName() { return last; }
0743: * public void setLastName(String name) { this.last = name; }
0744: * </pre>
0745: * <p>And given a template:
0746: * <pre>
0747: * Hello <!--V 'NAME:firstName'/--> <!--V 'NAME:lastName'/-->.
0748: * </pre>
0749: * <p>Calling this method with an instance of Person where
0750: * <code>first</code> was "Jim" and <code>last</code> was "James", and the
0751: * prefix "NAME:", would produce:
0752: * <pre>Hello Jim James.</pre>
0753: * <p>Calling this method is equivalent to calling {@link
0754: * #setValue(String, String) setValue} individually for each property of
0755: * the bean prefixed with the given prefix.
0756: * <p>This method uses this template's {@linkplain #getEncoder encoder} to
0757: * encode the bean properties before setting the values. To prevent this,
0758: * use {@linkplain #setBean(Object, String, boolean) the other form of
0759: * setBean}.
0760: * <p>Only <em>bean properties</em> will be considered for insertion in
0761: * the template. This means only properties with a <em>getter and a setter</em>
0762: * will be considered.
0763: *
0764: * @param bean a bean whose properties will be used to fill in values in
0765: * the template
0766: * @param prefix the prefix of values which will be filled with the given
0767: * bean's property values
0768: * @exception TemplateException if this template has no bean handling
0769: * capability; or
0770: * <p>an error occurred during the introspection of the bean
0771: * @see #removeBean
0772: * @since 1.0
0773: */
0774: public void setBean(Object bean, String prefix)
0775: throws TemplateException;
0776:
0777: /**
0778: * Sets all values in this template whose names match names of properties
0779: * in the given bean, preceded by the given prefix, if present. If the
0780: * given prefix is <code>null</code>, it is ignored.
0781: * <p>For example, given a class:
0782: * <pre>
0783: * class Person {
0784: * private String first;
0785: * private String last;
0786: *
0787: * public String getFirstName() { return first; }
0788: * public void setFirstName(String name) { this.first = name; }
0789: *
0790: * public String getLastName() { return last; }
0791: * public void setLastName(String name) { this.last = name; }
0792: * </pre>
0793: * <p>And given a template:
0794: * <pre>
0795: * Hello <!--V 'NAME:firstName'/--> <!--V 'NAME:lastName'/-->.
0796: * </pre>
0797: * <p>Calling this method with an instance of Person where
0798: * <code>first</code> was "Jim" and <code>last</code> was "James", and the
0799: * prefix "NAME:", would produce:
0800: * <pre>Hello Jim James.</pre>
0801: * <p>Calling this method is equivalent to calling {@link
0802: * #setValue(String, String) setValue} individually for each property of
0803: * the bean prefixed with the given prefix.
0804: * <p>If <code>encode</code> is <code>true</code>, this method will use
0805: * this template's {@linkplain #getEncoder encoder} to encode the bean
0806: * properties before setting the values.
0807: * <p>Only <em>bean properties</em> will be considered for insertion in
0808: * the template. This means only properties with a <em>getter and a setter</em>
0809: * will be considered.
0810: *
0811: * @param bean a bean whose properties will be used to fill in values in
0812: * the template
0813: * @param prefix the prefix of values which will be filled with the given
0814: * bean's property values
0815: * @param encode <code>true</code> if the bean poroperty values have to be
0816: * encoded; or
0817: * <p><code>false</code> otherwise
0818: * @exception TemplateException if this template has no bean handling
0819: * capability; or
0820: * <p>an error occurred during the introspection of the bean
0821: * @see #removeBean
0822: * @since 1.0
0823: */
0824: public void setBean(Object bean, String prefix, boolean encode)
0825: throws TemplateException;
0826:
0827: /**
0828: * Reverts all values to their defaults when the identifiers match
0829: * properties of the given bean, whether or not those values were set with
0830: * a previous call to {@link #setBean(Object) setBean}. The values of the
0831: * bean's properties are ignored.
0832: * <p>Calling this method is equivalent to calling {@link #removeValue
0833: * removeValue} once for the name of each property of the given bean.
0834: *
0835: * @param bean a bean
0836: * @exception TemplateException if this template has no bean handling
0837: * capability; or
0838: * <p>an error occurred during the introspection of the bean
0839: * @see #setBean
0840: * @since 1.0
0841: */
0842: public void removeBean(Object bean) throws TemplateException;
0843:
0844: /**
0845: * Reverts all values to their defaults when the identifiers match
0846: * properties of the given bean preceded by the given prefix, whether or
0847: * not those values were set with a previous call to {@link
0848: * #setBean(Object) setBean}. The values of the bean's properties are
0849: * ignored.
0850: * <p>Calling this method is equivalent to calling {@link #removeValue
0851: * removeValue} once for the name of each property of the given bean,
0852: * prefixed with the given prefix.
0853: *
0854: * @param bean a bean whose properties will be used to determine which
0855: * values to remove from the template
0856: * @param prefix a prefix
0857: * @exception TemplateException if this template has no bean handling
0858: * capability; or
0859: * <p>an error occurred during the introspection of the bean
0860: * @see #setBean
0861: * @since 1.0
0862: */
0863: public void removeBean(Object bean, String prefix)
0864: throws TemplateException;
0865:
0866: /**
0867: * Appends the result of calling {@link String#valueOf(Object)
0868: * String.valueOf} on the given <code>value</code> to the specified value
0869: * in this template.
0870: *
0871: * @param id the ID of the value in this template
0872: * @param value an object
0873: * @exception TemplateException if the specified value ID does not exist
0874: * in this template
0875: * @see #setValue
0876: * @see #isValueSet
0877: * @see #removeValue
0878: * @see #removeValues
0879: * @see #blankValue
0880: * @see #hasValueId
0881: * @since 1.0
0882: */
0883: public void appendValue(String id, Object value)
0884: throws TemplateException;
0885:
0886: /**
0887: * Appends <code>"true"</code> or <code>"false"</code> to the specified
0888: * value in this template, depending on the given <code>value</code>.
0889: *
0890: * @param id the ID of the value in this template
0891: * @param value a boolean value
0892: * @exception TemplateException if the specified value ID does not exist
0893: * in this template
0894: * @see #setValue
0895: * @see #isValueSet
0896: * @see #removeValue
0897: * @see #blankValue
0898: * @see #hasValueId
0899: * @since 1.0
0900: */
0901: public void appendValue(String id, boolean value)
0902: throws TemplateException;
0903:
0904: /**
0905: * Appends the single specified character to the specified value in this
0906: * template.
0907: *
0908: * @param id the ID of the value in this template
0909: * @param value a character
0910: * @exception TemplateException if the specified value ID does not exist
0911: * in this template
0912: * @see #setValue
0913: * @see #isValueSet
0914: * @see #removeValue
0915: * @see #removeValues
0916: * @see #blankValue
0917: * @see #hasValueId
0918: * @since 1.0
0919: */
0920: public void appendValue(String id, char value)
0921: throws TemplateException;
0922:
0923: /**
0924: * Appends the given characters to the specified value in this template.
0925: * The given value must not be <code>null</code>.
0926: *
0927: * @param id the ID of the value in this template
0928: * @param value a string of characters
0929: * @exception TemplateException if the specified value ID does not exist
0930: * in this template
0931: * @see #setValue
0932: * @see #isValueSet
0933: * @see #removeValue
0934: * @see #removeValues
0935: * @see #blankValue
0936: * @see #hasValueId
0937: * @since 1.0
0938: */
0939: public void appendValue(String id, char[] value)
0940: throws TemplateException;
0941:
0942: /**
0943: * Appends the specified range of the given character string to the
0944: * specified value in this template. The specified number of bytes from
0945: * <code>value</code> will be used, starting at the character specified by
0946: * <code>offset</code>.
0947: *
0948: * @param id the ID of the value in this template
0949: * @param value a character string
0950: * @param offset the index in <code>value</code> of the first character to
0951: * use
0952: * @param count the number of characters to use
0953: * @exception TemplateException if the specified value ID does not exist
0954: * in this template
0955: * @see #setValue
0956: * @see #isValueSet
0957: * @see #removeValue
0958: * @see #removeValues
0959: * @see #blankValue
0960: * @see #hasValueId
0961: * @since 1.0
0962: */
0963: public void appendValue(String id, char[] value, int offset,
0964: int count) throws TemplateException;
0965:
0966: /**
0967: * Appends the given double precision floating point value to the
0968: * specified value in this template. This method uses the {@linkplain
0969: * String#valueOf(double) String.valueOf} method to print the given value,
0970: * which probably prints more digits than you like. You probably want
0971: * {@link String#format String.format} or {@link NumberFormat} instead.
0972: *
0973: * @param id the ID of the value in this template
0974: * @param value a floating point value
0975: * @exception TemplateException if the specified value ID does not exist
0976: * in this template
0977: * @see #setValue
0978: * @see #isValueSet
0979: * @see #removeValue
0980: * @see #removeValues
0981: * @see #blankValue
0982: * @see #hasValueId
0983: * @since 1.0
0984: */
0985: public void appendValue(String id, double value)
0986: throws TemplateException;
0987:
0988: /**
0989: * Appends the given floating point value to the specified value in this
0990: * template. This method uses the {@linkplain String#valueOf(float)
0991: * String.valueOf} method to print the given value, which probably prints
0992: * more digits than you like. You probably want {@link String#format
0993: * String.format} or {@link NumberFormat} instead.
0994: *
0995: * @param id the ID of the value in this template
0996: * @param value a floating point value
0997: * @exception TemplateException if the specified value ID does not exist
0998: * in this template
0999: * @see #setValue
1000: * @see #isValueSet
1001: * @see #removeValue
1002: * @see #removeValues
1003: * @see #blankValue
1004: * @see #hasValueId
1005: * @since 1.0
1006: */
1007: public void appendValue(String id, float value)
1008: throws TemplateException;
1009:
1010: /**
1011: * Appends the given integer to the specified value in this template.
1012: *
1013: * @param id the ID of the value in this template
1014: * @param value an integer
1015: * @exception TemplateException if the specified value ID does not exist
1016: * in this template
1017: * @see #setValue
1018: * @see #isValueSet
1019: * @see #removeValue
1020: * @see #removeValues
1021: * @see #blankValue
1022: * @see #hasValueId
1023: * @since 1.0
1024: */
1025: public void appendValue(String id, int value)
1026: throws TemplateException;
1027:
1028: /**
1029: * Appends the given long to the specified value in this template.
1030: *
1031: * @param id the ID of the value in this template
1032: * @param value a long
1033: * @exception TemplateException if the specified value ID does not exist
1034: * in this template
1035: * @see #setValue
1036: * @see #isValueSet
1037: * @see #removeValue
1038: * @see #removeValues
1039: * @see #blankValue
1040: * @see #hasValueId
1041: * @since 1.0
1042: */
1043: public void appendValue(String id, long value)
1044: throws TemplateException;
1045:
1046: /**
1047: * Appends the given string, or an empty string if <code>value</code> is
1048: * <code>null</code>, to the specified value in this template.
1049: *
1050: * @param id the ID of the value in this template
1051: * @param value a string, or <code>null</code>
1052: * @exception TemplateException if the specified value ID does not exist
1053: * in this template
1054: * @see #setValue
1055: * @see #isValueSet
1056: * @see #removeValue
1057: * @see #removeValues
1058: * @see #blankValue
1059: * @see #hasValueId
1060: * @since 1.0
1061: */
1062: public void appendValue(String id, String value)
1063: throws TemplateException;
1064:
1065: /**
1066: * Returns the current content of the specified value as a string.
1067: *
1068: * @param id the ID of a value in this template
1069: * @return the current content value of the specified value
1070: * @exception TemplateException if the specified value ID does not exist
1071: * in this template
1072: * @see #setValue
1073: * @see #isValueSet
1074: * @see #removeValue
1075: * @see #removeValues
1076: * @see #blankValue
1077: * @see #hasValueId
1078: * @since 1.0
1079: */
1080: public String getValue(String id) throws TemplateException;
1081:
1082: /**
1083: * Returns the original text of the specified value, before any
1084: * modification that may have been made using {@link #setValue} or similar
1085: * methods.
1086: * <p>If no default value was specified for the given value, this method
1087: * will return <code>null</code>.
1088: *
1089: * @param id the ID of a value in this template, or <code>null</code>
1090: * @return the original text value of the specified value
1091: * @see #hasDefaultValue
1092: * @since 1.0
1093: */
1094: public String getDefaultValue(String id);
1095:
1096: /**
1097: * Returns whether a {@linkplain #getDefaultValue default value} was
1098: * specified in this template for the specified value.
1099: *
1100: * @param id the ID of a value in this template
1101: * @return whether the specified value has a default value
1102: * @see #getDefaultValue
1103: * @since 1.0
1104: */
1105: public boolean hasDefaultValue(String id);
1106:
1107: /**
1108: * Each template type supports a set of special block tags that are used
1109: * for adding automated features like localization, block value scripting,
1110: * config value setting, ... Instead of having to parse all template block
1111: * identifiers each time these features are used, RIFE filters them out at
1112: * template compilation and keeps them available in a separate collection.
1113: * <p>This method is mainly used by the framework itself, the supported
1114: * filter regular expressions are available from {@link TemplateFactory}
1115: * and {@link TemplateFactoryEngineTypes}.
1116: *
1117: * @param filter a template factory regular expression
1118: * @return a list of captured groups for matching block ID's
1119: * @see #hasFilteredBlocks
1120: * @since 1.0
1121: */
1122: public List<String[]> getFilteredBlocks(String filter);
1123:
1124: /**
1125: * Returns whether any block matched a particular filter at template
1126: * compilation.
1127: *
1128: * @param filter a template factory regular expression
1129: * @return whether any matching blocks exist in this template
1130: * @see #getFilteredBlocks
1131: * @since 1.0
1132: */
1133: public boolean hasFilteredBlocks(String filter);
1134:
1135: /**
1136: * Each template type supports a set of special value tags that are used
1137: * for adding automated features like embedded elements, localization,
1138: * block value scripting, config value setting, ... Instead of having to
1139: * parse all template value identifiers each time these features are used,
1140: * RIFE filters them out at template compilation and keeps them available
1141: * in a separate collection.
1142: * <p>This method is mainly used by the framework itself, the supported
1143: * filter regular expressions are available from {@link TemplateFactory}
1144: * and {@link TemplateFactoryEngineTypes}.
1145: *
1146: * @param filter a template factory regular expression
1147: * @return a list of captured groups for matching value ID's
1148: * @see #hasFilteredValues
1149: * @since 1.0
1150: */
1151: public List<String[]> getFilteredValues(String filter);
1152:
1153: /**
1154: * Returns whether any value matched a particular filter at template
1155: * compilation.
1156: *
1157: * @param filter a template factory regular expression
1158: * @return whether any matching values exist in this template
1159: * @see #getFilteredValues
1160: * @since 1.0
1161: */
1162: public boolean hasFilteredValues(String filter);
1163:
1164: /**
1165: * Fills all values in this template which match "<code>L10N:<em>key</em></code>",
1166: * where "<code>key</code>" is a {@linkplain
1167: * ResourceBundle#getObject(String) key} in a {@linkplain
1168: * #addResourceBundle(ResourceBundle) resource bundle} registered for this
1169: * template. Each value will be filled with the value in the resource
1170: * bundle with the corresponding key.
1171: * <p>This method is normally called automatically during template
1172: * initialization. You should call it if you wish to re-evaluate the tags
1173: * at any time during the template's life.
1174: *
1175: * @return the list of names of the template values that were generated
1176: * @since 1.0
1177: */
1178: public List<String> evaluateL10nTags();
1179:
1180: /**
1181: * Fills all values in this template which match "<code>CONFIG:<em>key</em></code>",
1182: * where "<code>key</code>" is a configuration value name in the {@link
1183: * Config} instance returned by {@link Config#getRepInstance()}. Each
1184: * valuev will be filled with the value of the configuration option with
1185: * the corresponding key.
1186: * <p>This method is normally called automatically during template
1187: * initialization. You should call it if you wish to re-evaluate the tags
1188: * at any time during the template's life.
1189: *
1190: * @return the list of names of the template values that were generated
1191: * @since 1.0
1192: */
1193: public List<String> evaluateConfigTags();
1194:
1195: /**
1196: * Fills the value "<code>LANG:<em>id</em></code>" with the value of the
1197: * block "<code>LANG:<em>id</em>:<em>langid</em></code>", where "<code>id</code>"
1198: * is the given ID, and "<code>langid</code>" is this template's
1199: * {@linkplain #getLanguage() current language ID}.
1200: * <p>If no matching block for the current language is found, the content
1201: * of the specified value will not be modified.
1202: * <p>This method is called automatically when the output is generated
1203: * (such as when calling {@link #getContent()}). You can manually call
1204: * this method to force evaluation of the tags earlier than that.
1205: *
1206: * @param id the ID whose language tag should be filled with the
1207: * appropriate block
1208: * @return the list of names of the template values that were generated
1209: * @since 1.0
1210: */
1211: public List<String> evaluateLangTags(String id);
1212:
1213: /**
1214: * Evaluates the specified OGNL, Groovy, or Janino expression tag. For
1215: * example, if a value exists with ID "<code>OGNL:<em>id</em>:[[<em>script</em>]]</code>",
1216: * where "<code>id</code>" is the given ID and "<code>script</code>" is
1217: * some OGNL expression, this method will replace this value with the
1218: * value of the evaluated OGNL expression, using the current set of
1219: * {@linkplain #getExpressionVars() expression variables}.
1220: * <p>The prefix for OGNL is "OGNL:", the prefix for Groovy is "GROOVY:"
1221: * and the prefix for Janino is "JANINO:".
1222: * <p>This method is called automatically when the output is generated
1223: * (such as when calling {@link #getContent()}). You can manually call
1224: * this method to force evaluation of the tags earlier than that.
1225: *
1226: * @param id the ID whose expression tag will be replaced with the value
1227: * of the evaluated expression in the tag ID
1228: * @return the list of names of the template values that were generated
1229: * @since 1.0
1230: */
1231: public List<String> evaluateExpressionTags(String id);
1232:
1233: /**
1234: * Evaluates the specified OGNL, Groovy, or Janino configuration
1235: * expression tag. For example, if a value exists with ID "OGNL:CONFIG:<em>id</em>:[[<em>script</em>]]",
1236: * where "id" is the given ID and "script" is some OGNL expression, this
1237: * method will replace this value with the value of the evaluated OGNL
1238: * expression, using the current set of {@linkplain #getExpressionVars()
1239: * expression variables}.
1240: * <p>The prefix for OGNL is "<code>OGNL:</code>", the prefix for Groovy
1241: * is "<code>GROOVY:</code>" and the prefix for Janino is "<code>JANINO:</code>".
1242: * <p>The context for the expressions will be the {@link Config} object
1243: * returned by {@link Config#getRepInstance()}.
1244: * <p>Expression config tags are evaluated automatically when the output
1245: * is generated (such as when calling {@link #getContent()}). You can
1246: * manually call this method to force evaluation of the tags earlier than
1247: * that.
1248: *
1249: * @param id the ID whose expression tag will be replaced with the value
1250: * of the evaluated expression in the tag ID
1251: * @return the list of names of the template values that were generated
1252: * @since 1.0
1253: */
1254: public List<String> evaluateExpressionConfigTags(String id);
1255:
1256: /**
1257: * Evalutes all values in this template with ID's of the form "<code>RENDER:<em>class</em></code>"
1258: * or "<code>RENDER:<em>class</em>:<em>differentiato</em></code><em>r</em>",
1259: * where "<code>class</code>" is the fully-qualified name of a class which
1260: * extends {@link ValueRenderer}, the result of calling {@link
1261: * ValueRenderer#render(Template, String, String) ValueRenderer.render} on
1262: * a new instance of the class. The class must contain a zero-argument
1263: * ("no-arg") constructor.
1264: * <p>For example, given a class <code>MyRenderer</code> in the package "<code>org.rifers.something</code>",
1265: * which extends {@link ValueRenderer}, a value "<code>RENDER:org.rifers.something.MyRenderer:test</code>"
1266: * would create a new instance of <code>MyRenderer</code> (using its
1267: * no-arg constructor), call <code>render(this,
1268: * "RENDER:org.rifers.something.MyRenderer:test", "test")</code>, and set
1269: * the value in this template to whatever value the call returns.
1270: * <p>Value renderer tags are evaluated automatically when the output is
1271: * generated (such as when calling {@link #getContent()}). You can
1272: * manually call this method to force evaluation of the tags earlier than
1273: * that.
1274: *
1275: * @exception TemplateException if a class in a render tag cannot be
1276: * instantiated
1277: * @return the list of names of the template values that were generated
1278: * @since 1.0
1279: */
1280: public List<String> evaluateRenderTags() throws TemplateException;
1281:
1282: /**
1283: * Returns whether this template contains a block with the given ID.
1284: *
1285: * @param id the prospective ID of a block
1286: * @return whether this template contains a block with the given ID
1287: * @see #appendBlock
1288: * @see #setBlock
1289: * @see #getBlock
1290: * @see #getContent
1291: * @since 1.0
1292: */
1293: public boolean hasBlock(String id);
1294:
1295: /**
1296: * Returns whether the specified value has been set. If this method
1297: * returns <code>false</code>, the value has its original default value.
1298: * <p>If no such value exists in this template, this method will not throw
1299: * an exception, it will return <code>false</code>.
1300: *
1301: * @param id the ID of a value in this template
1302: * @return whether the specified value has been set
1303: * @see #appendValue
1304: * @see #setValue
1305: * @see #isValueSet
1306: * @see #removeValue
1307: * @see #removeValues
1308: * @see #blankValue
1309: * @see #hasValueId
1310: * @since 1.0
1311: */
1312: public boolean isValueSet(String id);
1313:
1314: /**
1315: * Returns the number of values in this template which {@linkplain
1316: * #isValueSet(String) have been set}.
1317: *
1318: * @return the number of values in this template which have been set
1319: * @since 1.0
1320: */
1321: public int countValues();
1322:
1323: /**
1324: * Reverts the specified value back to its default value.
1325: *
1326: * @param id the ID of a value in this template
1327: * @see #appendValue
1328: * @see #setValue
1329: * @see #isValueSet
1330: * @see #hasValueId
1331: * @since 1.0
1332: */
1333: public void removeValue(String id);
1334:
1335: /**
1336: * Reverts the specified values back to their default value.
1337: *
1338: * @param ids the IDs of values in this template
1339: * @see #appendValue
1340: * @see #setValue
1341: * @see #isValueSet
1342: * * @see #removeValue
1343: * @see #hasValueId
1344: * @since 1.6
1345: */
1346: public void removeValues(List<String> ids);
1347:
1348: /**
1349: * Set the content of the specified value to an empte string.
1350: *
1351: * @param id the ID of a value in this template
1352: * @see #appendValue
1353: * @see #setValue
1354: * @see #isValueSet
1355: * @see #hasValueId
1356: * @see #removeValue
1357: * @see #removeValues
1358: * @since 1.4
1359: */
1360: public void blankValue(String id);
1361:
1362: /**
1363: * Resets all values in this template and removes any resource bundles.
1364: * Configuration and localization tags are re-evaluated.
1365: *
1366: * @since 1.0
1367: */
1368: public void clear();
1369:
1370: /**
1371: * Returns a list of the ID's of all values present in this template,
1372: * including set and unset values.
1373: *
1374: * @return a list of ID's of all set and unset value
1375: * @since 1.0
1376: */
1377: public String[] getAvailableValueIds();
1378:
1379: /**
1380: * Returns a list of the ID's of all values in this template which
1381: * {@linkplain #isValueSet(String) have not been set}.
1382: *
1383: * @return a list of ID's of values in this template which have not been
1384: * set
1385: * @since 1.0
1386: */
1387: public Collection<String> getUnsetValueIds();
1388:
1389: /**
1390: * Returns whether this template contains a value with the given ID.
1391: *
1392: * @param id the potential ID of a value in this template
1393: * @return whether this template contains a value with the given ID
1394: * @see #appendValue
1395: * @see #setValue
1396: * @see #isValueSet
1397: * @see #removeValue
1398: * @see #removeValues
1399: * @see #blankValue
1400: * @see #hasValueId
1401: * @since 1.0
1402: */
1403: public boolean hasValueId(String id);
1404:
1405: /**
1406: * Returns when the file corresponding to this template was modified, in
1407: * milliseconds since the Unix epoch.
1408: *
1409: * @return the time at which the underlying template file was modified
1410: * @since 1.0
1411: */
1412: public long getModificationTime();
1413:
1414: /**
1415: * Returns this template's {@linkplain BeanHandler bean handler}. The bean
1416: * handler is used for filling bean values into template values, and for
1417: * building forms.
1418: *
1419: * @return this template's bean handler
1420: * @since 1.0
1421: */
1422: public BeanHandler getBeanHandler();
1423:
1424: /**
1425: * Returns the encoder that this template uses to convert strings to
1426: * values in the template's generated text output. In an HTML template,
1427: * for example, this encoder may be used to convert text which may contain
1428: * HTML special characters like <code><></code> to corresponding
1429: * escaped strings.
1430: *
1431: * @return this template's encoder
1432: * @since 1.0
1433: */
1434: public TemplateEncoder getEncoder();
1435:
1436: /**
1437: * Adds a resource bundle to this template. Resource bundles are used in
1438: * many places, including when generating labels for forms, generating
1439: * options for <code><select></code> tags, and {@linkplain
1440: * #evaluateL10nTags() using localized text}.
1441: *
1442: * @param resourceBundle a resource bundle
1443: * @see #getResourceBundles
1444: * @see #hasResourceBundles
1445: * @since 1.0
1446: */
1447: public void addResourceBundle(ResourceBundle resourceBundle);
1448:
1449: /**
1450: * Returns a list of the resource bundles used by this template. This will
1451: * contain any bundles added through {@link #addResourceBundle
1452: * addResourceBundle} as well as any default resource bundles.
1453: *
1454: * @return a list of this template's resource bundles
1455: * @see #addResourceBundle
1456: * @see #hasResourceBundles
1457: * @since 1.0
1458: */
1459: public Collection<ResourceBundle> getResourceBundles();
1460:
1461: /**
1462: * Returns whether this template has any resource bundles {@linkplain
1463: * #addResourceBundle registered}.
1464: *
1465: * @return whether this template contains any resource bundles
1466: * @see #addResourceBundle
1467: * @see #getResourceBundles
1468: * @since 1.0
1469: */
1470: public boolean hasResourceBundles();
1471:
1472: /**
1473: * Sets this template's current language code, such as "en".
1474: * <p>This is used when {@link #evaluateL10nTags filling localized text
1475: * values}.
1476: *
1477: * @param lang a 2-letter language code for the language to be used by
1478: * this template
1479: * @see #getLanguage
1480: * @since 1.0
1481: */
1482: public void setLanguage(String lang);
1483:
1484: /**
1485: * Returns this template's current 2-letter language code. This code is
1486: * used when {@link #evaluateL10nTags filling localized text values}. If
1487: * the language has not been {@linkplain #setLanguage set}, it defaults to
1488: * the language set by the RIFE configuration parameter "<code>L10N_DEFAULT_LANGUAGE</code>".
1489: *
1490: * @return the 2-letter language code currently used by this template
1491: * @see #setLanguage
1492: * @since 1.0
1493: */
1494: public String getLanguage();
1495:
1496: /**
1497: * Sets a variable which can be accessed by {@linkplain
1498: * #evaluateExpressionTags expression tags} in OGNL, Groovy, or Janino.
1499: *
1500: * @param name the name of the variable
1501: * @param value the value to associate with the given variable name
1502: * @see #setExpressionVars
1503: * @see #getExpressionVars
1504: * @since 1.0
1505: */
1506: public void setExpressionVar(String name, Object value);
1507:
1508: /**
1509: * Sets the given variables to the given corresponding values, for use in
1510: * {@linkplain #evaluateExpressionTags expression tags}. Calling this
1511: * method is equivalent to calling {@link #setExpressionVar
1512: * setExpressionVar} for each entry in the given map.
1513: *
1514: * @param map a map from variable name to variable value
1515: * @see #setExpressionVar
1516: * @see #getExpressionVars
1517: * @since 1.0
1518: */
1519: public void setExpressionVars(Map<String, Object> map);
1520:
1521: /**
1522: * Returns the name and value of all of the expression variables which
1523: * have been {@linkplain #setExpressionVar set} in this template.
1524: *
1525: * @return the expression variables currently set in this template
1526: * @see #setExpressionVar
1527: * @see #setExpressionVars
1528: * @since 1.0
1529: */
1530: public Map<String, Object> getExpressionVars();
1531:
1532: /**
1533: * Stores the given value in a cache, associated with the given key. This
1534: * is mainly used by OGNL, Groovy, and Janino expression evaluation system
1535: * to store caches to classes. You should probably not use the template
1536: * caching system to avoid conflicting with the expression evaluation
1537: * system.
1538: *
1539: * @param key a name under which the given value should be stored
1540: * @param value an object
1541: * @since 1.0
1542: */
1543: public void cacheObject(String key, Object value);
1544:
1545: /**
1546: * Returns the value corresponding to the given key in this template's
1547: * cache, or <code>null</code> if no such cached object exists. As noted
1548: * in {@link #cacheObject}, you should probably not use this method to
1549: * avoid conflicting with RIFE's internal use of the cache.
1550: *
1551: * @param key a key whose associated cached object should be returned
1552: * @return the value associated with the given key, or <code>null</code>
1553: * if none exists
1554: * @since 1.0
1555: */
1556: public Object getCacheObject(String key);
1557:
1558: /**
1559: * Returns a list of URL's that this template depends on, and their last
1560: * modification dates (in milliseconds since the Unix epoch). This method
1561: * should return templates which are included by this template, and any
1562: * other resources which are required to fully render the template.
1563: *
1564: * @return a list of URL's and last modification dates of resources on
1565: * which this template depends
1566: * @since 1.0
1567: */
1568: public Map<URL, Long> getDependencies();
1569:
1570: /**
1571: * Returns this template's name, without path information or file
1572: * extension. For example, for /Users/me/Something/templates/xyz.html,
1573: * this method will return "xyz".
1574: *
1575: * @return this template's name, without path or file extension
1576: * @since 1.0
1577: */
1578: public String getName();
1579:
1580: /**
1581: * Returns this template's full name, as it was used to instantiate it
1582: * by a template factory.
1583: *
1584: * @return this template's full name
1585: * @since 1.6
1586: */
1587: public String getFullName();
1588:
1589: /**
1590: * Returns this template's default content type, for example <code>text/html</code>.
1591: *
1592: * @return this template's default content type; or
1593: * <p><code>null</code> if no default content type is known for this template instance
1594: * @since 1.3
1595: */
1596: public String getDefaultContentType();
1597:
1598: /**
1599: * Returns a shallow copy of this template, with the same values,
1600: * expression variables, and so on.
1601: *
1602: * @return a shallow copy of this template
1603: * @since 1.0
1604: */
1605: public Object clone();
1606: }
|