Author: steveh Date: Fri Dec 10 13:45:11 2004 New Revision: 111550 URL: http://svn.apache.org/viewcvs?view=rev&rev=111550 Log: Integrating live site edits to beta branch. Modified: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsProgramming.xml incubator/beehive/trunk/docs/forrest/src/documentation/skinconf.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&rev=111550&p1=incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsProgramming.xml&r1=111549&p2=incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsProgramming.xml&r2=111550 ============================================================================== --- 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 Fri Dec 10 13:45:11 2004 @@ -31,9 +31,9 @@ <p><strong>Enqueueing using OrderQueueBean (<em>Client Code</em>)</strong></p> <source>OrderQueueBean orderBean = (OrderQueueBean) -java.beans.Beans.instantiate(âorg.apache.beehive.controls.examples.OrderQueueBeanâ); -Order order = new Order(myID, new String [ ] {âitem1â, âitem2â}; -OrderBean.submitOrder(order, â01-28-2004â); +java.beans.Beans.instantiate("org.apache.beehive.controls.examples.OrderQueueBean"); +Order order = new Order(myID, new String [ ] {"item1", "item2"}; +OrderBean.submitOrder(order, "01-28-2004"); </source> <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> @@ -116,7 +116,7 @@ @ControlInterface public interface JmsMessageControl { - â + ... }</source> <p>The only basic rule for a Control Public Interface is that it must be annotated by the org.apache.beehive.controls.api.bean.ControlInterface marker interface.</p> <p>The second source artifact a Control author would create to define a new type of Control is the Control Implementation Class. This declaration of the implementation class for our JmsMessageControl would look like:</p> @@ -125,7 +125,7 @@ public class JmsMessageControlImpl implements JmsMessageControl { - â + ... }</source> <p>The only basic rule for a Control Implementation Class is that it must always implement the associated Control Public Interface.</p> <p>From these two source files, the Control compiler will create a third artifact, the ControlBean Generated Class. This class need not necessarily ever appear within an application in source code form; but for the purposes of explaining the overall architecture and client model, we will present source examples of the derived ControlBean Generated Class. </p> @@ -138,7 +138,7 @@ { private JmsMessageControlImpl _impl; - â + ... }</source> <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> @@ -158,20 +158,20 @@ <strong>@Control public JmsMessageControlBean myJmsBean;</strong> - â + ... public void someOperation() { - myJmsBean.sendTextMessage(âA Text Messageâ); + myJmsBean.sendTextMessage("A Text Message"); } }</source> <p>This example shows a second Control Implementation Class (PublisherControlImpl) that internally uses the services of JmsMessageControl to enqueue a JMS message. The child Control field is not explicitly initialized within the PublisherControl implementation class; by the time someOperation() is called, it is guaranteed that the myJmsBean reference has been initialized by the wrapping PublisherControlBean that contains the implementation.</p> <p>It is also possible to parameterize the attributes of a Control at construction time, again using metadata attributes. These attributes can be placed on the field declaration (in addition to the @Control annotation) and will be used to do construction-time initialization.</p> -<p>The second example below shows initialization of the myJmsBean field again. In this case, an initial value of the @Destination ânameâ attribute is also provided using JSR-175 metadata:</p> +<p>The second example below shows initialization of the myJmsBean field again. In this case, an initial value of the @Destination "name" attribute is also provided using JSR-175 metadata:</p> <p><strong>Declarative Instantiation with Properties (Client Code)</strong></p> <source>public class PublisherControlImpl extends PublisherControl { - <strong>@Control @Destination(name=âInvoiceQueueâ) </strong> + <strong>@Control @Destination(name="InvoiceQueue") </strong> public JmsMessageControlBean myJmsBean;</source> <p>This example performs <strong>exactly</strong> the same initialization as the earlier declarative example, but does so using JSR-175 attribute syntax instead of passing parameters to a factory-based constructor.</p> <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> @@ -181,17 +181,24 @@ <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) - <strong>java.beans.Beans.instantiate(cl, âorg.apache.beehive.controls.examples.JmsMessageControlBeanâ);</strong></source> +<strong>java.beans.Beans.instantiate( + cl, + "org.apache.beehive.controls.examples.JmsMessageControlBean" +);</strong></source> <p>The Control runtime also provides an extended factory model that allows metadata attributes to be passed into the factory constructor:</p> <p><strong>Programmatic Instantiation with Properties (Client Code)</strong></p> <source>import org.apache.beehive.controls.api.bean.Controls; import org.apache.beehive.controls.api.properties.PropertyMap; PropertyMap jmsAttr = new (PropertyMap(JmsMessageControl.Destination.class); -jmsAttr.setProperty(ânameâ, âInvoiceQueueâ); +jmsAttr.setProperty("name", "InvoiceQueue"); JmsMessageControlBean myJmsBean = (JmsMessageControlBean) - <strong>Controls.instantiate(cl, âorg.apache.beehive.controls.examples.JmsMessageControlBeanâ, jmsAttr);</strong> </source> - <p>In this example, the JmsMessageControlBean is being constructed with the Destination ânameâ property set to âInvoiceQueueâ. The AttributeMap class is a simple helper class that can hold a set of name-value pairs of a Controlâs properties, which are initialized by the factory-based constructor. More details on Controls properties are provided in a later section.</p> + <strong>Controls.instantiate( + cl, + "org.apache.beehive.controls.examples.JmsMessageControlBean", + jmsAttr + );</strong> </source> + <p>In this example, the JmsMessageControlBean is being constructed with the Destination "name" property set to "InvoiceQueue". The AttributeMap class is a simple helper class that can hold a set of name-value pairs of a Controlâs properties, which are initialized by the factory-based constructor. More details on Controls properties are provided in a later section.</p> </section> </section> @@ -212,7 +219,7 @@ <strong>public void sendTextMessage(String text); public void sendObjectMessage(Serializable object);</strong> - â + ... }</source> <p>The Control Implementation Class implements the public interface for the Control, defining the operation methods, and the body of these methods.</p> <p><strong>Implementing Operations (Control Implementation Class)</strong></p> @@ -223,13 +230,13 @@ <strong>public void sendTextMessage(String text) { // Code to send a TextMessage to the destination - â. + ... } public void sendObjectMessage(Serializable object) { // Code to send an ObjectMessage to the destination - â. + ... }</strong> } </source> @@ -244,16 +251,16 @@ <strong>public void sendTextMessage(String text) { - â. + ... _impl.sendTextMessage(text); - â. + ... } public void sendObjectMessage(Serializable object) { - â. + ... _impl.sendObjectMessage(object); - â. + ... }</strong> </source> @@ -262,7 +269,7 @@ <title>7.2 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> +<source> myJmsBean.sendTextMessage("A Text Message");</source> <p>The invocation model for operations is the same, whether the Control instance was created using declarative or programmatic mechanisms.</p> </section> </section> @@ -295,7 +302,7 @@ void onMessage(Message m); }</strong> - â + ... }</source> <p>If a Control Public Interface has defined an EventSet interface, then the associated ControlBean Generated Class will have two public methods supporting client listener management:</p> @@ -306,18 +313,19 @@ public class JmsMessageControIBean implements JmsMessageControl { - â + ... /** Registers a new client listener for this bean instance */ - <strong>public void addCallbackListener(Callback listener) throws TooManyListenersException</strong> + <strong>public void addCallbackListener(Callback listener) + throws TooManyListenersException</strong> { - â. + ... } /** Deregisters a client listener for this bean instance */ <strong>public void removeCallbackListener(Callback listener)</strong> { - â. + ... } }</source> <p>The name of the listener registration methods are based upon the name of the associated EventSet interface. In the previous example, the EventSet interface was named Callback, so the associated listener registration method was addCallbackListener(), and the deregistration method was removeCallbackListener().</p> @@ -340,11 +348,11 @@ public void sendTextMessage(String text) { // Code to construct and send a TextMessage to the destination - TextMessage m = â; - â. + TextMessage m = ...; + ... <strong>client.onMessage(m);</strong> } - â + ... }</source> </section> <section> @@ -365,13 +373,15 @@ @Control public JmsMessageControlBean myJmsBean; - <strong>@EventHandler (field=âmyJmsBeanâ, evenSet= JmsMessageControl.Callback.class, - eventName=âonMessageâ) + <strong>@EventHandler ( + field="myJmsBean", + evenSet= JmsMessageControl.Callback.class, + eventName="onMessage") public void myJmsBeanMessageHandler(Message m) { // Code implementing onMessage event handler }</strong> - â + ... }</source> </section> @@ -388,7 +398,8 @@ { // Code implementing on Message event handler } - });</source> + } +);</source> <p>There is no requirement that an anonymous inner class be used. One alternative would be to delegate to an instance of another class (as long as that class implements the Callback interface). In the preceding example, if event listening was implemented for the purposes of logging sent messages, and MessageLogger class could be declared (implementing the Callback interface), multiple beans could delegate to a single instance of this logging listener.</p> </section> </section> @@ -418,13 +429,12 @@ { <strong>@Context ControlBeanContext context;</strong> - public void sendTextMessage(String text) - { - JmsMessageControl.Destination = - <strong>context.getControlPropertySet(JmsMessageControl.Destination.class);</strong> - - â - } + public void sendTextMessage(String text) + { + JmsMessageControl.Destination = + <strong>context.getControlPropertySet(JmsMessageControl.Destination.class);</strong> + ... + } }</source> <p>In this example, the JmsMessageControl implementation class expresses its desire to access ControlBeanContext services via the annotated declaration of the context field; when code in sendTextMessage operation is invoked, this contextual service has already been initialized by the containing ControlBean instance.</p> <p>The ControlBeanContext for an authored Control is always accessed using the declarative mechanism. Other contextual services may be accessed declaratively, or using the programmatic mechanisms described in the following section.</p> @@ -445,15 +455,15 @@ { <strong>@Context ControlBeanContext context;</strong> - public void sendTextMessage(String text) + public void sendTextMessage(String text) { - <strong>ServletContext servletContext = context.getService(ServletContext.class, null);</strong> - if (servletContext == null) - { - // no ServletContext provider is available - } - - â + <strong>ServletContext servletContext = + context.getService(ServletContext.class, null);</strong> + if (servletContext == null) + { + // no ServletContext provider is available + } + ... } }</source> <p>The code in the sample uses the ControlBeanContext.getService API to request that it provide a ServletContext service. The parameters to this method are the Class of the requested service, and an (optional) service-specific selector that can be used to parameterize the service. </p> @@ -501,19 +511,19 @@ @ControlInterface public interface JmsMessageControl { - â + ... public enum DestinationType { QUEUE, TOPIC } - <strong>@PropertySet(prefix=âDestinationâ) - @Target({FIELD, TYPE}) - @Retention(RetentionPolicy.RUNTIME) + <strong>@PropertySet(prefix="Destination") + @Target({FIELD, TYPE}) + @Retention(RetentionPolicy.RUNTIME) public @interface Destination { public DestinationType type() default QUEUE; public String name(); }</strong> - â + ... }</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> @@ -538,22 +548,19 @@ public class JmsMessageControIBean implements JmsMessageControl { - â - public void setDestinationType(DestinationType type) { â } - public DestinationType getDestinationType() { â} - public void setDestinationName(String name) { â} + ... + public void setDestinationType(DestinationType type) { ... } + public DestinationType getDestinationType() { ...} + public void setDestinationName(String name) { ...} public String getDestinationName(); }</source> <p>Client code to set the Destination properties on a JmsMessageControlBean instance would look like:</p> <p><strong>Using Property Accessors (Client Code)</strong></p> <source>@Control JmsMessageControlBean jmsBean; - -â - +... <strong>jmsBean.setDestinationType(Destination.QUEUE); - jmsBean.setDestinationName(âmyTargetQueueâ);</strong></source> - + jmsBean.setDestinationName("myTargetQueue");</strong></source> </section> <section> <title>10.3 Accessing Properties from Control Implementation code</title> @@ -563,13 +570,17 @@ <p><strong>ControlBeanContext APIs for Property Access</strong></p> <source>package org.apache.beehive.controls.api.context; -public interface ControlBeanContext extends java.beans.beancontext.BeanContextServices +public interface ControlBeanContext + extends java.beans.beancontext.BeanContextServices { - â. - public <T extends Annotation> T getControlPropertySet(Class<T> propertySet); - public <T extends Annotation> T getMethodPropertySet(Method m, Class<T> propertySet); - public <T extends Annotation> T getParameterPropertySet(Method m, index I, Class<T> propertySet); - â + ... + public <T extends Annotation> T + getControlPropertySet(Class<T> propertySet); + public <T extends Annotation> T + getMethodPropertySet(Method m, Class<T> propertySet); + public <T extends Annotation> T + getParameterPropertySet(Method m, index I, Class<T> propertySet); + ... }</source> <p>The propertySet argument passed to these methods must be a valid PropertySet interface associated with the ControlInterface. The ControlBeanContext will return the current value for properties in the PropertySet, or will return null if no PropertySet value has been associated with this control instance.</p> <p>Here is a simple example of using ControlBeanContext.getControlPropertySet() to query a property set:</p> @@ -578,26 +589,29 @@ <source>package org.apache.beehive.controls.examples; import org.apache.beehive.controls.api.context.Context; -import org.apache.beehive.controls.api.context.ControlBeanContext; +import org.apache.beehive.controls.api.context.ControlBeanContext; public class JmsMessageControlImpl implements JmsMessageControl { <strong>@Context ControlBeanContext context;</strong> + ... - â - - @EventHandler(field=âcontextâ, eventSet=ControlBeanContext.Lifecycle.class, eventName=âonAcquireâ) + @EventHandler( + field="context", + eventSet=ControlBeanContext.Lifecycle.class, + eventName="onAcquire" + ) public void onBeanAcquire() { // // Acquire the property values needed for initialization // <strong>Destination destProp = - (Destination)context.getControlPropertySet(JmsMessageControl.Destination.class);</strong> + (Destination)context.getControlPropertySet(JmsMessageControl.Destination.class);</strong> if (destProp == null) { // No destination property set for the control - â + ... }</source> <p>This code above queries for the value of the JmsMessageControl.Destination PropertySet on the current JmsMessageControl instance.</p> <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> @@ -626,12 +640,12 @@ import org.apache.beehive.controls.api.bean.ControlExtension; <strong>@ControlInterface</strong> [EMAIL PROTECTED](type=JmsMessageControl.QUEUE, name=âqueue.ordersâ) [EMAIL PROTECTED](type=JmsMessageControl.QUEUE, name="queue.orders") <strong>public interface OrderQueue extends JmsMessageControl</strong> { - â + ... }</source> -<p>This example shows that this interface shows that property values can be configured on the extended interface to further parameterize the use case. In this case, the InvoiceQueue interface is being designed for a very specific use case: to enable orders to be enqueued to a JMS queue named âqueue.ordersâ.</p> +<p>This example shows that this interface shows that property values can be configured on the extended interface to further parameterize the use case. In this case, the InvoiceQueue interface is being designed for a very specific use case: to enable orders to be enqueued to a JMS queue named "queue.orders".</p> <p>Once defined, the Control extension author can now begin to define additional operations on it, in this case the ability to enqueue messages to the OrderQueue by calling methods on it.</p> <p><strong>Declaring Extended Operations with Properties (Control Extension Interface)</strong></p> @@ -640,20 +654,21 @@ import org.apache.beehive.controls.api.bean.ControlExtension; @ControlExtension [EMAIL PROTECTED](type=JmsMessageControl.QUEUE, name=âqueue.ordersâ) [EMAIL PROTECTED](type=JmsMessageControl.QUEUE, name="queue.orders") <strong>public interface OrderQueue extends JmsMessageControl</strong> { public class Order implements java.io.Serializable { - public Order(int buyer, String list) { buyerID = buyer; itemList list; } - int buyerID; + public Order(int buyer, String list) { buyerID = buyer; itemList list; } + int buyerID; String [ ] itemList; } <strong>@Message (OBJECT) public void submitOrder( - @Body Order order, - @Property ( name=âDeliverByâ) String deliverBy);</strong> + @Body Order order, + @Property ( name="DeliverBy") String deliverBy + );</strong> }</source> <p>This interface defines a single operation, submitOrder, that enqueues an ObjectMessage containing a new order. The body of the message will be a single instance of the Order class, and it will have a single StringProperty with the expected delivery date (enabling message selector-based queries for orders that are past due).</p> <p>The message format (in this case an ObjectMessage) and the mapping of operation parameters to message content and/or properties are all defined using JSR-175 metadata on the method or its parameters. This format makes it very easy for tools to assist in the creation and presentation of extension interfaces.</p> @@ -674,26 +689,25 @@ @ControlInterface public interface JmsMessageControl { - â - - public enum MessageType { BYTES, MAP, OBJECT, STREAM, TEXT } - - <strong>@Target({METHOD}) - @Retention(RUNTIME) - public @interface Message - { - public MessageType value() default TEXT; - } + ... + public enum MessageType { BYTES, MAP, OBJECT, STREAM, TEXT } - @Target({PARAMETER} - @Retention(RUNTIME) + <strong>@Target({METHOD}) + @Retention(RUNTIME) + public @interface Message + { + public MessageType value() default TEXT; + } + + @Target({PARAMETER} + @Retention(RUNTIME) public interface Body {} - @Target({PARAMETER}) - @Retention(RUNTIME) + @Target({PARAMETER}) + @Retention(RUNTIME) public @interface Property { - public String name(); + public String name(); }</strong> }</source> <p>The JmsMessageMessageControl defines three annotation types: Message, Body, and Property. The @Target annotation on the Message declaration specifies that Message can be placed on the method declaration to indicate the type of JMS message that will be enqueued by the operation. The Body annotation is used to indicate the method parameter that contains the contents of the message (and must have a type that is compatible with the specified MessageType). The Property annotation on a method parameter indicates that the parameterâs value should be stored as a property on the enqueue message, with the property name coming from the value of the annotation and the property type derived from the type of the method parameter.</p> @@ -713,13 +727,13 @@ public class JmsMessageControlImpl implements JmsMessageControl, Extensible { - @Context ControlBeanContext context; + @Context ControlBeanContext context; <strong>public Object invoke(Method m, Object [] args) throws Throwable { - // Extensibility implementation - â - }</strong> + // Extensibility implementation + ... + }</strong> } </source> <p>The invoke() method on the Control Implementation Class will be called any time an operation defined on an extension interface is called on the Control by its client. The implementation of this method has responsibility for examining the current set of properties for the Control instance, methods, and parameters and using them to parameterize the behavior of the Control.</p> @@ -727,12 +741,11 @@ <p><strong>Accessing Method Properties Using the Context (Control Implementation)</strong></p> <source>Object invoke(Method m, Object [] args) throws Throwable { - â - + ... int bodyIndex = 1; for (int i= 0; i < args.length; i++) - if (context.getArgumentPropertySet(m, i, JMMessageControl.Body.class) != null) - bodyIndex = i; + if (context.getArgumentPropertySet(m, i, JMMessageControl.Body.class) != null) + bodyIndex = i; // // Create a message of the appropriate type @@ -742,29 +755,29 @@ <strong>context.getMethodPropertySet(m, JMSMessageControl.Message.class);</strong> switch(msgProp.value()) { - case MessageType.OBJECT: - msg = session.createObjectMessage(args[bodyIndex]); - break; - â + case MessageType.OBJECT: + msg = session.createObjectMessage(args[bodyIndex]); + break; + ... } // // Decorate the message with properties defined by any arguments // for (int i= 0; i < args.length; i++) - { - JMSMessageControl.Property jmsProp = - <strong>context.getParameterPropertySet(m,i, JmsMessageControl.Property.class);</strong> - if (jmsgProp != null) - { + { + JMSMessageControl.Property jmsProp = + <strong>context.getParameterPropertySet(m,i, JmsMessageControl.Property.class);</strong> + if (jmsgProp != null) + { String name = jmsProp.value(); - if (args[I] instanceof String) - msg.setStringProperty(name, ((String)args[i]); - else if (args[I] instanceof Integer) - â - else - msg.setObjectProperty(name, args[I); - } + if (args[I] instanceof String) + msg.setStringProperty(name, ((String)args[i]); + else if (args[I] instanceof Integer) + ... + else + msg.setObjectProperty(name, args[I); + } }</source> <p>In the sample code above, the Control Implementation Class uses the ControlBeanContext getMethodProperty and getParameterProperty APIs to query properties of the invoked method and its argument. These query methods will return null if the property is not found and no default was defined for the attribute member.</p> @@ -775,12 +788,11 @@ <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> <source><strong>@Control org.apache.beehive.controls.examples.OrderQueueBean orderBean;</strong> - -â - Order order = new OrderQueue.Order(); +... + Order order = new OrderQueue.Order(); order.buyerID = myID; - order.itemList = new String [] {âitem1â, âitem2â}; - orderBean.submitOrder(order, â12-31-2004â); + order.itemList = new String [] {"item1", "item2"}; + orderBean.submitOrder(order, "12-31-2004"); </source> <p>Looking closely at the example, youâll notice that a derived ControlBean type (OrderQueueBean) is generated by the Control compiler, just as it is for a base Control type. The skeleton of this ControlBean Generated Class is shown below: @@ -788,18 +800,18 @@ <p><strong>Implementation of Extended Operations (ControlBean Generated Class)</strong></p> <source>Package org.apache.beehive.controls.examples; -public class OrderQueueBean extends JmsMessageControlBean - implements OrderQueue +public class OrderQueueBean + extends JmsMessageControlBean + implements OrderQueue { - JmsMessageControlImpl _impl; - â. + JmsMessageControlImpl _impl; + ... Public void submitOrder(Object order, String deliveryBy) { - â - _impl.invoke(submitOrderMethod, new Object [] {order, deliveryBy}; - â + ... + _impl.invoke(submitOrderMethod, new Object [] {order, deliveryBy}; + ... } - }</source> <p>There are several attributes worth noting about the extended ControlBean Generated Class:</p> <ul> @@ -824,21 +836,21 @@ public class OrderRouterImpl { - @Control @Destination(Name=âRushOrdersâ) + @Control @Destination(Name="RushOrders") OrderQueueBean rushOrders; - @Control @Destination(Name=âOrdersâ) - OrderQueueBean orders; + @Control @Destination(Name="Orders") + OrderQueueBean orders; - â + ... public void submitOrder(Order order, String deliverBy) - { - if (needsRushDelivery(deliveryBy)) + { + if (needsRushDelivery(deliveryBy)) rushOrders.submitOrder(order, deliverBy); - else - orders.submitOrder(order, deliverBy); - } + else + orders.submitOrder(order, deliverBy); + } } </source> <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> @@ -852,29 +864,31 @@ public class OrderRouterImpl { - OrderQueueBean rushOrders; // no @Control annotation, so no auto-init - OrderQueueBean orders; // no @Control annotation, so no auto-init + // no @Control annotation, so no auto-init + OrderQueueBean rushOrders; + // no @Control annotation, so no auto-init + OrderQueueBean orders; <strong>@Context ControlBeanContext context;</strong> - â + ... - public void context_onCreate() - { + public void context_onCreate() + { ClassLoader cl = Thread.currentThread().getContextClassLoader(); - rushOrders = - (OrderQueueBean)Beans.instantiate(cl, - âorg.apache.beehive.controls.examples.OrderQueueBeanâ); - rushOrders.setDestinationName(âRushOrdersâ); + rushOrders = + (OrderQueueBean)Beans.instantiate(cl, + "org.apache.beehive.controls.examples.OrderQueueBean"); + rushOrders.setDestinationName("RushOrders"); <strong>context.add(rushOrders);</strong> orders = (OrderQueueBean)Beans.instantiate(cl, - âorg.apache.beehive.controls.examples.OrderQueueBeanâ); - orders.setDestinationName(âRushOrdersâ); + "org.apache.beehive.controls.examples.OrderQueueBean"); + orders.setDestinationName("RushOrders"); <strong>context.add(orders);</strong> } public void submitOrder(Order order, String deliverBy) - { - â. + { + ... } }</source> @@ -899,18 +913,19 @@ <p><strong>Context Life Cycle Events</strong></p> <source>import org.apache.beehive.controls.api.context; -public interface ControlBeanContext extends java.beans.beancontext.BeanContextServices +public interface ControlBeanContext + extends java.beans.beancontext.BeanContextServices { - â - <strong>public interface Callback extends java.util.EventListener - { - public void onCreate(); - public void onAcquire(); - public void onRelease(); - } + ... + <strong>public interface Callback extends java.util.EventListener + { + public void onCreate(); + public void onAcquire(); + public void onRelease(); + } - public void addCallbackListener(Callback lifecycleListener); - public void removeCallbackListener(Callback lifecycleListener); </strong> + public void addCallbackListener(Callback lifecycleListener); + public void removeCallbackListener(Callback lifecycleListener); </strong> }</source> <p>The specific life cycle events are described in the following section:</p> <section> @@ -950,20 +965,26 @@ { <strong>@Context ControlBeanContext context; - @EventHandler(field=âcontextâ, eventSet=ControlBeanContext.LifeCycle.class, - eventName=âonAcquireâ) + @EventHandler( + field="context", + eventSet=ControlBeanContext.LifeCycle.class, + eventName="onAcquire" + ) public void onAcquire() { - // Code to acquire JMS connection/session/destination/writers - â + // Code to acquire JMS connection/session/destination/writers + ... } - @EventHandler(field=âcontextâ, eventSet=ControlBeanContext.LifeCycle.class, - eventName=âonReleaseâ) + @EventHandler( + field="context", + eventSet=ControlBeanContext.LifeCycle.class, + eventName="onRelease" + ) public void onRelease() { - // Code to release JMS connection/session/destination/writer - â + // Code to release JMS connection/session/destination/writer + ... }</strong> }</source> <p>When using the declarative mechanism, a Control Implementation Class is free to implement only a subset of the life cycle listeners; it is not necessary that it provide a handler for all events.</p> @@ -973,17 +994,17 @@ <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 getPeerContext API, and then using the addCallbackListener 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> -<source> JmsMessageControlBean myJmsBean = â; +<source> JmsMessageControlBean myJmsBean = ...; - ControlBeanContext peerContext = myBean.getControlBeanContext(); - peerContext.addCallbackListener( - new ControlBeanContext.LifeCycle() - { - public void onCreate() { ... }; - public void onAcquire() { ... }; - public void onRelease() { ... }; - } - );</source> + ControlBeanContext peerContext = myBean.getControlBeanContext(); + peerContext.addCallbackListener( + new ControlBeanContext.LifeCycle() + { + public void onCreate() { ... }; + public void onAcquire() { ... }; + public void onRelease() { ... }; + } + );</source> </section> </section> <section> @@ -995,7 +1016,7 @@ <li> java.beans.BeanContextServices</li> </ul> <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>[Issue: there is not a declarative mechanism for receiving these events, but probably should be.]</em></p> + <p><em>[todo][Issue: there is not a declarative mechanism for receiving these events, but probably should be.]</em></p> <section> <title>13.3.1 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> @@ -1021,21 +1042,26 @@ import org.apache.beehive.controls.api.bean.ControlInterface; import org.apache.beehive.controls.api.events.EventSet; -import org.apache.beehive.controls.api.properties.PropertySet; +import org.apache.beehive.controls.api.properties.PropertySet; /** - * The JmsMessageControl defines a basic Control to enable messages to be enqueued to a JMS - * queue or topic. Using Control properties, you can configure the connection, session, and - * destination attributes that should be used to connect to the JMS provider. The Control - * will transparently connect to the JMS provider and obtain any necessary resources to - * enqueue the messages. The Control will also sure that the resources are properly released - * at the end of the current resource scope associated with the Controlâs runtime environment. + * The JmsMessageControl defines a basic Control to enable messages + * to be enqueued to a JMS queue or topic. Using Control properties, + * you can configure the connection, session, and destination attributes + * that should be used to connect to the JMS provider. The Control + * will transparently connect to the JMS provider and obtain any + * necessary resources to enqueue the messages. The Control will + * also sure that the resources are properly released at the end of the + * current resource scope associated with the Controlâs runtime + * environment. * - * The Control provides a basic set of operations that allow a simple text or object message to - * be written to the configured destination. It also provides an extensibility mechanism - * that allows new operations to be defined by extending this interface. Extended operations - * define the enqueueing of message with a specific type (TextMessage, ObjectMessage, ...) - * where operation parameters can be mapped to message properties or content. + * The Control provides a basic set of operations that allow a simple text + * or object message to be written to the configured destination. It also + * provides an extensibility mechanism that allows new operations to be + * defined by extending this interface. Extended operations define the + * enqueueing of message with a specific type + * (TextMessage, ObjectMessage, ...) where operation parameters can be + * mapped to message properties or content. */ @ControlInterface public interface JmsMessageControl @@ -1053,20 +1079,19 @@ * @param object the object to use as the contents of the message */ public void sendObjectMessage(java.io.Serializable object); - - - - // EVENTS + + // EVENTS - /** + /** * The Callback interface defines the events for the JmsMessageControl. */ - @EventSet + @EventSet public interface Callback { /** - * The onSend event is delivered to a registered client listener whenever a - * a message has been sent by the Control. + * The onSend event is delivered to a registered + * client listener whenever a + * message has been sent by the Control. * @param msg the message that was sent */ public void onMessage(javax.jms.Message msg); @@ -1075,9 +1100,9 @@ // PROPERTIES /** - * The Connection property defines the attributes of the connection and session used - * to enqueue the message. This annotation can appear on both class and Control - * field declarations. + * The Connection property defines the attributes of the connection + * and session used to enqueue the message. This annotation + * can appear on both class and Control field declarations. */ @PropertySet @Target({FIELD, TYPE}) @@ -1092,7 +1117,8 @@ public enum DestinationType { QUEUE, TOPIC } /** - * The Destination property defines the attributes of the JMS destination that should + * The Destination property defines the attributes + * of the JMS destination that should * be the target of any enqueued messages. */ @PropertySet @@ -1102,10 +1128,8 @@ public DestinationType type() default QUEUE; public String name(); } - - - // EXTENSIBILITY ATTRIBUTES + // EXTENSIBILITY ATTRIBUTES /** * The set of supported message types for extended operations @@ -1113,10 +1137,14 @@ public enum MessageType { TEXT, OBJECT, BYTES } /** - * The Message attribute can be placed on an extended operation to describe the format of the - * message that should be enqueued when the operation is invoked. The method is expected to - * have a least parameter annotated with the Body attribute, and zero or more parameters with - * the Property attribute defining message properties. + * The Message attribute can be placed on an + * extended operation to describe the format + * of the message that should be enqueued when + * the operation is invoked. The method is + * expected to have a least parameter annotated + * with the Body attribute, and zero or more + * parameters with the Property attribute + * defining message properties. */ @Target({METHOD}) public @interface Message @@ -1124,21 +1152,25 @@ public MessageType value() default TEXT; } - /** The Body attribute indicates that the associated method parameter on an extended operation - * contains the message body. - */ + /** + * The Body attribute indicates that the associated + * method parameter on an extended operation + * contains the message body. + */ @Target({PARAMETER} public interface Body {} /** - * The Property attribute can be used to define operation parameters that should be used to - * set properties on the message. The type of property to set will be inferred based upon + * The Property attribute can be used to define + * operation parameters that should be used to + * set properties on the message. The type of + * property to set will be inferred based upon * the type of the parameter. */ @Target({PARAMETER}) public @interface Property { - public String name(); + public String name(); } }</source> </section> @@ -1166,9 +1198,12 @@ import javax.jms.Message; /** - * The JmsMessageControlImpl class is the Control Implementation Class for the JmsMessageControl. - * It implements two basic operations (sendTextMessage and sendObjectMessage) as well as an - * extensibility model that enables custom message formats to be defined and associated with + * The JmsMessageControlImpl class is the + * Control Implementation Class for the JmsMessageControl. + * It implements two basic operations + * (sendTextMessage and sendObjectMessage) + * as well as an extensibility model that enables custom + * message formats to be defined and associated with * extended method signatures. */ @ControlImplementation @@ -1185,29 +1220,35 @@ @Client Callback client; /** - * The fields are used to hold transient JMS resources that are acquired and held for + * The fields are used to hold transient JMS resources + * that are acquired and held for * the resource scope associated with the Control */ transient javax.jms.Connection _connection; transient javax.jms.Session _session; transient javax.jms.MessageProduction _producer; - - - /* + /* * The onAcquire event handler - * This method will be called prior to any operation with a given resource scope. It is - * responsible for obtaining the connection, session, destination, and appropriate + * This method will be called prior to any operation with + * a given resource scope. It is responsible for + * obtaining the connection, session, destination, and appropriate * writer instance, for use within the operation. */ - @EventHandler(field=âcontextâ, eventSet=ControlBeanContext.Lifecycle.class, eventName=âonAcquireâ) + @EventHandler( + field="context", + eventSet=ControlBeanContext.Lifecycle.class, + eventName="onAcquire" + ) public void onBeanAcquire() { // // Acquire the property values needed for initialization // - Destination destProp = (Destination)context.getControlPropertySet(Destination.class); - Connection connProp = (Connection)context.getControlPropertySet(Connection.class); + Destination destProp = + (Destination)context.getControlPropertySet(Destination.class); + Connection connProp = + (Connection)context.getControlPropertySet(Connection.class); try { @@ -1224,21 +1265,21 @@ if (destProp.type() = JmsControl.QUEUE) { javax.jms.QueueConnectionFactory connFactory = - (QueueConnectionFactory)jndiContext.lookup(connProp.factoryName()); + (QueueConnectionFactory)jndiContext.lookup(connProp.factoryName()); _connection = connFactory.createQueueConnection(); _session = (QueueConnection)_connection).createQueueConnection( - connProp.transacted(), - connProp.acknowledgeMode()); + connProp.transacted(), + connProp.acknowledgeMode()); _producer = (QueueSession)_session).createSender((Queue)_dest); } else { javax.jms.TopicConnectionFactory connFactory = - (TopicConnectionFactory)jndiContext.lookup(connProp.factoryName()); + (TopicConnectionFactory)jndiContext.lookup(connProp.factoryName()); _connection = connFactory.createTopicConnection(); _session = ((TopicConnection)_connection).createTopicConnection( - connProp.transacted(), - connProp.acknowledgeMode()); + connProp.transacted(), + connProp.acknowledgeMode()); _producer = ((TopicSession)_session).createPublisher((Topic)_dest); } @@ -1261,7 +1302,11 @@ * The onRelease event handler for the associated context * This method will release all resource acquired by onAcquire. */ - @EventHandler (field=âcontextâ, eventSet=ControlBeanContext.Lifecycle.class , eventName=âonReleaseâ) + @EventHandler ( + field="context", + eventSet=ControlBeanContext.Lifecycle.class, + eventName="onRelease" + ) public void onRelease() { try @@ -1323,8 +1368,9 @@ /** * Implements the Extensible.invoke() interface for this Control - * This method uses the Message property to determine the type of message to construct, - * and then uses the Body and Property attributes of method parameters to supply message + * This method uses the Message property to determine the type + * of message to construct, and then uses the Body and Property + * attributes of method parameters to supply message * content and properties. */ public Object invoke(Method m, Object [] args) throws Throwable @@ -1339,7 +1385,10 @@ } } if (bodyIndex == -1) - throw new ControlException("No @Body argument defined for operation: " + m.getName()); + throw new ControlException( + "No @Body argument defined for operation: " + + m.getName() + ); // // Create a message based upon the value of the Message property of the method Modified: incubator/beehive/trunk/docs/forrest/src/documentation/skinconf.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/skinconf.xml?view=diff&rev=111550&p1=incubator/beehive/trunk/docs/forrest/src/documentation/skinconf.xml&r1=111549&p2=incubator/beehive/trunk/docs/forrest/src/documentation/skinconf.xml&r2=111550 ============================================================================== --- incubator/beehive/trunk/docs/forrest/src/documentation/skinconf.xml (original) +++ incubator/beehive/trunk/docs/forrest/src/documentation/skinconf.xml Fri Dec 10 13:45:11 2004 @@ -138,6 +138,7 @@ padding: .5em; background-color: #f0f0f0; font-family: monospace; + font-size: 11px; } </extra-css> <colors>
