View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    * 
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   * 
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  package org.apache.struts2.jasper.compiler.tagplugin;
19  
20  
21  /***
22   * This interface allows the plugin author to make inqueries about the
23   * properties of the current tag, and to use Jasper resources to generate
24   * direct Java codes in place of tag handler invocations.
25   */
26  
27  public interface TagPluginContext {
28      /***
29       * @return true if the body of the tag is scriptless.
30       */
31      boolean isScriptless();
32  
33      /***
34       * @param attribute Name of the attribute
35       * @return true if the attribute is specified in the tag
36       */
37      boolean isAttributeSpecified(String attribute);
38  
39      /***
40       * @return An unique temporary variable name that the plugin can use.
41       */
42      String getTemporaryVariableName();
43  
44      /***
45       * Generate an import statement
46       *
47       * @param s Name of the import class, '*' allowed.
48       */
49      void generateImport(String s);
50  
51      /***
52       * Generate a declaration in the of the generated class.  This can be
53       * used to declare an innter class, a method, or a class variable.
54       *
55       * @param id   An unique ID identifying the declaration.  It is not
56       *             part of the declaration, and is used to ensure that the
57       *             declaration will only appear once.  If this method is
58       *             invoked with the same id more than once in the translation
59       *             unit, only the first declaration will be taken.
60       * @param text The text of the declaration.
61       */
62      void generateDeclaration(String id, String text);
63  
64      /***
65       * Generate Java source codes
66       */
67      void generateJavaSource(String s);
68  
69      /***
70       * @return true if the attribute is specified and its value is a
71       *         translation-time constant.
72       */
73      boolean isConstantAttribute(String attribute);
74  
75      /***
76       * @return A string that is the value of a constant attribute.  Undefined
77       *         if the attribute is not a (translation-time) constant.
78       *         null if the attribute is not specified.
79       */
80      String getConstantAttribute(String attribute);
81  
82      /***
83       * Generate codesto evaluate value of a attribute in the custom tag
84       * The codes is a Java expression.
85       * NOTE: Currently cannot handle attributes that are fragments.
86       *
87       * @param attribute The specified attribute
88       */
89      void generateAttribute(String attribute);
90  
91      /***
92       * Generate codes for the body of the custom tag
93       */
94      void generateBody();
95  
96      /***
97       * Abandon optimization for this tag handler, and instruct
98       * Jasper to generate the tag handler calls, as usual.
99       * Should be invoked if errors are detected, or when the tag body
100      * is deemed too compilicated for optimization.
101      */
102     void dontUseTagPlugin();
103 
104     /***
105      * Get the PluginContext for the parent of this custom tag.  NOTE:
106      * The operations available for PluginContext so obtained is limited
107      * to getPluginAttribute and setPluginAttribute, and queries (e.g.
108      * isScriptless().  There should be no calls to generate*().
109      *
110      * @return The pluginContext for the parent node.
111      *         null if the parent is not a custom tag, or if the pluginConxt
112      *         if not available (because useTagPlugin is false, e.g).
113      */
114     TagPluginContext getParentContext();
115 
116     /***
117      * Associate the attribute with a value in the current tagplugin context.
118      * The plugin attributes can be used for communication among tags that
119      * must work together as a group.  See <c:when> for an example.
120      */
121     void setPluginAttribute(String attr, Object value);
122 
123     /***
124      * Get the value of an attribute in the current tagplugin context.
125      */
126     Object getPluginAttribute(String attr);
127 }
128