Author: kylem Date: Mon Jan 3 16:41:50 2005 New Revision: 124047 URL: http://svn.apache.org/viewcvs?view=rev&rev=124047 Log: Update lifecycle and resource events examples in the Controls Programming model doc.
Modified: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsOverview.xml incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsProgramming.xml Modified: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsOverview.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsOverview.xml?view=diff&rev=124047&p1=incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsOverview.xml&r1=124046&p2=incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsOverview.xml&r2=124047 ============================================================================== --- incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsOverview.xml (original) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsOverview.xml Mon Jan 3 16:41:50 2005 @@ -178,10 +178,13 @@ </p> <source> -public interface TimerControl extends Control [EMAIL PROTECTED] +public interface TimerControl { public void start() throws IllegalStateException; public void stop(); + + @EventSet public interface Callback { public void onTimeout(long time); @@ -242,7 +245,8 @@ <p> The declaration of the TimerControl JSR-175 attribute and member might look something like: </p> -<source>Package com.myco; +<source> [EMAIL PROTECTED] public @interface Timer { /** @return timeout Duration as string */ @@ -289,12 +293,12 @@ <p> An example of the customized interface for this Control might look like: </p> - <source>public interface CustomerDatabase extends ControlExtension, DatabaseControl + <source>@ControlExtension public interface CustomerDatabase extends DatabaseControl { - @sql statement="INSERT INTO CUSTOMERDB (ID, NAME) VALUES ({id}, {name})" + @sql (statement="INSERT INTO CUSTOMERDB (ID, NAME) VALUES ({id}, {name})") int newCustomer(int id, String name) throws SQLException; - @sql statement="SELECT * FROM CUSTOMERDB WHERE ID = {id}" + @sql (statement="SELECT * FROM CUSTOMERDB WHERE ID = {id}") Customer findCustomer(int id); }</source> <p> @@ -386,7 +390,7 @@ The programmatic client model follows the basic pattern of JavaBeans construction and event handling: </p> <source>TimerControlBean myTimerBean = - (TimerControlBean)ControlBean.instantiate(classloader, "com.myco.TimerControlBean"); + (TimerControlBean)Controls.instantiate(classloader, "com.myco.TimerControlBean"); myTimerBean.setTimeout("3 seconds"); myTimerBeans.addTimerControlEventListener( new TimerControlEventListener() // anonymous event handler class Modified: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsProgramming.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsProgramming.xml?view=diff&rev=124047&p1=incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsProgramming.xml&r1=124046&p2=incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsProgramming.xml&r2=124047 ============================================================================== --- incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsProgramming.xml (original) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsProgramming.xml Mon Jan 3 16:41:50 2005 @@ -181,23 +181,20 @@ <p>The client model for Controls supports instantiation of a new Control instance using the same factory-based model supported by JavaBeans. For example, the following code could be used to create a new instance of the JmsMessageControlBean generated class:</p> <p><strong>Programmatic Instantiation (Client Code)</strong></p> <source>JmsMessageControlBean myJmsBean = (JmsMessageControlBean) -<strong>java.beans.Beans.instantiate( - cl, - "org.apache.beehive.controls.examples.JmsMessageControlBean" -);</strong></source> +<strong>java.beans.Beans.instantiate(cl, + "org.apache.beehive.controls.examples.JmsMessageControlBean");</strong></source> <p>The Control runtime also provides an extended factory model that allows metadata attributes to be passed into the factory constructor:</p> <p><strong>Programmatic Instantiation with Properties (Client Code)</strong></p> <source>import org.apache.beehive.controls.api.bean.Controls; +import org.apache.beehive.controls.api.properties.PropertyKey; import org.apache.beehive.controls.api.properties.PropertyMap; +import org.apache.beehive.controls.api.properties.BeanPropertyMap; -PropertyMap jmsAttr = new PropertyMap(JmsMessageControl.Destination.class); -jmsAttr.setProperty("name", "InvoiceQueue"); +PropertyMap jmsAttr = new BeanPropertyMap(JmsControl.Destination.class); +jmsAttr.setProperty(new PropertyKey(JmsControl.Destination.class, "name"), "InvoiceQueue"); JmsMessageControlBean myJmsBean = (JmsMessageControlBean) - <strong>Controls.instantiate( - cl, - "org.apache.beehive.controls.examples.JmsMessageControlBean", - jmsAttr - );</strong> </source> + <strong>Controls.instantiate(cl, + "org.apache.beehive.controls.examples.JmsMessageControlBean", jmsAttr);</strong></source> <p>In this example, the JmsMessageControlBean is being constructed with the Destination "name" property set to "InvoiceQueue". The AttributeMap class is a simple helper class that can hold a set of name-value pairs of a Controlâs properties, which are initialized by the factory-based constructor. More details on Controls properties are provided in a later section.</p> </section> </section> @@ -908,66 +905,100 @@ </section> <section> - <title>13. Context Events</title> - <p>The Control programming model also exposes a basic set of lifecycle events to enable the Control to perform efficient initialization and resource management. These events are delivered by the peer ControlBeanContext associated with a ControlBean instance. A listener can register to receive these events using the addCallbackListener API on ControlBeanContext; the actual Callback event interface itself is defined there as well:</p> + <title>13. Context and Resource Events</title> + <p>The Controls programming model includes two contextual services that provide a set of supporting life cycle and resource events to assist the author of a Control Implementation. This section describes the events exposed by these services: + <section> + <title>13.1 Life Cycle Events</title> + <p>The ControlBeanContext life cycle events provide notification to the associated ControlBean derived class and Control Implementation Class (and potentially other interested listeners) of significant events related to the peer bean instance.</p> + <p>The Control programming model exposes a basic set of lifecycle events to enable the Control to perform efficient initialization and state management. These events are delivered by the peer ControlBeanContext associated with a ControlBean instance. A listener can register to receive these events using the addLifeCycleListener API on ControlBeanContext; the actual LifeCycle event interface itself is defined there as well:</p> <p><strong>Context Life Cycle Events</strong></p> -<source>import org.apache.beehive.controls.api.context; +<source>package org.apache.beehive.controls.api.context; public interface ControlBeanContext - extends java.beans.beancontext.BeanContextServices + extends java.beans.beancontext.BeanContextServices { ... - <strong>public interface Callback extends java.util.EventListener + @EventSet + <strong>public interface LifeCycle { public void onCreate(); - public void onAcquire(); - public void onRelease(); + public void onPropertyChange(PropertyChangeEvent pce); + public void onVetoablePropertyChange(PropertyChangeEvent pce) + throws PropertyVetoException; } - public void addCallbackListener(Callback lifecycleListener); - public void removeCallbackListener(Callback lifecycleListener); </strong> + public void addLifeCycleListener(LifeCycle listener); + public void removeLifeCycleListener(LifeCycle listener);</strong> }</source> -<p>The specific life cycle events are described in the following section:</p> - <section> - <title>13.1 Life Cycle Events</title> - <p>The ControlBeanContext life cycle events provide notification to the associated ControlBean derived class and Control Implementation Class (and potentially other interested listeners) of significant events related to the peer bean instance.</p> +<p>The specific life cycle and resource events are described in the following section:</p> <section> <title>13.1.1 The onCreate Event</title> <p>The onCreate event is delivered when the Control Implementation instance associated with the ControlBean has been constructed and all declarative initialization has been completed. This provides an opportunity for the implementation instance to perform any additional initialization required; implementation instances should generally use the onCreate event instead of writing constructor code.</p> </section> <section> - <title>13.1.2 The onAcquire Event</title> - <p>The onAcquire event is delivered to a registered listener the first time a ControlBean operation is invoked within a particular resource context. It provides an opportunity for the Control Implementation instance (or other related entities, such as a contextual service provider) to acquire any short-term resources (connections, sessions, etc) needed by the ControlBean.</p> -<p>The onAcquire event is guaranteed to be delivered once (and only once) prior to invocation of any operation within a resource context; it is also guaranteed that a paired onRelease event will be delivered when the resource context ends.</p> + <title>13.1.2 The onPropertyChange Event</title> + <p>The onPropertyChange event is delivered to a registered listener any time a bound property is changed on the ControlBean. This provides an opportunity for the Control Implementation to change any internal state that might be dependent upon a property value.</p> + </section> + + <section> + <title>13.1.3 The onVetoableChange Event</title> + <p>The onVetoableChange event is delivered to a registered listener any time a constrained property is changed on the ControlBean. This provides an opportunity for the Control Implementation to validate the set value and veto any client-initiated change if necessary (by throwing a VetoException</p> + </section> + + </section> + <section> + <title>13.2 Resource Events</title> +<p>The Control programming model exposes a set of resource events to enable the control to manage external resources (connections, sessions, ...) that it needs to provide its services. The model enables resources to be acquired and held for a resource scope that is determined by the container in which the Controls are executing. For example, in the servlet container, the scope might enable resources to be held for the duration of processing a single http request.</p> + +<source>package org.apache.beehive.controls.api.context; + +public interface ResourceContext +{ + ... + @EventSet + <strong>public interface ResourceEvents + { + public void onAcquire(); + public void onRelease(); + } + + public void addResourceEventsListener(ResourceEvents listener); + public void removeResourceEventsListener(ResourceEvents listener);</strong> +}</source> + <section> + <title>13.2.1 The onAcquire Event</title> + <p>The onAcquire event is delivered to a registered listener the first time a ControlBean operation is invoked within a particular resource scope. It provides an opportunity for the Control Implementation instance (or other related entities, such as a contextual service provider) to acquire any short-term resources (connections, sessions, etc) needed by the ControlBean.</p> +<p>The onAcquire event is guaranteed to be delivered once (and only once) prior to invocation of any operation within a resource scope; it is also guaranteed that a paired onRelease event will be delivered when the resource scope ends.</p> <p>For more details on resource management, refer to the <link href="controlsOverview.html">Control Overview</link> document.</p> </section> + <section> - <title>13.1.3 The onRelease Event</title> - <p>The onRelease event is the companion event to onAcquire. It is guaranteed to be called once (and only once) on any bean instance that has received an onAcquire event, when its associated resource context has ended. It acts as the signal that any short-term resources (connections, sessions, etc) acquired by the Control should be released.</p> + <title>13.2.2 The onRelease Event</title> + <p>The onRelease event is the companion event to onAcquire. It is guaranteed to be called once (and only once) on any bean instance that has received an onAcquire event, when its associated resource scope has ended. It acts as the signal that any short-term resources (connections, sessions, etc) acquired by the Control should be released.</p> </section> </section> <section> - <title>13.2 Receiving Life Cycle Events</title> -<p>For a Control Implementation Class, the model for receiving context life cycle events is consistent with the general client model for event registration and delivery. Both declarative and programmatic mechanisms are supported.</p> + <title>13.3 Receiving Life Cycle or Resource Events</title> +<p>For a Control Implementation Class, the model for receiving context life cycle or resource events is consistent with the general client model for event registration and delivery. Both declarative and programmatic mechanisms are supported.</p> <section> - <title>13.2.1 Declarative Access to Life Cycle Events</title> - <p>A Control Implementation Class can receive Life Cycle Events simply by declaring the annotated @Context ControlBeanContext and then defining event handlers that follow the <contextFieldName>_<eventName> convention.</p> + <title>13.3.1 Declarative Access to events</title> + <p>A Control Implementation Class can receive Life Cycle or Resource Events simply by declaring the annotated @Context Context interface and then defining event handlers that follow the <contextFieldName>_<eventName> convention.</p> <p>The following sample code shows the JmsMessageControl registering to receive onAcquire and onRelease events:</p> <p><strong>Declarative Handling of Life Cycle Events (Control Implementation Class)</strong></p> <source>package org.apache.beehive.controls.examples; import org.apache.beehive.controls.api.context.Context; -import org.apache.beehive.controls.api.context.ControlBeanContext; +import org.apache.beehive.controls.api.context.ResourceContext; import org.apache.beehive.controls.api.events.EventHandler; Public class JmsMessageControlImpl implements JmsMessageControl { - <strong>@Context ControlBeanContext context; + <strong>@Context ResourceContext resourceContext; @EventHandler( - field="context", - eventSet=ControlBeanContext.LifeCycle.class, + field="resourceContext", + eventSet=ResourceContext.ResourceEvents.class, eventName="onAcquire" ) public void onAcquire() @@ -977,8 +1008,8 @@ } @EventHandler( - field="context", - eventSet=ControlBeanContext.LifeCycle.class, + field="resourceContext", + eventSet=ResourceContext.ResourceEvents.class, eventName="onRelease" ) public void onRelease() @@ -987,28 +1018,28 @@ ... }</strong> }</source> -<p>When using the declarative mechanism, a Control Implementation Class is free to implement only a subset of the life cycle listeners; it is not necessary that it provide a handler for all events.</p> +<p>When using the declarative mechanism, a Control Implementation Class is free to implement only a subset of the events; it is not necessary that it provide a handler for all events.</p> </section> <section> - <title>13.2.2 Programmatic Access to Life Cycle Events</title> - <p>An external entity (such as contextual service provider or even a client) is also able to register for life cycle events on a ControlBean instance as well. This is done by obtaining a reference to the peer ControlBeanContext for the instance using the getPeerContext API, and then using the addCallbackListener API to register a lifecycle event listener.</p> + <title>13.3.2 Programmatic Access to Events</title> + <p>An external entity (such as contextual service provider or even a client) is also able to register for life cycle events on a ControlBean instance as well. This is done by obtaining a reference to the peer ControlBeanContext for the instance using the getControlBeanContext API, and then using the addLifeCycleListener API to register a lifecycle event listener.</p> <p>This is shown by the following code:</p> <p><strong>Programmatic Handling of Life Cycle Events (Control Implementation Class) </strong></p> <source> JmsMessageControlBean myJmsBean = ...; ControlBeanContext peerContext = myBean.getControlBeanContext(); - peerContext.addCallbackListener( + peerContext.addLifeCycleListener( new ControlBeanContext.LifeCycle() { public void onCreate() { ... }; - public void onAcquire() { ... }; - public void onRelease() { ... }; + public void onPropertyChange(PropertyChangeEvent pce) { ... }; + public void onVetoableChange(PropertyChangeEvent pce) { ... }; } );</source> </section> </section> <section> - <title>13.3 JavaBean Context Events</title> + <title>13.4 JavaBean Context Events</title> <p>The org.apache.beehive.controls.api.context.ControlBeanContext API extends the following standard JavaBean context APIs:</p> <ul> <li> java.beans.BeanContextChild</li> @@ -1018,15 +1049,15 @@ <p>These APIs provide access to a standard set of JavaBean events that the Control Implementation Class can register an interest in. </p> <p><em>[todo][Issue: there is not a declarative mechanism for receiving these events, but probably should be.]</em></p> <section> - <title>13.3.1 PropertyChange Events</title> + <title>13.4.1 PropertyChange Events</title> <p>The java.beans.BeanContextChild interface provides the addPropertyChangeListener() and addVetoableChangeListener() APIs to register for notification when a property is modified.</p> </section> <section> - <title>13.3.2 Membership Events</title> + <title>13.4.2 Membership Events</title> <p>The java.beans.BeanContext interface provides the addMembershipChangeListener() API to register for notification whenever a child is added or removed from the BeanContext.</p> </section> <section> - <title>13.3.3 Context Services Events</title> + <title>13.4.3 Context Services Events</title> <p>The java.beans.BeanContextServices interface provides the addBeanContextServicesListener API to register for notification when new contextual services become available or are revoked.</p> </section> </section> @@ -1089,7 +1120,7 @@ public interface Callback { /** - * The onSend event is delivered to a registered + * The onMessage event is delivered to a registered * client listener whenever a * message has been sent by the Control. * @param msg the message that was sent @@ -1182,6 +1213,7 @@ import org.apache.beehive.controls.api.bean.ControlImplementation; import org.apache.beehive.controls.api.bean.Extensible; import org.apache.beehive.controls.api.context.ControlBeanContext; +import org.apache.beehive.controls.api.context.ResourceContext; import org.apache.beehive.controls.api.events.Client; import org.apache.beehive.controls.api.events.EventHandler; @@ -1228,6 +1260,11 @@ transient javax.jms.Session _session; transient javax.jms.MessageProduction _producer; + /** + * The Resourceontext instance associated with the Control + */ + @Context ResouceContext resourceContext; + /* * The onAcquire event handler * This method will be called prior to any operation with @@ -1236,8 +1273,8 @@ * writer instance, for use within the operation. */ @EventHandler( - field="context", - eventSet=ControlBeanContext.Lifecycle.class, + field="resourceContext", + eventSet=ResourceContext.ResourceEvents.class, eventName="onAcquire" ) public void onBeanAcquire() @@ -1303,8 +1340,8 @@ * This method will release all resource acquired by onAcquire. */ @EventHandler ( - field="context", - eventSet=ControlBeanContext.Lifecycle.class, + field="resourceContext", + eventSet=ResourceContext.ResourceEvents.class, eventName="onRelease" ) public void onRelease()
