Versions Compared

Old Version 2

changes.mady.by.user Unknown User (mjarillas)

Saved on

compared with

New Version Current

changes.mady.by.user Guillaume Nodet

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin

Overview of the ServiceMix

...

2.x WSIF Example

This document describes the 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 illustrates the following:

  • an example of declarative programming
  • how to enable a service to be exposed 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 is adorned with includes additional WSIF additional 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.

How it Works

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

...



...

Image Modified

...



The logical flow of the program isFollowing, are the details of example program's logic flow:

  1. A user opens a web browser and access accesses a web form with a "zipcodezip code" input field and a submit button. The submit button sends the form and the zipcode typed in 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 webservice 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 let's lets the user know whether or not DSL is available at the zipcodein the specified zip code area.

Details

The following table provides more details about the function of each the checkAvailability component and bean in the servicemix.xml filethe Web Service MDB:

Component or Bean ID

Description

jbi

jbi is the "id" of the JBI container and provides the basic infrastructure services for myComponent. During initialization, several singletons are instantiated: transactionManager, broker, jmsFactory, and jbi. Also, take note of the properties installationDirPath and deploymentDirPath defined in servicemix.xml. ServiceMix automatically installs components found in the folder specified in the installationDirPath property. It automatically deploys component-specific artifacts found in the folder specified in the deploymentDirPath property.

JMSClient

This Java standalone program, through the ActiveMQConnectionFactory, connects to topic "demo.org.servicemix.source." It then creates a text message from the file message.soap and publishes it to the topic "demo.org.servicemix.source," then requests and waits for a response. It eventually prints the response to the console.

myComponent

This JMS service component subscribes to the "demo.org.servicemix.source" topic via its defaultDestinationName property specified in the servicemix.xml configuration file. Through its template property, it uses jmsFactory to listen on port 61616 via ActiveMQConnectionFactory. It is implemented by the JmsServiceComponent that has an onMessage() method which is called by ActiveMQ when a message arrives on the topic. This method creates a normalized message, which is sent over the ServiceMix bus to the PxeBpelEngine as specified on its destinationService property.

jndi

This bean loads up database and transaction manager resources, which will be used by the other components in the system. More importantly, the JNDI context must be configured so that PXE can be deployed.

Pxe-install.jar

This jarfile is located in the examples\bpel\install directory. It contains many files, which in turn contain the classes that implement the PXE BPEL engine. It also has a jbi.xml file, which is used by ServiceMix to install the PXE BPEL engine as a ServiceMix service-engine component. Note, that in this file the component type is "service-engine" and the component name is PxeBpelEngine. When processes are deployed to the PXE engine (see next row with AsyncProcess-sa.jar), it exposes them as services on the JBI, which can be referenced by other components as destinationService(s), with destinationEnpoint(s) - see the servicemix.xml file.

AsyncProcess-sa.jar

This jarfile is located in the examples\bpel\deploy directory. It contains a jbi.xml file, which references the PxeBpelEngine. This ties the processes to the PXE engine described in the previous section. The jbi.xml file also references the AsyncProcess-su.zip file, which is also contained in the AsycnProcess-sa.jar file. This zipfile contains other configuration files and WSDL files, i.e., pxe-system.xml and resource_X.stream, which describe the services deployed on the PXE engine.

broker

The broker bean uses the activemq.xml file to configure the message broker, which handles the JMS messages for the components that require JMS messaging services.

transactionManager

This bean is configured to be the default transaction manager for the jbi container. This transaction manager provides transactional services between the resource adapter (in this case the ActiveMQ resource adapter provided by the jencks JCA container) and components in the jbi container.

jmsFactory

This bean listens on port 61616 and provides a pooled ActiveMQ connection.

Related Documentation

For more information on the following topics please see:

checkAvailability

This component uses the WSIFBinding class to integrate WSIF to ServiceMix as specified in the class property. Its definitionResource property is set to read the classpath:org/servicemix/components/wsif/service.wsdl file, which is the WSDL file that will be used. The service.wsdl file can be found at [servicemix-2.x_src_install_dir]\components\base\src\test\resources\org\servicemix\components\wsif. In the init() method of the WSIFBinding class, service.wsdl is read to define the binding extension.

MDB

This MDB is the actual implementation of the service. It acts like a message listener on the queue specified in the config files. When a message is delivered, it extracts the body which is a ZIP Code. It then applies some logic to determine whether DSL service is available at this ZIP Code or not. For simplicity, it just returns true for all ZIP Codes < 50000 and false otherwise. The return message is sent to the queue specified in the replyTo field of the request message. NOTE: The MDB must encode the correct JMSCorrelationID in the return message in order for it to be picked up by WSIF.

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: