Author: ekoneil
Date: Wed Aug 24 10:15:06 2005
New Revision: 239717
URL: http://svn.apache.org/viewcvs?rev=239717&view=rev
Log:
Code formatting and syntax fixup in the Controls overview document.
BB: self
DRT build.release pass
Modified:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/overview.xml
Modified:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/overview.xml
URL:
http://svn.apache.org/viewcvs/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/overview.xml?rev=239717&r1=239716&r2=239717&view=diff
==============================================================================
---
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/overview.xml
(original)
+++
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/overview.xml
Wed Aug 24 10:15:06 2005
@@ -36,21 +36,20 @@
What initially appears to be a simple task in the abstract (call these EJBs or
enqueue a message that looks like this) can devolve into hours or days of
reading J2EE HowTo books and Javadoc API references, getting the right
deployment descriptor values configured, and calling all the right APIs, at all
of the right times, in the right order. In the resulting application or
service, often the directly application-related code (i.e. calling the bean
business method or building message contents) is a small fraction of the total
code required to accomplish the task.</p>
<p>
Here is an example of the code required to invoke a single method on an
exposed EJB using standard J2EE APIs: </p>
- <source>Trader trader = null;
-try
-{
+ <source>
+Trader trader = null;
+
+try {
InitialContext ic = new InitialContext();
TraderHome home = (TraderHome)ic.lookup("MyTraderBean");
Trader trader = home.create();
TradeResult tradeResult = trader.buy(stock, shares);
- return tradeResult;
+ return tradeResult;
}
-catch (NamingException ne)
-{
+catch (NamingException e) {
...
}
-finally
-{
+finally {
if (trader != null)
trader.remove();
}</source>
@@ -68,29 +67,48 @@
</section>
<section>
<title>Solution: Controls: A Unified Client Programming Model
</title>
- <p>Controls reduce the complexity and learning curve
associated with acting as a client of J2EE resources by providing a unified
client model that can provide access to diverse types of resources.</p>
+ <p>Controls reduce the complexity and learning curve
associated with acting as a client of J2EE resources by providing
+ a unified client model that can provide access to diverse
types of resources.
+ </p>
<p>
<strong>To the client, Controls appear as JavaBeans that
can be instantiated and used for resource access.</strong>
</p>
- <p>Properties that parameterize resource access can be set
using JSR-175 metadata attributes, as arguments to factory-based instantiation,
or even bound using externalized configuration data. These configuration
mechanisms are consistent across all resource types, and Controls provide the
appropriate mapping to resource-type-specific APIs or deployment descriptor
entries. </p>
+ <p>Properties that parameterize resource access can be set
using JSR-175 metadata attributes, as arguments to factory-based
+ instantiation, or even bound using externalized
configuration data. These configuration mechanisms are consistent across
+ all resource types, and Controls provide the appropriate
mapping to resource-type-specific APIs or deployment descriptor entries.
+ </p>
<p>
-Controls present operations on the resource as methods on the JavaBean
interface. They also support a two-way communication style where resource
events can be delivered to a registered listener.</p>
+ Controls present operations on the resource as methods on the
JavaBean interface. They also support a two-way communication style
+ where resource events can be delivered to a registered
listener.
+ </p>
<p>
- <strong>
-Controls provide a consistent model for discovering the configuration options,
operations, and events exposed by a resource. </strong>
+ <strong>Controls provide a consistent model for
discovering the configuration options, operations, and events exposed by a
resource. </strong>
</p>
<p>
-Controls can also provide transparent (to the client) resource management of
connections, sessions, or other resources to be obtained on behalf of the
client, held for an appropriate resource scope to achieve best performance, and
then released. This resource management mechanism frees the client from having
to learn or understand the acquisition mechanisms, and from having to directly
participate in guaranteeing their release. The Controls architecture provides
this functionality by defining a simple resource management contract that can
cooperate with an outer container to manage resources at the appropriate scope
(for example, bounded to a transaction context or outer container operation or
request scope).</p>
+ Controls can also provide transparent (to the client) resource
management of connections, sessions, or other resources to be obtained on
+ behalf of the client, held for an appropriate resource scope
to achieve best performance, and then released. This resource management
mechanism
+ frees the client from having to learn or understand the
acquisition mechanisms, and from having to directly participate in guaranteeing
their
+ release. The Controls architecture provides this functionality
by defining a simple resource management contract that can cooperate with an
+ outer container to manage resources at the appropriate scope
(for example, bounded to a transaction context or outer container operation or
request scope).
+ </p>
<p>
-Using a Control that exposes the Trader EJB in the earlier example, the code
to invoke the buy() method on this bean can become:</p>
- <p>The TraderBean Control fully encapsulates the JNDI lookup
as well as the home/bean interface operations needed to get an instance of the
Trader EJB and invoke the buy() method on it, and exposes the JNDI name of the
EJB as a property that can be set either programmatic, via metadata, or using
an external deployment descriptor. </p>
+ Using a Control that exposes the Trader EJB in the earlier
example, the code to invoke the buy() method on this bean can become:
+ </p>
+<source>
+ traderControl.buy();
+</source>
+ <p>The TraderBean Control fully encapsulates the JNDI lookup
as well as the home/bean interface operations needed to get an
+ instance of the Trader EJB and invoke the buy() method on
it, and exposes the JNDI name of the EJB as a property that can
+ be set either programmatic, via metadata, or using an
external deployment descriptor.
+ </p>
<p>
-Controls also provide an extensibility model that allows customized view of a
resource to be
-constructed, with discrete operations defined as methods on the control. For
example, it is
-possible to define a custom operation on a Control type representing a JMS
queue resource,
-that uses metadata attributes to define the format of the message, with
message contents set
-from message parameters. This enables the professional developer (or even the
corporate
-developer) to construct new customized facades for resource access with a
minimum of effort. </p>
+ Controls also provide an extensibility model that allows
customized view of a resource to be
+ constructed, with discrete operations defined as methods on
the control. For example, it is
+ possible to define a custom operation on a Control type
representing a JMS queue resource,
+ that uses metadata attributes to define the format of the
message, with message contents set
+ from message parameters. This enables the professional
developer (or even the corporate
+ developer) to construct new customized facades for resource
access with a minimum of effort.
+ </p>
<p>
<strong>The goal of the Controls architecture is not to
define the standards for how specific resource types will be exposed; rather,
it is to guarantee that when exposed they will have a commonality in mechanism
that makes them easier to understand and use by developers.</strong>
</p>
@@ -151,10 +169,8 @@
<p>Controls also provide a JAR-based packaging mechanism, for
how Control types can be discovered within a jar. </p>
<p><strong>
The Controls architecture provides a well-defined packaging model that enables
system vendors, 3rd party providers, or J2EE system developers (in the
collaborative scenario) to distribute controls that offer client access to
provided services or components. An IDE can then discover packaged controls to
present them in a palette or list of available resource types for client use.
-</strong></p>
-
-
-
+</strong>
+</p>
</section>
</section>
<section>
@@ -182,24 +198,23 @@
Here is a simple example that represents the client interface to a timer
service resource:
</p>
<source>
+import org.apache.beehive.controls.api.bean.ControlExtension;
@ControlInterface
-public interface TimerControl
-{
+public interface TimerControl {
+
public void start() throws IllegalStateException;
public void stop();
@EventSet
- public interface Callback
- {
+ public interface Callback {
public void onTimeout(long time);
}
-} </source>
+}
+</source>
<p>In this example, TimerControl is the base public interface for timer
Control. The TimerControl supports operations related to setting and using a
timer (start, stop), as well as a single event (onTimeout) that will be
delivered when the timer fires.
</p>
-
-
</section>
<section>
<title> Public Interface / Private Implementation /
ControlBean Wrapper </title>
@@ -255,15 +270,17 @@
public @interface Timer {
/** @return timeout Duration as string */
- @AccessModes (property-style=true, external=true) String timeOut();
-...
- }</source>
+ @AccessModes (property-style=true, external=true)
+ String timeOut();
+ }
+</source>
<p>
This defines a metadata attribute (com.myco.Timer) that has a String member
value named 'timeOut'. The AccessModes meta-attribute specifies that the member
can be set via JavaBean property-style accessors and external configuration, as
well as using declarative metadata.
</p>
<p>An example of setting the timeOut member of the Timer metadata attribute
inside of client code might look like:
</p>
-<source>@Timer(timeout="3 seconds")
+<source>
[EMAIL PROTECTED](timeout="3 seconds")
public TimerControlBean myTimerBean;
</source>
<p>
@@ -279,11 +296,12 @@
</p>
<p>
The configuration of the timeout member based upon external configuration
would look something like: </p>
-<source>â¦
- <timer:timer xmlns:timer="http://openuri.org/com/myco/TimerControl";>
- <timer:timeOut>3 seconds</timer:timeOut>
- </timer:timer>
-â¦</source>
+<source><![CDATA[
+ <timer:timer xmlns:timer="http://openuri.org/com/anyco/TimerControl";>
+ <timer:timeOut>3 seconds</timer:timeOut>
+ </timer:timer>
+]]>
+</source>
<p></p>
</section>
@@ -298,14 +316,25 @@
<p>
An example of the customized interface for this Control might look like:
</p>
- <source>@ControlExtension public interface CustomerDatabase
extends DatabaseControl
-{
- @sql (statement="INSERT INTO CUSTOMERDB (ID, NAME) VALUES ({id},
{name})")
- int newCustomer(int id, String name) throws SQLException;
+ <source>
+
+import javax.sql.SQLException;
+
+import org.apache.beehive.controls.api.bean.ControlExtension;
+import org.apache.beehive.controls.system.jdbc.JdbcControl;
+
[EMAIL PROTECTED]()
+public interface CustomerDatabase
+ extends JdbcControl {
+
+ @SQL(statement="INSERT INTO CUSTOMERDB (ID, NAME) VALUES ({id}, {name})")
+ int newCustomer(int id, String name)
+ throws SQLException;
- @sql (statement="SELECT * FROM CUSTOMERDB WHERE ID = {id}")
- Customer findCustomer(int id);
-}</source>
+ @SQL(statement="SELECT * FROM CUSTOMERDB WHERE ID = {id}")
+ Customer findCustomer(int id);
+}
+</source>
<p>
In this simple example, each operation on the interface corresponds to a SQL
prepared statement to be executed. Metadata attributes on the methods are used
to define the additional semantics required, in this case the actual SQL
statement to invoke. </p>
<p>
@@ -395,18 +424,18 @@
<p>
The programmatic client model follows the basic pattern of JavaBeans
construction and event handling:
</p>
-<source>TimerControlBean myTimerBean =
- (TimerControlBean)Controls.instantiate(classloader,
"com.myco.TimerControlBean");
+<source>
+TimerControlBean myTimerBean =
(TimerControlBean)Controls.instantiate(classloader,
"com.myco.TimerControlBean");
myTimerBean.setTimeout("3 seconds");
myTimerBeans.addTimerControlEventListener(
- new TimerControlEventListener() // anonymous event handler class
- {
- public void onTimeout(long time)
- {
+ // anonymous event handler class
+ new TimerControlEventListener() {
+ public void onTimeout(long time) {
// timer event handling code
}
}
-);</source>
+);
+</source>
<p>
In the example above, a factory-based instantiation API
(Controls.instantiate()) is used to construct a new instance of the
TimerControlBean. It is programmatically initialized to the desired
configuration, and then an event handler (based upon the declaration of an
anonymous inner class) is used to service events from the bean.
</p>
@@ -417,14 +446,15 @@
<p>
The following example is equivalent to the preceding example, but uses
declarative style construction and event routing:
</p>
-<source>@Timer(timeout="3 seconds") TimerControlBean myTimerBean;
+<source>
[EMAIL PROTECTED](timeout="3 seconds") TimerControlBean myTimerBean;
...
-public void myTimerBean_onTimeout(long time)
-{
+public void myTimerBean_onTimeout(long time) {
// timer event handling code
-}</source>
+}
+</source>
<p>In this example, the TimerControlBean instance is declared with attributes
specified using JSR-175 metadata. There is no implicit construction of the bean
instance; the client container for the ControlBean will recognize the presence
of the Control declaration and will implicitly initialize the instance.
Additionally, it (also implicitly) declares the necessary event listener class
and routing code to deliver onTimeout events on the TimerControlBean instance
to the declared event handler.</p>
</section>
</section>
