GuiEnv


1   package org.sapia.gumby;
2   
3   /**
4    * This interface specifies "environment" behavior, as some shared state that is
5    * scoped and made available to some parts of an application.
6    * <p>
7    * Implementations of this interface are expected to follow a delegation model
8    * where given instances can have other instances as ancesters, and where the
9    * ancestors are "consulted" after a given operation is performed at a child -
10   * and if that operation fails at the child.
11   * 
12   * @author Yanick Duchesne
13   * 
14   * <dl>
15   * <dt><b>Copyright: </b>
16   * <dd>Copyright &#169; 2002-2005 <a HREF="http://www.sapia-oss.org">Sapia Open
17   * Source Software </a>. All Rights Reserved.</dd>
18   * </dt>
19   * <dt><b>License: </b>
20   * <dd>Read the license.txt file of the jar or visit the <a
21   * HREF="http://www.sapia-oss.org/license.html">license page </a> at the Sapia
22   * OSS web site</dd>
23   * </dt>
24   * </dl>
25   */
26  public interface GuiEnv {
27  
28    /**
29     * This method attempts to retrieve the object bound under the given name.
30     * This method delegates the call to the ancestor of this instance if it
31     * cannot find the object at its level (and so on).
32     * <p>
33     * This method looks for the object in all scopes, in the order in which the
34     * scopes where created.
35     * 
36     * @see #addScope(String, Scope)
37     * @see #put(String, Object, String)
38     * 
39     * @param name
40     *          the name of an object.
41     * @return the desired <code>Object</code>, or <code>null</code> if no
42     *         such object was found.
43     */
44    public Object   get(String   name);
45  
46    /**
47     * This method looks for the object of the given name in the specified scope.
48     * 
49     * @see #get(String)
50     */
51    public Object   get(String   name, String   scope);
52  
53    /**
54     * @see #get(String)
55     * @throws IllegalArgumentException
56     *           if the desired object could not be found.
57     */
58    public Object   acquire(String   name) throws IllegalArgumentException  ;
59  
60    /**
61     * @see #get(String, String)
62     * @throws IllegalArgumentException
63     *           if the desired object could not be found.
64     */
65    public Object   acquire(String   name, String   scope)
66        throws IllegalArgumentException  ;
67  
68    /**
69     * Puts the given object in the given scope, under the given name. If no scope
70     * currently exists for the scope name that is specified, the parent
71     * environment is searched - and so on; if still no scope exist that
72     * correspond to the given scope name, new one is created within this
73     * instance. If an object is already bound under the given name (in the
74     * specified scope), it is overwritten.
75     * 
76     * @param name
77     *          the name under which to bind the object.
78     * @param obj
79     *          the <code>Object</code> to bind.
80     * @param scope
81     *          the name of the scope under which to bind the object.
82     */
83    public void put(String   name, Object   obj, String   scope);
84  
85    /**
86     * This methods internally binds the given scope under the given name within
87     * this instance. If a scope with an identical name exists in a parent
88     * environment, that it will become invisible to clients of this instance
89     * (this instance's identically named scope will prevail).
90     * <p>
91     * In addition, if a scope with the given name already exists within this
92     * instance, it is overwritten.
93     * 
94     * @param name
95     *          the name under which the given scope should be kept within this
96     *          instance.
97     * @param scope
98     *          a <code>Scope</code>.
99     */
100   public void addScope(String   name, Scope scope);
101 
102   /**
103    * Removes the scope with the given name from this instance. Parent
104    * environments are not affected by this operation, even if no such scope
105    * exists at this instance's level.
106    * 
107    * @param name
108    *          the name of a scope.
109    */
110   public void removeScope(String   name);
111 
112   /**
113    * Returns the scope that corresponds to the given name. If no such scope is
114    * found at this instance's level, ancestors are searched.
115    * 
116    * @param name
117    *          the name of a scope.
118    * @return the <code>Scope</code> corresponding to the given name, or
119    *         <code>null</code> if no such scope exists.
120    */
121   public Scope getScope(String   name);
122 
123   /**
124    * @param name
125    *          the name of a scope.
126    * @return <code>true</code> if this instance or one of its ancestors has
127    *         such a scope.
128    */
129   public boolean hasScope(String   name);
130 
131 }
132
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags