You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@beehive.apache.org by st...@apache.org on 2005/09/14 01:42:01 UTC
svn commit: r280719 -
/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/programming.xml
Author: steveh
Date: Tue Sep 13 16:41:59 2005
New Revision: 280719
URL: http://svn.apache.org/viewcvs?rev=280719&view=rev
Log:
Partial fix for BEEHIVE-922:group of doc issues in Controls Programming document
I have folded in all of Jeremiah's comments.
Also the code samples in the appendixes now compile.
Still have to make sure all of the code snippets throughout the doc compile (and make sense).
Modified:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/programming.xml
Modified: beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/programming.xml
URL: http://svn.apache.org/viewcvs/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/programming.xml?rev=280719&r1=280718&r2=280719&view=diff
==============================================================================
--- beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/programming.xml (original)
+++ beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/programming.xml Tue Sep 13 16:41:59 2005
@@ -158,7 +158,7 @@
import org.apache.beehive.controls.api.bean.ControlImplementation;
@ControlImplementation
-public class PublisherControlImpl extends PublisherControl
+public class PublisherControlImpl implements PublisherControl
{
<strong>@Control
public JmsMessageControlBean myJmsBean;</strong>
@@ -175,7 +175,7 @@
<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>@ControlImplementation
-public class PublisherControlImpl extends PublisherControl
+public class PublisherControlImpl implements PublisherControl
{
<strong>@Control @Destination(name="InvoiceQueue") </strong>
public JmsMessageControlBean myJmsBean;</source>
@@ -377,7 +377,7 @@
import org.apache.beehive.controls.api.events.EventHandler
@ControlImplementation
-public class PublisherControlImpl extends PublisherControl
+public class PublisherControlImpl implements PublisherControl
{
@Control
public JmsMessageControlBean myJmsBean;
@@ -538,11 +538,11 @@
public enum DestinationType { QUEUE, TOPIC }
<strong>@PropertySet(prefix="Destination")
- @Target({FIELD, TYPE})
+ @Target({ElementType.FIELD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface Destination
{
- public DestinationType type() default QUEUE;
+ public DestinationType type() default DestinationType.QUEUE;
public String name();
}</strong>
...
@@ -589,7 +589,7 @@
<p><strong>Using Property Accessors (Client Code)</strong></p>
<source>@Control JmsMessageControlBean jmsBean;
...
- <strong>jmsBean.setDestinationType(Destination.QUEUE);
+ <strong>jmsBean.setDestinationType(DestinationType.QUEUE);
jmsBean.setDestinationName("myTargetQueue");</strong></source>
</section>
<section id="accessing_props_from_impl_code">
@@ -618,6 +618,7 @@
<p><strong>Acccessing Control Properties (Client Implementation Class)</strong></p>
<source>package org.apache.beehive.controls.examples;
+import javax.servlet.ServletContext;
import org.apache.beehive.controls.api.bean.ControlImplementation;
import org.apache.beehive.controls.api.context.Context;
import org.apache.beehive.controls.api.context.ControlBeanContext;
@@ -625,26 +626,19 @@
@ControlImplementation
public class JmsMessageControlImpl implements JmsMessageControl
{
- <strong>@Context ControlBeanContext context;</strong>
- ...
+ @Context ControlBeanContext context;
- @EventHandler(
- field="context",
- eventSet=ControlBeanContext.Lifecycle.class,
- eventName="onAcquire"
- )
- public void onBeanAcquire()
+ public void sendTextMessage(String text)
{
- //
- // Acquire the property values needed for initialization
- //
- <strong>Destination destProp =
- (Destination)context.getControlPropertySet(JmsMessageControl.Destination.class);</strong>
- if (destProp == null)
- {
- // No destination property set for the control
- ...
- }</source>
+ ...
+ Destination destinationProperty = (Destination) context.getControlPropertySet( Hello.Destination.class );
+ if( destinationProperty == null ) {
+ System.out.println( "Dest Property NOT Set" );
+ } else {
+ System.out.println( "Dest Property Set" );
+ }
+ }
+}</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>
<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>
@@ -664,43 +658,67 @@
by client code, (2) external overriding of the control, and (3)
the Beehive runtime version required by the control. </p>
<p><strong>Note:</strong> the constraint rules are enforced at build time,
- when controls are
- declared in client code by <code>@Control</code>. There is no runtime
- enforcement
- of the rules.</p>
- <p>For example the following constraint requires that exactly one property
- be referenced when declaring the control BookControl.</p>
- <source>
+ when controls are declared in client code by <code>@Control</code>. There is no runtime
+ enforcement of the rules.</p>
+ <p>For example the following constraints require that</p>
+ <ul>
+ <li>
+ all attributes must be referenced when declaring the control BookControl
+ </li>
+ <li>
+ the values of the "title" and "subject" attributes must not exceed 10 characters in length
+ </li>
+ <li>
+ the value of the "content" attribute must not exceed 200 characters in length
+ </li>
+ </ul>
+ <source>import java.lang.annotation.*;
+
+import org.apache.beehive.controls.api.bean.AnnotationContstraints.MembershipRule;
+import org.apache.beehive.controls.api.bean.AnnotationContstraints.MembershipRuleValues;
+import org.apache.beehive.controls.api.properties.PropertySet;
+
@ControlInterface
public interface BookControl
{
...
/**
- * The user must set one value, and only one value when
+ * The user must set all attribute values when
* instantiating controls declaratively.
*/
@PropertySet
@Target ({ElementType.FIELD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
- <strong>@AnnotationConstraints.MembershipRule(AnnotationConstraints.MembershipRuleValues.EXACTLY_ONE)</strong>
+ <strong>@AnnotationConstraints.MembershipRule(
+ AnnotationConstraints.MembershipRuleValues.ALL_IF_ANY)</strong>
public @interface Intro
{
- @AnnotationMemberTypes.Text(maxLength=8)
- public String title();
- @AnnotationMemberTypes.Text(maxLength=8)
- public String subject();
- @AnnotationMemberTypes.Text(maxLength=8)
- public String content();
+ <strong>@AnnotationMemberTypes.Text(maxLength=10)
+ public String title();
+ @AnnotationMemberTypes.Text(maxLength=10)
+ public String subject();
+ @AnnotationMemberTypes.Text(maxLength=200)
+ public String content(); </strong>
}
...
}
</source>
- <p>The following client code will cause a compile error, because it violates the
- "exactly one" constraint on the BookControl.Intro property.</p>
+ <p>The following client code will cause a compile error, because it violates two of the
+ constraints:</p>
+ <ul>
+ <li>
+ The "all if any" constraint on the BookControl.Intro annotation is violated
+ because only two (title and subject) of the three attributes (title, subject,
+ and content) are referenced.
+ </li>
+ <li>
+ The subject attribute's value exceeds 10 characters in length.
+ </li>
+ </ul>
<source> @Control
- @BookControl.Intro(title="some title", subject="some subject")
+ @BookControl.Intro( title="title", subject="subject of the book" )
BookControlBean myBook</source>
<p>When constraining properties with <code>@AnnotationConstraints</code>, all of the property
members must be annotated
@@ -738,8 +756,10 @@
import org.apache.beehive.controls.api.bean.ControlExtension;
+import org.apache.beehive.controls.examples.JmsMessageControl.*;
+
<strong>@ControlExtension</strong>
-@Destination(type=JmsMessageControl.QUEUE, name="queue.orders")
+@Destination(type=DestinationType.QUEUE, name="queue.orders")
<strong>public interface OrderQueue extends JmsMessageControl</strong>
{
...
@@ -758,15 +778,18 @@
{
public class Order implements java.io.Serializable
{
- public Order(int buyer, String list) { buyerID = buyer; itemList list; }
- int buyerID;
- String [ ] itemList;
+ public Order(int buyer, String[] list){
+ buyerID = buyer;
+ itemList list;
+ }
+ private int buyerID;
+ private String[ ] itemList;
}
- <strong>@Message (OBJECT)
+ <strong>@Message (MessageType.OBJECT)
public void submitOrder(
- @Body Order order,
- @Property ( name="DeliverBy") String deliverBy
+ @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>
@@ -782,28 +805,32 @@
<source>package org.apache.beehive.controls.examples;
import java.io.Serializable;
-import javax.jms.Message;
+java.lang.annotation.ElementType
+import java.lang.annotations.Retention;
+import java.lang.annotations.RetentionPolicy;
+import java.lang.annotations.Target;
+
import org.apache.beehive.controls.api.bean.ControlInterface;
@ControlInterface
public interface JmsMessageControl
{
...
- public enum MessageType { BYTES, MAP, OBJECT, STREAM, TEXT }
+ public enum MessageType { BYTES, MAP, OBJECT, STREAM, TEXT }
- <strong>@Target({METHOD})
- @Retention(RUNTIME)
+ <strong>@Target({ElementType.METHOD})
+ @Retention(RetentionPolicy.RUNTIME)
public @interface Message
{
- public MessageType value() default TEXT;
+ public MessageType value() default MessageType.TEXT;
}
- @Target({PARAMETER}
- @Retention(RUNTIME)
- public interface Body {}
+ @Target({ElementType.PARAMETER}
+ @Retention(RetentionPolicy.RUNTIME)
+ public @interface Body {}
- @Target({PARAMETER})
- @Retention(RUNTIME)
+ @Target({ElementType.PARAMETER})
+ @Retention(RetentionPolicy.RUNTIME)
public @interface Property
{
public String name();
@@ -824,6 +851,7 @@
import org.apache.beehive.controls.api.context.Context;
import org.apache.beehive.controls.api.context.ControlBeanContext;
import org.apache.beehive.controls.api.bean.Extensible;
+import java.lang.reflect.Method;
@ControlImplementation
public class JmsMessageControlImpl implements JmsMessageControl, Extensible
@@ -1589,9 +1617,9 @@
msg = _session.createObjectMessage((java.io.Serializable)args[bodyIndex]);
break;
case BYTES:
- javax.jms.BytesMessage bmsg;
+ javax.jms.BytesMessage bmsg;
msg = bmsg = _session.createBytesMessage();
- bmsg.writeBytes((byte []) args[bodyIndex]);
+ bmsg.writeBytes((byte []) args[bodyIndex]);
break;
}
}
@@ -1631,7 +1659,7 @@
// Send it
//
sendMessage(msg);
- return msg;
+ return msg;
}
}</source>
</section>