GPEL Client Library API

Depends on modules: xpp5, xsul5, and Apache httpclient library

To lear more about GPEL visit GPEL website.

Reference card (typical usage patterns)

Typical Usage Pattern: From workflow deployment to workflow execution.

Open connection to GPEL engine

GpelClient provides access to all GPEL client API.

  URI gpelEngineLocation = URI.create("http://...");
  GpelUserCredentials credentials = new GpelUserCredentials("userName", "password");
  GcHttpTransport transport = new Transport(credentials);
  GpelClient gcl = new GpelClient(gpelEngineLocation, transport);

Workflow deployment

For workflo deployment following resources are needed:

• GPEL or BPEL process definition
• WSDL files representing port types of services used
• Parent link types definitions (they can be part of WSDL files or separate)

Each deployed resource is represented as GcWebResource which is an abstract class with several subclasses representing GPEL/BPEL process (GcProcessResource) or WSDL definitions (GcWsdlResource).

For deploymebnt resource should be gathered in a list:

  List links = new ArrayList();

  GcProcessResource processResource = processResFromFile("simple-adder.gpel", PROCESS_GPEL);
  links.add(processResource);

  GcWsdlResource adderWsdlResource = wsdlResFromFile("simple-adder.wsdl", ADDER_WSDL);
  links.add(adderWsdlResource);

Then GpelClient can be used to create a workflow template and associate list of required resources to deply them. When a workflow template is deployed it get an unique id.

  GcTemplate template = gcl.createTemplate("simple-adder.gwt");

  template.setLinks(links);

  gcl.deployTemplate(template);

  // ids can only accessed after they were created by server during deployment
  URI wfTemplateId = template.getTemplateId();

In this example we used following utility methods:

  public GcWsdlResource wsdlResFromFile(String title, String wsdlFileName) {
	return wsdlResFromFile(title, wsdlFileName, GcWsdlResource.class);
  }

  public <T extends GcWsdlResource> T wsdlResFromFile(
	String title, String wsdlFileName, Class<T> klass) {
	WsdlDefinitions processWsdl = WsdlResolver.getInstance().loadWsdlFromPath(
	  getClass(), wsdlFileName);
	GcWsdlResource wsdlResource = new GcWsdlResource(title, processWsdl);
	T t = wsdlResource.xml().viewAs(klass);
	return t;

  }

  public GcProcessResource processResFromFile(String title, String gpelFileName) {
	GpelProcess process = GpelResolver.getInstance().loadGpel(
	  getClass(), gpelFileName);
	GcProcessResource processResource = new GcProcessResource(title, process);
	return processResource;
  }

Workflow instance creation

Each created instance has an unique id.

  URI wfTemplateId = ...
  GcTemplate template = gcl.retrieveTemplate(wfTemplateId);
  GcInstance instance = template.createInstance();
  URI instanceId = instance.getInstanceId();

Starting workflow instance

To run workflow it is required to provie concrete WSDL files for all service partners. The WSDL files must have SOAP doc/literal binding and point to a service endpoint. Such WSDl files are special version of GcWsdlResource called GcUsesWsdlResource.

  GcUsesWsdlResource adderServiceWsdl
    = wsdlResFromFile("adderPartner", // NOTE: this MUST be partner name from .gpel (that has partnerRole)
		ADDER_WSDL,
	    GcUsesWsdlResource.class);

Each such WSDL needs to be added to list of instance links and the instance needs to be updated by callind stored().

  instance.getLinks().add(adderServiceWsdl);
  instance.store();

When all required WSDLs for services used by the instance are stored then the workflow can be started:

   instance.start();

Now the workflow is ready to be invoked.

Interacting with workflow

A started workflow instance is a Web Service and it has a WSDL(s). The workflow instance may have many WSDLs in case it acts as in several roles. The name of role (partner) is needed to retrieve workflow WSDL.

  String WF_PUBLIC_PN = "workflowUserPartner";
  // access public WSDL for created workflow (contains actual location os SOAP endpoint)
  GcProvidesWsdlResource workflowPublicWsdl = (GcProvidesWsdlResource)
    instance.getLinkWithTitleAndRel(
      WF_PUBLIC_PN , // NOTE: this MUST be partner name from .gpel (that has myRole)
      GcProvidesWsdlResource.REL);

NOTE: you need ot use XSUL API to parse WSDL or you can convert WSDL into string and parse it into XML and use your favorite WSDL API such as WSDL4J).

To extract the workflow instance endpoint address:

  WsdlDefinitions wsdl = workflowPublicWsdl.getWsdl();
  String wsdlAsString  = wsdl.xmlString(); //to string
  WsdlService ws = wsdl.services().iterator().next();
  WsdlPort wsp = ws.ports().iterator().next();
  WsdlSoapPort soapPort = wsp.xml().viewAs(WsdlSoapPort.class);
  WsdlSoapAddress soapAddress = soapPort.getSoapAddress();
  URI wsdlServLoc  = soapAddress.getLocation();

Getting workflow status

Workflow status is maintained in an XML document stored in GPEL engine. To retrieve this status use the workflow instance object:

  GcState state = instance.retrieveCurrentState();
  System.err.println("instance " + instance.getId() + " status=" + state.getStatus());
  Date d = new Date(state.getUpdated().getTimeInMillis());
  System.err.println("instance " + instance.getId() + " updated=" + d);