Skip to Main Content U.S. Department of Energy
 

Web Service

The following describes: *An overview of the EchoWebServiceSynchTest and EchoWebServiceAsyncTest sample included in the MIF package. *How to run the samples. *A walkthrough of the code used to construct this sample.

Prerequisites

Please refer to the getting started page and the installation page to prepare to use the following sample.

Also, if you would like to use this example outside of Eclipse, please refer to the development environment page.

Other useful information includes the documentation for Apache CXF, which is used as our implementation of web services, and can be found here.

Overview of the Web Services Samples

The implementation of web services into the MIF pipeline is a little more complicated than simply adding a web services endpoint to one of the MIF modules. We instead have to incorporate the Apache CXF API to run our web services and, in implementing the API, we have to define several of its key features which are explained below in our walk through of the various bits of code.

Here is an overview of how the web services module works.

The Web Services Module

The Echo module inside the Web Services Module is actually the component that will process the instructions sent into the module via web services because it is responsible for translating the web services code that comes in into language usable by the module through its implementation of the Apache CXF API.

And here is an example of how it can be implemented into the MIF workflow.

Sample Snippet of MIF Workflow

This picture is simplified to two components in the BPEL engine; in reality, there could be a far greater number of components in the engine, each of which is a MIF workflow component. In essence, each component is a mini-MIF pipeline which is encapsulated as a component. The web services endpoints are determined dynamically at run time, which means they receive the endpoints from the instructions sent from the components in the BPEL engine. So in this example, the first web service module in the mini-pipeline would receive its instructions and dynamically change the endpoint of the last web service module in the pipeline to the reply.to address of the next necessary BPEL component as determined by the BPEL engine.

The difference between the asynchronous and synchronous web service modules comes down to the time in which each pipeline takes to run. Some pipelines can take substantially longer to complete; long enough that the component waiting for the result will eventually time out and render the BPEL engine useless. The solution to this is to use an asynchronous web service module when the pipeline will take longer to complete than the time before the second component times out. The scenario in which the next component in the workflow waits for the pipeline to complete is the sychronous web service module.

Running EchoWebServiceSynchTest and EchoWebServiceAsynchTest

Note: MIF_HOME represents the installation directory of MIF (where you extracted it).

To run EchoWebServiceSynchTest and EchoWebServiceAsynchTest:

  • Open up a shell and navigate to $MIF_HOME.
  • From there, run:
bin/run-mif.bat -c gov.pnnl.mif.samples.ws.async.EchoWebServiceAsyncTest (or the Synch equivalent)

The Pipeline Behind the Web Services Samples

The code for EchoWebServiceSynchTest (referred to hereafter as “sync”) and EchoWebServiceAsyncTest (referred to hereafter as “async”) is very similar. First we will take a look at the async code:

public static void main(String[] args) {
 MifPipeline pipeline = new MifPipeline();
 pipeline.addMifConnector(EndpointProtocol.CXF);
 pipeline.addMifWsModule(EchoAsync.class.getName(), "cxf://localhost:9090/echoAsyncService", null);
 pipeline.start();
}

And now the sync code:

public static void main(String[] args) {
 MifPipeline pipeline = new MifPipeline();
 pipeline.addMifWsModule(Echo.class.getName(), "http://localhost:9000/echoService", null);
 pipeline.start();
}

As you can see, the only variation between the two main programs are the inclusion of an endpoint protocol as a mif connector in async as well as the differences in the MifWsModule. In the sync program, a pipeline is created and we add the MifWsModule whose parameters are (String mifProcessor, String inUri, String outUri). These first of these parameters represents the processor used to translate the BPEL instructions into usable code for the pipeline; the second and third paramters are the reply.to endpoints - the first specifies where to receive information from while the second specifies where the data should be sent to. As alluded to above, while these endpoints may not be dynamic, they can be made dynamic to interact with various workflow components in MIF workflow.

Echo and EchoAsync

Next, we will examine the Echo and EchoAsync classes.

First the Echo class:

import javax.jws.WebMethod;
import javax.jws.WebService;
 
@WebService(endpointInterface = "gov.pnnl.mif.samples.ws.sync.EchoInterface", serviceName = "echoService")
public class Echo implements EchoInterface {
 
  @WebMethod
  public String doEcho(String echoArg) {
    System.out.println("echo-ing: " + echoArg);
    return echoArg;
  }
}

As you can see in this class, we import the WebMethod and WebService APIs to handle the information that comes in via web services. The WebService API necessitates that we define @Webservice with an endpointInterface and a service name. The one method that must be defined with the implmentation of EchoInterface is doEcho which returns a string.

Async is much the same:

import javax.jws.Oneway;
import javax.jws.WebMethod;
import javax.jws.WebService;
 
@WebService(endpointInterface = "gov.pnnl.mif.samples.ws.async.EchoAsyncInterface", serviceName = "echoAsyncService")
public class EchoAsync implements EchoAsyncInterface {
 
  @Oneway
  @WebMethod
  public void doEcho(String echoArg) {
    System.out.println("echo-ing: " + echoArg);
  }
 
}

Here, however, the doEcho is void because in Async the reply.to returns immediately. We also import the Oneway so that we can avoid the timeout hassle should the pipeline take too long to complete.

EchoAsyncInterface is reproduced below:

import javax.jws.WebParam;
import javax.jws.WebService;
 
@WebService
public interface EchoAsyncInterface {
 
  public void doEcho(@WebParam(name = "echoArg") String echoArg);
}

This is very similar to the sync interface with the exception that “void” is changed to “String”.

 
workflowmodule.txt · Last modified: 2010/05/27 11:32 by adamw