001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: *
017: * $Header:$
018: */
019: package org.apache.beehive.controls.api.context;
020:
021: import java.beans.beancontext.BeanContextServices;
022: import java.beans.PropertyChangeEvent;
023: import java.beans.PropertyVetoException;
024: import java.lang.annotation.Annotation;
025: import java.lang.reflect.AnnotatedElement;
026: import java.lang.reflect.Method;
027:
028: import org.apache.beehive.controls.api.bean.ControlBean;
029: import org.apache.beehive.controls.api.events.EventSet;
030: import org.apache.beehive.controls.api.properties.PropertyMap;
031:
032: /**
033: * The ControlBeanContext interface defines the basic set of contextual services and lifecycle
034: * events for Java ControlBean implementations.
035: * <p>
036: * ControlBeanContext also extends the <code>java.beans.beancontext.BeanContextServices</code>
037: * interface, so it also provide core Java Beans services for managing contained controls,
038: * looking up contextual services, and locating the parent {@link java.beans.beancontext.BeanContext} context.
039: * <p>
040: * A Control implementation class can obtain access to the ControlBeanContext associated
041: * with it by declaring an instance field of this type and annotating it with the
042: * <code>org.apache.beehive.controls.api.context.Context</code> annotation, as in the following
043: * example:
044: *
045: * <code><pre>
046: * import org.apache.beehive.controls.api.context.Context;
047: * import org.apache.beehive.controls.api.context.ControlBeanContext;
048: *
049: * <sp>@ControlImplementation
050: * public class MyControlImpl
051: * {
052: * <sp>@Context
053: * ControlBeanContext myContext;
054: * }
055: * </pre></code>
056: * The Java Control runtime will automatically initialize this field to a reference to the
057: * ControlBeanContext associated with the implementation instance.
058: */
059: public interface ControlBeanContext extends BeanContextServices {
060: /**
061: * Returns the public or extension interface associated with the context
062: */
063: public Class getControlInterface();
064:
065: /**
066: * Returns the current value of PropertySet for the associated control, or
067: * null if the property set has not been bound. Actual bindings for property
068: * values may be the result of annotations on the control field or class,
069: * property setting via factory arguments or setter APIs, or external
070: * configuration.
071: *
072: * @param propertySet the PropertySet to return
073: * @return the requested PropertySet instance, or null if not bound
074: *
075: * @see org.apache.beehive.controls.api.properties.PropertySet
076: */
077: public <T extends Annotation> T getControlPropertySet(
078: Class<T> propertySet);
079:
080: /**
081: * Returns the current value of PropertySet for the provided method, or null
082: * if the property set has not been bound for this method.
083: *
084: * @param m the Method to check for properties.
085: * @param propertySet the PropertySet to return
086: * @return the requested PropertySet instance, or null if not bound
087: *
088: * @see org.apache.beehive.controls.api.properties.PropertySet
089: */
090: public <T extends Annotation> T getMethodPropertySet(Method m,
091: Class<T> propertySet) throws IllegalArgumentException;
092:
093: /**
094: * Returns the current value of PropertySet for the selected (by index) method parameter,
095: * or null if the property set has not been bound for this method.
096: *
097: * @param m the Method to check for properties
098: * @param i the index of the method parameter to check for the request PropertySet
099: * @param propertySet the PropertySet to return
100: * @return the request PropertySet instance, or null if not bound
101: */
102: public <T extends Annotation> T getParameterPropertySet(Method m,
103: int i, Class<T> propertySet)
104: throws IllegalArgumentException, IndexOutOfBoundsException;
105:
106: /**
107: * Returns an array containing the parameter names for the specified method
108: *
109: * @param m the Method whose parameter names should be returned.
110: * @return the array of parameter names (or an empty array if no parameters)
111: */
112: public String[] getParameterNames(Method m)
113: throws IllegalArgumentException;
114:
115: /**
116: * Returns the value of a named method parameter from the input parameter array.
117: *
118: * @param m the Method associated with the input parameter list
119: * @param parameterName the name of the requested parameter
120: * @param parameters the array of method parameters
121: * @return the element in the input parameter array that corresponds to the requested
122: * parameter
123: */
124: public Object getParameterValue(Method m, String parameterName,
125: Object[] parameters) throws IllegalArgumentException;
126:
127: /**
128: * Returns the current set of properties (in PropertyMap format) for the control
129: * associated with the context. The return map will contain the values for all bound
130: * properties for the control.
131: * @return the PropertyMap containing properties of the control. This map is read-only;
132: * any changes to it will not effect the local bean instance.
133: *
134: * @see org.apache.beehive.controls.api.properties.PropertyMap
135: */
136: public PropertyMap getControlPropertyMap();
137:
138: /**
139: * Returns an instance of a contextual service based upon the local context. If
140: * no provider for this service is available, then null will be returned.
141: *
142: * @param serviceClass the class of the requested service
143: * @param selector the service dependent parameter
144: * @return an instance of the request service, or null if unavailable
145: *
146: * @see java.beans.beancontext.BeanContextServices#getService
147: */
148: public <T> T getService(Class<T> serviceClass, Object selector);
149:
150: /**
151: * Returns a ControlHandle instance that enables operations and events to be dispatched
152: * to the target control, if it is running inside of a container that supports external
153: * event dispatch. If the runtime container for the control does not support this
154: * functionality, a value of null will be returned.
155: *
156: * @return a ControlHandle instance for the control, or null.
157: *
158: * @see org.apache.beehive.controls.api.context.ControlHandle
159: */
160: public ControlHandle getControlHandle();
161:
162: /**
163: * Returns the PropertyMap containing default properties for an AnnotatedElement
164: * in the current context.
165: */
166: public PropertyMap getAnnotationMap(AnnotatedElement annotElem);
167:
168: /**
169: * Returns the ClassLoader used to load the ControlBean class associated with the control
170: * implementation instance. This is useful for loading other classes or resources that may
171: * have been packaged with the public interfaces of the Control type (since they may not
172: * necessarily have been packaged directly with the implementation class).
173: */
174: public java.lang.ClassLoader getClassLoader();
175:
176: /**
177: * Returns true if this container guarantees single-threaded behaviour.
178: */
179: public boolean isSingleThreadedContainer();
180:
181: /**
182: * Returns the peer ControlBean associated with this ControlBeanContext. If the context
183: * represents a top-level container (i.e. not a Control containing other controls), null
184: * will be returned.
185: */
186: public ControlBean getControlBean();
187:
188: /**
189: * Returns any child ControlBean that is nested in the ControlBeanContext, or null
190: * if no matching child is found. The <code>id</code> parameter is relative to
191: * the current nesting context, not an absolute control id.
192: */
193: public ControlBean getBean(String id);
194:
195: /**
196: * The Lifecycle event interface defines a set of lifecycle events exposed by the
197: * ControlBeanContext to any registered listener.
198: */
199: @EventSet
200: public interface LifeCycle {
201: /**
202: * The onCreate event is delivered when the control implementation instance for
203: * the associated bean has been instantiated and fully initialized.
204: */
205: public void onCreate();
206:
207: /**
208: * The onPropertyChange event is delivered when a property setter method is
209: * called for a bound property on the Java Control.
210: *
211: * @see org.apache.beehive.controls.api.packaging.PropertyInfo
212: */
213: public void onPropertyChange(PropertyChangeEvent pce);
214:
215: /**
216: * The onVetoableChange event is delivered when a property setter method is
217: * called for a constrained property on the Java Control. A PropertyVetoException
218: * may be thrown to veto the change made by the client.
219: *
220: * @see org.apache.beehive.controls.api.packaging.PropertyInfo
221: */
222: public void onVetoableChange(PropertyChangeEvent pce)
223: throws PropertyVetoException;
224: }
225:
226: /**
227: * Registers a new listener for LifeCycle events on the context.
228: *
229: * @see org.apache.beehive.controls.api.context.ControlBeanContext.LifeCycle
230: */
231: public void addLifeCycleListener(LifeCycle listener);
232:
233: /**
234: * Removes a currently registered LifeCycle event listener on the context.
235: *
236: * @see org.apache.beehive.controls.api.context.ControlBeanContext.LifeCycle
237: */
238: public void removeLifeCycleListener(LifeCycle listener);
239: }
|