beehive-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ky...@apache.org
Subject svn commit: r124047 - /incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsOverview.xml /incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsProgramming.xml
Date Tue, 04 Jan 2005 00:41:52 GMT
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
+@ControlInterface
+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>
+@PropertySet
 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 &lt;contextFieldName>_&lt;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 &lt;contextFieldName>_&lt;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()

Mime
View raw message