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>
[EMAIL PROTECTED]
+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;
