ControlBeanContext


1   package org.apache.beehive.controls.api.context;
2   /*
3    * Copyright 2004 The Apache Software Foundation.
4    *
5    * Licensed under the Apache License, Version 2.0 (the "License");
6    * you may not use this file except in compliance with the License.
7    * You may obtain a copy of the License at
8    * 
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   * 
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   *
17   * $Header:$
18   */
19  
20  import java.beans.beancontext.BeanContextServices  ;
21  import java.beans.PropertyChangeEvent  ;
22  import java.beans.PropertyVetoException  ;
23  import java.lang.annotation.Annotation  ;
24  import java.lang.reflect.AnnotatedElement  ;
25  import java.lang.reflect.Method  ;
26  
27  import org.apache.beehive.controls.api.bean.ControlBean;
28  import org.apache.beehive.controls.api.events.EventSet;
29  import org.apache.beehive.controls.api.properties.PropertyMap;
30  
31  /**
32   * The ControlBeanContext interface defines the basic set of contextual services and lifecycle
33   * events for Java ControlBean implementations.
34   * <p>
35   * ControlBeanContext also extends the <code>java.beans.beancontext.BeanContextServices</code>
36   * interface, so it also provide core Java Beans services for managing contained controls,
37   * looking up contextual services, and locating the parent BeanContext context.
38   * <p>
39   * A Control implementation class can obtain access to the ControlBeanContext associated
40   * with it by declaring an instance field of this type and annotating it with the
41   * <code>org.apache.beehive.controls.api.context.Context</code> annotation, as in the following
42   * example:
43   *
44   * <code><pre>
45   * import org.apache.beehive.controls.api.context.Context;
46   * import org.apache.beehive.controls.api.context.ControlBeanContext;
47   *
48   * <sp>@ControlImplementation
49   * public class MyControlImpl
50   * {
51   *     <sp>@Context
52   *     ControlBeanContext myContext;
53   * }
54   * </pre></code>
55   * The Java Control runtime will automatically initialize this field to a reference to the
56   * ControlBeanContext associated with the implementation instance.
57   */
58  public interface ControlBeanContext extends BeanContextServices  
59  {
60      /**
61       * Returns the public or extension interface associated with the context
62       */
63      public Class   getControlInterface();
64  
65      /**
66       * Returns the current value of PropertySet for the associated control, or
67       * null if the property set has not been bound.  Actual bindings for property
68       * values may be the result of annotations on the control field or class,
69       * property setting via factory arguments or setter APIs, or external
70       * configuration.
71       *
72       * @param propertySet the PropertySet to return
73       * @return the requested PropertySet instance, or null if not bound
74       *
75       * @see org.apache.beehive.controls.api.properties.PropertySet
76       */
77      public <T extends Annotation  > T getControlPropertySet(Class  <T> propertySet);
78  
79      /**
80       * Returns the current value of PropertySet for the provided method, or null
81       * if the property set has not been bound for this method.
82       *
83       * @param m the Method to check for properties.
84       * @param propertySet the PropertySet to return
85       * @return the requested PropertySet instance, or null if not bound
86       *
87       * @see org.apache.beehive.controls.api.properties.PropertySet
88       */
89      public <T extends Annotation  > T getMethodPropertySet(Method   m, Class  <T> propertySet)
90                                      throws IllegalArgumentException  ;
91  
92      /**
93       * Returns the current value of PropertySet for the selected (by index) method parameter,
94       * or null if the property set has not been bound for this method.
95       *
96       * @param m the Method to check for properties
97       * @param i the index of the method parameter to check for the request PropertySet
98       * @param propertySet the PropertySet to return
99       * @return the request PropertySet instance, or null if not bound
100      */
101     public <T extends Annotation  > T getParameterPropertySet(Method   m, int i, Class  <T> propertySet)
102                                     throws IllegalArgumentException  , IndexOutOfBoundsException  ;
103 
104     /**
105      * Returns an array containing the parameter names for the specified method
106      *
107      * @param m the Method whose parameter names should be returned.
108      * @return the array of parameter names (or an empty array if no parameters)
109      */
110     public String   [] getParameterNames(Method   m) throws IllegalArgumentException  ;
111 
112     /**
113      * Returns the value of a named method parameter from the input parameter array.
114      *
115      * @param m the Method associated with the input parameter list
116      * @param parameterName the name of the requested parameter
117      * @param parameters the array of method parameters
118      * @return the element in the input parameter array that corresponds to the requested
119      *         parameter
120      */
121     public Object   getParameterValue(Method   m, String   parameterName, Object   [] parameters)
122                   throws IllegalArgumentException  ;
123 
124     /**
125      * Returns the current set of properties (in PropertyMap format) for the control 
126      * associated with the context.  The return map will contain the values for all bound 
127      * properties for the control.
128      * @return the PropertyMap containing properties of the control.  This map is read-only;
129      * any changes to it will not effect the local bean instance.
130      *
131      * @see org.apache.beehive.controls.api.properties.PropertyMap
132      */
133     public PropertyMap getControlPropertyMap();
134 
135     /**
136      * Returns an instance of a contextual service based upon the local context.  If
137      * no provider for this service is available, then null will be returned.
138      *
139      * @param serviceClass the class of the requested service
140      * @param selector the service dependent parameter
141      * @return an instance of the request service, or null if unavailable
142      *
143      * @see java.beans.beancontext.BeanContextServices#getService
144      */
145     public <T> T getService(Class  <T> serviceClass, Object   selector);
146 
147     /**
148      * Returns a ControlHandle instance that enables operations and events to be dispatched
149      * to the target control, if it is running inside of a container that supports external
150      * event dispatch.  If the runtime container for the control does not support this
151      * functionality, a value of null will be returned.
152      *
153      * @return a ControlHandle instance for the control, or null.
154      *
155      * @see org.apache.beehive.controls.api.context.ControlHandle
156      */
157     public ControlHandle getControlHandle();
158 
159     /**
160      * Returns the PropertyMap containing default properties for an AnnotatedElement
161      * in the current context.
162      */
163     public PropertyMap getAnnotationMap(AnnotatedElement   annotElem);
164 
165     /**
166      * Returns the ClassLoader used to load the ControlBean class associated with the control
167      * implementation instance.  This is useful for loading other classes or resources that may 
168      * have been packaged with the public interfaces of the Control type (since they may not 
169      * necessarily have been packaged directly with the implementation class).
170      */
171     public java.lang.ClassLoader   getClassLoader();
172 
173     /**
174      * Returns true if this container guarantees single-threaded behaviour.
175      */
176     public boolean isSingleThreadedContainer();
177 
178     /**
179      * Returns the peer ControlBean associated with this ControlBeanContext.  If the context
180      * represents a top-level container (i.e. not a Control containing other controls), null
181      * will be returned.
182      */
183     public ControlBean getControlBean();
184      
185     /**
186      * Returns any child ControlBean that is nested in the ControlBeanContext, or null
187      * if no matching child is found.  The <code>id</code> parameter is relative to
188      * the current nesting context, not an absolute control id.
189      */
190     public ControlBean getBean(String   id);
191 
192     /**
193      * The Lifecycle event interface defines a set of lifecycle events exposed by the
194      * ControlBeanContext to any registered listener.
195      */
196     @EventSet
197     public interface LifeCycle
198     {
199         /**
200          * The onCreate event is delivered when the control implementation instance for
201          * the associated bean has been instantiated and fully initialized.
202          */
203         public void onCreate();
204 
205         /**
206          * The onPropertyChange event is delivered when a property setter method is
207          * called for a bound property on the Java Control.
208          *
209          * @see org.apache.beehive.controls.api.packaging.PropertyInfo
210          */
211         public void onPropertyChange(PropertyChangeEvent   pce);
212 
213         /**
214          * The onVetoableChange event is delivered when a property setter method is
215          * called for a constrained property on the Java Control.  A PropertyVetoException
216          * may be thrown to veto the change made by the client.
217          *
218          * @see org.apache.beehive.controls.api.packaging.PropertyInfo
219          */
220         public void onVetoableChange(PropertyChangeEvent   pce) throws PropertyVetoException  ;
221     }
222 
223     /**
224      * Registers a new listener for LifeCycle events on the context.
225      *
226      * @see org.apache.beehive.controls.api.context.ControlBeanContext.LifeCycle
227      */
228     public void addLifeCycleListener(LifeCycle listener);
229 
230     /**
231      * Removes a currently registered LifeCycle event listener on the context.
232      *
233      * @see org.apache.beehive.controls.api.context.ControlBeanContext.LifeCycle
234      */
235     public void removeLifeCycleListener(LifeCycle listener);
236 }
237
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags