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/05/10 22:57:55 UTC
svn commit: r169521 -
/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsProgramming.xml
Author: steveh
Date: Tue May 10 13:57:54 2005
New Revision: 169521
URL: http://svn.apache.org/viewcvs?rev=169521&view=rev
Log:
Adding section on control property constraints.
Modified:
incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsProgramming.xml
Modified: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsProgramming.xml
URL: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsProgramming.xml?rev=169521&r1=169520&r2=169521&view=diff
==============================================================================
--- incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsProgramming.xml (original)
+++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsProgramming.xml Tue May 10 13:57:54 2005
@@ -1,11 +1,11 @@
<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v13.dtd">
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
<document>
<header>
<title>Controls Programming</title>
</header>
<body>
- <section>
+ <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>
@@ -22,10 +22,10 @@
<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 <link href="controlsOverview.html">Control Overview: Providing Simplified and Unified Access to J2EE Resources</link></p>
+ <p>An overview of the Control architecture and toolable access models can be found in the companion document entitled <a href="controlsOverview.html">Control Overview: Providing Simplified and Unified Access to J2EE Resources</a></p>
</section>
- <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>
@@ -38,7 +38,7 @@
<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>
+ <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>
<ul>
@@ -76,7 +76,7 @@
<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>
+ <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>
<ul>
@@ -90,7 +90,7 @@
</section>
- <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>
@@ -143,7 +143,7 @@
<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>
+ <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>
<section>
@@ -199,7 +199,7 @@
</section>
</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>
<section>
@@ -271,7 +271,7 @@
</section>
</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>
@@ -402,7 +402,7 @@
</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>
@@ -479,7 +479,7 @@
</section>
</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>
@@ -489,12 +489,21 @@
<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>
+ <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. 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>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>
<source>package org.apache.beehive.controls.examples;
@@ -524,10 +533,18 @@
}</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.</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>
+ <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>
@@ -559,7 +576,7 @@
<strong>jmsBean.setDestinationType(Destination.QUEUE);
jmsBean.setDestinationName("myTargetQueue");</strong></source>
</section>
- <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>
@@ -614,15 +631,62 @@
<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>
+ <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>
</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 constraint requires that exactly one property
+ be referenced when declaring the control BookControl.</p>
+ <source>
+@ControlInterface
+public interface BookControl
+{
+ ...
+
+ /**
+ * The user must set one value, and only one value when
+ * instantiating controls declaratively.
+ */
+ @PropertySet
+ @Target ({ElementType.FIELD, ElementType.TYPE})
+ @Retention(RetentionPolicy.RUNTIME)
+ <strong>@AnnotationConstraints.MembershipRule(AnnotationConstraints.MembershipRuleValues.EXACTLY_ONE)</strong>
+ public @interface Intro
+ {
+ @AnnotationMemberTypes.Text(maxLength=8)
+ public String title();
+ @AnnotationMemberTypes.Text(maxLength=8)
+ public String subject();
+ @AnnotationMemberTypes.Text(maxLength=8)
+ public String content();
+ }
+
+ ...
+}
+ </source>
+ <p>The following client code will cause a compile error, because it violates the
+ "exactly one" constraint on the BookControl.Intro property.</p>
+ <source> @Control
+ @BookControl.Intro(title="some title", subject="some subject")
+ BookControlBean myBook</source>
</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>
@@ -822,7 +886,7 @@
</section>
</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>
<section>
@@ -905,7 +969,7 @@
<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>
+ <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>
@@ -935,7 +999,7 @@
</section>
- <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>
<section>
@@ -1000,7 +1064,7 @@
<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 <link href="controlsOverview.html">Control Overview</link> document.</p>
+<p>For more details on resource management, refer to the <a href="controlsOverview.html">Control Overview</a> document.</p>
</section>
<section>
@@ -1094,7 +1158,7 @@
</section>
</section>
- <section>
+ <section id="appendix_a">
<title>Appendix A: The JmsMessageControl Public Interface</title>
<source>package org.apache.beehive.controls.examples;
@@ -1237,7 +1301,7 @@
}</source>
</section>
- <section>
+ <section id="appendix_b">
<title>Appendix B: The JmsMessageControl Implementation Class</title>
<source>package org.apache.beehive.controls.examples;