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 20:10:16 UTC
svn commit: r289285 [2/2] -
/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=289285&r1=289284&r2=289285&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 Thu Sep 15 11:10:13 2005
@@ -714,7 +714,7 @@
<section>
<title>Programmatic Implementation of Event Handling</title>
<p>
- The programmatic style follows the tradition Java event listener pattern. The client expresses its interest
+ The programmatic style follows the traditional 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>
@@ -858,9 +858,14 @@
</section>
<section>
<title>Programmatic Access to Contextual Services</title>
-<p>The ControlBeanContext service also provides the base mechanism to discover and use other services programmatically. The following code fragment shows an example of how to use this API to obtain access to a service provider that provides the javax.servlet.ServletContext interface.</p>
-
-<p><strong>Programmatic Access to Context Services (Control Implementation Class)</strong></p>
+ <p>
+ The ControlBeanContext service also provides the base mechanism to discover and use other services programmatically.
+ The following code fragment shows an example of how to use this API to obtain access to a service provider that
+ provides the javax.servlet.ServletContext interface.
+ </p>
+ <p>
+ <strong>Programmatic Access to Context Services (Control Implementation Class)</strong>
+ </p>
<source>package org.apache.beehive.controls.examples;
import javax.servlet.ServletContext;
@@ -876,7 +881,7 @@
public void sendTextMessage(String text)
{
<strong>ServletContext servletContext =
- context.getService(ServletContext.class, null);</strong>
+ context.getService(ServletContext.class, null);</strong>
if (servletContext == null)
{
// no ServletContext provider is available
@@ -884,53 +889,92 @@
...
}
}</source>
-<p>The code in the sample uses the ControlBeanContext.getService API to request that it provide a ServletContext service. The parameters to this method are the Class of the requested service, and an (optional) service-specific selector that can be used to parameterize the service. </p>
-<p>The ServletContext service is contextual because it is available only to controls running in the web tier. If the above sample control was running anywhere else, the call to ControlBeanContext.getService() would return null.</p>
-
+ <p>
+ The code in the sample uses the ControlBeanContext.getService API to request that it provide a ServletContext
+ service. The parameters to this method are the Class of the requested service, and an (optional) service-specific
+ selector that can be used to parameterize the service.
+ </p>
+ <p>
+ The ServletContext service is contextual because it is available only to controls running in the web tier. If the
+ above sample control was running anywhere else, the call to ControlBeanContext.getService() would return null.
+ </p>
</section>
<section>
<title>Tradeoffs between Declarative and Programmatic Access</title>
-<p>Declarative access to context services is always available to a Control Implementation Class, and generally results in less code associated with accessing services. Why then, would using programmatic access ever be useful? There is a key difference between the two:</p>
-
-<ul>
- <li> When using the declarative model for accessing a contextual service, the Control is effectively saying that the service is required for it to function; if not available in a particular runtime environment, then construction of an instance of the Control will fail. Essentially, the annotated context acts as a notification to the runtime factory that this prerequisite must be satisfied.</li>
-
- <li> Use of the programmatic model allows a Control Implementation Class to implement conditional behavior based upon whether a contextual service is or is not available. The Control Implementation Class can use the programmatic accessor, and then make a decision how to proceed based upon whether the requested service is available.</li>
-</ul>
+ <p>
+ Declarative access to context services is always available to a Control Implementation Class, and generally
+ results in less code associated with accessing services. Why then, would using programmatic access ever be
+ useful? There is a key difference between the two:
+ </p>
+ <ul>
+ <li>
+ When using the declarative model for accessing a contextual service, the Control is effectively saying
+ that the service is required for it to function; if not available in a particular runtime environment, then
+ construction of an instance of the Control will fail. Essentially, the annotated context acts as a
+ notification to the runtime factory that this prerequisite must be satisfied.
+ </li>
+ <li>
+ Use of the programmatic model allows a Control Implementation Class to implement conditional behavior
+ based upon whether a contextual service is or is not available. The Control Implementation Class can
+ use the programmatic accessor, and then make a decision how to proceed based upon whether the requested
+ service is available.
+ </li>
+ </ul>
</section>
</section>
-
<section id="properties">
<title>Properties</title>
- <p>This section describes Control properties. Properties provide the basic mechanism for parameterizing the behavior of a Control instance.</p>
- <p>The Controls architecture takes the basic JavaBeans notion of properties and extends it to support two new capabilities:</p>
- <ul>
- <li> A declarative annotation model where properties can be preconfigured on a ControlBean using JSR-175 annotations</li>
-
- <li> An administrative model where the value of ControlBean properties can be externally defined or overridden.</li>
- </ul>
- <p>The external configuration and administrative model for Controls will be described in a separate document.</p>
+ <p>
+ This section describes Control properties. Properties provide the basic mechanism for parameterizing the behavior
+ of a Control instance.
+ </p>
+ <p>
+ The Controls architecture takes the basic JavaBeans notion of properties and extends it to support two new
+ capabilities:
+ </p>
+ <ul>
+ <li>
+ A declarative annotation model where properties can be preconfigured on a ControlBean using JSR-175 annotations
+ </li>
+ <li>
+ An administrative model where the value of ControlBean properties can be externally defined or overridden.
+ </li>
+ </ul>
+ <p>
+ The external configuration and administrative model for Controls will be described in a separate document.
+ </p>
<section id="declaring_props">
<title>Declaring Properties for a Control Type</title>
- <p>For Controls, the set of properties is explicitly declared on the Control Public Interface.
+ <p>
+ For Controls, the set of properties is explicitly declared on the Control Public Interface.
This makes the available parameterization of a Control type readily visible to both code
- and tools.</p>
-<p>Properties are grouped together into related groups called PropertySets. All Properties within a
- PropertySet will have a common set of attributes (such as where they can be declared, the access
- model for JavaBean accessors, etc) and will have property names based upon a common naming
- convention.</p>
-<p>A PropertySet is declared as a JSR-175 attribute interface within the Control Public Interface,
- which is also decorated with the org.apache.beehive.controls.api.properties.PropertySet
- meta-attribute. Each of the members within a PropertySet will refer to a distinct property
- within the set, and the return value of the member defines the property type.</p>
-<p>Here is a sample declaration of the Destination PropertySet for the JmsMessageControl, which can
- be used to configure the target JMS destination for the Control:</p>
-
-<p><strong>Declaring Properties (Control Public Interface)</strong></p>
+ and tools.
+ </p>
+ <p>
+ Properties are grouped together into related groups called PropertySets. All Properties within a
+ PropertySet will have a common set of attributes (such as where they can be declared, the access
+ model for JavaBean accessors, etc) and will have property names based upon a common naming
+ convention.
+ </p>
+ <p>
+ A PropertySet is declared as a JSR-175 attribute interface within the Control Public Interface,
+ which is also decorated with the org.apache.beehive.controls.api.properties.PropertySet
+ meta-attribute. Each of the members within a PropertySet will refer to a distinct property
+ within the set, and the return value of the member defines the property type.
+ </p>
+ <p>
+ Here is a sample declaration of the Destination PropertySet for the JmsMessageControl, which can
+ be used to configure the target JMS destination for the Control:
+ </p>
+ <p>
+ <strong>Declaring Properties (Control Public Interface)</strong>
+ </p>
<source>package org.apache.beehive.controls.examples;
import org.apache.beehive.controls.api.bean.ControlInterface
-import org.javacontrols.api.properties.PropertySet;
+import org.apache.beehive.controls.api.properties.PropertySet;
+
+import java.lang.annotation.ElementType;
import java.lang.annotations.Retention;
import java.lang.annotations.RetentionPolicy;
import java.lang.annotations.Target;
@@ -952,31 +996,56 @@
}</strong>
...
}</source>
-<p>This declaration defines the PropertySet named âDestinationâ that includes two properties: type and name. The type property is based upon the DestinationType enumerated type, which is also defined in the public interface. The name attribute is a simple String property.</p>
-<p>Meta-attributes on a PropertySet or property declaration can be used to provide additional details about the properties and how they may be used. In the above example, the standard java.lang.annotations.Target annotation is used to define the places where the @Destination property set can appear (in this case in either an extension class or field declaration). </p>
-<p>The full set of meta-attributes that can decorate PropertySet or Property declarations are TBD.
- They can be used to define constraint models for property values, or relationships between
- properties (such as exclusive or, where one is set or the other, but never both). These
- meta-attributes can be read and used by development or administrative tools to aid in the
- selection of property values. They can also be used by the runtime for runtime validation of
- property values when set dynamically. The current set of property constraint mechanisms
- is implemented by the <code>@AnnotationConstraints</code> annotation. See
- <a href="#property_constraints">Defining Property Constraints</a> below for details.
- </p>
-
+ <p>
+ This declaration defines the PropertySet named âDestinationâ that includes two properties: type and name.
+ The type property is based upon the DestinationType enumerated type, which is also defined in the public interface.
+ The name attribute is a simple String property.
+ </p>
+ <p>
+ Meta-attributes on a PropertySet or property declaration can be used to provide additional details about the
+ properties and how they may be used. In the above example, the standard java.lang.annotations.Target annotation
+ is used to define the places where the @Destination property set can appear (in this case in either an extension
+ class or field declaration).
+ </p>
+ <p>
+ The full set of meta-attributes that can decorate PropertySet or Property declarations are TBD.
+ They can be used to define constraint models for property values, or relationships between
+ properties (such as exclusive or, where one is set or the other, but never both). These
+ meta-attributes can be read and used by development or administrative tools to aid in the
+ selection of property values. They can also be used by the runtime for runtime validation of
+ property values when set dynamically. The current set of property constraint mechanisms
+ is implemented by the <code>@AnnotationConstraints</code> annotation. See
+ <a href="#property_constraints">Defining Property Constraints</a> below for details.
+ </p>
</section>
<section id="accessing_props_from_client_code">
<title>Accessing Properties from Client Code</title>
-<p>The properties defined in the Control Public Interface will be exposed to the client programmer using traditional JavaBean setter/getter methods on the ControlBean Generated Class. These methods will follow a simple naming pattern based upon the PropertySet interface name, and optional PropertySet prefix, and property member name. </p>
-<p>The basic pattern for these accessors is:</p>
-
-<p><strong>Property Accessor Generation (Conventions)</strong></p>
+ <p>
+ The properties defined in the Control Public Interface will be exposed to the client programmer using traditional
+ JavaBean setter/getter methods on the ControlBean Generated Class. These methods will follow a simple naming
+ pattern based upon the PropertySet interface name, and optional PropertySet prefix, and property member name.
+ </p>
+ <p>
+ The basic pattern for these accessors is:
+ </p>
+ <p>
+ <strong>Property Accessor Generation (Conventions)</strong>
+ </p>
<source> public void set<PropertySetPrefix><MemberName>(<MemberType>);
public <MemberType> get<PropertySetPrefix><MemberName>();</source>
- <p>The PropertySetPrefix refers to the optional prefix attribute of the PropertySet annotation. If unspecified, it will default to an empty string (no prefix). The MemberName refers to the PropertySet method name that declares the property, with the first character converted to uppercase, and the MemberType refers to the return value type of this method declaration.</p>
-<p>So for the Destination PropertySet interface shown in the example above, the resulting ControlBean Generated Class would expose the following accessors:</p>
-
-<p><strong>Property Accessors (ControlBean Generated Class)</strong></p>
+ <p>
+ The PropertySetPrefix refers to the optional prefix attribute of the PropertySet annotation. If unspecified, it
+ will default to an empty string (no prefix). The MemberName refers to the PropertySet method name that declares
+ the property, with the first character converted to uppercase, and the MemberType refers to the return value type
+ of this method declaration.
+ </p>
+ <p>
+ So for the Destination PropertySet interface shown in the example above, the resulting ControlBean Generated Class
+ would expose the following accessors:
+ </p>
+ <p>
+ <strong>Property Accessors (ControlBean Generated Class)</strong>
+ </p>
<source>package org.apache.beehive.controls.examples;
import java.util.TooManyListenersException;
@@ -989,20 +1058,34 @@
public void setDestinationName(String name) { ...}
public String getDestinationName();
}</source>
-<p>Client code to set the Destination properties on a JmsMessageControlBean instance would look like:</p>
+ <p>
+ Client code to set the Destination properties on a JmsMessageControlBean instance would look like:
+ </p>
+ <p>
+ <strong>Using Property Accessors (Client Code)</strong>
+ </p>
+<source> @Control JmsMessageControlBean jmsBean;
+
+ ...
-<p><strong>Using Property Accessors (Client Code)</strong></p>
-<source>@Control JmsMessageControlBean jmsBean;
-...
<strong>jmsBean.setDestinationType(DestinationType.QUEUE);
jmsBean.setDestinationName("myTargetQueue");</strong></source>
</section>
<section id="accessing_props_from_impl_code">
<title>Accessing Properties from Control Implementation code</title>
- <p>The Control Implementation class contains code that executes from within the context of the Control JavaBean that is generated to host the control. The generated bean will automatically manage the resolution of properties values from annotations, external configuration, or dynamic values set by the client.</p>
-<p>Access to these properties is provided by the ControlBeanContext instance associated with the Control Implementation Class. This interface provides a set of property accessors that allow the implementation to query for property values:</p>
-
-<p><strong>ControlBeanContext APIs for Property Access</strong></p>
+ <p>
+ The Control Implementation class contains code that executes from within the context of the Control JavaBean that
+ is generated to host the control. The generated bean will automatically manage the resolution of properties
+ values from annotations, external configuration, or dynamic values set by the client.
+ </p>
+ <p>
+ Access to these properties is provided by the ControlBeanContext instance associated with the Control
+ Implementation Class. This interface provides a set of property accessors that allow the implementation to
+ query for property values:
+ </p>
+ <p>
+ <strong>ControlBeanContext APIs for Property Access</strong>
+ </p>
<source>package org.apache.beehive.controls.api.context;
public interface ControlBeanContext
@@ -1017,13 +1100,19 @@
getParameterPropertySet(Method m, index I, Class<T> propertySet);
...
}</source>
- <p>The propertySet argument passed to these methods must be a valid PropertySet interface associated with the ControlInterface. The ControlBeanContext will return the current value for properties in the PropertySet, or will return null if no PropertySet value has been associated with this control instance.</p>
-<p>Here is a simple example of using ControlBeanContext.getControlPropertySet() to query a property set:</p>
-
-<p><strong>Acccessing Control Properties (Client Implementation Class)</strong></p>
+ <p>
+ The propertySet argument passed to these methods must be a valid PropertySet interface associated with the
+ ControlInterface. The ControlBeanContext will return the current value for properties in the PropertySet, or
+ will return null if no PropertySet value has been associated with this control instance.
+ </p>
+ <p>
+ Here is a simple example of using ControlBeanContext.getControlPropertySet() to query a property set:
+ </p>
+ <p>
+ <strong>Acccessing Control Properties (Client Implementation Class)</strong>
+ </p>
<source>package org.apache.beehive.controls.examples;
-import javax.servlet.ServletContext;
import org.apache.beehive.controls.api.bean.ControlImplementation;
import org.apache.beehive.controls.api.context.Context;
import org.apache.beehive.controls.api.context.ControlBeanContext;
@@ -1036,48 +1125,71 @@
public void sendTextMessage(String text)
{
...
- Destination destinationProperty = (Destination) context.getControlPropertySet( Hello.Destination.class );
- if( destinationProperty == null ) {
+ Destination destProperty = (Destination) context.getControlPropertySet( Destination.class );
+ if( destProperty == null ) {
System.out.println( "Dest Property NOT Set" );
} else {
System.out.println( "Dest Property Set" );
}
- }
+ }
}</source>
- <p>This code above queries for the value of the JmsMessageControl.Destination PropertySet on the current JmsMessageControl instance.</p>
- <p>These query methods will return the value of resolved properties for the Control instance, method, or method argument, respectively. Control implementations should never use Java reflection metadata accessors directly on Control classes or methods; these accessors wonât reflect any property values that have been set dynamically by ControlBean client accessor methods or externally using administrative configuration mechanisms. The ControlBeanContext provides a consistent resolution of source annotation, client-provided, and external values.</p>
-<p>A simple example of using the ControlBeanContext property accessor methods for accessing Method and Parameter properties is provided in the section on Extensibility.</p>
+ <p>
+ This code above queries for the value of the JmsMessageControl.Destination PropertySet on the current
+ JmsMessageControl instance.
+ </p>
+ <p>
+ These query methods will return the value of resolved properties for the Control instance, method, or method
+ argument, respectively. Control implementations should never use Java reflection metadata accessors directly on
+ Control classes or methods; these accessors wonât reflect any property values that have been set dynamically by
+ ControlBean client accessor methods or externally using administrative configuration mechanisms.
+ The ControlBeanContext provides a consistent resolution of source annotation, client-provided, and external values.
+ </p>
+ <p>
+ A simple example of using the ControlBeanContext property accessor methods for accessing Method and Parameter
+ properties is provided in the section on Extensibility.
+ </p>
</section>
<section id="external_config_of_props">
<title>External Configuration of Control Properties</title>
- <p>Controls also support an administrative model that allows Control property values to be bound using external configuration syntax. The enables Control behavior to be parameterized externally to the code, and using a consistent mechanism that is well-defined and structured to enable tooling.</p>
-<p>The specifics of this administrative model are not covered within this document.</p>
-
+ <p>
+ Controls also support an administrative model that allows Control property values to be bound using external
+ configuration syntax. The enables Control behavior to be parameterized externally to the code, and using a
+ consistent mechanism that is well-defined and structured to enable tooling.
+ </p>
+ <p>
+ The specifics of this administrative model are not covered within this document.
+ </p>
</section>
- <section id="property_constraints">
- <title>Defining Property Constraints</title>
- <p>You can set up constraints on control properties using the
- <code>@AnnotationConstraints</code>
- annotation. <code>@AnnotationConstraints</code> allows you to set up
- rules related to (1) the instantiation of the control properties
- by client code, (2) external overriding of the control, and (3)
- the Beehive runtime version required by the control. </p>
- <p><strong>Note:</strong> the constraint rules are enforced at build time,
- when controls are declared in client code by <code>@Control</code>. There is no runtime
- enforcement of the rules.</p>
- <p>For example the following constraints require that</p>
- <ul>
- <li>
- all attributes must be referenced when declaring the control BookControl
- </li>
- <li>
- the values of the "title" and "subject" attributes must not exceed 10 characters in length
- </li>
- <li>
- the value of the "content" attribute must not exceed 200 characters in length
- </li>
- </ul>
- <source>import java.lang.annotation.*;
+ <section id="property_constraints">
+ <title>Defining Property Constraints</title>
+ <p>
+ You can set up constraints on control properties using the
+ <code>@AnnotationConstraints</code>
+ annotation. <code>@AnnotationConstraints</code> allows you to set up
+ rules related to (1) the instantiation of the control properties
+ by client code, (2) external overriding of the control, and (3)
+ the Beehive runtime version required by the control.
+ </p>
+ <p>
+ <strong>Note:</strong> the constraint rules are enforced at build time,
+ when controls are declared in client code by <code>@Control</code>. There is no runtime
+ enforcement of the rules.
+ </p>
+ <p>
+ For example the following constraints require that
+ </p>
+ <ul>
+ <li>
+ all attributes must be referenced when declaring the control BookControl
+ </li>
+ <li>
+ the values of the "title" and "subject" attributes must not exceed 10 characters in length
+ </li>
+ <li>
+ the value of the "content" attribute must not exceed 200 characters in length
+ </li>
+ </ul>
+<source>import java.lang.annotation.*;
import org.apache.beehive.controls.api.bean.AnnotationContstraints.MembershipRule;
import org.apache.beehive.controls.api.bean.AnnotationContstraints.MembershipRuleValues;
@@ -1108,29 +1220,29 @@
}
...
-}
- </source>
- <p>The following client code will cause a compile error, because it violates two of the
- constraints:</p>
- <ul>
- <li>
- The "all if any" constraint on the BookControl.Intro annotation is violated
- because only two (title and subject) of the three attributes (title, subject,
- and content) are referenced.
- </li>
- <li>
- The subject attribute's value exceeds 10 characters in length.
- </li>
- </ul>
- <source> @Control
+}</source>
+ <p>
+ The following client code will cause a compile error, because it violates two of the constraints:
+ </p>
+ <ul>
+ <li>
+ The "all if any" constraint on the BookControl.Intro annotation is violated
+ because only two (title and subject) of the three attributes (title, subject,
+ and content) are referenced.
+ </li>
+ <li>
+ The subject attribute's value exceeds 10 characters in length.
+ </li>
+ </ul>
+<source> @Control
@BookControl.Intro( title="title", subject="subject of the book" )
BookControlBean myBook</source>
-<p>When constraining properties with <code>@AnnotationConstraints</code>, all of the property
- members must be annotated
- with <code>@AnnotationMemberTypes</code>, or compile errors will be thrown. For example, the following
- will <em>not</em> compile, because not all of the property members (namely <code>someMember3()</code>)
- are decorated with
- <code>@AnnotationMemberTypes</code>.</p>
+ <p>
+ When constraining properties with <code>@AnnotationConstraints</code>, all of the property members must be annotated
+ with <code>@AnnotationMemberTypes</code>, or compile errors will be thrown. For example, the following
+ will <em>not</em> compile, because not all of the property members (namely <code>someMember3()</code>)
+ are decorated with <code>@AnnotationMemberTypes</code>.
+ </p>
<source>
@AnnotationConstraints.MembershipRule(AnnotationConstraints.MembershipRuleValues.EXACTLY_ONE)
public @interface SomeProperty
@@ -1143,20 +1255,38 @@
}</source>
<p>Not all Java types are supported by <code>@AnnotationMemberTypes</code>. For a list of the supported types
see <a href="../apidocs/classref_controls/org/apache/beehive/controls/api/bean/AnnotationMemberTypes.html">Interface AnnotationMemberTypes</a>.</p>
- </section>
+ </section>
</section>
<section id="extensibility">
<title>Extensibility</title>
-<p>The Controls architecture supports an extensibility model that enables the declarations of user-defined operations or events, based upon a predefined set of semantics defined by the author of the Control type. The extensibility mechanism enables the definition of an interface to the resource where operations (or events) have very specific context. </p>
-<p>For example, in the JmsMessageControl sample, the extensibility mechanism will be used to raise the level of abstraction: instead of a low-level mechanism to enqueue messages to a topic or queue, the Control enables extensibility where operations can be defined that correspond to enqueuing messages with a very specific format and set of properties, and where message or property content is derived from method parameters. This creates a logical view of the resource (in this case a queue or topic) where the operations available on it have very specific (and constrained) semantics.</p>
-<p>For this section, weâll start with the how an extension is defined, look at the authoring model for defining an extensible Control type, and finally show the client view of using an extended type.</p>
+ <p>
+ The Controls architecture supports an extensibility model that enables the declarations of user-defined operations or
+ events, based upon a predefined set of semantics defined by the author of the Control type. The extensibility
+ mechanism enables the definition of an interface to the resource where operations (or events) have very specific
+ context.
+ </p>
+ <p>
+ For example, in the JmsMessageControl sample, the extensibility mechanism will be used to raise the level of
+ abstraction: instead of a low-level mechanism to enqueue messages to a topic or queue, the Control enables
+ extensibility where operations can be defined that correspond to enqueuing messages with a very specific format and
+ set of properties, and where message or property content is derived from method parameters. This creates a
+ logical view of the resource (in this case a queue or topic) where the operations available on it have very specific
+ (and constrained) semantics.
+ </p>
+ <p>
+ For this section, weâll start with the how an extension is defined, look at the authoring model for defining an
+ extensible Control type, and finally show the client view of using an extended type.
+ </p>
<section>
<title>Defining an Extended Interface for a Control Type</title>
- <p>An extension to a base Control type that defines a specific resource use case is
-created by defining a new Control type that derives from the original type and is annotated with the
-ControlExtension annotation type:</p>
-
-<p><strong>Declaring a Control Extension (Control Extension Interface)</strong></p>
+ <p>
+ An extension to a base Control type that defines a specific resource use case is
+ created by defining a new Control type that derives from the original type and is annotated with the
+ ControlExtension annotation type:
+ </p>
+ <p>
+ <strong>Declaring a Control Extension (Control Extension Interface)</strong>
+ </p>
<source>package org.apache.beehive.controls.examples;
import org.apache.beehive.controls.api.bean.ControlExtension;
@@ -1169,10 +1299,18 @@
{
...
}</source>
-<p>This example shows how property values can be configured on the extended interface to further parameterize the use case. In this case, the InvoiceQueue interface is being designed for a very specific use case: to enable orders to be enqueued to a JMS queue named "queue.orders".</p>
-<p>Once defined, the Control extension author can now begin to define additional operations on it, in this case the ability to enqueue messages to the OrderQueue by calling methods on it.</p>
-
-<p><strong>Declaring Extended Operations with Properties (Control Extension Interface)</strong></p>
+ <p>
+ This example shows how property values can be configured on the extended interface to further parameterize the use
+ case. In this case, the InvoiceQueue interface is being designed for a very specific use case: to enable orders
+ to be enqueued to a JMS queue named "queue.orders".
+ </p>
+ <p>
+ Once defined, the Control extension author can now begin to define additional operations on it, in this case the
+ ability to enqueue messages to the OrderQueue by calling methods on it.
+ </p>
+ <p>
+ <strong>Declaring Extended Operations with Properties (Control Extension Interface)</strong>
+ </p>
<source>package org.apache.beehive.controls.examples;
import org.apache.beehive.controls.api.bean.ControlExtension;
@@ -1197,16 +1335,35 @@
@Property ( name="DeliverBy" ) String deliverBy
);</strong>
}</source>
-<p>This interface defines a single operation, submitOrder, that enqueues an ObjectMessage containing a new order. The body of the message will be a single instance of the Order class, and it will have a single StringProperty with the expected delivery date (enabling message selector-based queries for orders that are past due).</p>
-<p>The message format (in this case an ObjectMessage) and the mapping of operation parameters to message content and/or properties are all defined using JSR-175 metadata on the method or its parameters. This format makes it very easy for tools to assist in the creation and presentation of extension interfaces.</p>
-<p>How does the extension author (or tool) know about the set of annotations that can be used on the extension interface? This is the topic of the next section.</p>
+ <p>
+ This interface defines a single operation, submitOrder, that enqueues an ObjectMessage containing a new order.
+ The body of the message will be a single instance of the Order class, and it will have a single StringProperty
+ with the expected delivery date (enabling message selector-based queries for orders that are past due).
+ </p>
+ <p>
+ The message format (in this case an ObjectMessage) and the mapping of operation parameters to message content
+ and/or properties are all defined using JSR-175 metadata on the method or its parameters. This format makes it
+ very easy for tools to assist in the creation and presentation of extension interfaces.
+ </p>
+ <p>
+ How does the extension author (or tool) know about the set of annotations that can be used on the extension
+ interface? This is the topic of the next section.
+ </p>
</section>
<section>
<title>Defining Extension Semantics for a Control Type</title>
- <p>A Control author is responsible for defining the extensibility semantics for a particular type, since ultimately they are responsible for providing the implementation that fulfills the semantics. </p>
-<p>The extension semantics for a Control are part of the public contract for the Control, and thus are defined on the Control Public Interface as well. As with Control properties, these are defined in the form of JSR-175 annotation interfaces, as show in the following sample code from the JmsMessageControl Public Interface:</p>
-
-<p><strong>Declaring Extension Semantics (Control Public Interface)</strong></p>
+ <p>
+ A Control author is responsible for defining the extensibility semantics for a particular type, since ultimately
+ they are responsible for providing the implementation that fulfills the semantics.
+ </p>
+ <p>
+ The extension semantics for a Control are part of the public contract for the Control, and thus are defined on
+ the Control Public Interface as well. As with Control properties, these are defined in the form of JSR-175
+ annotation interfaces, as show in the following sample code from the JmsMessageControl Public Interface:
+ </p>
+ <p>
+ <strong>Declaring Extension Semantics (Control Public Interface)</strong>
+ </p>
<source>package org.apache.beehive.controls.examples;
import java.io.Serializable;
@@ -1241,15 +1398,38 @@
public String name();
}</strong>
}</source>
-<p>The JmsMessageMessageControl defines three annotation types: Message, Body, and Property. The @Target annotation on the Message declaration specifies that Message can be placed on the method declaration to indicate the type of JMS message that will be enqueued by the operation. The Body annotation is used to indicate the method parameter that contains the contents of the message (and must have a type that is compatible with the specified MessageType). The Property annotation on a method parameter indicates that the parameterâs value should be stored as a property on the enqueue message, with the property name coming from the value of the annotation and the property type derived from the type of the method parameter.</p>
-<p>The key is that the Control Public Interface contains sufficient details about the expected annotations that a tool can support the construction. It also makes it possible for the Control compiler (that converts the extended interface to an associated bean implementation) to perform validation of interface and method annotations.</p>
-<p>More details on how these extension semantics are implemented are described in the next section.</p>
+ <p>
+ The JmsMessageMessageControl defines three annotation types: Message, Body, and Property. The @Target annotation
+ on the Message declaration specifies that Message can be placed on the method declaration to indicate the type of
+ JMS message that will be enqueued by the operation. The Body annotation is used to indicate the method parameter
+ that contains the contents of the message (and must have a type that is compatible with the specified MessageType).
+ The Property annotation on a method parameter indicates that the parameterâs value should be stored as a property
+ on the enqueue message, with the property name coming from the value of the annotation and the property type
+ derived from the type of the method parameter.
+ </p>
+ <p>
+ The key is that the Control Public Interface contains sufficient details about the expected annotations that a
+ tool can support the construction. It also makes it possible for the Control compiler (that converts the
+ extended interface to an associated bean implementation) to perform validation of interface and method annotations.
+ </p>
+ <p>
+ More details on how these extension semantics are implemented are described in the next section.
+ </p>
</section>
<section>
<title>Authoring an Extensible Control Type</title>
- <p>The author of a Control type is responsible for providing the code that implements the extension semantics for the Control. Support for extensibility is optional; so a Control author indicates extensibility of a type by declaring that that the Control Implementation Class implements the org.apache.beehive.controls.api.bean.Extensible interface. This interface has a single method named invoke(). </p>
-<p>The skeleton of this code for the JmsMessageControlImpl class is shown below:</p>
-<p><strong>Implementing Extended Operations (Control Implementation Class)</strong></p>
+ <p>
+ The author of a Control type is responsible for providing the code that implements the extension semantics for
+ the Control. Support for extensibility is optional; so a Control author indicates extensibility of a type by
+ declaring that that the Control Implementation Class implements the org.apache.beehive.controls.api.bean.Extensible
+ interface. This interface has a single method named invoke().
+ </p>
+ <p>
+ The skeleton of this code for the JmsMessageControlImpl class is shown below:
+ </p>
+ <p>
+ <strong>Implementing Extended Operations (Control Implementation Class)</strong>
+ </p>
<source>package org.apache.beehive.controls.examples;
import org.apache.beehive.controls.api.bean.ControlImplementation;
@@ -1270,9 +1450,19 @@
}</strong>
}
</source>
-<p>The invoke() method on the Control Implementation Class will be called any time an operation defined on an extension interface is called on the Control by its client. The implementation of this method has responsibility for examining the current set of properties for the Control instance, methods, and parameters and using them to parameterize the behavior of the Control.</p>
-<p>This is demonstrated by the code below, which shows a portion of the implementation of invoke() for the JmsMessageControlImpl class:</p>
-<p><strong>Accessing Method Properties Using the Context (Control Implementation)</strong></p>
+ <p>
+ The invoke() method on the Control Implementation Class will be called any time an operation defined on an
+ extension interface is called on the Control by its client. The implementation of this method has responsibility
+ for examining the current set of properties for the Control instance, methods, and parameters and using them to
+ parameterize the behavior of the Control.
+ </p>
+ <p>
+ This is demonstrated by the code below, which shows a portion of the implementation of invoke() for the
+ JmsMessageControlImpl class:
+ </p>
+ <p>
+ <strong>Accessing Method Properties Using the Context (Control Implementation)</strong>
+ </p>
<source>Object invoke(Method m, Object [] args) throws Throwable
{
...
@@ -1313,26 +1503,41 @@
msg.setObjectProperty(name, args[I);
}
}</source>
-<p>In the sample code above, the Control Implementation Class uses the ControlBeanContext getMethodProperty and getParameterProperty APIs to query properties of the invoked method and its argument. These query methods will return null if the property is not found and no default was defined for the attribute member.</p>
-
+ <p>
+ In the sample code above, the Control Implementation Class uses the ControlBeanContext getMethodProperty and
+ getParameterProperty APIs to query properties of the invoked method and its argument. These query methods will
+ return null if the property is not found and no default was defined for the attribute member.
+ </p>
</section>
<section>
<title>Client Model for Using an Extended Control Type</title>
- <p>The client model for using an extended Control type is exactly the same as the model for using a base Control type. The same set of declarative and programmatic instantiation mechanisms (described in the previous section) will be used, and operations or events are handled the same way.</p>
-<p>Below is sample code that uses the OrderQueue extended type (using declarative client model):</p>
-<p><strong>Using a Control Extension (Client Code)</strong></p>
-<source><strong>@Control org.apache.beehive.controls.examples.OrderQueueBean orderBean;</strong>
-...
- Order order = new OrderQueue.Order();
- order.buyerID = myID;
- order.itemList = new String [] {"item1", "item2"};
- orderBean.submitOrder(order, "12-31-2004");
+ <p>
+ The client model for using an extended Control type is exactly the same as the model for using a base Control type.
+ The same set of declarative and programmatic instantiation mechanisms (described in the previous section) will be
+ used, and operations or events are handled the same way.
+ </p>
+ <p>
+ Below is sample code that uses the OrderQueue extended type (using declarative client model):
+ </p>
+ <p>
+ <strong>Using a Control Extension (Client Code)</strong>
+ </p>
+<source><strong> @Control org.apache.beehive.controls.examples.OrderQueueBean orderBean;</strong>
+ ...
+ Order order = new OrderQueue.Order();
+ order.buyerID = myID;
+ order.itemList = new String [] {"item1", "item2"};
+ orderBean.submitOrder(order, "12-31-2004");
</source>
-<p>Looking closely at the example, youâll notice that a derived ControlBean type (OrderQueueBean) is generated by the Control compiler, just as it is for a base Control type.
-The skeleton of this ControlBean Generated Class is shown below:
-</p>
-<p><strong>Implementation of Extended Operations (ControlBean Generated Class)</strong></p>
-<source>Package org.apache.beehive.controls.examples;
+ <p>
+ Looking closely at the example, youâll notice that a derived ControlBean type (OrderQueueBean) is generated by
+ the Control compiler, just as it is for a base Control type. The skeleton of this ControlBean Generated Class is
+ shown below:
+ </p>
+ <p>
+ <strong>Implementation of Extended Operations (ControlBean Generated Class)</strong>
+ </p>
+<source>package org.apache.beehive.controls.examples;
public class OrderQueueBean
extends JmsMessageControlBean
@@ -1340,32 +1545,57 @@
{
JmsMessageControlImpl _impl;
...
- Public void submitOrder(Object order, String deliveryBy)
+ public void submitOrder(Object order, String deliveryBy)
{
...
_impl.invoke(submitOrderMethod, new Object [] {order, deliveryBy};
...
}
}</source>
- <p>There are several attributes worth noting about the extended ControlBean Generated Class:</p>
- <ul>
- <li> Its implementation will be a subclass of the base type ControlBean, so implementation of base type operations is inherited.</li>
-
- <li> The extended bean will implement the extended Control interface, meaning all extended operations will be implemented by the bean.</li>
-</ul>
-<p>The implementation of these extended operations will always delegate down to the base Control Implementation Class by calling the Extensible.invoke() method.</p>
+ <p>
+ There are several attributes worth noting about the extended ControlBean Generated Class:
+ </p>
+ <ul>
+ <li>
+ Its implementation will be a subclass of the base type ControlBean, so implementation of base type operations
+ is inherited.
+ </li>
+ <li>
+ The extended bean will implement the extended Control interface, meaning all extended operations will be
+ implemented by the bean.
+ </li>
+ </ul>
+ <p>
+ The implementation of these extended operations will always delegate down to the base Control Implementation Class
+ by calling the Extensible.invoke() method.
+ </p>
</section>
</section>
-
<section id="composition">
<title>Composition</title>
- <p>The Controls architecture supports a composition model, based upon the JavaBeans Runtime Containment and Services Protocol. This means that it is possible for new types of ControlBeans to be defined that are built through composition of one or more other types.</p>
+ <p>
+ The Controls architecture supports a composition model, based upon the JavaBeans Runtime Containment and Services
+ Protocol. This means that it is possible for new types of ControlBeans to be defined that are built through
+ composition of one or more other types.
+ </p>
<section>
<title>Composition Using Declarative Instantiation</title>
- <p>Additionally, the ControlBeans authoring model makes composition very simple based upon the declarative instantiation model. Within any ControlBean implementation, any @Control fields will automatically be initialized as children of the local beanâs context.</p>
-<p>Hereâs a simple example based upon our previous OrderQueue example. Letâs say that we want to create a logical Control that can be used to submit orders. This Control will submit to one of two different queues, depending upon whether the order needs to ship in less than 30 days, or greater than 30 days.</p>
-<p>The implementation of this Control could look like:</p>
- <p><strong>Composition Using Declarative Instantiation (Control Implementation Class)</strong></p>
+ <p>
+ Additionally, the ControlBeans authoring model makes composition very simple based upon the declarative
+ instantiation model. Within any ControlBean implementation, any @Control fields will automatically be
+ initialized as children of the local beanâs context.
+ </p>
+ <p>
+ Hereâs a simple example based upon our previous OrderQueue example. Letâs say that we want to create a logical
+ Control that can be used to submit orders. This Control will submit to one of two different queues, depending
+ upon whether the order needs to ship in less than 30 days, or greater than 30 days.
+ </p>
+ <p>
+ The implementation of this Control could look like:
+ </p>
+ <p>
+ <strong>Composition Using Declarative Instantiation (Control Implementation Class)</strong>
+ </p>
<source>package org.apache.beehive.controls.examples;
@ControlImplementation(isTransient=true)
@@ -1388,13 +1618,30 @@
}
}
</source>
-<p>In this example, the OrderRouterImpl Control itself uses the services of two different OrderQueue Controls referencing two different queues, and uses a helper method (needsRushDelivery) to decide where to enqueue a particular order. The new Control has the same operations exposed as the original Controls; but now uses the services of one or the other of its children to satisfy the request.</p>
-<p>The next section describes doing an equivalent composition using mechanisms to instantiate and build the Control hierarchy.</p>
+ <p>
+ In this example, the OrderRouterImpl Control itself uses the services of two different OrderQueue Controls
+ referencing two different queues, and uses a helper method (needsRushDelivery) to decide where to enqueue a
+ particular order. The new Control has the same operations exposed as the original Controls; but now uses the
+ services of one or the other of its children to satisfy the request.
+ </p>
+ <p>
+ The next section describes doing an equivalent composition using mechanisms to instantiate and build the Control
+ hierarchy.
+ </p>
<section>
<title>Composition using Programmatic Mechanisms</title>
-<p>Because the ControlBeans architecture is built using the JavaBeans Runtime Containment protocol, which defines a base composition model for JavaBeans, it is also possible to manually instantiate and Controls using the APIs it defines. The ControlBeanContext API extends the java.beans.beancontext.BeanContext API, which provides support for adding children to the current beanâs context.</p>
-<p>Hereâs the previous sample, rewritten to use programmatic composition:</p>
-<p><strong>Composition Using Programmatic Instantiation (Control Implementation Class)</strong></p>
+ <p>
+ Because the ControlBeans architecture is built using the JavaBeans Runtime Containment protocol, which defines
+ a base composition model for JavaBeans, it is also possible to manually instantiate and Controls using the APIs
+ it defines. The ControlBeanContext API extends the java.beans.beancontext.BeanContext API, which provides
+ support for adding children to the current beanâs context.
+ </p>
+ <p>
+ Hereâs the previous sample, rewritten to use programmatic composition:
+ </p>
+ <p>
+ <strong>Composition Using Programmatic Instantiation (Control Implementation Class)</strong>
+ </p>
<source>package org.apache.beehive.controls.examples;
@ControlImplementation(isTransient=true)
@@ -1432,54 +1679,114 @@
</section>
<section>
<title>Internal Architecture for Composition and Services</title>
- <p>The JavaBeans Runtime Containment and Services Protocol provides the base composition model for Control composition and containment. In this model, JavaBeans are associated with a BeanContext that manages the composition hierarchy and also manages any contextual services requested by the contained beans.</p>
-<p>In the Control architecture, a ControlBean will potentially be related to two different BeanContexts: a parent context that represents the outer container for the bean, and a peer context that provides containment and services to other beans nested within that Control.</p>
-<p>These context relationships from the previous sample are shown in the following diagram:</p>
-<p><img src="images/conProg3.gif" alt=""/></p>
-<p>In the diagram, the two OrderQueueBean instances created by OrderRouterBean are nested within the ControlBeanContext; while not shown, these two beans would also have a peer ControlBeanContext providing them with contextual services.</p>
-<p>The peer ControlBeanContext provides localized generic services to the associated Control Implementation instance, such as ability to resolve property values from the local bean instance or externalized configuration, and the delivery of lifecycle events. The ControlBean architecture uses a delegation model for service discovery. If an implementation instance requests a service that is not implemented by the peer BeanContext, it will delegate up to the parent context to find a provider for the service.</p>
-<p>At the root of the bean composition hierarchy is an instance of a ContainerBeanContext. This context represents the external runtime environment, within which the ControlBean is running. This might represent an EJB, servlet, web service, Java application, or any ControlBean-capable container. The ContainerBeanContext is responsible for the initialization and provisioning of service providers that are specific to runtime environment with which it is associated.</p>
-<p>Whether ContainerBeanContext or ControlBeanContext, the BeanContext instances also provide the basic hierarchy of composition, as shown by the parent-child relationships above.</p>
+ <p>
+ The JavaBeans Runtime Containment and Services Protocol provides the base composition model for Control
+ composition and containment. In this model, JavaBeans are associated with a BeanContext that manages the
+ composition hierarchy and also manages any contextual services requested by the contained beans.
+ </p>
+ <p>
+ In the Control architecture, a ControlBean will potentially be related to two different BeanContexts: a parent
+ context that represents the outer container for the bean, and a peer context that provides containment and
+ services to other beans nested within that Control.
+ </p>
+ <p>
+ These context relationships from the previous sample are shown in the following diagram:
+ </p>
+ <p>
+ <img src="images/conProg3.gif" alt=""/>
+ </p>
+ <p>
+ In the diagram, the two OrderQueueBean instances created by OrderRouterBean are nested within the
+ ControlBeanContext; while not shown, these two beans would also have a peer ControlBeanContext providing them
+ with contextual services.
+ </p>
+ <p>
+ The peer ControlBeanContext provides localized generic services to the associated Control Implementation instance,
+ such as ability to resolve property values from the local bean instance or externalized configuration, and the
+ delivery of lifecycle events. The ControlBean architecture uses a delegation model for service discovery. If
+ an implementation instance requests a service that is not implemented by the peer BeanContext, it will delegate up
+ to the parent context to find a provider for the service.
+ </p>
+ <p>
+ At the root of the bean composition hierarchy is an instance of a ContainerBeanContext. This context represents
+ the external runtime environment, within which the ControlBean is running. This might represent an EJB, servlet, web
+ service, Java application, or any ControlBean-capable container. The ContainerBeanContext is responsible for the
+ initialization and provisioning of service providers that are specific to runtime environment with which it is
+ associated.
+ </p>
+ <p>
+ Whether ContainerBeanContext or ControlBeanContext, the BeanContext instances also provide the basic hierarchy of
+ composition, as shown by the parent-child relationships above.
+ </p>
</section>
</section>
<section id="inheritance">
<title>Inheritance</title>
- <p>The Controls architecture also makes it possible to extend the functionality of existing Controls using standard Java inheritance. While more complex scenarios are possible, a common model for extending a Control type using inheritance involves extending both public interface and the implementation to extend base functionality by adding new operations, events, or properties.</p>
-<p>The following code sample shows the basic structure:</p>
-<p><strong>Basic Inheritance Sample Code</strong></p>
-<source>
- // A.java: The base control interface
- @ControlInterface
- public interface A { ... }
-
- // AImpl.java: The implementation of the base control interface
- @ControlImplementation(isTransient=true)
- public class AImpl implements A { ... }
-
- // B.java: The extension of the base interface that adds
- // operations, properties, and/or events
- @ControlInterface
- public interface B extends A { ... }
-
- // BImpl.java: The implementation of the extended control interface
- @ControlImplementation(isTransient=true)
- public class BImpl implements B { ... }
-</source>
+ <p>
+ The Controls architecture also makes it possible to extend the functionality of existing Controls using standard Java
+ inheritance. While more complex scenarios are possible, a common model for extending a Control type using
+ inheritance involves extending both public interface and the implementation to extend base functionality by adding
+ new operations, events, or properties.
+ </p>
+ <p>
+ The following code sample shows the basic structure:
+ </p>
+ <p>
+ <strong>Basic Inheritance Sample Code</strong>
+ </p>
+<source>// A.java: The base control interface
+@ControlInterface
+public interface A { ... }
-<p>In the example above, the BBean JavaBean class that results from processing of B.java will expose the operations, properties, and events defined by both the A and B control interfaces. The BImpl class would need to implement all operations defined by the B interface, and could also choose to override some, all, or none of the operations defined by A.</p>
+// AImpl.java: The implementation of the base control interface
+@ControlImplementation
+public class AImpl implements A { ... }
-<p>Inheritance is also supported for extensible control types. If AImpl implements the Extensible interface, then BImpl could choose to define additional extensibility PropertySets and implement a new Extensible.invoke() method to provide their semantics (delegating to AImpl.invoke() as appropriate). It could also choose not to extend the extensibilty semantics and allow all operations defined within a ControlExtension derived from B to be handled by AImpl.invoke().</p>
+// B.java: The extension of the base interface that adds
+// operations, properties, and/or events
+@ControlInterface
+public interface B extends A { ... }
+// BImpl.java: The implementation of the extended control interface
+@ControlImplementation
+public class BImpl implements B { ... }
+</source>
+ <p>
+ In the example above, the BBean JavaBean class that results from processing of B.java will expose the operations,
+ properties, and events defined by both the A and B control interfaces. The BImpl class would need to implement all
+ operations defined by the B interface, and could also choose to override some, all, or none of the operations defined
+ by A.
+ </p>
+ <p>
+ Inheritance is also supported for extensible control types. If AImpl implements the Extensible interface, then BImpl
+ could choose to define additional extensibility PropertySets and implement a new Extensible.invoke() method to provide
+ their semantics (delegating to AImpl.invoke() as appropriate). It could also choose not to extend the extensibilty
+ semantics and allow all operations defined within a ControlExtension derived from B to be handled by AImpl.invoke().
+ </p>
</section>
-
<section id="context_and_resource_events">
<title>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:</p>
+ <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:
+ </p>
<section>
<title>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>
+ <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>package org.apache.beehive.controls.api.context;
public interface ControlBeanContext
@@ -1498,26 +1805,44 @@
public void addLifeCycleListener(LifeCycle listener);
public void removeLifeCycleListener(LifeCycle listener);</strong>
}</source>
-<p>The specific life cycle and resource events are described in the following section:</p>
+ <p>
+ The specific life cycle and resource events are described in the following section:
+ </p>
<section>
<title>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>
+ <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>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>
+ <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>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>
+ <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>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>
-
+ <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
@@ -1535,25 +1860,51 @@
}</source>
<section>
<title>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 <a href="site:control_overview">Control Overview</a>.</p>
+ <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 <a href="site:control_overview">Control Overview</a>.
+ </p>
</section>
-
<section>
<title>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>
-
+ <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>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>
+ <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>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>
+ <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.bean.ControlImplementation;
@@ -1588,13 +1939,25 @@
...
}</strong>
}</source>
-<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>
+ <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>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>
+ <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();
@@ -1610,82 +1973,98 @@
</section>
<section>
<title>JavaBean Context Events</title>
- <p>The org.apache.beehive.controls.api.context.ControlBeanContext API extends the following standard JavaBean context APIs:</p>
+ <p>
+ The org.apache.beehive.controls.api.context.ControlBeanContext API extends the following standard JavaBean context APIs:
+ </p>
<ul>
- <li> java.beans.BeanContextChild</li>
- <li> java.beans.BeanContext</li>
- <li> java.beans.BeanContextServices</li>
+ <li>java.beans.BeanContextChild</li>
+ <li>java.beans.BeanContext</li>
+ <li>java.beans.BeanContextServices</li>
</ul>
- <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>
+ <p>
+ These APIs provide access to a standard set of JavaBean events that the Control Implementation Class can register
+ an interest in.
+ </p>
+ <!--[todo][Issue: there is not a declarative mechanism for receiving these events, but probably should be.]-->
<section>
<title>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>
+ <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>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>
+ <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>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>
+ <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>
</section>
-
<section id="appendix_a">
<title>Appendix A: The JmsMessageControl Public Interface</title>
<source>package org.apache.beehive.controls.examples;
-import java.io.*;
-import java.lang.annotation.*;
-import javax.jms.*;
-
import org.apache.beehive.controls.api.bean.ControlInterface;
import org.apache.beehive.controls.api.events.EventSet;
import org.apache.beehive.controls.api.properties.PropertySet;
+import javax.jms.Session;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
/**
- * The JmsMessageControl defines a basic Control to enable messages
- * to be enqueued to a JMS queue or topic. Using Control properties,
- * you can configure the connection, session, and destination attributes
- * that should be used to connect to the JMS provider. The Control
- * will transparently connect to the JMS provider and obtain any
- * necessary resources to enqueue the messages. The Control will
- * also sure that the resources are properly released at the end of the
- * current resource scope associated with the Controlâs runtime
- * environment.
- *
- * The Control provides a basic set of operations that allow a simple text
- * or object message to be written to the configured destination. It also
- * provides an extensibility mechanism that allows new operations to be
- * defined by extending this interface. Extended operations define the
- * enqueueing of message with a specific type
- * (TextMessage, ObjectMessage, ...) where operation parameters can be
- * mapped to message properties or content.
- */
+ * The JmsMessageControl defines a basic Control to enable messages
+ * to be enqueued to a JMS queue or topic. Using Control properties,
+ * you can configure the connection, session, and destination attributes
+ * that should be used to connect to the JMS provider. The Control
+ * will transparently connect to the JMS provider and obtain any
+ * necessary resources to enqueue the messages. The Control will
+ * also sure that the resources are properly released at the end of the
+ * current resource scope associated with the Controlâs runtime
+ * environment.
+ *
+ * The Control provides a basic set of operations that allow a simple text
+ * or object message to be written to the configured destination. It also
+ * provides an extensibility mechanism that allows new operations to be
+ * defined by extending this interface. Extended operations define the
+ * enqueueing of message with a specific type
+ * (TextMessage, ObjectMessage, ...) where operation parameters can be
+ * mapped to message properties or content.
+ */
@ControlInterface
public interface JmsMessageControl
{
// OPERATIONS
- /**
- * Sends a simple TextMessage to the Controlâs destination
- * @param text the contents of the TextMessage
- */
+ /**
+ * Sends a simple TextMessage to the Controlâs destination
+ * @param text the contents of the TextMessage
+ */
public void sendTextMessage(String text) throws javax.jms.JMSException;
/**
- * Sends a simple ObjectMessage to the Controlâs destination
- * @param object the object to use as the contents of the message
- */
+ * Sends a simple ObjectMessage to the Controlâs destination
+ * @param object the object to use as the contents of the message
+ */
public void sendObjectMessage(java.io.Serializable object) throws javax.jms.JMSException;
// EVENTS
- /**
- * The Callback interface defines the events for the JmsMessageControl.
- */
+ /**
+ * The Callback interface defines the events for the JmsMessageControl.
+ */
@EventSet
public interface Callback
{
@@ -1700,11 +2079,11 @@
// PROPERTIES
- /**
[... 53 lines stripped ...]