This document describes a brief usage of SOAP workflow framework when developing a service consumer.
Getting started
First thing you need to do is to check the service endpoint description page and WSDL document using provided endpoint address.
Usually the address for endpoint description page looks like this: http://<host>:<port>/application-name/InvokerService and WSDL location like this: http://<host>:<port>/application-name/InvokerService?wsdl. When accessing the endpoint description page you should see something like this:
and when trying to access the WSDL location you should be able to see the valid WSDL document.
When you have the WSDL document you can start generating the DTO classes. Many programming languages have it's own tools for class generation from WSDL.
One of the easiest ways to do this in JAVA is to use JAX-WS and Maven with plugin called jaxws-maven-plugin. The example Maven pom.xml file could look like this:
<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.example.integration.crm</groupId> <artifactId>example-client</artifactId> <version>1.0-SNAPSHOT</version> <name>Example integration project</name> <description>Example integration project</description> <scm> <developerConnection>scm:svn:https://svn.example.com/svn/dev/integration/example-client</developerConnection> </scm> <properties> <project.java.version>1.6</project.java.version> </properties> <dependencyManagement> <dependencies> <dependency> <groupId>javax.xml.ws</groupId> <artifactId>jaxws-api</artifactId> <version>2.2.7</version> </dependency> <dependency> <groupId>javax.xml.bind</groupId> <artifactId>jaxb-api</artifactId> <version>2.2.6</version> </dependency> <dependency> <groupId>javax.xml.soap</groupId> <artifactId>saaj-api</artifactId> <version>1.3.4</version> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>com.sun.xml.ws</groupId> <artifactId>jaxws-rt</artifactId> <version>2.1.4</version> <scope>provided</scope> </dependency> <dependency> <groupId>javax.xml.bind</groupId> <artifactId>jaxb-api</artifactId> </dependency> <dependency> <groupId>javax.xml.ws</groupId> <artifactId>jaxws-api</artifactId> </dependency> <dependency> <groupId>javax.jws</groupId> <artifactId>jsr181-api</artifactId> </dependency> <dependency> <groupId>javax.xml.soap</groupId> <artifactId>saaj-api</artifactId> </dependency> <dependency> <groupId>javax.xml</groupId> <artifactId>jax-qname</artifactId> <version>1.1</version> </dependency> </dependencies> <build> <sourceDirectory>src/main/java</sourceDirectory> <testSourceDirectory>src/test/java</testSourceDirectory> <resources> <resource> <directory>src/main/resources</directory> </resource> </resources> <testResources> <testResource> <directory>src/test/resources</directory> </testResource> </testResources> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <configuration> <source>${project.java.version}</source> <target>${project.java.version}</target> </configuration> </plugin> <plugin> <groupId>org.jvnet.jax-ws-commons</groupId> <artifactId>jaxws-maven-plugin</artifactId> <version>2.1</version> <executions> <execution> <goals> <goal>wsimport</goal> </goals> </execution> </executions> <configuration> <packageName>com.example.service</packageName> </configuration> </plugin> </plugins> </build> </project>
Place the WSDL document in <project_dir>/src/wsdl and run the following command to generate the class source files:
mvn generate-sources
When you have successfully generated the class sources, you can start developing your service client using these classes and invoking the workflows.
Lets say you have to invoke the workflow which expects you to send the following structure.
Request:
Key |
Value type |
Mandatory |
Description |
---|---|---|---|
CONTEXT |
ComplexValueDTO |
true |
Context object, mandatory in each request. |
CONTEXT:
Key |
Value type |
Mandatory |
Description |
---|---|---|---|
LANGUAGE |
StringValueDTO |
true |
Language code. EN, FR, DK, etc. Used for displaying error messages. |
OPERATOR |
StringValueDTO |
true |
Operator information. |
BRAND_ID |
StringValueDTO |
false |
Id of the brand if applicable. |
Then your client code would look something like this:
private static final String YOUR_HOOKPOINT_KEY = "YOUR_HOOKPOINT_KEY"; private static final String CONTEXT_KEY = "CONTEXT"; private static final String LANGUAGE_KEY = "LANGUAGE"; private static final String OPERATOR_KEY = "OPERATOR"; private static final String LANGUAGE_EN = "EN"; private static final String OPERATOR_DUMMY = "DUMMY"; <...> public void invokeYourWorkflow() { InvokerService_Service service = new InvokerService_Service(); InvokerService servicePort = service.getInvokerServicePort(); RequestDTO request = new RequestDTO(); request.setHookpointKey(YOUR_HOOKPOINT_KEY); StringValueDTO language = new StringValueDTO(); language.setKey(LANGUAGE_KEY); language.setValue(LANGUAGE_EN); StringValueDTO operator = new StringValueDTO(); language.setKey(OPERATOR_KEY); language.setValue(OPERATOR_DUMMY); ComplexValueDTO context = new ComplexValueDTO(); context.setKey(CONTEXT_KEY); context.getValue().add(language); context.getValue().add(operator); request.getValues().add(context); ResponseDTO response = servicePort.executeMethod(request); }
This approach gives a lot of flexibility as the changes to service maybe applied rapidly, it's just a matter of adding another DTO to a value list.
Note: You can also have a tree-like structure using ComplexValueDTO objects, that means, you can have a list of ComplexValueDTO objects inside another ComplexValueDTO object.