Author: steveh
Date: Tue Mar 1 15:56:10 2005
New Revision: 155842
URL: http://svn.apache.org/viewcvs?view=rev&rev=155842
Log:
A fix for BEEHIVE-151: Section number issues in ControlsProgramming doc
I applied Jeremiah's patch to make the fix.
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?view=diff&r1=155841&r2=155842
==============================================================================
---
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 Mar 1 15:56:10 2005
@@ -6,7 +6,7 @@
</header>
<body>
<section>
- <title>1. Overview</title>
+ <title>Overview</title>
<p>The Control architecture is a lightweight component framework
based upon JavaBeans, which exposes a simple and consistent client model for
accessing a variety of resource types. Controls take the base functionality
of JavaBeans and add in the following unique new capabilities:</p>
<ul>
<li>Enhanced authoring model: uses a public interface contract and an
associated implementation class to enable generation of a supporting JavaBean
class for handling the details of property management and initialization. </li>
@@ -26,7 +26,7 @@
</section>
<section>
- <title>2. An Example</title>
+ <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>
<source>OrderQueueBean orderBean = (OrderQueueBean)
@@ -39,7 +39,7 @@
</section>
<section>
- <title>3. The Control Authoring Model</title>
+ <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>
<li><strong><em>Control Public Interface</em></strong>: source
file that defines the set of operations, events, extensibility model, and
properties associated with the Control type.</li>
@@ -77,7 +77,7 @@
</section>
<section>
- <title>4. The Control Client Models</title>
+ <title>The Control Client Models</title>
<p>There are actually two distinct programming models that may be
available to clients of Controls:</p>
<ul>
<li><strong>Declarative Model.</strong> Uses a
metadata-based variant of the Inversion of Control (IoC) design pattern to
allow a component author to declare Control instances, contextual services, and
event handlers using annotated fields and methods. The declarative model
simplifies client programming, because many of the details of initialization
and event routing are left to an external container supporting the model. A
declarative programming style is also more toolable, since it is much easier
for tools to manage and manipulate metadata rather than code.</li>
@@ -91,7 +91,7 @@
</section>
<section>
- <title>5. Defining a New Control Type</title>
+ <title>Defining a New Control Type</title>
<p>Controls are designed to make it very easy for users (and tools) to define
new types of Controls. Control authors might be:</p>
<ul>
<li> System vendors exposing specific types of resources</li>
@@ -144,10 +144,10 @@
</section>
<section>
- <title>6. Instantiating a Control</title>
+ <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>
- <title>6.1 Declarative Instantiation</title>
+ <title>Declarative Instantiation</title>
<p>The client model for Controls supports a declarative model for
instantiating a Control instance, when running in containers that support this
model. In this model, the client class can annotate fields on the class
using a special marker annotation
(org.apache.beehive.controls.api.bean.Control) that indicates that the fields
should be initialized to a ControlBean instance of the requested type.</p>
<p>Here is an example of declarative instantiation:</p>
<p><strong>Declarative Instantiation (Client Code)</strong></p>
@@ -177,7 +177,7 @@
<p>The Controls architecture includes a mechanism for defining the expected
set of annotations that might appear on a Control field. This mechanism is
described in greater detail in the section on Properties.</p>
</section>
<section>
- <title>6.2 Programmatic Instantiation</title>
+ <title>Programmatic Instantiation</title>
<p>The client model for Controls supports instantiation of a
new Control instance using the same factory-based model supported by JavaBeans.
For example, the following code could be used to create a new instance of the
JmsMessageControlBean generated class:</p>
<p><strong>Programmatic Instantiation (Client Code)</strong></p>
<source>JmsMessageControlBean myJmsBean = (JmsMessageControlBean)
@@ -200,10 +200,10 @@
</section>
<section>
- <title>7. Operations</title>
+ <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>
- <title>7.1 Declaring and Implementing Operations for a Control
</title>
+ <title>Declaring and Implementing Operations for a Control
</title>
<p>All methods declared or inherited (via extension) by the
Control Public Interface are considered to be Control operations. The
following example shows the definition of two operations on the
JmsMessageControl that will enqueue messages when invoked:</p>
<p><strong>Declaring Operations (Control Public Interface)</strong></p>
<source>package org.apache.beehive.controls.examples;
@@ -263,7 +263,7 @@
</section>
<section>
- <title>7.2 Invoking Operations on a Control</title>
+ <title>Invoking Operations on a Control</title>
<p>The client model for invoking an operation on a Control is very
straightforward: simply call the method on a held ControlBean instance as
demonstrated by the following example:</p>
<p><strong>Invoking an Operation (Client Code)</strong></p>
<source> myJmsBean.sendTextMessage("A Text Message");</source>
@@ -272,12 +272,12 @@
</section>
<section>
- <title>8. Events</title>
+ <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>
<section>
- <title>8.1 Declaring Events</title>
+ <title>Declaring Events</title>
<p>Events are declared on an inner interface of the Control Public Interface,
which is annotated with the org.apache.beehive.controls.api.events.EventSet
annotation. The following example shows the declaration of an event
interface for the JmsMessageControl, with a single event (onMessage):</p>
<p><strong>Declaring Events (Control Public Interface)</strong></p>
<source>package org.apache.beehive.controls.examples;
@@ -329,7 +329,7 @@
<p>A Control Public Interface can have more than one inner interface that is
annotated as an EventSet interface. Each declared EventSet will have its own
independently managed list of registered listeners.</p>
</section>
<section>
- <title>8.2 Firing Events</title>
+ <title>Firing Events</title>
<p>This section describes the mechanism available to a Control
author to deliver events to any registered client listener. <strong>An
initialized event proxy is created when the Control Implementation Class
declares a field of an EventSet interface type, and annotates it with the
org.apache.beehive.controls.events.Client annotation type.</strong> The
containing ControlBean will initialize this reference to a valid proxy
implementing the EventSet interface, and the Control Implementation Class can
use this proxy to fire events back to any registered client.</p>
<p>This is demonstrated in the following sample code from the JmsControlBean
implementation class, which will fire an onMessage event back to any registered
client any time a message is enqueued:</p>
@@ -353,10 +353,10 @@
}</source>
</section>
<section>
- <title>8.3 Listening for Events</title>
+ <title>Listening for Events</title>
<p>The client of a Control can express an interest in
receiving events from a Control and write client event handlers to service them
once delivered. Two basic event handling mechanisms are supported: Java event
listeners or declarative event handlers (where supported by the client
container).</p>
<section>
- <title>8.3.1 Declarative Implementation of Event
Handling</title>
+ <title>Declarative Implementation of Event Handling</title>
<p>If the client code is implemented in a container that
supports the declarative programming model for Controls (such as the Control
Implementation Class itself), it can use a simplified convention for authoring
event handlers for a declared Control instance.</p>
<p>If a Control is declared using the @Control marker interface, then
<strong>the user can declare event handlers for the Control by using the
EventHandler annotation type</strong>. These annotated methods will be
considered an event handler for the Control event, and the container will
automatically register for events and deliver them to this handler.</p>
<p>The previous example could be rewritten using the declarative event
handling style as:</p>
@@ -383,7 +383,7 @@
</section>
<section>
- <title>8.3.2 Programmatic Implementation of Event
Handling</title>
+ <title>Programmatic Implementation of Event
Handling</title>
<p>The programmatic style follows the tradition Java event
listener pattern. The client expresses its interest in receiving the event and
also authors a (often anonymous inner) class that implements the event
interface to receive events when delivered.</p>
<p>This is shown by the following sample code:</p>
@@ -403,7 +403,7 @@
</section>
<section>
- <title>9. Contextual Services</title>
+ <title>Contextual Services</title>
<p>The Control authoring model makes use of contextual services to
provide access to services from the current runtime environment of the
ControlBean. The model for contextual services is based upon the existing
standards for services in JavaBeans: The JavaBeans Runtime Containment and
Services Protocol. This protocol provides a base mechanism for a JavaBean to
locate and use services from the runtime environment, as well as an extensible
service provider model to enable new (or environment-specific) types of
services to be authored and made available to JavaBeans/Controls.</p>
<p>A key aspect of this service model is that it can be contextual; for
example, it might be possible to write a basic security service interface that
provides logical role-checking functionality. The actual implementation of
this interface might vary for different runtime contexts: for example, the
role check might be done differently for a Control running within the context
of an EJB container (by delegating to the containing EJBContext) vs. a Control
running within the Web tier (by delegating to ServletHttpRequest services).</p>
<p>Having an extensibility and service provider location model is important to
enable the following scenarios:</p>
@@ -413,7 +413,7 @@
</ul>
<p><strong>One key contextual service for Controls that is guaranteed to be
available in all contexts is the
org.apache.beehive.controls.api.context.ControlBeanContext service interface.
</strong>This service provides a common set of generic services that are
available to Control authors, such as the ability to query property values on
the current instance, or to receive a set of basic lifecycle or resource
management events. The ControlBeanContext interface extends the
java.beans.beancontext.BeanContextServices interface, so it also provides
access to services provided by the JavaBeans bean context APIs. Later
sections describe an overview of the internal architecture for contextual
services, APIs to support property resolution, and lifecycle events.</p>
<section>
- <title>9.1 Declarative Access to Contextual Services</title>
+ <title>Declarative Access to Contextual Services</title>
<p>To signal the desire to access a contextual service, a
Control author only needs to declare a field of the desired context interface
and annotate it with the org.apache.beehive.controls.api.context.Context marker
annotation. The following example shows how the JmsMessageControlImpl class
would use the declarative model to access its ControlBeanContext:</p>
<p><strong>Declarative Access to Context Services (Control Implementation
Class)</strong></p>
@@ -438,7 +438,7 @@
</section>
<section>
- <title>9.2 Programmatic Access to Contextual Services</title>
+ <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>
@@ -468,7 +468,7 @@
</section>
<section>
- <title>9.3 Tradeoffs between Declarative and Programmatic
Access</title>
+ <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>
@@ -480,7 +480,7 @@
</section>
<section>
- <title>10. Properties</title>
+ <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>
@@ -490,7 +490,7 @@
</ul>
<p>The external configuration and administrative model for Controls
will be described in a separate document.</p>
<section>
- <title>10.1 Declaring Properties for a Control Type</title>
+ <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>
@@ -528,7 +528,7 @@
</section>
<section>
- <title>10.2 Accessing Properties from Client Code</title>
+ <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>
@@ -560,7 +560,7 @@
jmsBean.setDestinationName("myTargetQueue");</strong></source>
</section>
<section>
- <title>10.3 Accessing Properties from Control Implementation
code</title>
+ <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>
@@ -615,7 +615,7 @@
<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>
- <title>10.4 External Configuration of Control
Properties</title>
+ <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>
@@ -623,12 +623,12 @@
</section>
<section>
- <title>11. Extensibility</title>
+ <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>
<section>
- <title>11.1 Defining an Extended Interface for a Control
Type</title>
+ <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>
@@ -674,7 +674,7 @@
<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>11.2 Defining Extension Semantics for a Control
Type</title>
+ <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>
@@ -714,7 +714,7 @@
<p>More details on how these extension semantics are implemented are described
in the next section.</p>
</section>
<section>
- <title>11.3 Authoring an Extensible Control Type</title>
+ <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>
@@ -782,7 +782,7 @@
</section>
<section>
- <title>11.4 Client Model for Using an Extended Control
Type</title>
+ <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>
@@ -823,10 +823,10 @@
</section>
<section>
- <title>12. Composition</title>
+ <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>
- <title>12.1 Composition Using Declarative Instantiation</title>
+ <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>
@@ -855,7 +855,7 @@
<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>12.1.1 Composition using Programmatic
Mechanisms</title>
+ <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>
@@ -894,7 +894,7 @@
</section>
</section>
<section>
- <title>12.2 Internal Architecture for Composition and
Services</title>
+ <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>
@@ -907,10 +907,10 @@
</section>
<section>
- <title>13. Context and Resource Events</title>
+ <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>
- <title>13.1 Life Cycle Events</title>
+ <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>
@@ -934,22 +934,22 @@
}</source>
<p>The specific life cycle and resource events are described in the following
section:</p>
<section>
- <title>13.1.1 The onCreate Event</title>
+ <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>
</section>
<section>
- <title>13.1.2 The onPropertyChange Event</title>
+ <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>
</section>
<section>
- <title>13.1.3 The onVetoableChange Event</title>
+ <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>
</section>
</section>
<section>
- <title>13.2 Resource Events</title>
+ <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>
<source>package org.apache.beehive.controls.api.context;
@@ -968,23 +968,23 @@
public void removeResourceEventsListener(ResourceEvents listener);</strong>
}</source>
<section>
- <title>13.2.1 The onAcquire Event</title>
+ <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>
</section>
<section>
- <title>13.2.2 The onRelease Event</title>
+ <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>
</section>
</section>
<section>
- <title>13.3 Receiving Life Cycle or Resource Events</title>
+ <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>
<section>
- <title>13.3.1 Declarative Access to events</title>
+ <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>
@@ -1023,7 +1023,7 @@
<p>When using the declarative mechanism, a Control Implementation Class is
free to implement only a subset of the events; it is not necessary that it
provide a handler for all events.</p>
</section>
<section>
- <title>13.3.2 Programmatic Access to Events</title>
+ <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>
@@ -1041,7 +1041,7 @@
</section>
</section>
<section>
- <title>13.4 JavaBean Context Events</title>
+ <title>JavaBean Context Events</title>
<p>The
org.apache.beehive.controls.api.context.ControlBeanContext API extends the
following standard JavaBean context APIs:</p>
<ul>
<li> java.beans.BeanContextChild</li>
@@ -1051,22 +1051,22 @@
<p>These APIs provide access to a standard set of JavaBean
events that the Control Implementation Class can register an interest in. </p>
<p><em>[todo][Issue: there is not a declarative mechanism for
receiving these events, but probably should be.]</em></p>
<section>
- <title>13.4.1 PropertyChange Events</title>
+ <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>
</section>
<section>
- <title>13.4.2 Membership Events</title>
+ <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>
</section>
<section>
- <title>13.4.3 Context Services Events</title>
+ <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>
</section>
</section>
</section>
<section>
- <title>14. Appendix A: The JmsMessageControl Public
Interface</title>
+ <title>Appendix A: The JmsMessageControl Public Interface</title>
<source>package org.apache.beehive.controls.examples;
import java.io.*;
@@ -1209,7 +1209,7 @@
</section>
<section>
- <title>15. Appendix B: The JmsMessageControl Implementation
Class</title>
+ <title>Appendix B: The JmsMessageControl Implementation
Class</title>
<source>package org.apache.beehive.controls.examples;
import org.apache.beehive.controls.api.bean.ControlImplementation;
