Author: iocanel
Date: Thu Jan 13 21:31:29 2011
New Revision: 1058751
URL: http://svn.apache.org/viewvc?rev=1058751&view=rev
Log:
[SMX4-625] Added documentation for servicemix-bean component.
Modified:
servicemix/documentation/trunk/src/main/webapp/jbi/components/servicemix-bean.conf
Modified:
servicemix/documentation/trunk/src/main/webapp/jbi/components/servicemix-bean.conf
URL:
http://svn.apache.org/viewvc/servicemix/documentation/trunk/src/main/webapp/jbi/components/servicemix-bean.conf?rev=1058751&r1=1058750&r2=1058751&view=diff
==============================================================================
---
servicemix/documentation/trunk/src/main/webapp/jbi/components/servicemix-bean.conf
(original)
+++
servicemix/documentation/trunk/src/main/webapp/jbi/components/servicemix-bean.conf
Thu Jan 13 21:31:29 2011
@@ -7,20 +7,16 @@ h4. Namespace and xbean.xml
The namespace URI for the servicemix-bean JBI component is
{{http://servicemix.apache.org/bean/1.0}}. This is an example of an
{{xbean.xml}} file with a namespace definition with prefix {{bean}}.
{pygmentize:lang=xml}
<beans xmlns:bean="http://servicemix.apache.org/bean/1.0";>
-
- <!-- add bean:endpoint definitions here -->
-
-</beans>
+ <bean:endpoint service="test:service" endpoint="endpoint"
bean="#listenerBean"/>
+ <bean id="listenerBean"
class="org.apache.servicemix.bean.beans.ListenerBean"/>
+</beans></beans>
{pygmentize}
h4. Endpoint types
The servicemix-bean component only defines one endpoint, called
{{bean:endpoint}}. It can be used to receive and send message exchanges
from/to the NMR.
h3. {{Endpoint bean:endpoint}}
-
-h4. Endpoint properties
-{include:jbi/components/_servicemix-bean-endpoint.conf}
-
+There are two ways to configure the bean endpoint. The first is using the
fully qualified name of the class and the second is by passing to the endpoint
a reference to an existing bean.
h4. Using a Java class
When definining a {{bean:endpoint}} specifying a Java class name, a new
instance of this class will be created for handling a single message exchange.
@@ -33,5 +29,161 @@ When definining a {{bean:endpoint}} spec
</beans>
{pygmentize}
+h4. Using a spring bean
+Alternative, a reference to an existing bean can be passed to the bean
endpoint.
+{pygmentize:lang=xml}
+<beans xmlns:bean="http://servicemix.apache.org/bean/1.0";>
+ <bean:endpoint service="test:service" endpoint="endpoint"
bean="#listenerBean"/>
+ <bean id="listenerBean"
class="org.apache.servicemix.bean.beans.ListenerBean"/>
+</beans>
+{pygmentize}
+\\
+*Attention*: The Bean Endpoint schema allows to set a Bean or a Bean Name. The
Bean will create a *single* instance of the POJO per endpoint whereas the Bean
Name will create an instance per request (message exchange).
+
+h4. Endpoint properties
+{include:jbi/components/_servicemix-bean-endpoint.conf}
+
+h3. {{MessageExchangeListener}}
+The first kind of POJOs you can deploy implement the
[{{MessageExchagneListener}}|http://incubator.apache.org/servicemix/dist/servicemix-3.1-incubating/site/core/servicemix-core/apidocs/org/apache/servicemix/MessageExchangeListener.html]
interface. In such a case, {{servicemix-bean}} acts as a replacement of the
lightweight container component. This level offers the most control on the
exchange received and sent. This is usually used with the injected
{{DeliveryChannel}} to send back the exchanges, or if the POJOs needs to act as
a consumer (i.e. creating and sending exchanges to other services).
+
+These POJOs are low-level POJOs: you need to understand the JBI Api and
Message Exchange Patterns to correctly handle incoming exchanges.
+
+Note that at this point (v 3.1), there is no base class that you can inherit
to speed you in this process of implementing a POJO to handle JBI exchanges,
but hopefully it will come in the future.
+
+h3. Examples
+
+This example on the right shows the most simple bean. When it receives an
exchange, it will print it to the console and set the status to DONE before
sending the exchange back. This bean can not handle InOut exchanges, as it does
not set any response (an exception would be thrown in such a case).
+
+{pygmentize:lang=java}
+import org.apache.servicemix.jbi.listener.MessageExchangeListener;
+
+import javax.annotation.Resource;
+import javax.jbi.messaging.DeliveryChannel;
+import javax.jbi.messaging.ExchangeStatus;
+import javax.jbi.messaging.MessageExchange;
+import javax.jbi.messaging.MessagingException;
+
+public class ListenerBean implements MessageExchangeListener {
+
+ @Resource
+ private DeliveryChannel channel;
+
+ public void onMessageExchange(MessageExchange exchange) throws
MessagingException {
+ System.out.println("Received exchange: " + exchange);
+ exchange.setStatus(ExchangeStatus.DONE);
+ channel.send(exchange);
+ }
+
+}
+{pygmentize}
+
+This example will handle an InOut exchange and will send back the input as the
response.
+Note that this example would fail if receiving an InOnly exchange, as setting
a response on an InOnly exchange is not a legal operation.
+
+{pygmentize:lang=java}
+import org.apache.servicemix.jbi.listener.MessageExchangeListener;
+import org.apache.servicemix.jbi.util.MessageUtil;
+
+import javax.annotation.Resource;
+import javax.jbi.messaging.DeliveryChannel;
+import javax.jbi.messaging.ExchangeStatus;
+import javax.jbi.messaging.MessageExchange;
+import javax.jbi.messaging.MessagingException;
+
+public class ListenerBean implements MessageExchangeListener {
+
+ @Resource
+ private DeliveryChannel channel;
+
+ public void onMessageExchange(MessageExchange exchange) throws
MessagingException {
+ if (exchange.getStatus() == ExchangeStatus.ACTIVE) {
+ MessageUtil.transferInToOut(exchange, exchange);
+ channel.send(exchange);
+ }
+ }
+
+}
+{pygmentize}
+
+This is similar example as the one from above (also works only for InOut
exchange) but it shows how you can extract message from an exchange in order to
process it and send back.
+{pygmentize:lang=java}
+import org.apache.servicemix.jbi.listener.MessageExchangeListener;
+import org.apache.servicemix.jbi.util.MessageUtil;
+import org.apache.servicemix.jbi.jaxp.SourceTransformer;
+
+import javax.annotation.Resource;
+import javax.jbi.messaging.DeliveryChannel;
+import javax.jbi.messaging.ExchangeStatus;
+import javax.jbi.messaging.MessageExchange;
+import javax.jbi.messaging.MessagingException;
+import javax.jbi.messaging.NormalizedMessage;
+import javax.xml.transform.Source;
+
+public class ListenerBean implements MessageExchangeListener {
+
+ @Resource
+ private DeliveryChannel channel;
+
+ public void onMessageExchange(MessageExchange exchange) throws
MessagingException {
+ if (exchange.getStatus() == ExchangeStatus.ACTIVE) {
+ NormalizedMessage message = exchange.getMessage("in");
+ Source content = message.getContent();
+ //process content according to your logic
+ //e.g. to access the message body as a String use
+ String body = (new
SourceTransformer()).toString(content);
+
+ message.setContent(content);
+ exchange.setMessage(message, "out");
+ channel.send(exchange);
+ }
+ }
+
+}
+{pygmentize}
+
+h3. Disclaimer
+
+In versions 3.1 to 3.1.2 the ServiceMix Bean component will not handle
asynchronous messages correctly because the final send of the message marked as
DONE back to the NMR will be handled as a consumer message and that fails
because there is no corresponding provider message. The only workaround is to
send the messages synchronously.
+
+Note: This was resolved in 3.1.3, 3.2.x and later via
[SM-1110|https://issues.apache.org/jira/browse/SM-1110].
+
+h3. MessageExchange dispatching
+
+If the POJO deployed implements the
{{org.apache.servicemix.MessageExchangeListener}}, every message received for
this POJO will be dispatched to the {{onMessageExchange}} method.
+
+In other cases, exchanges in a provider role will be dispatched according to
the {{MethodInvocationStrategy}} configured on the endpoint. The default one
try to find the method according to the operation name defined on the exchange.
If there is only a single method acting as an operation, it will always be
used.
+
+h3. Annotations
+
+The {{servicemix-bean}} component can accept different kind of POJOs. These
POJOs may be annotated to customize their behavior. All the following
annotations belong to the {{org.apache.servicemix.bean}} package.
+|| Annotation || Target || Description ||
+|
[Callback|http://incubator.apache.org/servicemix/dist/servicemix-3.1-incubating/site/deployables/serviceengines/servicemix-bean/apidocs/org/apache/servicemix/bean/Callback.html]
| Method | |
+|
[Content|http://incubator.apache.org/servicemix/dist/servicemix-3.1-incubating/site/deployables/serviceengines/servicemix-bean/apidocs/org/apache/servicemix/bean/Content.html]
| Parameter | |
+|
[Correlation|http://incubator.apache.org/servicemix/dist/servicemix-3.1-incubating/site/deployables/serviceengines/servicemix-bean/apidocs/org/apache/servicemix/bean/Correlation.html]
| Type | |
+|
[Endpoint|http://incubator.apache.org/servicemix/dist/servicemix-3.1-incubating/site/deployables/serviceengines/servicemix-bean/apidocs/org/apache/servicemix/bean/Endpoint.html]
| Type | This annotation is mandatory if the bean is automatically searched
from a list of packages. |
+|
[ExchangeTarget|http://incubator.apache.org/servicemix/dist/servicemix-3.1-incubating/site/deployables/serviceengines/servicemix-bean/apidocs/org/apache/servicemix/bean/ExchangeTarget.html]
| Field | |
+|
[Operation|http://incubator.apache.org/servicemix/dist/servicemix-3.1-incubating/site/deployables/serviceengines/servicemix-bean/apidocs/org/apache/servicemix/bean/Operation.html]
| Method | |
+|
[Property|http://incubator.apache.org/servicemix/dist/servicemix-3.1-incubating/site/deployables/serviceengines/servicemix-bean/apidocs/org/apache/servicemix/bean/Property.html]
| Parameter | |
+|
[XPath|http://incubator.apache.org/servicemix/dist/servicemix-3.1-incubating/site/deployables/serviceengines/servicemix-bean/apidocs/org/apache/servicemix/bean/XPath.html]
| Parameter | |
+
+In addition, standard annotations can be used:
+
+|| Annotation || Target || Description ||
+|
[Resource|http://java.sun.com/javase/6/docs/api/javax/annotation/Resource.html]
| Field | The Resource annotation marks a resource that is needed by the
application. Currently, this annotation is only supported on fields of type
{{ComponentContext}} and {{DeliveryChannel}}. The component will inject the
specified resource when the POJO is instantiated. |
+|
[PostConstruct|http://java.sun.com/javase/6/docs/api/javax/annotation/PostConstruct.html]
| Method | The PostConstruct annotation is used on a method that needs to be
executed after dependency injection is done to perform any initialization. |
+|
[PreDestroy|http://java.sun.com/javase/6/docs/api/javax/annotation/PreDestroy.html]
| Method | The PreDestroy annotation is used on methods as a callback
notification to signal that the instance is in the process of being removed by
the container. |
+
+The following interfaces are part of this API:
+
+|| Interface || Description ||
+|
[MessageExchangeListener|http://incubator.apache.org/servicemix/dist/servicemix-3.1-incubating/site/core/servicemix-core/apidocs/org/apache/servicemix/MessageExchangeListener.html]
| When the POJO implements this interface, *all* exchanges will be dispatched
to the {{onMessageExchange}} method. |
+|
[Destination|http://incubator.apache.org/servicemix/dist/servicemix-3.1-incubating/site/deployables/serviceengines/servicemix-bean/apidocs/org/apache/servicemix/bean/Destination.html]
| This interface can be used to define a property on the bean, annotated with
the {{@ExchangeTarget}} annotation. This is a very simple API to send
exchanges from a POJO. More complex use cases can use an injected
{{DeliveryChannel}} directly or to create a ServiceMix [client|Client API]. |
+
+h3. More Examples
+
+*
[AnnotatedBean|http://incubator.apache.org/servicemix/dist/servicemix-3.1-incubating/site/deployables/serviceengines/servicemix-bean/xref-test/org/apache/servicemix/bean/beans/AnnotatedBean.html]
+*
[AutoDeployedBean|http://incubator.apache.org/servicemix/dist/servicemix-3.1-incubating/site/deployables/serviceengines/servicemix-bean/xref-test/org/apache/servicemix/bean/beans/AutoDeployedBean.html]
+*
[ConsumerBean|http://incubator.apache.org/servicemix/dist/servicemix-3.1-incubating/site/deployables/serviceengines/servicemix-bean/xref-test/org/apache/servicemix/bean/beans/ConsumerBean.html]
+*
[ListenerBean|http://incubator.apache.org/servicemix/dist/servicemix-3.1-incubating/site/deployables/serviceengines/servicemix-bean/xref-test/org/apache/servicemix/bean/beans/ListenerBean.html]
+*
[PlainBean|http://incubator.apache.org/servicemix/dist/servicemix-3.1-incubating/site/deployables/serviceengines/servicemix-bean/xref-test/org/apache/servicemix/bean/beans/PlainBean.html]
-h4. TODO: add other configuration types
