You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@beehive.apache.org by ek...@apache.org on 2005/08/24 19:15:10 UTC
svn commit: r239717 -
/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/overview.xml
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>
+@Timer(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;
+
+@ControlExtension()
+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>
+@Timer(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>