[jboss-svn-commits] JBL Code SVN: r36785 - in labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US: extras/developing_custom_actions and 1 other directory.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Sun Mar 6 13:25:32 EST 2011
Author: kevin.conner at jboss.com
Date: 2011-03-06 13:25:32 -0500 (Sun, 06 Mar 2011)
New Revision: 36785
Removed:
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/developing_custom_actions/configtree.xmlt
Modified:
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Developing_Custom_Actions.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/developing_custom_actions/abstractaction.xmlt
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/developing_custom_actions/actionbean.xmlt
Log:
Add docs about action options, threading etc: JBESB-3577
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Developing_Custom_Actions.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Developing_Custom_Actions.xml 2011-03-04 17:43:46 UTC (rev 36784)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Developing_Custom_Actions.xml 2011-03-06 18:25:32 UTC (rev 36785)
@@ -10,42 +10,52 @@
Developing Custom Actions
</title>
- <para>
- In order to implement a custom Action Processor, simply use the
- <interfacename>org.jboss.soa.esb.actions.ActionPipelineProcessor</interfacename>
- interface.
- </para>
-
- <para>
- This interface supports the implementation of <firstterm>managed
- life-cycle</firstterm> stateless actions. A single instance of a
- class that implements this interface is instantiated on a
- "per-pipeline" basis (in other words, per-action configuration.)
- This means that one can cache the resources needed by the action in
- the <methodname>initialise</methodname> method, and then clean them
- up by using the <methodname>destroy</methodname> method.
+ <para> JBoss ESB allows custom actions to be developed in a number of ways, each of which has their
+ own advantages. These can be split into</para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>Lifecycle actions, implementing
+ <interfacename>org.jboss.soa.esb.actions.ActionLifecycle</interfacename> or
+ <interfacename>org.jboss.soa.esb.actions.ActionPipelineProcessor</interfacename></para>
+ </listitem>
+ <listitem>
+ <para>Java bean actions, implementing
+ <interfacename>org.jboss.soa.esb.actions.BeanConfiguredAction</interfacename>
+ </para>
+ </listitem>
+ <listitem>
+ <para>Annotated actions</para>
+ </listitem>
+ <listitem>
+ <para>Legacy actions</para>
+ </listitem>
+ </itemizedlist>
+ In order to understand the defferences between each implementation it is
+ necessary to understand
+ <itemizedlist>
+ <listitem>
+ <para>How the actions are configured</para>
+ </listitem>
+ <listitem>
+ <para>When the actions are instantiated and the implications on thread safety</para>
+ </listitem>
+ <listitem>
+ <para>Whether they have visibility of lifecycle events</para>
+ </listitem>
+ <listitem>
+ <para>Whether the action methods are invoked directly or via reflection </para>
+ </listitem>
+ </itemizedlist>
</para>
- <para>
- The implementing class should process the message from within the
- the <methodname>process</methodname> method.
- </para>
-
- <para>
- It should be convenient to simply extend the
- <classname>org.jboss.soa.esb.actions.AbstractActionPipelineProcessor</classname>:
- </para>
-
- <programlisting language="Java" role="JAVA"><xi:include href="extras/developing_custom_actions/abstractaction.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
-
-
<section>
<title>
Configuring Actions Using Properties
</title>
<para>
- Actions generally act as templates. They require external
+ Actions generally act as templates, requiring external
configuration in order to perform their tasks. For example, a
<classname>PrintMessage</classname> action might use a property
named <property>message</property> to indicate what to print and
@@ -55,36 +65,58 @@
would look something like this:
</para>
-
<programlisting language="XML" role="XML"><xi:include href="extras/developing_custom_actions/hworld.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
-
- <para>
- A <classname>ConfigTree</classname> instance is the default
- method to use in order to load property values into an
- action implementation. The <classname>ConfigTree</classname>
- provides a <abbrev>DOM</abbrev>-like view of the action
- <abbrev>XML</abbrev> code. By default, actions are expected
- to have a public constructor that takes a
- <classname>ConfigTree</classname> as a parameter. For
- example:
- </para>
-
- <programlisting language="Java" role="JAVA"><xi:include href="extras/developing_custom_actions/configtree.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
-
+ <para> How this configuration is then mapped on to the action instance will depend on the type
+ of action. </para>
+ </section>
- <para>
- One may take another approach to setting properties by adding
- "setters" on the action that will correspond to the property
- names. This will thereby allow the framework to populate them
- automatically. The action class must implement the
- <classname>org.jboss.soa.esb.actions.BeanConfiguredAction</classname>
- marker interface in order to make the action Bean populate
- automatically. The following class has the same behavior as that
- shown above, in order to demonstrate this:
- </para>
+ <section>
+ <title>Lifecycle Actions</title>
+ <para> Lifecycle actions are those which are derived from the lifecycle interfaces,
+ <interfacename>org.jboss.soa.esb.actions.ActionLifecycle</interfacename> and
+ <interfacename>org.jboss.soa.esb.actions.ActionPipelineProcessor</interfacename>.
+ ActionLifecycle implements the pipeline lifecycle methods,
+ <methodname>initialise</methodname> and <methodname>destroy</methodname>, with
+ ActionPipelineProcessor extending this interface to include the message processing
+ methods, <methodname>process</methodname>, <methodname>processSuccess</methodname> and
+ <methodname>processException</methodname>.</para>
+
+ <para>This interface supports the implementation of <firstterm>managed
+ life-cycle</firstterm> stateless actions. A single instance of a class implementing
+ either of these interfaces is instantiated on a "per-pipeline" basis (in other words,
+ per-action configuration) and must be thread safe. The
+ <methodname>initialise</methodname> and <methodname>destroy</methodname> methods can
+ be overridden to allow the action to perform resource management for the lifetime of the
+ pipeline, e.g. caching resources needed in the <methodname>initialise</methodname>
+ method, and then cleaning them up in the <methodname>destroy</methodname> method.</para>
+ <para>These actions must define a constructor which takes a single
+ <classname>ConfigTree</classname> instance as a parameter, representing the
+ configuration of the specific action within the pipeline.</para>
+ <para>The pipeline will invoke each method directly provided that the action has implemented
+ the appropraite interface and that the method names are not overridden in the
+ configuration. Any method invocations which are not implemented via the interfaces, or
+ which have been overridden in the action configuration, will be invoked using
+ reflection. </para>
+ <para>To simplify development there are two abstract base classes provided in the codebase,
+ each implementing the appropriate interface and providing empty stub methods for all but
+ the <methodname>process</methodname> method. These are
+ <classname>org.jboss.soa.esb.actions.AbstractActionPipelineProcessor</classname> and
+ <classname>org.jboss.soa.esb.actions.AbstractActionLifecycle</classname> and can be
+ used as follows: </para>
+
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/developing_custom_actions/abstractaction.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"/></programlisting>
+ </section>
+ <section>
+ <title>Java Bean Actions</title>
+ <para>One may take another approach to setting properties by adding "setters" on the action
+ that will correspond to the property names. This will thereby allow the framework to
+ populate them automatically. The action class must implement the
+ <classname>org.jboss.soa.esb.actions.BeanConfiguredAction</classname> marker
+ interface in order to make the action Bean populate automatically, for example. </para>
+
- <programlisting language="Java" role="JAVA"><xi:include href="extras/developing_custom_actions/actionbean.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/developing_custom_actions/actionbean.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"/></programlisting>
<note>
<para>
@@ -95,13 +127,14 @@
</para>
</note>
- <para>
- The <methodname>BeanConfiguredAction</methodname> method of
- loading properties is a good choice for actions that take simple
- arguments, while the <methodname>ConfigTree</methodname> method
- is a better option in situations when one needs to deal with the
- <abbrev>XML</abbrev> representation directly.
- </para>
+ <para>The <methodname>BeanConfiguredAction</methodname> method of loading properties is a good
+ choice for actions that take simple arguments, while the
+ <methodname>ConfigTree</methodname> method is a better option in situations when one
+ needs to deal with the <abbrev>XML</abbrev> representation directly.</para>
+ <para>These actions <emphasis>do not</emphasis> support the lifecycle methods, will be
+ instantiated for <emphasis>every</emphasis> message passing through the pipeline and
+ will always have their <methodname>process</methodname> methods invoked using
+ reflection.</para>
</section>
@@ -110,15 +143,15 @@
Annotated Action Classes
</title>
- <para>
- The <application>JBoss Enterprise Service
- Bus</application> has a set of <firstterm>action
- annotations</firstterm> that make it easier to create
- clean <systemitem>action</systemitem> implementations.
- This hides the complexity associated with implementing
- interfaces, abstract classes and dealing with the
- <systemitem>ConfigTree</systemitem> type (the configuration information provided in the <filename>jboss-esb.xml</filename> file).
- </para>
+ <para> The <application>JBoss Enterprise Service Bus</application> has a set of
+ <firstterm>action annotations</firstterm> that make it easier to create clean
+ <systemitem>action</systemitem> implementations. This hides the complexity
+ associated with implementing interfaces, abstract classes and dealing with the
+ <systemitem>ConfigTree</systemitem> type (the configuration information provided in
+ the <filename>jboss-esb.xml</filename> file). A single instance of annotated actions
+ will be instantiated on a "per-pipeline" basis (in other words, per-action
+ configuration) and must be thread safe. The pipeline will always invoke the action
+ methods using reflection.</para>
<para>
These are the annotations:
@@ -663,4 +696,29 @@
</section>
</section>
+ <section>
+ <title>
+ Legacy Actions
+ </title>
+
+ <para>Any actions which do not fit into the above categories are treated by the pipeline as
+ legacy, inheriting the behaviour present in the original Rosetta codebase. In practice
+ this implies the following<itemizedlist>
+ <listitem>
+ <para>Configuration of the action is through the provision of a constructor with
+ a single <classname>ConfigTree</classname> parameter</para>
+ </listitem>
+ <listitem>
+ <para>The action will be instantiated for <emphasis>every</emphasis> message
+ passing through the pipeline</para>
+ </listitem>
+ <listitem>
+ <para>The action has no knowledge of any of the lifecycle methods</para>
+ </listitem>
+ <listitem>
+ <para>The invocation of the <methodname>process</methodname> methods will always
+ do done via reflection</para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
</chapter>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/developing_custom_actions/abstractaction.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/developing_custom_actions/abstractaction.xmlt 2011-03-04 17:43:46 UTC (rev 36784)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/developing_custom_actions/abstractaction.xmlt 2011-03-06 18:25:32 UTC (rev 36785)
@@ -1,12 +1,17 @@
public class ActionXXXProcessor extends AbstractActionPipelineProcessor {
+ public ActionXXXProcessor(final ConfigTree config) {
+ // extract configuration
+ }
+
public void initialise() throws ActionLifecycleException {
- // Initialize resources...
- }
- public Message process(final Message message) throws
- ActionProcessingException {
- // Process messages in a stateless fashion...
- }
+ // Initialize resources...
+ }
+
+ public Message process(final Message message) throws ActionProcessingException {
+ // Process messages in a stateless fashion...
+ }
+
public void destroy() throws ActionLifecycleException {
- // Cleanup resources...
- }
+ // Cleanup resources...
+ }
}
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/developing_custom_actions/actionbean.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/developing_custom_actions/actionbean.xmlt 2011-03-04 17:43:46 UTC (rev 36784)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/developing_custom_actions/actionbean.xmlt 2011-03-06 18:25:32 UTC (rev 36785)
@@ -1,5 +1,4 @@
-public class PrintMessage extends AbstractActionPipelineProcessor
- implements BeanConfiguredAction {
+public class PrintMessage implements BeanConfiguredAction {
private String information;
private Integer repeatCount;
public setInformation(String information) {
Deleted: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/developing_custom_actions/configtree.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/developing_custom_actions/configtree.xmlt 2011-03-04 17:43:46 UTC (rev 36784)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/developing_custom_actions/configtree.xmlt 2011-03-06 18:25:32 UTC (rev 36785)
@@ -1,15 +0,0 @@
-public class PrintMessage extends AbstractActionPipelineProcessor {
- private String information;
- private Integer repeatCount;
- public PrintMessage(ConfigTree config) {
- information = config.getAttribute("information");
- repeatCount = new Integer(config.getAttribute("repeatCount"));
- }
- public Message process(Message message) throws
- ActionProcessingException {
- for (int i=0; i < repeatCount; i++) {
- System.out.println(information);
- }
- }
-}
-
More information about the jboss-svn-commits
mailing list