Page History

Overview of the ServiceMix

...

2.x

...

This document describes how to run ServiceMix's BPEL example and provides details about what it does. For information on the business use case, please refer to: Use Case for BPEL.

WSIF Example

Web Services Invocation Framework (WSIF) provides a Java API for calling Web services, hiding the details of how the service is provided, i.e., via SOAP, JMS, etc. The following guide describes the ServiceMix components that integrate with the Apache Web Service Invocation Framework (WSIF) to perform web service invocations using a number of different implementation protocols such as Axis, local Java, EJB, JMS, JCA and CCI.

The WSIF example illustratesThe BPEL example illustrates the following:

• an example of declarative programming
• how to perform BPEL integration with ServiceMix
• how to use JmsTemplate for publishing and subscribing to ActiveMQ topics

The XML code for the BPEL example is located in the ServiceMix installation directory under the examples\bpel directory in the servicemix.xml file. It is recommended that you refer to the servicemix.xml file while reading this document.

This example has a client application, JMSClient, which sends a SOAP message to a ServiceMix binding component called myComponent. myComponent forwards the request to the PXE BPEL engine and waits for a response. In other words, JMSClient places a book order and myComponent receives the order and then sends it to the Webservice that takes orders. The client, JMSClient, and the binding component, myComponent, communicate via JMS; this communication is external to the ServiceMix JBI. myComponent and the PXE BPEL service engine communicate internally over the Normalized Message Router (NMR).

Prerequisites to Run the BPEL Example

The following must be installed to run this example:

...

• expose web service over a JMS queue through WSIF

NOTE: This is not a complete, working example. Rather, it illustrates how WSIF can be used in a ServiceMix component, through a typical and realistic web application. The following components in the diagram have not been completely implemented:

1. The Web Form has not been created
2. The HTTP Binding Component has not been configured, via a servicemix.xml file, to use the "checkAvailabity" component as its destination.

This example shows critical code snippets from a larger example, which can be found at Apache Web Services Project. A client application submits a ZIP Code to a Web Services application via a JMS queue. The web service then checks if DSL service is available in the ZIP Code area and responds to the client, also by sending a JMS message. The client software uses WSIF to hide the implementation details of JMS.

In the ServiceMix example, the WSIF API is used by the client to make the ZIP Code request to the web service. The WSIF API takes care of the JMS details for the client (although other transport mechanisms, such as SOAP, JCA, etc., could have been used). The ServiceMix WSIF API provides a single API to the client and handles the details of the web service invocation for the client, simplifying the client code.

The example also shows an important feature of the ServiceMix Client API - how to bind a WSDL file for a web service, which includes additional WSIF metadata to configure the service implementation. In other words, the service.wsdl file contains WSIF extensions to WSDL that bind the web service to the transport protocol. Some of the coding details will be shown later in this document

Running the BPEL Example

Before running this example, the following setup must be done. PXE has a JBI component and deployment unit, which can be auto-deployed in any JBI compliant container, in this case ServiceMix. To use PXE with ServiceMix, the PXE deployment unit must be placed in the install directory so it will be auto-deployed in ServiceMix. NOTE: The PXE deployment unit has already been placed into the install directory for you - take a look at the servicemix_install_dir\examples\bpel\install directory to see the PXE jar file.

Perform the following steps to run the BPEL example:

...

cd [servicemix_install_dir]\examples\bpel

...

[servicemix_install_dir]\bin\servicemix servicemix.xml

OR

..\..\bin\servicemix servicemix.xml

...

ant

...

Stopping the BPEL Example

To terminate the BPEL example type "CTRL-C" in the command shell in which it is running and answer "y" to the "Terminate batch job (y/n)?" question.

How it Works

The diagram below illustrates the example program's logical flow of the program through the BPEL components:

...

...

...

Image Removed

The logical flow of the program is:

1. The JMSClient, through ActiveMQConnectionFactory, connects to the topic named "demo.org.servicemix.source" and sends a text message containing the message.soap file.
2. myComponent, being a subscriber of the topic "demo.org.servicemix.source," receives the message.
3. The myComponent implementation class, JmsServiceComponent, sends the message over the ServiceMix bus to the PxeBpelEngine by executing its onMessage() method. The destinationService property defines the destination of the message. NOTE: the destinationService property is found in the servicemix.xml file.
4. PxeBpelEngine sends a response back to myComponent through the ServiceMix bus, the NMR.
5. myComponent uses the jmsTemplate bean to publish the message.
6. jmsTemplate uses the jmsFactory bean to get a connection to the port associated with the JMS topic called "demo.org.servicemix.source." The message is published on the "demo.org.servicemix.source" topic.
7. JMSClient, being a subscriber of topic "demo.org.servicemix.source," receives the message.
8. The response is printed on the console.

Logging information is written to the console as files are transmitted. Typical output looks like the following:

 
 
ServiceMix ESB: 1.0

Loading ServiceMix from file: servicemix.xml
[INFO] XmlBeanDefinitionReader - -Loading XML bean definitions from file C:\exist\servicemix\servicemix-1.0.1\examples\bpel\servicemix.xml]
[INFO] CollectionFactory - -JDK 1.4+ collections available
[INFO] CollectionFactory - -Commons Collections 3.x available
[INFO] FileSystemXmlApplicationContext - -Bean factory for application context 
[org.springframework.context.support.FileSystemXmlApplicationContext;hashCode=110
2920]: org.springframework.beans.factory.support.DefaultListableBeanFactory defining beans 
[jndi,broker,transactionManager,jmsFactory,jbi];
 root of BeanFactory hierarchy[INFO] FileSystemXmlApplicationContext - -5 beans defined in application context
 [org.springframework.context.support.FileSystemXmlApplicationContext;hashCode=1102920]
[INFO] FileSystemXmlApplicationContext - -Unable to locate MessageSource with name 'messageSource': using default 
[org.springframework.context.support.DelegatingMessageSource@18e2b22]
[INFO] FileSystemXmlApplicationContext - -Unable to locate ApplicationEventMulticaster with name 'applicationEventMulticaster': 
using default [org.springframework.context.event.SimpleApplicationEventMulticaster@13caecd]
[INFO] DefaultListableBeanFactory - -Pre-instantiating singletons in factory
 [org.springframework.beans.factory.support.DefaultListableBeanFactory 
defining beans [jndi,broker,transactionManager,jmsFactory,jbi]; root of BeanFactory hierarchy]
[INFO] DefaultListableBeanFactory - -Creating shared instance of singleton bean'jndi'
[INFO] DefaultListableBeanFactory - -Creating shared instance of singleton bean 'broker'
[INFO] SpringBrokerContainerFactory - -Loading ActiveMQ broker from configuration: class path resource [activemq.xml]
[INFO] ActiveMQBeanDefinitionReader - -Loading XML bean definitions from class path resource [activemq.xml]
[INFO] ActiveMQBeanFactory - -Creating shared instance of singleton bean 'broker'
[INFO] ActiveMQBeanFactory - -Creating shared instance of singleton bean 'memoryManager'
[INFO] ActiveMQBeanFactory - -Creating shared instance of singleton bean 'derby-ds'
[INFO] ActiveMQBeanFactory - -Creating shared instance of singleton bean 'mysql-ds'
[INFO] BrokerContainerImpl - -ActiveMQ 3.1-M6 JMS Message Broker (ID:el2tong-1095-1129854563062-0:0) is starting
[INFO] BrokerContainerImpl - -For help or more information please see: http://www.logicblaze.com
[INFO] JDBCPersistenceAdapter - -Database driver recognized: [apache_derby_embedded_jdbc_driver]
[INFO] DefaultJDBCAdapter - -Could not create JDBC tables; they could already exist. Failure was: 
CREATE TABLE ACTIVEMQ_MSGS(ID INTEGER NOT NULL, CONTAINER VARCHAR(250), MSGID VARCHAR(250), MSG BLOB, PRIMARY KEY ( ID ) ) 
Message: Table/View 'ACTIVEMQ_MSGS' already exists in Schema 'APP'. SQLState: X0Y32 Vendor code: 20000
[INFO] DefaultJDBCAdapter - -Could not create JDBC tables; they could already exist. Failure was: 
CREATE TABLE ACTIVEMQ_TXS(XID VARCHAR(250) NOT NULL, PRIMARY KEY ( XID )) Message: Table/View 'ACTIVEMQ_TXS' already exists in Schema 'APP'. SQLState: X0Y32 Vendor code: 20000
[INFO] DefaultJDBCAdapter - -Could not create JDBC tables; they could already exist. Failure was: 
CREATE TABLE ACTIVEMQ_ACKS(SUB VARCHAR(250) NOT NULL, CONTAINER VARCHAR(250) NOT NULL, LAST_ACKED_ID INTEGER, SE_ID INTEGER, 
SE_CLIENT_ID VARCHAR(250), SE_CONSUMER_NAME VARCHAR(250), SE_SELECTOR VARCHAR(250), PRIMARY KEY (
 SUB, CONTAINER )) Message: Table/View 'ACTIVEMQ_ACKS' already exists in Schema 'APP'. SQLState: X0Y32 Vendor code: 20000
[INFO] DefaultJDBCAdapter - -Could not create JDBC tables; they could already exist. Failure was: 
ALTER TABLE ACTIVEMQ_MSGS ADD EXPIRATION BIGINT Message: Column 'EXPIRATION' already exists in Table/View 'APP.ACTIVEMQ_MSGS'. SQLState: X0Y32 Vendor code: 20000
[INFO] JournalPersistenceAdapter - -Opening journal.
[INFO] JournalPersistenceAdapter - -Opened journal: Active Journal: using 2 x 20.0 Megs at: ..\var\journal
[INFO] JournalPersistenceAdapter - -Journal Recovery Started.
[INFO] JournalPersistenceAdapter - -Journal Recovered: 0 message(s) in transactions recovered.
[INFO] TcpTransportServerChannel - -Listening for connections at: tcp://el2tong:61616
[INFO] BrokerConnectorImpl - -ActiveMQ connector started: TcpTransportServerChannel@tcp://el2tong:61616
[INFO] BrokerContainerImpl - -ActiveMQ JMS Message Broker (ID:el2tong-1095-1129854563062-0:0) has started
[INFO] DefaultListableBeanFactory - -Creating shared instance of singleton bean 'transactionManager'
[INFO] DefaultListableBeanFactory - -Creating shared instance of singleton bean 'jmsFactory'
[INFO] DefaultListableBeanFactory - -Creating shared instance of singleton bean 'jbi'
[INFO] ActiveMQConnection - -channel status changed: Channel: TcpTransportChannel: Socket[addr=localhost/127.0.0.1,port=61616,localport=1096] has connected
[INFO] BrokerContainerImpl - -Adding new client: ID:el2tong-1095-1129854563062-5:0 on transport: TcpTransportChannel: Socket[addr=/127.0.0.1,port=1096,localport=61616]
[INFO] JBIContainer - -ServiceMix JBI Container (http://servicemix.org/) name: defaultJBI running version: ServiceMix.
[INFO] JBIContainer - -Activating component for: [container=defaultJBI,name=myComponent,id=myComponent]
 with service: {uri:fivesight.com/examples/AsyncProcessJBI}JmsService component: org.servicemix.components.jms.JmsServiceComponent@1b82d69
[INFO] ComponentContextImpl - -Component: myComponent activated endpoint: {uri:fivesight.com/examples/AsyncProcessJBI}JmsService : myComponent

Details

...

Image Added

Following, are the details of example program's logic flow:

1. A user opens a web browser and accesses a web form with a "zip code" input field and a submit button. The submit button sends the form and the ZIP Code entered by the user to a Servicemix HTTP binding component.
2. The ServiceMix HTTP binding component creates an InOut exchange message through the client API. The message is sent through the NMR to the checkAvailability component.
3. The checkAvailability component sends the request to the JMS queue.
4. The web service is implemented with as a message-driven EJB (MDB), who's "onMessage" method is listening for messages on the queue.
5. The MDB processes the request and sends back a response to the checkAvailability component through a temporary queue. The response is either "true" (DSL service is available) or "false" (DSL service is not available).
6. The checkAvailability component receives the response from the queue.
7. The checkAvailability component responds to the HTTP client.
8. The HTTP client sends the result back to the web form. The value of the result property is displayed and lets the user know whether or not DSL is available in the specified zip code area.

Details

The following table provides more details about the function of the checkAvailability component and the Web Service MDB:

Additional Coding Details

The following snippet is from the servicemix.xml file. Note: that the WSIFBinding class has the service.wsdl file as a property.

...

Following is an example of how to enable a service to be exposed over a JMS topic or queue. This is a snippet of code from the service.wsdl file. It shows how to configure the JMS binding:

...

Here are descriptions of the properties found in the service.wsdl file. The descriptions are quoted from the WSDL Bindings for JMS web page:

• <jms:address> describes a target port that is accessible via JMS.
• destinationStyle must either be queue or topic, although only queue is supported at this time.
• jndiDestinationName is the JNDI name of the JMS queue that WSIF will send requests to.
• jndiConnectionFactoryName is the JNDI name of the connection factory that WSIF will be used.
• jndiProviderURL and initialContextFactory specify which JNDI database to use. If they are not present, WSIF uses the default JNDI.
• jms:binding specifies that this binding is for Native JMS. The type is the type of the JMS message that will be sent. In this case it will be a text message.

Working with XML versus properties

The JBI standard requires encoding WSDL 1.1 parts using an XML encoding mechanism. ServiceMix supports this requirement. However, in addition ServicMix also allows the message properties, of an NMR message, to use the named parts of the service.wsdl file, to avoid unnecessary XML marshalling.

A Java client can be programmed as an alternative way of invoking the web service, in lieu of a web form. The following is a Java client example using the ServiceMix Client API in a WSIF approach, passing in and fetching out named parameters. This Java client is performing the role originally assigned to the HTTP Client above. It also needs to be configured (not shown) to communicate to the "checkAvailability" service via the ServiceMix NMR. In other words, it needs to have "checkAvailability" set as its "destination" for the NMR messages it sends.

...

The previous Java code works against the given WSDL 1.1 service.wsdl file using its named parts:

...

Related Documentation

For more information, please see:

• NMR

• WSIF

• Apache WSIF

Related Documentation

For more information on the following topics please see:

• ActiveMQ related components, jmsFactory, jmsTemplate, broker

• NMR

• PXE BPEL Engine

• Spring