View Javadoc

1   /*
2    * $Id: TilesContainer.java 736275 2009-01-21 09:58:20Z apetrelli $
3    *
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   * http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
20   */
21  package org.apache.tiles;
22  
23  import java.util.Map;
24  import java.io.IOException;
25  import java.io.Writer;
26  
27  /***
28   * An encapsulation of the tiles framework.  This interface is
29   * used to expose tiles features to frameworks which leverage
30   * it as a plugin.  It can alternately be used by web applications
31   * which would like a programmatic interface.
32   *
33   * @since 2.0
34   * @version $Rev: 736275 $ $Date: 2009-01-21 10:58:20 +0100 (mer, 21 gen 2009) $
35   */
36  public interface TilesContainer {
37  
38      /***
39       * Initialize the container with the given
40       * configuration.
41       *
42       * @param initParameters application context
43       */
44      void init(Map<String, String> initParameters);
45  
46      /***
47       * Retrieve the containers context.
48       *
49       * @return current application context
50       */
51      TilesApplicationContext getApplicationContext();
52  
53      /***
54       * Retrive the attribute context of the current request.
55       * @param requestItems the current request objects.
56       * @return map of the attributes in the current attribute context.
57       */
58      AttributeContext getAttributeContext(Object... requestItems);
59  
60      /***
61       * Starts a new context, where attribute values are stored independently
62       * from others.<br>
63       * When the use of the contexts is finished, call
64       * {@link TilesContainer#endContext(Object...)}
65       *
66       * @param requestItems the current request objects.
67       * @return The newly created context.
68       */
69      AttributeContext startContext(Object... requestItems);
70  
71      /***
72       * Ends a context, where attribute values are stored independently
73       * from others.<br>
74       * It must be called after a
75       * {@link TilesContainer#startContext(Object...)} call.
76       *
77       * @param requestItems the current request objects.
78       */
79      void endContext(Object... requestItems);
80  
81      /***
82       * Renders the current context, as it is.
83       *
84       * @param requestItems the current request objects.
85       * @since 2.1.0
86       */
87      void renderContext(Object... requestItems);
88  
89      /***
90       * Executes a preparer.
91       *
92       * @param preparer The name of the preparer to execute.
93       * @param requestItems the current request objects.
94       */
95      void prepare(String preparer, Object... requestItems);
96  
97      /***
98       * Render the given tiles request.
99       *
100      * @param definition the current definition.
101      * @param requestItems the current request objects.
102      */
103     void render(String definition, Object... requestItems);
104 
105     /***
106      * Render the given Attribute.
107      *
108      * @param attribute The attribute to render.
109      * @param writer A writer. <strong>IT WON'T BE EVALUATED!!!</strong>
110      * @param requestItems the current request objects.
111      * @throws IOException If something goes wrong during writing to the output.
112      * @deprecated Use {@link #render(Attribute, Object...)}.
113      */
114     @Deprecated
115     void render(Attribute attribute, Writer writer, Object... requestItems)
116         throws IOException;
117 
118     /***
119      * Render the given Attribute.
120      *
121      * @param attribute The attribute to render.
122      * @param requestItems the current request objects.
123      * @throws IOException If something goes wrong during writing to the output.
124      * @since 2.1.2
125      */
126     void render(Attribute attribute, Object... requestItems)
127         throws IOException;
128 
129     /***
130      * Evaluates the given attribute.
131      *
132      * @param attribute The attribute to evaluate.
133      * @param requestItems the current request objects.
134      * @return The evaluated object.
135      * @since 2.1.0
136      */
137     Object evaluate(Attribute attribute, Object... requestItems);
138 
139     /***
140      * Determine whether or not the definition exists.
141      *
142      * @param definition the name of the definition.
143      * @param requestItems the current request objects.
144      *
145      * @return true if the definition is found.
146      */
147     boolean isValidDefinition(String definition, Object... requestItems);
148 }