You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@beehive.apache.org by st...@apache.org on 2005/09/15 00:55:16 UTC
svn commit: r280962 -
/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/programming.xml
Author: steveh
Date: Wed Sep 14 15:55:12 2005
New Revision: 280962
URL: http://svn.apache.org/viewcvs?rev=280962&view=rev
Log:
(1) A fix for BEEHIVE-917.
(2) General review of doc.
Modified:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/programming.xml
Modified: beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/programming.xml
URL: http://svn.apache.org/viewcvs/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/programming.xml?rev=280962&r1=280961&r2=280962&view=diff
==============================================================================
--- beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/programming.xml (original)
+++ beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/programming.xml Wed Sep 14 15:55:12 2005
@@ -7,108 +7,231 @@
<body>
<section id="overview">
<title>Overview</title>
- <p>The Control architecture is a lightweight component framework based upon JavaBeans, which exposes a simple and consistent client model for accessing a variety of resource types. Controls take the base functionality of JavaBeans and add in the following unique new capabilities:</p>
-<ul>
- <li>Enhanced authoring model: uses a public interface contract and an associated implementation class to enable generation of a supporting JavaBean class for handling the details of property management and initialization. </li>
-
- <li>Extensibility model: enables the construction of views and custom operations (with implied semantics) on the Control using metadata-annotated interfaces. </li>
-
- <li>JSR-175 metadata attributes and external configuration data: provides an enhanced configuration model for resource access.</li>
-</ul>
-<p>This document focuses on the Controls programming and configuration model from two distinct perspectives:</p>
-<ul>
- <li> The authoring and extensibility model for defining a new type of Control</li>
-
- <li> The client access model for declaring and using Controls</li>
-</ul>
-
- <p>An overview of the Control architecture and toolable access models can be found in the companion document entitled <a href="site:control_overview">Control Overview: Providing Simplified and Unified Access to J2EE Resources</a></p>
+ <p>
+ The Control architecture is a lightweight component framework based upon JavaBeans,
+ which exposes a simple and consistent client model for accessing a variety of resource
+ types. Controls take the base functionality of JavaBeans and add in the following
+ unique new capabilities:
+ </p>
+ <ul>
+ <li>
+ Enhanced authoring model: uses a public interface contract and an associated
+ implementation class to enable generation of a supporting JavaBean class for
+ handling the details of property management and initialization.
+ </li>
+ <li>
+ Extensibility model: enables the construction of views and custom operations
+ (with implied semantics) on the Control using metadata-annotated interfaces.
+ </li>
+ <li>
+ JSR-175 metadata attributes and external configuration data: provides an
+ enhanced configuration model for resource access.
+ </li>
+ </ul>
+ <p>
+ This document focuses on the Controls programming and configuration model from
+ two distinct perspectives:
+ </p>
+ <ul>
+ <li>
+ The authoring and extensibility model for defining a new type of Control
+ </li>
+ <li>
+ The client access model for declaring and using Controls
+ </li>
+ </ul>
+ <p>
+ An overview of the Control architecture and toolable access models can be found in
+ the companion document entitled <a href="site:control_overview">Control Overview:
+ Providing Simplified and Unified Access to J2EE Resources</a>
+ </p>
</section>
-
<section id="example">
<title>An Example</title>
- <p>In the course of describing the programming model for Controls, this document builds upon an example Control that simplifies the enqueueing of JMS messages with a specific format and set of properties. Once completed, client code to accomplish this should be as straightforward as:</p>
-<p><strong>Enqueueing using OrderQueueBean (<em>Client Code</em>)</strong></p>
+ <p>
+ In the course of describing the programming model for Controls, this document builds
+ upon an example Control that simplifies the enqueueing of JMS messages with a
+ specific format and set of properties. Once completed, client code to accomplish
+ this should be as straightforward as:
+ </p>
+ <p>
+ <strong>Enqueueing using OrderQueueBean (<em>Client Code</em>)</strong>
+ </p>
<source>OrderQueueBean orderBean = (OrderQueueBean)
java.beans.Beans.instantiate("org.apache.beehive.controls.examples.OrderQueueBean");
Order order = new Order(myID, new String [ ] {"item1", "item2"});
OrderBean.submitOrder(order, "01-28-2004");
</source>
-<p>This document starts with a brief overview of the Control Authoring and Client Programming Models to establish some basic context, eventually building to enable the example above.</p>
+ <p>
+ This document starts with a brief overview of the Control Authoring and Client
+ Programming Models to establish some basic context, eventually building to enable
+ the example above.
+ </p>
</section>
-
<section id="control_auth">
<title>The Control Authoring Model</title>
- <p>This section describes the basic authoring model for Controls. This includes a description of the following elements:</p>
+ <p>
+ This section describes the basic authoring model for Controls. This includes a
+ description of the following elements:
+ </p>
<ul>
- <li><strong><em>Control Public Interface</em></strong>: source file that defines the set of operations, events, extensibility model, and properties associated with the Control type.</li>
-
- <li><strong><em>Control Implementation Class</em></strong>: source file that provides the implementation of the operations and extensibility model described by the Control Public Interface.</li>
-
- <li><strong><em>ControlBean Generated Class</em></strong>: code-generated JavaBean class that is derived from the Control Public Interface and the Control Implementation Class by a Control compiler.</li>
+ <li>
+ <strong><em>Control Public Interface</em></strong>: source file that defines the set of operations, events,
+ extensibility model, and properties associated with the Control type.
+ </li>
+ <li>
+ <strong><em>Control Implementation Class</em></strong>: source file that provides the implementation of the
+ operations and extensibility model described by the Control Public Interface.
+ </li>
+ <li>
+ <strong><em>ControlBean Generated Class</em></strong>: code-generated JavaBean class that is derived from the
+ Control Public Interface and the Control Implementation Class by a Control compiler.
+ </li>
</ul>
- <p>This authoring model is a departure from the traditional JavaBeans programming model, which is largely based upon a set of conventions that a bean author is expected to follow when constructing a new JavaBean type. In the Controls model, the author defines operations, events, and properties in an interface (Control Public Interface) and builds an underlying implementation (Control Implementation Class). A Control compiler takes these two elements and generates a specialized type of JavaBean (ControlBean Generated Class), which represents the full client programmerâs view of the Control.</p>
-<p> There are two primary advantages of this model:</p>
-<ul>
- <li><strong>Simplicity.</strong> A key goal of any ease-of-use programming model is to free the developer from worrying about plumbing. Managing property values, event listener lists, and other basic JavaBean functions are fairly rote from implementation to implementation. The Controls architecture employs a unique variant of the Inversion of Control (IoC) design pattern based on JSR-175 metadata. This enables a Control Implementation Class to declaratively specify the events or services it requires to provide its semantics. The ControlBean Generated Class acts as a lightweight container to provide contextual hookup and implementation details.</li>
- <li><strong>Consistency.</strong> Instead of trying to provide consistency through convention, the Control compiler provides both verification and code generation services to ensure that the resulting implementation provides consistent APIs and behaviors for clients, tools, and application deployers or administrators.</li>
-</ul>
-<p><strong>Diagram: Control Architecture Elements and Flow</strong></p>
-<p><img src="images/conProg1.gif" alt=""/></p>
-<p>The client will interact with the Control by invoking operations defined on the Control Public Interface or dynamic property accessor methods on a ControlBean instance. The client can also express interest in any events the Control might generate by registering a listener to receive them.</p>
-<p>The following diagram represents the relationship between the Control Public Interface, the Control Implementation Class, and the ControlBean Generated Class:</p>
-<p><strong>Diagram: Relationships between Control Interface and Classes</strong></p>
-<p><img src="images/conProg2.gif" alt=""/></p>
-<p>The Control Public Interface defines the operations on the Control and will be implemented by both the Control Implementation Class and the ControlBean Generated Class. The ControlBean Generated Class will also define property accessor methods and internally will maintain the state of property values. It will also maintain a reference to one (and only one) Control Implementation instance. The Control Implementation instance, wrapped by a bean instance, provides the actual implementation of resource semantics for the Control.</p>
-<p>The subsequent sections will outline the various characteristics of Controls:</p>
-<ul>
- <li>Declaration / Instantiation</li>
- <li>Operations</li>
- <li>Events</li>
- <li>Contextual Services</li>
- <li>Properties</li>
- <li>Extensibility</li>
- <li>Composition</li>
- <li>Context Events</li>
-</ul>
-<p>Where applicable, the aspects of each of these characteristics will be explored in two dimensions: from the perspective of a Control author who is defining a new type of Control, and from the perspective of a Control client that is using the services of an available Control type.</p>
-<p>To make the descriptions more concrete, the characteristics will be presented within the context of a sample Control: the JmsMessageControl. This Control will provide a simplified client access model for enqueuing messages to a JMS queue or topic, freeing the client from having to learn the nuances of JMS client programming.</p>
+ <p>
+ This authoring model is a departure from the traditional JavaBeans programming model,
+ which is largely based upon a set of conventions that a bean author is expected to follow when constructing a new
+ JavaBean type. In the Controls model, the author defines operations, events, and properties in an interface
+ (Control Public Interface) and builds an underlying implementation (Control Implementation Class). A Control
+ compiler takes these two elements and generates a specialized type of JavaBean (ControlBean Generated Class),
+ which represents the full client programmerâs view of the Control.
+ </p>
+ <p>
+ There are two primary advantages of this model:
+ </p>
+ <ul>
+ <li>
+ <strong>Simplicity.</strong> A key goal of any ease-of-use programming model is to free the developer from
+ worrying about plumbing. Managing property values, event listener lists, and other basic JavaBean functions are
+ fairly rote from implementation to implementation. The Controls architecture employs a unique variant of the
+ Inversion of Control (IoC) design pattern based on JSR-175 metadata. This enables a Control Implementation Class
+ to declaratively specify the events or services it requires to provide its semantics. The ControlBean Generated
+ Class acts as a lightweight container to provide contextual hookup and implementation details.
+ </li>
+ <li>
+ <strong>Consistency.</strong> Instead of trying to provide consistency through convention, the Control compiler
+ provides both verification and code generation services to ensure that the resulting implementation provides
+ consistent APIs and behaviors for clients, tools, and application deployers or administrators.
+ </li>
+ </ul>
+ <p>
+ <strong>Diagram: Control Architecture Elements and Flow</strong>
+ </p>
+ <p>
+ <img src="images/conProg1.gif" alt=""/>
+ </p>
+ <p>
+ The client will interact with the Control by invoking operations defined on the Control Public Interface or dynamic
+ property accessor methods on a ControlBean instance. The client can also express interest in any events the Control
+ might generate by registering a listener to receive them.
+ </p>
+ <p>
+ The following diagram represents the relationship between the Control Public Interface, the Control Implementation
+ Class, and the ControlBean Generated Class:
+ </p>
+ <p>
+ <strong>Diagram: Relationships between Control Interface and Classes</strong>
+ </p>
+ <p>
+ <img src="images/conProg2.gif" alt=""/>
+ </p>
+ <p>
+ The Control Public Interface defines the operations on the Control and will be implemented by both the Control
+ Implementation Class and the ControlBean Generated Class. The ControlBean Generated Class will also define property
+ accessor methods and internally will maintain the state of property values. It will also maintain a reference to
+ one (and only one) Control Implementation instance. The Control Implementation instance, wrapped by a bean instance,
+ provides the actual implementation of resource semantics for the Control.
+ </p>
+ <p>
+ The subsequent sections will outline the various characteristics of Controls:
+ </p>
+ <ul>
+ <li>Declaration / Instantiation</li>
+ <li>Operations</li>
+ <li>Events</li>
+ <li>Contextual Services</li>
+ <li>Properties</li>
+ <li>Extensibility</li>
+ <li>Composition</li>
+ <li>Context Events</li>
+ </ul>
+ <p>
+ Where applicable, the aspects of each of these characteristics will be explored in two dimensions: from the
+ perspective of a Control author who is defining a new type of Control, and from the perspective of a Control client
+ that is using the services of an available Control type.
+ </p>
+ <p>
+ To make the descriptions more concrete, the characteristics will be presented within the context of a sample Control:
+ the JmsMessageControl. This Control will provide a simplified client access model for enqueuing messages to a JMS
+ queue or topic, freeing the client from having to learn the nuances of JMS client programming.
+ </p>
</section>
-
<section id="control_client">
<title>The Control Client Models</title>
- <p>There are actually two distinct programming models that may be available to clients of Controls:</p>
+ <p>
+ There are actually two distinct programming models that may be available to clients of Controls:
+ </p>
<ul>
<li><strong>Declarative Model.</strong> Uses a metadata-based variant of the Inversion of Control (IoC) design pattern to allow a component author to declare Control instances, contextual services, and event handlers using annotated fields and methods. The declarative model simplifies client programming, because many of the details of initialization and event routing are left to an external container supporting the model. A declarative programming style is also more toolable, since it is much easier for tools to manage and manipulate metadata rather than code.</li>
<li><strong>Programmatic Model.</strong> Uses the traditional JavaBean-style APIs for acting as a client of a bean, including factory-based constructor and event listeners. The programmatic model may be more comfortable to the traditional Java programmer, who wants to see and be in control of all the details. It also enables client use cases where there is no supporting container for the declarative model.</li>
</ul>
- <p>The programmatic client model is generally available in all contexts where Controls might be used. It offers full generality, but leaves many of the details up to the client programmer, such as initialization, composition, and event handling wire-up.</p>
-<p>The declarative model hides many of these details. Based upon its use of metadata it is also more tool friendly, allowing tools to present a view of the client code without code analysis. </p>
-<p>The declarative model requires support of an outer container or construction-time code that fulfills the contract implied by annotations on a client class. </p>
-<p>The ControlBean itself provides this support, so the Control Authoring Model is oriented towards using the declarative model, although programmatic equivalents are generally available.</p>
-
+ <p>
+ The programmatic client model is generally available in all contexts where Controls might be used. It offers full
+ generality, but leaves many of the details up to the client programmer, such as initialization, composition, and
+ event handling wire-up.
+ </p>
+ <p>
+ The declarative model hides many of these details. Based upon its use of metadata it is also more tool friendly,
+ allowing tools to present a view of the client code without code analysis.
+ </p>
+ <p>
+ The declarative model requires support of an outer container or construction-time code that fulfills the contract
+ implied by annotations on a client class.
+ </p>
+ <p>
+ The ControlBean itself provides this support, so the Control Authoring Model is oriented towards using the
+ declarative model, although programmatic equivalents are generally available.
+ </p>
</section>
-
<section id="defining_type">
<title>Defining a New Control Type</title>
-<p>Controls are designed to make it very easy for users (and tools) to define new types of Controls. Control authors might be:</p>
-<ul>
- <li> System vendors exposing specific types of resources</li>
-
- <li> Application developers defining new types of logical resources (possibly based upon physical ones)</li>
-
- <li>Third-party software vendors, using Controls as a mechanism to interface to components or subsystems they provide.</li>
-</ul>
-<p>In all instances, the goal of the Controls authoring model is to provide a basic set of conventions and supporting tools to make it easy to author a new Control type.</p>
-<p>To get started, a Control author would define the two basic artifacts: </p>
-<ul>
- <li> the Control Public Interface</li>
-
- <li> the Control Implementation Class</li>
-</ul>
-<p>For the JmsMessageControl, the declaration of the public interface might look like:</p>
-<p><strong>Interface Declaration (Control Public Interface)</strong></p>
+ <p>
+ Controls are designed to make it very easy for users (and tools) to define new types of Controls. Control authors
+ might be:
+ </p>
+ <ul>
+ <li>
+ System vendors exposing specific types of resources
+ </li>
+ <li>
+ Application developers defining new types of logical resources (possibly based upon physical ones)
+ </li>
+ <li>
+ Third-party software vendors, using Controls as a mechanism to interface to components or subsystems they provide.
+ </li>
+ </ul>
+ <p>
+ In all instances, the goal of the Controls authoring model is to provide a basic set of conventions and supporting
+ tools to make it easy to author a new Control type.
+ </p>
+ <p>
+ To get started, a Control author would define the two basic artifacts:
+ </p>
+ <ul>
+ <li>
+ the Control Public Interface
+ </li>
+ <li>
+ the Control Implementation Class
+ </li>
+ </ul>
+ <p>
+ For the JmsMessageControl, the declaration of the public interface might look like:
+ </p>
+ <p>
+ <strong>Interface Declaration (Control Public Interface)</strong>
+ </p>
<source>package org.apache.beehive.controls.examples;
import org.apache.beehive.controls.api.bean.ControlInterface;
@@ -118,23 +241,57 @@
{
...
}</source>
- <p>The only basic rule for a Control Public Interface is that it must be annotated by the org.apache.beehive.controls.api.bean.ControlInterface marker interface.</p>
- <p>The second source artifact a Control author would create to define a new type of Control is the Control Implementation Class. This declaration of the implementation class for our JmsMessageControl would look like:</p>
-<p><strong>Class Declaration (Control Implementation Class)</strong></p>
+ <p>
+ The only basic rule for a Control Public Interface is that it must be annotated by the
+ org.apache.beehive.controls.api.bean.ControlInterface marker interface.
+ </p>
+ <p>
+ The second source artifact a Control author would create to define a new type of Control is the Control
+ Implementation Class. This declaration of the implementation class for our JmsMessageControl would look like:
+ </p>
+ <p>
+ <strong>Class Declaration (Control Implementation Class)</strong>
+ </p>
<source>package org.apache.beehive.controls.examples;
import org.apache.beehive.controls.api.bean.ControlImplementation;
-@ControlImplementation
+@ControlImplementation(isTransient=true)
public class JmsMessageControlImpl implements JmsMessageControl
{
...
}</source>
-<p>The basic rules for a Control Implementation Class are that it must be annotated with org.apache.beehive.controls.api.bean.ControlImplementation and it must implement its associated Control Public Interface. </p>
-<p>From these two source files, the Control compiler will create a third artifact, the ControlBean Generated Class. This class need not necessarily ever appear within an application in source code form; but for the purposes of explaining the overall architecture and client model, we will present source examples of the derived ControlBean Generated Class. </p>
-<p>A Controls standard would focus only on the conventions for the external attributes of ControlBean Generated Classes, not upon the internal implementation. </p>
-<p>The ControlBean Generated Class for the JmsMessageControl would look like:</p>
-<p><strong>Class Declaration (ControlBean Generated Class)</strong></p>
+ <p>
+ The basic rules for a Control Implementation Class are:
+ </p>
+ <ul>
+ <li>
+ It must be annotated with <code>org.apache.beehive.controls.api.bean.ControlImplementation.</code>
+ </li>
+ <li>
+ It must implement its associated Control Public Interface.
+ </li>
+ <li>
+ It must either (1) implement the <code>java.io.Serializable</code> interface or (2) set the <code>isTransient</code> attribute of <code>@ControlImplementation</code> to true.
+ </li>
+ </ul>
+ <p>
+ From these two source files, the Control compiler will create a third artifact, the
+ ControlBean Generated Class. This class need not necessarily ever appear within an
+ application in source code form; but for the purposes of explaining the overall
+ architecture and client model, we will present source examples of the derived ControlBean
+ Generated Class.
+ </p>
+ <p>
+ A Controls standard would focus only on the conventions for the external attributes of
+ ControlBean Generated Classes, not upon the internal implementation.
+ </p>
+ <p>
+ The ControlBean Generated Class for the JmsMessageControl would look like:
+ </p>
+ <p>
+ <strong>Class Declaration (ControlBean Generated Class)</strong>
+ </p>
<source>package org.apache.beehive.controls.examples;
public class JmsMessageControIBean implements JmsMessageControl
@@ -143,77 +300,141 @@
...
}</source>
-<p>As shown above, the ControlBean Generated Class will also implement the Control Public Interface. The sample also shows that the bean will hold a private reference to an implementation instance used to support the bean.</p>
+ <p>
+ As shown above, the ControlBean Generated Class will also implement the Control Public Interface. The sample also
+ shows that the bean will hold a private reference to an implementation instance used to support the bean.
+ </p>
</section>
-
<section id="instantiating">
<title>Instantiating a Control</title>
- <p>This section covers the client mechanisms for creating a new instance of a Control. This can be done either programmatically or declarative, if running inside a container that support declarative initialization.</p>
+ <p>
+ This section covers the client mechanisms for creating a new instance of a Control. This can be done either
+ programmatically or declarative, if running inside a container that support declarative initialization.
+ </p>
<section>
<title>Declarative Instantiation</title>
-<p>The client model for Controls supports a declarative model for instantiating a Control instance, when running in containers that support this model. In this model, the client class can annotate fields on the class using a special marker annotation (org.apache.beehive.controls.api.bean.Control) that indicates that the fields should be initialized to a ControlBean instance of the requested type.</p>
-<p>Here is an example of declarative instantiation:</p>
-<p><strong>Declarative Instantiation (Client Code)</strong></p>
-<source>import org.apache.beehive.controls.api.bean.Control;
+ <p>
+ The client model for Controls supports a declarative model for instantiating a Control instance, when running in
+ containers that support this model. In this model, the client class can annotate fields on the class using a
+ special marker annotation (org.apache.beehive.controls.api.bean.Control) that indicates that the fields should be
+ initialized to a ControlBean instance of the requested type.
+ </p>
+ <p>
+ Here is an example of declarative instantiation:
+ </p>
+ <p>
+ <strong>Declarative Instantiation (Client Code)</strong>
+ </p>
+<source>package org.apache.beehive.controls.examples;
+
+import org.apache.beehive.controls.api.bean.Control;
import org.apache.beehive.controls.api.bean.ControlImplementation;
+import org.apache.beehive.controls.examples.JmsMessageControl;
-@ControlImplementation
+@ControlImplementation(isTransient=true)
public class PublisherControlImpl implements PublisherControl
{
- <strong>@Control
- public JmsMessageControlBean myJmsBean;</strong>
+ <strong>@Control
+ public JmsMessageControlBean myJmsBean;</strong>
- ...
+ ...
public void someOperation()
{
myJmsBean.sendTextMessage("A Text Message");
}
}</source>
-<p>This example shows a second Control Implementation Class (PublisherControlImpl) that internally uses the services of JmsMessageControl to enqueue a JMS message. The child Control field is not explicitly initialized within the PublisherControl implementation class; by the time someOperation() is called, it is guaranteed that the myJmsBean reference has been initialized by the wrapping PublisherControlBean that contains the implementation.</p>
-<p>It is also possible to parameterize the attributes of a Control at construction time, again using metadata attributes. These attributes can be placed on the field declaration (in addition to the @Control annotation) and will be used to do construction-time initialization.</p>
-<p>The second example below shows initialization of the myJmsBean field again. In this case, an initial value of the @Destination "name" attribute is also provided using JSR-175 metadata:</p>
-<p><strong>Declarative Instantiation with Properties (Client Code)</strong></p>
+ <p>
+ This example shows a second Control Implementation Class (PublisherControlImpl) that internally uses the services
+ of JmsMessageControl to enqueue a JMS message. The child Control field is not explicitly initialized within the
+ PublisherControl implementation class; by the time someOperation() is called, it is guaranteed that the myJmsControl
+ reference has been initialized by the wrapping PublisherControl that contains the implementation.
+ </p>
+ <p>
+ It is also possible to parameterize a Control at construction time, again using metadata
+ attributes. These attributes can be placed on the field declaration (in addition to the @Control annotation)
+ and will be used to do construction-time initialization.
+ </p>
+ <p>
+ The second example below shows initialization of the myJmsControl field again. In this case, an initial value of
+ the @Destination "name" attribute is also provided using JSR-175 metadata:
+ </p>
+ <p>
+ <strong>Declarative Instantiation with Properties (Client Code)</strong>
+ </p>
<source>@ControlImplementation
public class PublisherControlImpl implements PublisherControl
{
- <strong>@Control @Destination(name="InvoiceQueue") </strong>
+ @Control
+ <strong>@Destination(name="InvoiceQueue")</strong>
public JmsMessageControlBean myJmsBean;</source>
- <p>This example performs <strong>exactly</strong> the same initialization as the earlier declarative example, but does so using JSR-175 attribute syntax instead of passing parameters to a factory-based constructor.</p>
-<p>The Controls architecture includes a mechanism for defining the expected set of annotations that might appear on a Control field. This mechanism is described in greater detail in the section on Properties.</p>
+ <p>
+ This example performs <strong>exactly</strong> the same initialization as the earlier declarative example, but
+ does so using JSR-175 attribute syntax instead of passing parameters to a factory-based constructor.
+ </p>
+ <p>
+ The Controls architecture includes a mechanism for defining the expected set of annotations that might appear on
+ a Control field. This mechanism is described in greater detail in the section on Properties.
+ </p>
</section>
<section>
<title>Programmatic Instantiation</title>
- <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>
- <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;
+ <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 =
+ <strong>(JmsMessageControlBean) 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 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>
- <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>
+JmsMessageControlBean myJmsBean = <strong>(JmsMessageControlBean) 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>
-
<section id="operations">
<title>Operations</title>
- <p>Operations are actions that can be performed by a Control at the clientâs request. This section describes the authoring model for declaring and implementing a Control operation, as well as the client model for invoking operations on a ControlBean instance.</p>
+ <p>
+ Operations are actions that can be performed by a Control at the clientâs request. This section describes the
+ authoring model for declaring and implementing a Control operation, as well as the client model for invoking
+ operations on a ControlBean instance.
+ </p>
<section>
<title>Declaring and Implementing Operations for a Control </title>
- <p>All methods declared or inherited (via extension) by the Control Public Interface are considered to be Control operations. The following example shows the definition of two operations on the JmsMessageControl that will enqueue messages when invoked:</p>
-<p><strong>Declaring Operations (Control Public Interface)</strong></p>
+ <p>
+ All methods declared or inherited (via extension) by the Control Public Interface are considered to be Control
+ operations. The following example shows the definition of two operations on the JmsMessageControl that will
+ enqueue messages when invoked:
+ </p>
+ <p>
+ <strong>Declaring Operations (Control Public Interface)</strong>
+ </p>
<source>package org.apache.beehive.controls.examples;
+import java.io.Serializable;
import org.apache.beehive.controls.api.bean.ControlInterface
@ControlInterface
@@ -224,13 +445,19 @@
...
}</source>
-<p>The Control Implementation Class implements the public interface for the Control, defining the operation methods, and the body of these methods.</p>
-<p><strong>Implementing Operations (Control Implementation Class)</strong></p>
+ <p>
+ The Control Implementation Class implements the public interface for the Control, defining the operation methods,
+ and the body of these methods.
+ </p>
+ <p>
+ <strong>Implementing Operations (Control Implementation Class)</strong>
+ </p>
<source>package org.apache.beehive.controls.examples;
+import java.io.Serializable;
import org.apache.beehive.controls.api.bean.ControlImplementation;
-@ControlImplementation
+@ControlImplementation(isTransient=true)
public class JmsMessageControlImpl implements JmsMessageControl
{
<strong>public void sendTextMessage(String text)
@@ -246,9 +473,17 @@
}</strong>
}
</source>
-<p>Finally, the ControlBean Generated Class will also implement all operations (since it also implements the Control Public Interface). It will always delegate to the implementation class for the actual implementation of the operation; it might also perform additional container-specific pre/post invocation processing.</p>
-<p>Here is a skeleton of what the generated ControlBean code might look like for an operation:</p>
-<p><strong>Implemented Operations (ControlBean Generated Class)</strong></p>
+ <p>
+ Finally, the ControlBean Generated Class will also implement all operations (since it also implements the Control
+ Public Interface). It will always delegate to the implementation class for the actual implementation of the
+ operation; it might also perform additional container-specific pre/post invocation processing.
+ </p>
+ <p>
+ Here is a skeleton of what the generated ControlBean code might look like for an operation:
+ </p>
+ <p>
+ <strong>Implemented Operations (ControlBean Generated Class)</strong>
+ </p>
<source>package org.apache.beehive.controls.examples;
public class JmsMessageControlBean implements JmsMessageControl
@@ -273,27 +508,64 @@
</section>
<section>
<title>Invoking Operations on a Control</title>
-<p>The client model for invoking an operation on a Control is very straightforward: simply call the method on a held ControlBean instance as demonstrated by the following example:</p>
-<p><strong>Invoking an Operation (Client Code)</strong></p>
-<source> myJmsBean.sendTextMessage("A Text Message");</source>
-<p>The invocation model for operations is the same, whether the Control instance was created using declarative or programmatic mechanisms.</p>
+ <p>
+ The client model for invoking an operation on a Control is very straightforward: simply call the method on a
+ held ControlBean instance as demonstrated by the following example:
+ </p>
+ <p>
+ <strong>Invoking an Operation (Client Code)</strong>
+ </p>
+<source>package org.apache.beehive.controls.examples;
+
+import org.apache.beehive.controls.api.bean.Control;
+import org.apache.beehive.controls.api.bean.ControlImplementation;
+import org.apache.beehive.controls.examples.JmsMessageControl;
+
+@ControlImplementation(isTransient=true)
+public class PublisherControlImpl implements PublisherControl
+{
+ @Control
+ public JmsMessageControlBean myJmsBean;
+
+ ...
+
+ public void someOperation()
+ {
+ <strong>myJmsBean.sendTextMessage("A Text Message");</strong>
+ }
+}</source>
+ <p>
+ The invocation model for operations is the same, whether the Control instance was created using declarative or
+ programmatic mechanisms.
+ </p>
</section>
</section>
-
<section id="events">
<title>Events</title>
- <p>Events are notifications sent by the Control back to its client whenever some condition has been met or internal event has taken place. A client can express interest in a Controlâs events by registering (either explicitly or implicitly) to receive them, and can write event handler code to be called when the event has taken place.</p>
-<p>This section describes the declaration model for events, how an authored Control delivers them to a registered client, and the client code necessary to register and receive events.</p>
-
+ <p>
+ Events are notifications sent by the Control back to its client whenever some condition has been met or internal
+ event has taken place. A client can express interest in a Controlâs events by registering (either explicitly or
+ implicitly) to receive them, and can write event handler code to be called when the event has taken place.
+ </p>
+ <p>
+ This section describes the declaration model for events, how an authored Control delivers them to a registered
+ client, and the client code necessary to register and receive events.
+ </p>
<section>
<title>Declaring Events</title>
-<p>Events are declared on an inner interface of the Control Public Interface, which is annotated with the org.apache.beehive.controls.api.events.EventSet annotation. The following example shows the declaration of an event interface for the JmsMessageControl, with a single event (onMessage):</p>
-<p><strong>Declaring Events (Control Public Interface)</strong></p>
+ <p>
+ Events are declared on an inner interface of the Control Public Interface, which is annotated with the
+ org.apache.beehive.controls.api.events.EventSet annotation. The following example shows the declaration
+ of an event interface for the JmsMessageControl, with a single event (onMessage):
+ </p>
+ <p>
+ <strong>Declaring Events (Control Public Interface)</strong>
+ </p>
<source>package org.apache.beehive.controls.examples;
import java.io.Serializable;
-import javax.jms.Message;
-import org.apache.beehive.controls.api.events.EventSet;
+<strong>import javax.jms.Message;
+import org.apache.beehive.controls.api.events.EventSet;</strong>
import org.apache.beehive.controls.api.bean.ControlInterface;
@ControlInterface
@@ -302,17 +574,21 @@
public void sendTextMessage(String text);
public void sendObjectMessage(Serializable object);
- @EventSet
- <strong>public interface Callback
+ <strong>@EventSet
+ public interface Callback
{
void onMessage(Message m);
}</strong>
...
}</source>
-<p>If a Control Public Interface has defined an EventSet interface, then the associated ControlBean Generated Class will have two public methods supporting client listener management:</p>
-
-<p><strong>Event Listener Registration Methods (ControlBean Generated Class)</strong></p>
+ <p>
+ If a Control Public Interface has defined an EventSet interface, then the associated ControlBean Generated
+ Class will have two public methods supporting client listener management:
+ </p>
+ <p>
+ <strong>Event Listener Registration Methods (ControlBean Generated Class)</strong>
+ </p>
<source>package org.apache.beehive.controls.examples;
import java.util.TooManyListenersException;
@@ -334,49 +610,90 @@
...
}
}</source>
-<p>The name of the listener registration methods are based upon the name of the associated EventSet interface. In the previous example, the EventSet interface was named Callback, so the associated listener registration method was addCallbackListener(), and the deregistration method was removeCallbackListener().</p>
-<p>A Control Public Interface can have more than one inner interface that is annotated as an EventSet interface. Each declared EventSet will have its own independently managed list of registered listeners.</p>
+ <p>
+ The name of the listener registration methods are based upon the name of the associated EventSet interface. In
+ the previous example, the EventSet interface was named Callback, so the associated listener registration method
+ was addCallbackListener(), and the deregistration method was removeCallbackListener().
+ </p>
+ <p>
+ A Control Public Interface can have more than one inner interface that is annotated as an EventSet interface.
+ Each declared EventSet will have its own independently managed list of registered listeners.
+ </p>
</section>
<section>
<title>Firing Events</title>
- <p>This section describes the mechanism available to a Control author to deliver events to any registered client listener. <strong>An initialized event proxy is created when the Control Implementation Class declares a field of an EventSet interface type, and annotates it with the org.apache.beehive.controls.events.Client annotation type.</strong> The containing ControlBean will initialize this reference to a valid proxy implementing the EventSet interface, and the Control Implementation Class can use this proxy to fire events back to any registered client.</p>
-<p>This is demonstrated in the following sample code from the JmsControlBean implementation class, which will fire an onMessage event back to any registered client any time a message is enqueued:</p>
-
-<p><strong>Firing Events (Control Implementation Class)</strong></p>
+ <p>
+ This section describes the mechanism available to a Control author to deliver events to any registered client
+ listener. <strong>An initialized event proxy is created when the Control Implementation Class declares a field
+ of an EventSet interface type, and annotates it with the org.apache.beehive.controls.events.Client annotation
+ type.</strong> The containing ControlBean will initialize this reference to a valid proxy implementing the
+ EventSet interface, and the Control Implementation Class can use this proxy to fire events back to any registered
+ client.
+ </p>
+ <p>
+ This is demonstrated in the following sample code from the JmsControlBean implementation class, which will fire
+ an onMessage event back to any registered client any time a message is enqueued:
+ </p>
+ <p>
+ <strong>Firing Events (Control Implementation Class)</strong>
+ </p>
<source>package org.apache.beehive.controls.examples;
+import java.io.Serializable;
+import javax.jms.TextMessage;
import org.apache.beehive.controls.api.bean.ControlImplementation;
-import org.apache.beehive.controls.api.events.Client;
+<strong>import org.apache.beehive.controls.api.events.Client;</strong>
-@ControlImplementation
+@ControlImplementation(isTransient=true)
public class JmsMessageControlImpl implements JmsMessageControl
{
<strong>@Client Callback client;</strong>
- public void sendTextMessage(String text)
+ public void sendTextMessage(String text)
{
// Code to construct and send a TextMessage to the destination
TextMessage m = ...;
...
<strong>client.onMessage(m);</strong>
- }
- ...
+ }
+ ...
}</source>
</section>
<section>
<title>Listening for Events</title>
- <p>The client of a Control can express an interest in receiving events from a Control and write client event handlers to service them once delivered. Two basic event handling mechanisms are supported: Java event listeners or declarative event handlers (where supported by the client container).</p>
+ <p>
+ The client of a Control can express an interest in receiving events from a Control and write client event handlers
+ to service them once delivered. Two basic event handling mechanisms are supported: Java event listeners or
+ declarative event handlers (where supported by the client container).
+ </p>
<section>
<title>Declarative Implementation of Event Handling</title>
- <p>If the client code is implemented in a container that supports the declarative programming model for Controls (such as the Control Implementation Class itself), it can use a simplified convention for authoring event handlers for a declared Control instance.</p>
-<p>If a Control is declared using the @Control marker interface, then <strong>the user can declare event handlers for the Control by using the EventHandler annotation type</strong>. These annotated methods will be considered an event handler for the Control event, and the container will automatically register for events and deliver them to this handler.</p>
-<p>The previous example could be rewritten using the declarative event handling style as:</p>
-
-<p><strong>Declarative Handling of Events (Client Code)</strong></p>
-<source>import org.apache.beehive.controls.api.bean.ControlImplementation;
-import org.apache.beehive.controls.api.events.EventHandler
+ <p>
+ If the client code is implemented in a container that supports the declarative programming model for Controls
+ (such as the Control Implementation Class itself), it can use a simplified convention for authoring event
+ handlers for a declared Control instance.
+ </p>
+ <p>
+ If a Control is declared using the @Control marker interface, then <strong>the user can declare event handlers
+ for the Control by using the EventHandler annotation type</strong>. These annotated methods will be
+ considered an event handler for the Control event, and the container will automatically register for events
+ and deliver them to this handler.
+ </p>
+ <p>
+ The previous example could be rewritten using the declarative event handling style as:
+ </p>
+ <p>
+ <strong>Declarative Handling of Events (Client Code)</strong>
+ </p>
+<source>package org.apache.beehive.controls.examples;
-@ControlImplementation
+import javax.jms.Message;
+import org.apache.beehive.controls.api.bean.Control;
+import org.apache.beehive.controls.api.bean.ControlImplementation;
+import org.apache.beehive.controls.api.events.EventHandler;
+import org.apache.beehive.controls.examples.JmsMessageControl;
+
+@ControlImplementation(isTransient=true)
public class PublisherControlImpl implements PublisherControl
{
@Control
@@ -384,7 +701,7 @@
<strong>@EventHandler (
field="myJmsBean",
- evenSet= JmsMessageControl.Callback.class,
+ eventSet= JmsMessageControl.Callback.class,
eventName="onMessage")
public void myJmsBeanMessageHandler(Message m)
{
@@ -396,59 +713,147 @@
</section>
<section>
<title>Programmatic Implementation of Event Handling</title>
- <p>The programmatic style follows the tradition Java event listener pattern. The client expresses its interest in receiving the event and also authors a (often anonymous inner) class that implements the event interface to receive events when delivered.</p>
-<p>This is shown by the following sample code:</p>
-
-<p><strong>Programmatic Handling of Events (Client Code)</strong></p>
-<source> myJmsBean.addCallbackListener(
- new JmsMessageControl.Callback()
- {
- public void onMessage(Message m)
- {
- // Code implementing on Message event handler
- }
+ <p>
+ The programmatic style follows the tradition Java event listener pattern. The client expresses its interest
+ in receiving the event and also authors a (often anonymous inner) class that implements the event interface
+ to receive events when delivered.
+ </p>
+ <p>
+ This is shown by the following sample code:
+ </p>
+ <p>
+ <strong>Programmatic Handling of Events (Client Code)</strong>
+ </p>
+<source>myJmsBean.addCallbackListener(
+ new JmsMessageControl.Callback()
+ {
+ public void onMessage(Message m)
+ {
+ // Code implementing on Message event handler
+ }
}
);</source>
-<p>There is no requirement that an anonymous inner class be used. One alternative would be to delegate to an instance of another class (as long as that class implements the Callback interface). In the preceding example, if event listening was implemented for the purposes of logging sent messages, and MessageLogger class could be declared (implementing the Callback interface), multiple beans could delegate to a single instance of this logging listener.</p>
+ <p>
+ There is no requirement that an anonymous inner class be used. One alternative would be to delegate to an
+ instance of another class (as long as that class implements the Callback interface). In the preceding
+ example, if event listening was implemented for the purposes of logging sent messages, and MessageLogger
+ class could be declared (implementing the Callback interface), multiple beans could delegate to a single
+ instance of this logging listener.
+ </p>
</section>
</section>
</section>
-
<section id="contextual_services">
<title>Contextual Services</title>
- <p>The Control authoring model makes use of contextual services to provide access to services from the current runtime environment of the ControlBean. The model for contextual services is based upon the existing standards for services in JavaBeans: The JavaBeans Runtime Containment and Services Protocol. This protocol provides a base mechanism for a JavaBean to locate and use services from the runtime environment, as well as an extensible service provider model to enable new (or environment-specific) types of services to be authored and made available to JavaBeans/Controls.</p>
-<p>A key aspect of this service model is that it can be contextual; for example, it might be possible to write a basic security service interface that provides logical role-checking functionality. The actual implementation of this interface might vary for different runtime contexts: for example, the role check might be done differently for a Control running within the context of an EJB container (by delegating to the containing EJBContext) vs. a Control running within the Web tier (by delegating to ServletHttpRequest services).</p>
-<p>Having an extensibility and service provider location model is important to enable the following scenarios:</p>
-<ul>
- <li> The Controlâs implementation is designed to run in a wide variety of environments. It uses the contextual service mechanism to declare its prerequisites and receive a provider implementation that is appropriate to the current runtime context.</li>
- <li> The Controlâs implementation is designed to run in a very specific context (for example, only in the http servlet tier) and wants access to services that are very specific to that context (for example, session state or request query parameters). It should not be possible to instantiate this Control in other contexts (for example, from within an EJB).</li>
-</ul>
-<p><strong>One key contextual service for Controls that is guaranteed to be available in all contexts is the org.apache.beehive.controls.api.context.ControlBeanContext service interface. </strong>This service provides a common set of generic services that are available to Control authors, such as the ability to query property values on the current instance, or to receive a set of basic lifecycle or resource management events. The ControlBeanContext interface extends the java.beans.beancontext.BeanContextServices interface, so it also provides access to services provided by the JavaBeans bean context APIs. Later sections describe an overview of the internal architecture for contextual services, APIs to support property resolution, and lifecycle events.</p>
+ <p>
+ The Control authoring model makes use of contextual services to provide access to services from the current runtime
+ environment of the ControlBean. The model for contextual services is based upon the existing standards for services
+ in JavaBeans: The JavaBeans Runtime Containment and Services Protocol. This protocol provides a base mechanism for
+ a JavaBean to locate and use services from the runtime environment, as well as an extensible service provider model
+ to enable new (or environment-specific) types of services to be authored and made available to JavaBeans/Controls.
+ </p>
+ <p>
+ A key aspect of this service model is that it can be contextual; for example, it might be possible to write a basic
+ security service interface that provides logical role-checking functionality. The actual implementation of this
+ interface might vary for different runtime contexts: for example, the role check might be done differently for a
+ Control running within the context of an EJB container (by delegating to the containing EJBContext) vs. a Control
+ running within the Web tier (by delegating to ServletHttpRequest services).
+ </p>
+ <p>
+ Having an extensibility and service provider location model is important to enable the following scenarios:
+ </p>
+ <ul>
+ <li>
+ The Controlâs implementation is designed to run in a wide variety of environments. It uses the contextual service
+ mechanism to declare its prerequisites and receive a provider implementation that is appropriate to the current
+ runtime context.
+ </li>
+ <li>
+ The Controlâs implementation is designed to run in a very specific context (for example, only in the http servlet
+ tier) and wants access to services that are very specific to that context (for example, session state or request
+ query parameters). It should not be possible to instantiate this Control in other contexts (for example, from
+ within an EJB).
+ </li>
+ </ul>
+ <p>
+ <strong>One key contextual service for Controls that is guaranteed to be available in all contexts is the
+ org.apache.beehive.controls.api.context.ControlBeanContext service interface.</strong> This service provides a common
+ set of generic services that are available to Control authors, such as the ability to query property values on the
+ current instance, or to receive a set of basic lifecycle or resource management events. The ControlBeanContext
+ interface extends the java.beans.beancontext.BeanContextServices interface, so it also provides access to services
+ provided by the JavaBeans bean context APIs. Later sections describe an overview of the internal architecture for
+ contextual services, APIs to support property resolution, and lifecycle events.
+ </p>
<section>
<title>Declarative Access to Contextual Services</title>
- <p>To signal the desire to access a contextual service, a Control author only needs to declare a field of the desired context interface and annotate it with the org.apache.beehive.controls.api.context.Context marker annotation. The following example shows how the JmsMessageControlImpl class would use the declarative model to access its ControlBeanContext:</p>
+ <p>
+ Suppose the following Destination property set was added to the control:
+ </p>
+ <p>
+ <strong>Declarative Access to Context Services (Control Public Interface)</strong>
+ </p>
+<source>package org.apache.beehive.controls.examples;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.apache.beehive.controls.api.bean.ControlInterface;
+import org.apache.beehive.controls.api.properties.PropertySet;
+
+@ControlInterface
+public interface JmsMessageControl
+{
+ ...
-<p><strong>Declarative Access to Context Services (Control Implementation Class)</strong></p>
+ <strong>public enum DestinationType { QUEUE, TOPIC }
+
+ @PropertySet
+ @Retention(RetentionPolicy.RUNTIME)
+ @Target({ElementType.FIELD, ElementType.TYPE})
+ public @interface Destination
+ {
+ public DestinationType type() default DestinationType.QUEUE;
+ public String name();
+ }</strong>
+}</source>
+ <p>
+ To signal the desire to access a contextual service, a Control author only needs to declare a field of the desired
+ context interface and annotate it with the org.apache.beehive.controls.api.context.Context marker annotation.
+ The following example shows how the JmsMessageControlImpl class would use the declarative model to access its
+ ControlBeanContext:
+ </p>
+ <p>
+ <strong>Declarative Access to Context Services (Control Implementation Class)</strong>
+ </p>
<source>package org.apache.beehive.controls.examples;
import org.apache.beehive.controls.api.bean.ControlImplementation;
import org.apache.beehive.controls.api.context.Context;
import org.apache.beehive.controls.api.context.ControlBeanContext;
-@ControlImplementation
+@ControlImplementation(isTransient=true)
public class JmsMessageControlImpl implements JmsMessageControl
{
<strong>@Context ControlBeanContext context;</strong>
public void sendTextMessage(String text)
{
- JmsMessageControl.Destination =
+ JmsMessageControl.Destination destProp =
<strong>context.getControlPropertySet(JmsMessageControl.Destination.class);</strong>
...
}
}</source>
-<p>In this example, the JmsMessageControl implementation class expresses its desire to access ControlBeanContext services via the annotated declaration of the context field; when code in sendTextMessage operation is invoked, this contextual service has already been initialized by the containing ControlBean instance.</p>
-<p>The ControlBeanContext for an authored Control is always accessed using the declarative mechanism. Other contextual services may be accessed declaratively, or using the programmatic mechanisms described in the following section.</p>
+ <p>
+ In this example, the JmsMessageControl implementation class expresses its desire to access ControlBeanContext
+ services via the annotated declaration of the context field; when code in sendTextMessage operation is invoked,
+ this contextual service has already been initialized by the containing ControlBean instance.
+ </p>
+ <p>
+ The ControlBeanContext for an authored Control is always accessed using the declarative mechanism. Other contextual
+ services may be accessed declaratively, or using the programmatic mechanisms described in the following section.
+ </p>
</section>
<section>
@@ -463,7 +868,7 @@
import org.apache.beehive.controls.api.context.Context;
import org.apache.beehive.controls.api.context.ControlBeanContext;
-@ControlImplementation
+@ControlImplementation(isTransient=true)
public class JmsMessageControlImpl implements JmsMessageControl
{
<strong>@Context ControlBeanContext context;</strong>
@@ -623,7 +1028,7 @@
import org.apache.beehive.controls.api.context.Context;
import org.apache.beehive.controls.api.context.ControlBeanContext;
-@ControlImplementation
+@ControlImplementation(isTransient=true)
public class JmsMessageControlImpl implements JmsMessageControl
{
@Context ControlBeanContext context;
@@ -853,7 +1258,7 @@
import org.apache.beehive.controls.api.bean.Extensible;
import java.lang.reflect.Method;
-@ControlImplementation
+@ControlImplementation(isTransient=true)
public class JmsMessageControlImpl implements JmsMessageControl, Extensible
{
@Context ControlBeanContext context;
@@ -963,7 +1368,8 @@
<p><strong>Composition Using Declarative Instantiation (Control Implementation Class)</strong></p>
<source>package org.apache.beehive.controls.examples;
-public class OrderRouterImpl
+@ControlImplementation(isTransient=true)
+public class OrderRouterImpl implements OrderRouter
{
@Control @Destination(Name="RushOrders")
OrderQueueBean rushOrders;
@@ -991,7 +1397,8 @@
<p><strong>Composition Using Programmatic Instantiation (Control Implementation Class)</strong></p>
<source>package org.apache.beehive.controls.examples;
-public class OrderRouterImpl
+@ControlImplementation(isTransient=true)
+public class OrderRouterImpl implements OrderRouter
{
// no @Control annotation, so no auto-init
OrderQueueBean rushOrders;
@@ -1046,7 +1453,7 @@
public interface A { ... }
// AImpl.java: The implementation of the base control interface
- @ControlImplementation
+ @ControlImplementation(isTransient=true)
public class AImpl implements A { ... }
// B.java: The extension of the base interface that adds
@@ -1055,7 +1462,7 @@
public interface B extends A { ... }
// BImpl.java: The implementation of the extended control interface
- @ControlImplementation
+ @ControlImplementation(isTransient=true)
public class BImpl implements B { ... }
</source>
@@ -1154,7 +1561,7 @@
import org.apache.beehive.controls.api.context.ResourceContext;
import org.apache.beehive.controls.api.events.EventHandler;
-@ControlImplementation
+@ControlImplementation(isTransient=true)
public class JmsMessageControlImpl implements JmsMessageControl
{
<strong>@Context ResourceContext resourceContext;