KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > sapia > soto > state > Context


1 package org.sapia.soto.state;
2
3 import java.util.Map JavaDoc;
4
5
6 /**
7  * This interface models an execution context. An instance of this interface keeps variables
8  * in <code>Scope</code> instances. Each scope is internally bound under a given name; the scopes
9  * used to perform object lookups can be explicitely specified to this instance, using the
10  * <code>get(Object key, String[] scopeNames)</code> method.
11  *
12  * @author Yanick Duchesne
13  * <dl>
14  * <dt><b>Copyright:</b><dd>Copyright &#169; 2002-2003 <a HREF="http://www.sapia-oss.org">Sapia Open Source Software</a>. All Rights Reserved.</dd></dt>
15  * <dt><b>License:</b><dd>Read the license.txt file of the jar or visit the
16  * <a HREF="http://www.sapia-oss.org/license.html">license page</a> at the Sapia OSS web site</dd></dt>
17  * </dl>
18  */

19 public interface Context {
20   /**
21    * This constant specifies the character that corresponds to the "stack scope".
22    * The character is: .
23    */

24   public static final char STACK_SCOPE = '.';
25
26   // Scope-related methods //////////////////////////////////////
27

28   /**
29    * Returns the object corresponding to the given key.
30    *
31    * @param key an <code>Object</code>.
32    * @return the <code>Object</code> that matches the given key,
33    * or <code>null</code> if no corresponding object is found.
34    */

35   public Object JavaDoc get(Object JavaDoc key);
36
37   /**
38    * Returns the object corresponding to the given key; searches
39    * all the scopes whose names are given.
40    *
41    * @param key an <code>Object</code>.
42    * @param scopes an array of scope names.
43    * @return the <code>Object</code> that matches the given key,
44    * or <code>null</code> if no corresponding object is found.
45    */

46   public Object JavaDoc get(Object JavaDoc key, String JavaDoc[] scopes);
47
48   /**
49    * Returns the object corresponding to the given key; searches
50    * the scope whose name is given.
51    * <p>
52    * If the scope name corresponds to the "." string, than this method
53    * will return the object that is currently on stack, or <code>null</code>
54    * if no object is on stack.
55    *
56    * @see #currentObject()
57    * @see #STACK_SCOPE
58    *
59    * @param key an <code>Object</code>.
60    * @param scope the name of the scope in which to search.
61    * @return the <code>Object</code> that matches the given key,
62    * or <code>null</code> if no corresponding object is found.
63    */

64   public Object JavaDoc get(Object JavaDoc key, String JavaDoc scope);
65
66   /**
67    * @return the <code>Scope</code>s that this instance contains in a
68    * <code>Map</code>, under their corresponding name (the name is the key
69    * under which each <code>Scope</code> is bound in the <code>Map</code>.
70    */

71   public Map JavaDoc getScopes();
72
73   // Stack-related methods //////////////////////////////////////
74

75   /**
76    * Pushes the given object on the internal stack that this instance keeps.
77    *
78    * @param obj an <code>Object</code>.
79    */

80   public void push(Object JavaDoc obj);
81
82   /**
83    * Pops the given object from the internal stack that this instance keeps.
84    */

85   public Object JavaDoc pop();
86
87   /**
88    * @return The current object on this instance's internal stack.
89    *
90    * @throws IllegalStateException if this instance's internal stack is empty.
91    */

92   public Object JavaDoc currentObject() throws IllegalStateException JavaDoc;
93
94   /**
95    * @return <code>true</code> if at least one object is present on the context's
96    * stack.
97    */

98   public boolean hasCurrentObject();
99 }
100
Popular Tags