001: /*
002: * Copyright 1999,2004 The Apache Software Foundation.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.apache.jasper.compiler.tagplugin;
018:
019: /**
020: * This interface allows the plugin author to make inqueries about the
021: * properties of the current tag, and to use Jasper resources to generate
022: * direct Java codes in place of tag handler invocations.
023: */
024:
025: public interface TagPluginContext {
026: /**
027: * @return true if the body of the tag is scriptless.
028: */
029: boolean isScriptless();
030:
031: /**
032: * @param attribute Name of the attribute
033: * @return true if the attribute is specified in the tag
034: */
035: boolean isAttributeSpecified(String attribute);
036:
037: /**
038: * @return An unique temporary variable name that the plugin can use.
039: */
040: String getTemporaryVariableName();
041:
042: /**
043: * Generate an import statement
044: * @param s Name of the import class, '*' allowed.
045: */
046: void generateImport(String s);
047:
048: /**
049: * Generate a declaration in the of the generated class. This can be
050: * used to declare an innter class, a method, or a class variable.
051: * @param id An unique ID identifying the declaration. It is not
052: * part of the declaration, and is used to ensure that the
053: * declaration will only appear once. If this method is
054: * invoked with the same id more than once in the translation
055: * unit, only the first declaration will be taken.
056: * @param text The text of the declaration.
057: **/
058: void generateDeclaration(String id, String text);
059:
060: /**
061: * Generate Java source codes
062: */
063: void generateJavaSource(String s);
064:
065: /**
066: * @return true if the attribute is specified and its value is a
067: * translation-time constant.
068: */
069: boolean isConstantAttribute(String attribute);
070:
071: /**
072: * @return A string that is the value of a constant attribute. Undefined
073: * if the attribute is not a (translation-time) constant.
074: * null if the attribute is not specified.
075: */
076: String getConstantAttribute(String attribute);
077:
078: /**
079: * Generate codesto evaluate value of a attribute in the custom tag
080: * The codes is a Java expression.
081: * NOTE: Currently cannot handle attributes that are fragments.
082: * @param attribute The specified attribute
083: */
084: void generateAttribute(String attribute);
085:
086: /*
087: * Generate codes for the body of the custom tag
088: */
089: void generateBody();
090:
091: /**
092: * Abandon optimization for this tag handler, and instruct
093: * Jasper to generate the tag handler calls, as usual.
094: * Should be invoked if errors are detected, or when the tag body
095: * is deemed too compilicated for optimization.
096: */
097: void dontUseTagPlugin();
098:
099: /**
100: * Get the PluginContext for the parent of this custom tag. NOTE:
101: * The operations available for PluginContext so obtained is limited
102: * to getPluginAttribute and setPluginAttribute, and queries (e.g.
103: * isScriptless(). There should be no calls to generate*().
104: * @return The pluginContext for the parent node.
105: * null if the parent is not a custom tag, or if the pluginConxt
106: * if not available (because useTagPlugin is false, e.g).
107: */
108: TagPluginContext getParentContext();
109:
110: /**
111: * Associate the attribute with a value in the current tagplugin context.
112: * The plugin attributes can be used for communication among tags that
113: * must work together as a group. See <c:when> for an example.
114: */
115: void setPluginAttribute(String attr, Object value);
116:
117: /**
118: * Get the value of an attribute in the current tagplugin context.
119: */
120: Object getPluginAttribute(String attr);
121: }
|