View Javadoc

1   /*
2    * $Id: AttributeContext.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.util.Iterator;
25  import java.util.Set;
26  
27  /***
28   * Encapsulation of the current state of execution.
29   *
30   * @since Tiles 2.0
31   * @version $Rev: 736275 $ $Date: 2009-01-21 10:58:20 +0100 (mer, 21 gen 2009) $
32   */
33  public interface AttributeContext {
34  
35      /***
36       * Returns the attribute that will be used to render a template.
37       *
38       * @return The template attribute.
39       * @since 2.1.2
40       */
41      Attribute getTemplateAttribute();
42  
43      /***
44       * Sets the template attribute, that will be used to render the template
45       * page.
46       *
47       * @param templateAttribute The template attribute.
48       * @since 2.1.2
49       */
50      void setTemplateAttribute(Attribute templateAttribute);
51  
52      /***
53       * Get associated preparer instance.
54       *
55       * @return The preparer name.
56       * @since 2.1.0
57       */
58      String getPreparer();
59  
60      /***
61       * Set associated preparer instance.
62       *
63       * @param url The preparer name.
64       * @since 2.1.0
65       */
66      void setPreparer(String url);
67  
68      /***
69       * Add all attributes to the context.
70       *
71       * @param newAttributes the attributes to be added.
72       */
73      void addAll(Map<String, Attribute> newAttributes);
74  
75      /***
76       * Add all attributes to the context.
77       *
78       * @param defaultAttributes attributes which should be present.
79       */
80      void addMissing(Map<String, Attribute> defaultAttributes);
81  
82      /***
83       * Copies the cascaded attributes to this attribute context.
84       *
85       * @param parent The parent context to be used.
86       * @since 2.1.0
87       */
88      void inheritCascadedAttributes(AttributeContext parent);
89  
90      /***
91       * Copies all missing attributes from the <code>parent</code> attribute
92       * context to this one.
93       *
94       * @param parent The attribute context to copy attributes from.
95       * @since 2.1.0
96       */
97      void inherit(AttributeContext parent);
98  
99      /***
100      * Retrieve the named attribute, either cascaded or not.
101      *
102      * @param name key name for the attribute.
103      * @return Attribute associated with the given name.
104      */
105     Attribute getAttribute(String name);
106 
107     /***
108      * Retrieve the attribute that has been defined in this context (i.e. not
109      * cascaded).
110      *
111      * @param name key name for the attribute.
112      * @return Attribute The local attribute associated with the given name, if
113      * present, or <code>null</code> otherwise.
114      * @since 2.1.0
115      */
116     Attribute getLocalAttribute(String name);
117 
118     /***
119      * Retrieve the attribute that has been cascaded at upper levels.
120      *
121      * @param name key name for the attribute.
122      * @return Attribute The cascaded attribute associated with the given name,
123      * if present, or <code>null</code> otherwise.
124      * @since 2.1.0
125      */
126     Attribute getCascadedAttribute(String name);
127 
128     /***
129      * Iterator of all attribute names.
130      *
131      * @return iterator of all names.
132      * @deprecated Use {@link AttributeContext#getLocalAttributeNames()} or
133      * {@link AttributeContext#getCascadedAttributeNames()}.
134      */
135     @Deprecated
136     Iterator<String> getAttributeNames();
137 
138     /***
139      * Returns the names of the local attributes, i.e. the one that have not
140      * been cascaded.
141      *
142      * @return The local attribute names.
143      * @since 2.1.0
144      */
145     Set<String> getLocalAttributeNames();
146 
147     /***
148      * Returns the names of the cascaded attributes.
149      *
150      * @return The cascaded attribute names.
151      * @since 2.1.0
152      */
153     Set<String> getCascadedAttributeNames();
154 
155     /***
156      * Add the specified attribute. The attribute value will be available only
157      * in the current context, i.e. it is like calling
158      * {@link AttributeContext#putAttribute(String, Attribute, boolean)} with
159      * <code>cascade = false</code>.
160      *
161      * @param name name of the attribute
162      * @param value value of the attribute
163      */
164     void putAttribute(String name, Attribute value);
165 
166     /***
167      * Add the specified attribute.
168      *
169      * @param name name of the attribute
170      * @param value value of the attribute
171      * @param cascade If <code>true</code>, the attribute value will be
172      * available in all nested contexts. If <code>false</code>, it will be
173      * available only in the current context.
174      * @since 2.1.0
175      */
176     void putAttribute(String name, Attribute value, boolean cascade);
177 
178     /***
179      * Clear the attributes.
180      */
181     void clear();
182 }