Context


1   /***
2    * Jonathan: an Open Distributed Processing Environment 
3    * Copyright (C) 2000 France Telecom R&D
4    * Copyright (C) 2001 Kelua SA
5    * 
6    * This library is free software; you can redistribute it and/or
7    * modify it under the terms of the GNU Lesser General Public
8    * License as published by the Free Software Foundation; either
9    * version 2 of the License, or (at your option) any later version.
10   * 
11   * This library is distributed in the hope that it will be useful,
12   * but WITHOUT ANY WARRANTY; without even the implied warranty of
13   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14   * Lesser General Public License for more details.
15   * 
16   * You should have received a copy of the GNU Lesser General Public
17   * License along with this library; if not, write to the Free Software
18   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
19   * 
20   * Contact: jonathan@objectweb.org
21   *
22   * Author: Fabien Delpiano, Bruno Dumant
23   * 
24   */
25  
26  package org.objectweb.jonathan.apis.kernel;
27  
28  import java.util.Enumeration  ;
29  import java.io.Serializable  ;
30  
31  /** 
32   * A context represents a set of typed objects, each identified by a name.
33   */
34  public interface Context extends Component {
35  
36     /** 
37      * Adds an element in the target context.
38      *
39      * @param name the name of the object to be added;
40      * @param type the type of the object to be added;
41      * @param value the object to be added.
42      * @return the previous element, if any; null otherwise.
43      * @exception JonathanException if something goes wrong (usually, a type 
44      *            exception).
45      */
46     Element addElement(Name name, Class   type, Object   value) 
47        throws JonathanException;
48  
49     /** 
50      * Adds an element to the target context.
51      *
52      * In this case, the value's type must be promotable to
53      * an integer. <code>Class</code> is one of int.class, short.class, char.class,
54      * or byte.class.
55      *
56      * @param name  the name of the element to be added;
57      * @param type the type of the element to be added;
58      * @param value the integer value of the element to be added;
59      * @return the previous element, if any, null otherwise.
60      * @exception JonathanException if something goes wrong (usually, a type 
61      *            exception).
62      */
63     Element addElement(Name name, Class   type, int value) throws JonathanException;
64  
65     /** 
66      * Adds an element in the target context. If the component is already attached to some element,
67      * this attachment will be lost in this operation.
68      *
69      * @param name the name of the element to be added;
70      * @param component the component to be added;
71      * @return the previous element, if any; null otherwise.
72      * @exception JonathanException if something goes wrong (usually, a type 
73      *            exception).
74      */
75     Element addElement(Name name, Component component) 
76        throws JonathanException;
77  
78     /** 
79      * Adds an element to the target context. 
80      *
81      * @param element the element to be added.
82      * @return the previous element, if any, null otherwise. 
83      * @exception JonathanException if something goes wrong (usually, a type 
84      *            exception).
85      */
86     //Element addElement(Element element)  throws JonathanException;
87  
88  
89     /** 
90      * Adds an element to the target context.
91      * 
92      * This method is equivalent to {@link #addElement(Name,Class,Object) 
93      * <code>addElement(Name,Class,Object)</code>}, except that the name to use
94      * is specified by a string and a separator separating the different elements of
95      * the name.
96      *
97      * If <code>separator == 0</code>, the name corresponds to an object 
98      * local to the target context.
99      * If the name begins with the separator, the name is an absolute name (this 
100     * only makes sense if the context has a tree structure); otherwise, the name is
101     * relative to the target context.
102     *
103     * @param name a string representing the name of the seeked element;
104     * @param type the type of the object to be added;
105     * @param value the object to be added;
106     * @param separator the separator character used to parse <code>name</code>;
107     * @return the previous element, if any; null otherwise.
108     * @exception JonathanException if something goes wrong (usually, a type 
109     *            exception).
110     */
111    Element addElement(String   name,Class   type,Object   value,char separator) 
112       throws JonathanException;
113    
114    /** 
115     * Adds an element to the target context.
116     * 
117     * This method is equivalent to {@link #addElement(Name,Component) 
118     * <code>addElement(Name,Component)</code>}, except that the name to use
119     * is specified by a string and a separator separating the different elements of
120     * the name.
121     *
122     * If <code>separator == 0</code>, the name corresponds to an object 
123     * local to the target context.
124     * If the name begins with the separator, the name is an absolute name (this 
125     * only makes sense if the context has a tree structure); otherwise, the name is
126     * relative to the target context.
127     *
128     * @param name a string representing the name of the added element;
129     * @param component the component to be added;
130     * @param separator the separator character used to parse <code>name</code>;
131     * @return the previous element, if any; null otherwise.
132     * @exception JonathanException if something goes wrong (usually, a type 
133     *            exception).
134     */
135    Element addElement(String   name,Component component,char separator) 
136       throws JonathanException;
137    
138 
139    /** 
140     * Adds an element to the target context.
141     * 
142     * This method is equivalent to {@link #addElement(Name,Class,int) 
143     * <code>addElement(Name,Class,int)</code>}, except that the name to use
144     * is specified by a string and a separator separating the different elements of
145     * the name.
146     *
147     * If <code>separator == 0</code>, the name corresponds to an object 
148     * local to the target context.
149     * If the name begins with the separator, the name is an absolute name (this 
150     * only makes sense if the context has a tree structure); otherwise, the name is
151     * relative to the target context.
152     *
153     * @param name a string representing the name of the seeked element;
154     * @param type the type of the seeked element;
155     * @param value the integer value of the element to be added;
156     * @param separator the separator character used to parse <code>name</code>;
157     * @return the previous element, if any; null otherwise.
158     * @exception JonathanException if something goes wrong (usually, a type 
159     *            exception).
160     */
161    Element addElement(String   name,Class   type,int value,char separator) 
162       throws JonathanException ;
163 
164 
165    public Context addOrGetContext(String   _name,char _separator) throws JonathanException;
166    
167    public Context addOrGetContext(Name _name) throws JonathanException;
168 
169    /** 
170     * Returns the element in the target context identified by <code>name</code>, 
171     * null if no element is registered under name <code>name</code>.
172     *
173     * This method is equivalent to {@link #getElement(Name) 
174     * <code>getElement(Name)</code>}, except that the name to use
175     * is specified by a string and a separator separating the different elements of
176     * the name.
177     *
178     * If <code>separator == 0</code>, the name corresponds to an object 
179     * local to the target context.
180     * If the name begins with the separator, the name is an absolute name (this 
181     * only makes sense if the context has a tree structure); otherwise, the name is
182     * relative to the target context.
183     *
184     * @param name a string representing the name of the seeked element;
185     * @param separator the separator character used to parse <code>name</code>;
186     * @return the corresponding element, if any; null otherwise.
187     */
188    Element getElement(String   name,char separator);
189 
190    /** 
191     * Returns the component contained in the element registered in the target context under 
192     * the name <code>name</code>.
193     *
194     * This method is equivalent to {@link #getComponent(Name) 
195     * <code>getComponent(Name)</code>}, except that the name to use
196     * is specified by a string and a separator separating the different elements of
197     * the name.
198     *
199     * If <code>separator == 0</code>, the name corresponds to an object 
200     * local to the target context.
201     * If the name begins with the separator, the name is an absolute name (this 
202     * only makes sense if the context has a tree structure); otherwise, the name is
203     * relative to the target context.
204     *
205     * @param name the name of the element whose component is seeked; 
206     * @param separator the separator character used to parse <code>name</code>;
207     * @return the corresponding component, or null.
208     */
209    Component getComponent(String   name,char separator);
210 
211    /** 
212     * Returns the value of the element registered in the target context under 
213     * the name <code>name</code>.
214     *
215     * This method is equivalent to {@link #getValue(Name) 
216     * <code>getValue(Name)</code>}, except that the name to use
217     * is specified by a string and a separator separating the different elements of
218     * the name.
219     *
220     * If <code>separator == 0</code>, the name corresponds to an object 
221     * local to the target context.
222     * If the name begins with the separator, the name is an absolute name (this 
223     * only makes sense if the context has a tree structure); otherwise, the name is
224     * relative to the target context.
225     *
226     * @param name the name of the element whose value is seeked; 
227     * @param separator the separator character used to parse <code>name</code>;
228     * @return the corresponding value, or {@link #NO_VALUE <code>NO_VALUE</code>}.
229     */
230    Object   getValue(String   name,char separator);
231 
232    /** 
233     * Returns the value of the element registered in the target context under 
234     * the name <code>name</code>. 
235     * <p>
236     * A call to <code>getIntValue(name)</code> is equivalent to
237     * <code>{@link #getElement(Name) getElement(name)}.{@link Element#getIntValue()
238     * getIntValue()}</code> if the provided name actually corresponds to an 
239     * element. If it is not the case, 
240     * <code>Integer.MAX_VALUE</code> is returned.
241     *
242     * @param name the name of the element whose value is seeked; 
243     * @return the corresponding value, or <code>Integer.MAX_VALUE</code>
244     */
245    int getIntValue(Name name);
246 
247 
248    /** 
249     * Returns the value of the element registered in the target context under 
250     * the name <code>name</code>.
251     *
252     * This method is equivalent to {@link #getIntValue(Name) 
253     * <code>getIntValue(Name)</code>}, except that the name to use
254     * is specified by a string and a separator separating the different elements of
255     * the name.
256     *
257     * If <code>separator == 0</code>, the name corresponds to an object 
258     * local to the target context.
259     * If the name begins with the separator, the name is an absolute name (this 
260     * only makes sense if the context has a tree structure); otherwise, the name is
261     * relative to the target context.
262     *
263     * @param name the name of the element whose value is seeked; 
264     * @param separator the separator character used to parse <code>name</code>;
265     * @return the corresponding value, or <code>Integer.MAX_VALUE</code>
266     */
267    int getIntValue(String   name,char separator);
268 
269    /** 
270     * Returns an enumeration of the elements found in the target context.
271     * @return an enumeration of the elements found in the target context.
272     */
273    Enumeration   getElements();
274 
275    /** 
276     * Releases the target context, releasing all the resources it uses, if no one still
277     * uses it.
278     * The context should no longer
279     * be used once it has been released.
280     */
281    void release();
282 
283 
284    /** 
285     * Acquires the target context.
286     */
287    void acquire();
288    
289 
290    /** 
291     * Resets the target context, removing all its current elements.
292     */
293    void reset();
294 
295 
296    /** 
297     * Sets the scope of the target context;
298     * @param scope the new scope of the target context; 
299     * @return the previous scope of the target context;
300     */
301    Context setScope(Context scope);
302 
303    /** 
304     * Returns the scope of the target context;
305     * @return the scope of the target context;
306     */
307    Context getScope();
308    
309    /** 
310     * The NO_VALUE object is returned by {@link #getValue(String,char) getValue} 
311     *  if no value corresponds to the provided name. 
312     */
313    Object   NO_VALUE = new NO_VALUE();
314 
315    final class NO_VALUE implements Serializable   {
316       
317       private NO_VALUE(){}
318       
319       public String   toString() {
320          return "NO VALUE";
321       }
322    }
323 }
324
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags