Red Hat Training
A Red Hat training course is available for JBoss Enterprise SOA Platform
JBoss SOA BPEL Guide
This guide is for developers
Edition 5.3.1
David Le Sage
Suzanne Dorfield
Abstract
Preface
Chapter 1. Preface
1.1. Business Integration
1.2. What is a Service-Oriented Architecture?
A Service Oriented Architecture (SOA) is not a single program or technology. Think of it, rather, as a software design paradigm.
Note
1.3. Key Points of a Service-Oriented Architecture
- the messages being exchanged
- the agents that act as service requesters and providers
- the shared transport mechanisms that allow the messages to flow back and forth.
1.4. What is the JBoss Enterprise SOA Platform?
1.5. The Service-Oriented Architecture Paradigm
- Service Provider
- A service provider allows access to services, creates a description of a service and publishes it to the service broker.
- Service Requester
- A service requester is responsible for discovering a service by searching through the service descriptions given by the service broker. A requester is also responsible for binding to services provided by the service provider.
- Service Broker
- A service broker hosts a registry of service descriptions. It is responsible for linking a requester to a service provider.
1.6. Core and Components
1.7. Components of the JBoss Enterprise SOA Platform
- A full Java EE-compliant application server (the JBoss Enterprise Application Platform)
- an enterprise service bus (JBoss ESB)
- a business process management system (jBPM)
- a business rules engine (JBoss Rules)
- support for the optional JBoss Enterprise Data Services (EDS) product.
1.8. JBoss Enterprise SOA Platform Features
- The JBoss Enterprise Service Bus (ESB)
- The ESB sends messages between services and transforms them so that they can be processed by different types of systems.
- Business Process Execution Language (BPEL)
- You can use web services to orchestrate business rules using this language. It is included with SOA for the simple execution of business process instructions.
- Java Universal Description, Discovery and Integration (jUDDI)
- This is the default service registry in SOA. It is where all the information pertaining to services on the ESB are stored.
- Smooks
- This transformation engine can be used in conjunction with SOA to process messages. It can also be used to split messages and send them to the correct destination.
- JBoss Rules
- This is the rules engine that is packaged with SOA. It can infer data from the messages it receives to determine which actions need to be performed.
1.9. Features of the JBoss Enterprise SOA Platform's JBossESB Component
- Multiple transports and protocols
- A listener-action model (so that you can loosely-couple services together)
- Content-based routing (through the JBoss Rules engine, XPath, Regex and Smooks)
- Integration with the JBoss Business Process Manager (jBPM) in order to provide service orchestration functionality
- Integration with JBoss Rules in order to provide business rules development functionality.
- Integration with a BPEL engine.
- Be configured to work with a wide variety of transport mechanisms (such as e-mail and JMS),
- Be used as a general-purpose object repository,
- Allow you to implement pluggable data transformation mechanisms,
- Support logging of interactions.
Important
org.jboss.internal.soa.esb
and org.jboss.soa.esb
. Use the contents of the org.jboss.internal.soa.esb
package sparingly because they are subject to change without notice. By contrast, everything within the org.jboss.soa.esb
package is covered by Red Hat's deprecation policy.
1.10. Task Management
1.11. Integration Use Case
1.12. Utilising the JBoss Enterprise SOA Platform in a Business Environment
Chapter 2. Introduction
2.1. Intended Audience
2.2. Aim of This Book
2.3. Back Up Your Data
Warning
2.4. Variable Name: SOA_ROOT Directory
jboss-soa-p-5
directory. In the Standalone edition, though, it is the jboss-soa-p-standalone-5
directory.
SOA_ROOT
. Substitute either jboss-soa-p-5
or jboss-soa-p-standalone-5
as appropriate whenever you see this name.
2.5. Variable Name: PROFILE
2.6. Server Profiles
Table 2.1. Server Profiles
Profile | Description |
---|---|
default | Use this profile for development and testing. This profile uses less memory than the production profile but clustering is not enabled in this mode. In addition, this profile provides more verbose logging than the "all" and "production" profiles. This verbose logging provides you with additional information, but adversely affects server performance. Unless you explicitly specify a different profile, this profile is used when the server is started. |
production | Use this profile on production servers. This profile provides clustering and maximizes performance by using more memory and providing less verbose logging and screen console output than the "all" or "default" profiles. Note that output (such as the message from the "Hello World" quick start) does not appear on the console screen in this mode. It is written to the log only. |
minimal | Enables the minimum features needed for a functioning system. No archives are deployed. No ESB or SOA features are enabled. The BPEL Engine is not available. |
standard | This provides standard functionality for testing. No web, ESB, or SOA features are enabled. The BPEL Engine is not available. |
web | The jbossweb.sar archives are deployed when this profile is run. No ESB, or SOA features are enabled. The BPEL Engine is not available. |
all | All of the pre-packaged ESB archives are deployed when this profile is run. This profile offers less performance and scalability than the "production" profile, but requires less memory to run. |
2.7. Java Virtual Machine
Chapter 3. The BPEL Engine
3.1. BPEL Engine
Note
3.2. Business Process Execution Language (BPEL)
3.3. Business Rule Orchestration
3.4. Enterprise Service Bus
3.5. Apache ODE
3.6. Process Definition
Chapter 4. An Introductory Tutorial
4.1. Running BPEL Processes on the JBoss Enterprise SOA Platform
The "BPEL ESB Hello World" quickstart demonstrates how an ESB service can directly invoke a BPEL process, provided that:
- The BPEL engine and the ESB are located in the same JVM
- The invoked BPEL process is deployed to the BPEL engine instance running on the same ESB.
4.2. Deploy the "BPEL ESB Hello World" Quickstart
Procedure 4.1. Deploy the "BPEL ESB Hello World" Quickstart
- Check that the JBoss Enterprise SOA Platform server is running.
- Navigate to the directory containing the quickstarts:
cd SOA_ROOT/samples/quickstarts/bpel_helloworld
(orchdir SOA_ROOT\samples\quickstarts\bpel_helloworld
in Microsoft Windows). - Deploy the quickstart by running
ant deploy
. - Execute the quickstart by running
ant runtest
.
This command will send the text "Hello World via ESB to BPEL" to the ESB service, which will invoke the BPEL process. This in turn will append "Hello World" to the text and echo it back until it is received by the client application.
4.3. Quickstart
SOA_ROOT/jboss-as/samples/quickstarts/
directory. Build and deploy every quickstart by using Apache Ant.
4.4. ant deploy
ant deploy
compiles a quickstart's source code in the build
directory, then generates an .ESB file (such as Quickstart_helloworld.esb
) in the server profile's deploy
directory. (Note that it generates .JAR files for BPEL quickstarts.) The server detects the presence of the new .esb archive and deploys it. In the .ESB archive is a deployment.xml file that ant deploy
uses to configure a queue.
ant deploy
also uses an XSL template to transform generic JMS queue names into the specific JMS queues needed by the target server's messaging provider. Ant selects the correct messaging provider by examining the server for a messaging provider deployment. Only JBoss Messaging, JBoss MQ, and HornetQ are detected by the build script. Other messaging providers are not supported by the quick start. Ant then puts the deployment.xml
file into the build/META-INF
directory before including it in the same .ESB archive as the rest of the quickstart.
4.5. ant runtest
ant runtest
sends an ESB-unaware "Hello World" message (which is a plain String object) to the JMS Queue (queue/quickstart_helloworld_Request_gw
). It instructs Java to run the sender class (in the case of the "Hello World" quick start, this is called org.jboss.soa.esb.samples.quickstart.helloworld.test.sendJMSMessage
). By doing so, it sends a message directly to the deployed process.
Chapter 5. Managing Processes
5.1. Deploying Processes
- Via JBoss Developer Studio
- Directly (the sample quick starts use this approach).
5.2. Deploy a Process Using JBoss Developer Studio
Prerequisites
- JBoss Developer Studio.
Procedure 5.1. Task
- Launch JBoss Developer Studio.
- Create or import the JBDS BPEL project.(In this example, we are going to import an existing project from the
SOA_ROOT/jboss-as/samples/quickstart/bpel_esb_helloworld
directory).Select the Import menu item (found in JBDS's left-side navigation panel->General->Existing Projects into Workspace->Next. - Click the Browse button.
- Navigate to the
bpel_esb_helloworld
quickstart directory.Note
Once the project has been imported, you can inspect its contents, including the BPEL process and WSDL description. - Create a server configuration for the JBoss Enterprise SOA Platform. (The Server tab should be visible in the lower region of the JBDS window. If it is not present, click Window->Show Views->Servers.)
- Right-click in the Servers view and select New->Server.
- Select the appropriate version of the JBoss Enterprise SOA Platform.
- Click Finish.
- Start the new server by right-clicking on the server in the Servers tab and selecting Start.The output from the server will be displayed in the Console tab.
- Once the server has been started, right-click on the server entry again, and select Add and Remove->bpel_esb_helloworld.
- Click Add->Finish.The project deploys to the server. (It will show up as an entry below the server in the Servers tab.)
- Test the deployed BPEL process by using the Ant script provided with the quick start sample. Right-click on the project root folder's
build.xml
file and select Run As->Ant Build.Note
It is important to select the menu item with the "...
", as this launches a dialogue box that enables you to select which Ant target you wish to utilise. - De-select the deploy target.
- Select the runtest target.
- Click the Run button.A test 'hello' message is now sent to the server, and the response is displayed in the Console tab.
- To update the BPEL process, select assignHelloMesg->Properties->Details->Expression to Variable.You can update the
concat
function's second parameter in order to perform tasks such as adding UPDATED to the text. - Save the update.
- Go to the Server view.
- Click bpel_esb_helloworld>Full Publish.The project redeploys.
- Re-run the
runtest
target within thebuild.xml
file in order to send a new request and view the new response.The response should now reflect the changes you made in the BPEL process. - Go to the Server view and expand the deployed project node.You will see that both of the deployed versions are shown. (The older version is retained as there may still be BPEL process instances using that version of the process.)
- Use the Server view's project menu and click Add and Remove to undeploy the project.
Warning
If you right-click on each of the child nodes, you will see it is also possible to undeploy the specific versions. However, if you do manually undeploy a version, any remaining active process instances for that version will be terminated. - Go to the Server menu item and stop the server.
5.3. Test a Process Using JBoss Developer Studio
Prerequisites
- JBoss Developer Studio
Procedure 5.2. Task
- Launch JBoss Developer Studio.
- Right-click on the process and select WSDL.
- Click on Web Services.
- Click on Test with Web Service Explorer.
- Launch JBoss Developer Studio.
5.4. Deploy a Process Using the Direct Approach
Procedure 5.3. Task
- Open the process' Apache Ant build script in your text editor.
- Modify it appropriately. Here is an example:
<!-- Import the base Ant build script... --> <property file="../../../install/deployment.properties" /> <property name="version" value="1" /> <property name="server.dir" value="${org.jboss.as.home}/server/${org.jboss.as.config}"/> <property name="conf.dir" value="${server.dir}/conf"/> <property name="deploy.dir" value="${server.dir}/deploy"/> <property name="server.lib.dir" value="${server.dir}/lib"/> <property name="sample.jar.name" value="${ant.project.name}-${version}.jar" /> <target name="deploy"> <echo>Deploy ${ant.project.name}</echo> <jar basedir="bpel" destfile="${deploy.dir}/${sample.jar.name}" /> </target> <target name="undeploy"> <echo>Undeploy ${ant.project.name}</echo> <delete file="${deploy.dir}/${sample.jar.name}" /> </target>
- Save the file and exit.
5.5. Some Points About Direct Deployment of Processes
- It is necessary to provide the location of the JBoss Enterprise SOA Platform Server on which the BPEL process is to be deployed. (In this example, this is achieved by referring to the
deployment.properties
file found in the installation directory. - You can take a versioned approach where multiple versions of the same BPEL process are deployed at once. The name of the
JAR
archive file containing the BPEL process and any associated artifacts will have a version number suffix. You will need to increment this suffix number manually every time you deploy a distinct version of the BPEL process.Warning
Currently, the version must be specified as a single integer number. Non-numeric values, such as those that appear in a major.minor.incremental ( Maven-style) format, trigger an exception. - You need to define the deployment target to be used to create the BPEL process archive. Do so by using the contents of the
bpel
sub-directory and store them within the JBoss Enterprise SOA Platform'sSOA_ROOT/jboss-as/server/PROFILE/deploy
directory. - Finally, you need to define the undeployment target. This is simply used to remove the BPEL process archive from the JBoss Enterprise SOA Platform's
SOA_ROOT/jboss-as/server/PROFILE/deploy
directory.
5.6. Remove a Process
Warning
Procedure 5.4. Task
- Check to see if the processes have any active process instances.
- If there are any, use the BPEL Web Console to retire them first.
- Remove the processes only when there are no longer any active process instances.
5.7. Configure and Deploy an End-Point Reference
Procedure 5.5. Task
- Create a sample end-point file:
vi SOA_ROOT/jboss-as/samples/quickstart/hello_world/bpelContent/test.endpoint
. - Add the following content to it:
# 3 minutes mex.timeout=180000
- Save the file and exit.Once deployed, the
helloworld
example will wait up to three minutes to respond. - To test this out, edit the
hello_world.bpel
file and insert await
activity before the response:<wait> <for>'PT150S'</for> </wait>
This will make it wait two minutes and thirty seconds before responding, which is thirty seconds longer than the default timeout, but still within the limits of the new timeout period specified within thetest.endpoint
file. - Save the file and exit.
- If you wish to force the timeout to occur, increase the wait duration to three minutes and thirty seconds and re-submit the test message using the
ant runtest
command.Note
The BPEL Web Console does not yet support the global configuration file, so it can only obtain the configuration data from the deployed BPEL bundle. (Specifically, it looks in the root location within the BPEL deployment unit alongside the BPEL deployment descriptor.)
5.8. Supported End-Point Reference Configuration Properties
- mex.timeout
Chapter 6. Configuring Web Services
6.1. Web Service
6.2. Web Service End-Point
6.3. Web Services Description Language (WSDL)
- location of the service
- the operations that the service supports
- the protocol bindings the service supports (SOAP, HTTP, etc)
- access procedure
6.4. Web Service Stack
6.5. Java API for XML Web Services (JAX-WS)
6.6. JAX-WS Handlers and BPEL
HandlerChain
annotation on the Java interface representing the web service. However, in the case of a process deployed to BPEL, the JAX-WS service is created dynamically upon deployment.
6.7. Configure a JAX-WS Handler for BPEL
Procedure 6.1. Task
- Navigate to where you have placed your BPEL process definition and deployment descriptor.
- Create a file called
jws_handler.xml
:vi jws_handler.xml
. - Add your configuration settings to the file. Here is an example pertaining to the
bpel_service_handler
quickstart:<handler-chains xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee"> <handler-chain> <handler> <handler-name>JAXWSHandler</handler-name> <handler-class>org.jboss.soa.bpel.examples.jaxws.JAXWSHandler</handler-class> <init-param> <param-name>TestParam</param-name> <param-value>TestValue</param-value> </init-param> </handler> </handler-chain> </handler-chains>
This file is in the standard JAX-WS handler chain configuration format. One or more handler elements can be specified, with each handler defining a name and a class. (The handler configuration can optionally provide initialization parameters that are passed to the handler implementation'sinit
method). - Save the file and exit.
Note
This mechanism only installs JAX-WS handlers on the provider web service. At present, you cannot configure JAX-WS handlers for the client end-points that are used to invoke external web services from a BPEL process.Note
To learn more, study the example of this mechanism that is provided with theservice_handler
quick start.
6.8. jws_handler.xml
jws_handler.xml
is an XML-based configuration file for the JAX-WS API.
6.9. Apache CXF
6.10. Configure Apache CXF for Use as a Server End-Point
Prerequisites
- Apache CXF
Procedure 6.2. Task
- Navigate to the directory containing the BPEL deployment descriptor.
- Create a file called
jbossws-cxf.xml
:vi jbossws-cxf.xml
- Add your configuration settings to the file. Here is an example:
<beans xmlns='http://www.springframework.org/schema/beans' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:beans='http://www.springframework.org/schema/beans' xmlns:jaxws='http://cxf.apache.org/jaxws' xsi:schemaLocation='http://cxf.apache.org/core http://cxf.apache.org/schemas/core.xsd http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd'> <bean id="UsernameTokenSign_Request" class="org.apache.cxf.ws.security.wss4j.WSS4JInInterceptor"> <constructor-arg> <map> <entry key="action" value="UsernameToken Timestamp Signature"/> <entry key="passwordType" value="PasswordDigest"/> <entry key="user" value="serverx509v1"/> <entry key="passwordCallbackClass" value="org.jboss.test.ws.jaxws.samples.wsse.ServerUsernamePasswordCallback"/> <entry key="signaturePropFile" value="etc/Server_SignVerf.properties"/> <entry key="signatureKeyIdentifier" value="DirectReference"/> </map> </constructor-arg> </bean> <bean id="UsernameTokenSign_Response" class="org.apache.cxf.ws.security.wss4j.WSS4JOutInterceptor"> <constructor-arg> <map> <entry key="action" value="UsernameToken Timestamp Signature"/> <entry key="passwordType" value="PasswordText"/> <entry key="user" value="serverx509v1"/> <entry key="passwordCallbackClass" value="org.jboss.test.ws.jaxws.samples.wsse.ServerUsernamePasswordCallback"/> <entry key="signaturePropFile" value="etc/Server_Decrypt.properties"/> <entry key="signatureKeyIdentifier" value="DirectReference"/> <entry key="signatureParts" value="{Element}{http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd}Timestamp;{Element}{http://schemas.xmlsoap.org/soap/envelope/}Body"/> </map> </constructor-arg> </bean> <jaxws:endpoint id='SecureHelloWorldWS' address='http://@jboss.bind.address@:8080/Quickstart_bpel_secure_serviceWS' implementor='@provider@'> <jaxws:inInterceptors> <ref bean="UsernameTokenSign_Request"/> <bean class="org.apache.cxf.binding.soap.saaj.SAAJInInterceptor"/> </jaxws:inInterceptors> <jaxws:outInterceptors> <ref bean="UsernameTokenSign_Response"/> <bean class="org.apache.cxf.binding.soap.saaj.SAAJOutInterceptor"/> </jaxws:outInterceptors> </jaxws:endpoint> </beans>
This example code configures the web service to use the usernametoken
in conjunction with digital signature authentication.Note
Thejaxws:endpoint
element has an attribute called implementor. This attribute defines the Java class implementing the JAX-WS service. The BPEL Console dynamically creates this class automatically. Therefore, it is important that the attribute is set to the value@provider@
or it will not work. - Save the file and exit.
6.11. jbossws-cxf.xml
jbossws-cxf.xml
is a user-created XML-based configuration file is a user-created file. It should be placed in a project's /WEB-INF/
folder alongside the deployment descriptor. Use it to configure Apache CXF as a server end-point. It is also used by jbossws-cxf when deploying a web service based on the use of JAX-WS annotations.
6.12. Deployment Descriptor
6.13. jbossws-cxf-portname_local_part.xml
jbossws-cxf-{portname_local_part}.xml
, whereby portname_local_part
represents the local part of the port name of the web service being invoked.
6.14. Example of WSDL for an Apache CXF Client End-Point
<definitions name='SecureHelloWorldWSService' targetNamespace='http://secure_invoke/helloworld' .... > <portType name='SecureHelloWorld'> ... </portType> <service name='SecureHelloWorldWSService'> <port name='SecureHelloWorldPort' ... > ... </port> </service> </definitions>
6.15. Configure Apache CXF for Use as a Client End-Point
Prerequisites
- Apache CXF
Procedure 6.3. Task
- To edit the sample
jbossws-cxf-SecureHelloWorldPort.xml
CXF configuration file, issue this command:vi SOA_ROOT/jboss-as/samples/quickstarts/bpel_secure_invoke/bpelContent/jbossws-cxf-SecureHelloWorldPort.xml
- The configuration information contained within this file is for the CXF bus. Edit the file like this:
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:cxf="http://cxf.apache.org/core" xmlns:wsa="http://cxf.apache.org/ws/addressing" xmlns:http="http://cxf.apache.org/transports/http/configuration" xmlns:wsrm-policy="http://schemas.xmlsoap.org/ws/2005/02/rm/policy" xmlns:wsrm-mgr="http://cxf.apache.org/ws/rm/manager" xmlns:beans='http://www.springframework.org/schema/beans' xmlns:jaxws='http://cxf.apache.org/jaxws' xmlns:ns1='http://secure_invoke/helloworld' xsi:schemaLocation=" http://cxf.apache.org/core http://cxf.apache.org/schemas/core.xsd http://cxf.apache.org/transports/http/configuration http://cxf.apache.org/schemas/configuration/http-conf.xsd http://schemas.xmlsoap.org/ws/2005/02/rm/policy http://schemas.xmlsoap.org/ws/2005/02/rm/wsrm-policy.xsd http://cxf.apache.org/ws/rm/manager http://cxf.apache.org/schemas/configuration/wsrm-manager.xsd http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd"> <bean id="UsernameTokenSign_Request" class="org.apache.cxf.ws.security.wss4j.WSS4JOutInterceptor" > <constructor-arg> <map> <entry key="action" value="UsernameToken Timestamp Signature"/> <entry key="passwordType" value="PasswordDigest"/> <entry key="user" value="clientx509v1"/> <entry key="passwordCallbackClass" value="org.jboss.test.ws.jaxws.samples.wsse.ClientUsernamePasswordCallback"/> <entry key="signaturePropFile" value="etc/Client_Sign.properties"/> <entry key="signatureKeyIdentifier" value="DirectReference"/> <entry key="signatureParts" value="{Element}{http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd}Timestamp;{Element}{http://schemas.xmlsoap.org/soap/envelope/}Body"/> </map> </constructor-arg> </bean> <bean id="UsernameTokenSign_Response" class="org.apache.cxf.ws.security.wss4j.WSS4JInInterceptor" > <constructor-arg> <map> <entry key="action" value="UsernameToken Timestamp Signature"/> <entry key="passwordType" value="PasswordText"/> <entry key="user" value="serverx509v1"/> <entry key="passwordCallbackClass" value="org.jboss.test.ws.jaxws.samples.wsse.ClientUsernamePasswordCallback"/> <entry key="signaturePropFile" value="etc/Client_Encrypt.properties"/> <entry key="signatureKeyIdentifier" value="DirectReference"/> </map> </constructor-arg> </bean> <cxf:bus> <cxf:outInterceptors> <ref bean="UsernameTokenSign_Request"/> <bean class="org.apache.cxf.binding.soap.saaj.SAAJOutInterceptor"/> </cxf:outInterceptors> <cxf:inInterceptors> <ref bean="UsernameTokenSign_Response"/> <bean class="org.apache.cxf.binding.soap.saaj.SAAJInInterceptor"/> </cxf:inInterceptors> </cxf:bus> </beans>
These settings configure the web service client to utilise the username token and digital signature authentication. - Save the file and exit.
6.16. BPEL Processes and Web Services
6.17. Display a WSDL
Procedure 6.4. Task
- Look up the end-point URL of the service which has the "?wsdl" suffix.
- Once it is displayed, the <soap:address> will, by default, become associated with the server's "host bind" address.
Note
This address is defined in the ${jboss.bind.address} property.
6.18. Configure a BPEL Client End-Point to Invoke a Secure External Web Service
Procedure 6.5. Task
- Launch your test editor and create a new file.
- Add the relative locations of the key-store and trust-store files.
- Save the file as jboss-wsse-client.xml in the top level directory alongside your BPEL process and exit.
Note
For more information, see the secure_invoke_native quickstart.
6.19. Configure a BPEL Server End-Point to Provide a Secure Web Service
Procedure 6.6. Task
- Launch your test editor and create a new file.
- Add the relative locations of the key-store and trust-store files.
- Save the file as jboss-wsse-server.xml in the top level directory alongside your BPEL process and exit.
Note
For more information, see the secure_service_native quickstart.
Chapter 7. Advanced BPEL Engine Integration
7.1. Bi-directional Loose Coupling
7.2. Enterprise Service Bus
7.3. Use the BPELInvoke ESB Action
Prerequisites
- The BPEL Engine must be installed in the same Java virtual machine as the ESB
- The requested process must have been deployed to the local BPEL Engine.
Procedure 7.1. Task
- Open a
jboss-esb.xml
file in your text editor. - Add the the BPELInvoke ESB action.The following example shows the action being used together with the
bpel_esb_helloworld
quickstart:<action name="action2" class="org.jboss.soa.esb.actions.bpel.BPELInvoke"> <property name="service" value="{http://www.jboss.org/bpel/examples/wsdl}HelloService"/> <property name="port" value="HelloPort" /> <property name="operation" value="hello" /> <property name="requestPartName" value="TestPart" /> <property name="responsePartName" value="TestPart" /> </action>
- Save the file and exit.
7.4. BPELInvoke ESB Action Class
org.jboss.soa.esb.actions.bpel.BPELInvoke
) can be used to call upon the BPEL Engine from within ESB services.
7.5. BPELInvoke ESB Action Class Properties
Table 7.1. Properties
Property | Explanation |
---|---|
service |
This property is mandatory. It defines the service name registered in the WSDL which is associated with the deployed BPEL process.
|
port |
This property is optional. It defines the name of the port associated with the deployed BPEL process that is registered in the WSDL. This parameter is only required if port-specific end-point configuration information has been registered as part of the BPEL process deployment.
|
operation |
This property is mandatory. It represents the WSDL operation being invoked.
|
requestPartName |
Use this optional property to define the WSDL message part to which the inbound ESB message content should be mapped. Only use this property where the ESB message does not already represent a multi-part message.
|
responsePartName |
Use this optional property to extract the content of a response multi-part WSDL message and place it in the ESB message being passed to the next action in the pipeline. (If this property is not defined, the complete multi-part message value will be placed in the ESB message.)
|
abortOnFault |
Use this optional property to indicate whether a fault generated during the invocation of a BPEL process should be treated as a message (when the value of this property is false) or as an exception that will abort the ESB service. The default value is true, which aborts the service.
|
Table 7.2. Properties
Item | Explanation |
---|---|
DOM |
If the message content is a DOM document or element, it can be used as the complete multi-part message or as the content of a message part. Use the requestPartName property to define it.
|
Java String |
If the message content is a string representation of an XML document, the requestPartName is optional. If not specified, the document must represent the multi-part message.
If the message content is a string that does not represent an XML document, the requestPartName must be specified.
|
<message> <TestPart> Hello World </TestPart> </message>
TestPart
. This part is a text node, in this case called Hello World
. (However it could also have been an element representing the root node of a more complex XML value.)
7.6. BPELInvoke and the Action Pipeline
7.7. Action Pipeline
Chapter 8. BPEL and REST
8.1. BPEL Console RESTful Services
Table 8.1. BPEL Console RESTful Services
Method
|
Path
|
Description
|
Consumes
|
Produces
|
---|---|---|---|---|
Server Info (General REST server information)
|
GET
|
/gwt-console-server/rs/server/status
|
*/*
|
application/json
|
-
|
GET
|
/gwt-console-server/rs/server/resources/{project}
|
*/*
|
text/html
|
Process Management(Process related data.)
|
GET
|
/gwt-console-server/rs/process/definitions
|
*/*
|
application/json
|
-
|
GET
|
/gwt-console-server/rs/process/definition/{id}/instances
|
*/*
|
application/json
|
-
|
GET
|
/gwt-console-server/rs/process/instance/{id}/dataset
|
*/*
|
text/xml
|
-
|
POST
|
/gwt-console-server/rs/process/instance/{id}/end/{result}
|
*/*
|
application/json
|
-
|
GET
|
/gwt-console-server/rs/process/definition/{id}/image
|
*/*
|
image/*
|
-
|
GET
|
/gwt-console-server/rs/process/definition/{id}/image/{instance}
|
*/*
|
image/*
|
Process Engine(Process runtime state)
|
GET
|
/gwt-console-server/rs/engine/deployments
|
*/*
|
application/json
|
Process History(Process History Service)
|
GET
|
/gwt-console-server/rs//history/definition/{id}/instances
|
*/*
|
applications/json
|
-
|
GET
|
/gwt-console-server/rs//history/definitions
|
*/*
|
application/json
|
-
|
GET
|
/gwt-console-server/rs//history/definition/{id}/instances
|
*/*
|
application/json
|
-
|
GET
|
/gwt-console-server/rs//history/instance/{id}/activities
|
*/*
|
application/json
|
-
|
GET
|
/gwt-console-server/rs//history/instance/{id}/events
|
*/*
|
application/json
|
-
|
GET
|
/gwt-console-server/rs//history/definition/{id}/instances/completed
|
*/*
|
application/json
|
-
|
GET
|
/gwt-console-server/rs//history/definition/{id}/instances/failed
|
*/*
|
application/json
|
-
|
GET
|
/gwt-console-server/rs//history/definition/{id}/instances/terminated
|
*/*
|
application/json
|
-
|
GET
|
/gwt-console-server/rs//history/definition/{id}/instances/chart/completed
|
*/*
|
application/json
|
-
|
GET
|
/gwt-console-server/rs//history/definition/{id}/instances/chart/failed
|
*/*
|
application/json
|
Chapter 9. Fault Handling
9.1. BPELInvoke Fault Handling
9.2. BPELInvoke Fault Handling Reference
Loan Fault
quickstart:
<action name="action2" class="org.jboss.soa.esb.actions.bpel.BPELInvoke"> <property name="service" value="{http://example.com/loan-approval/wsdl/}loanService"/> <property name="operation" value="request" /> <property name="abortOnFault" value="true" /> </action>
- Fault code:
javax.xml.namespace.QName
ESB message body part:org.jboss.soa.esb.message.fault.detail.code
This body part identifies the specific WSDL fault returned by the BPEL process.Warning
The version of the QName used by the JBoss Enterprise SOA Platform server is found in thelib/endorsed/stax-api.jar
file. (If this file is absent, you will encounter a class version exception.) - Fault code (as a textual representation of the QName).ESB message body part:
org.jboss.soa.bpel.message.fault.detail.code
This body part returns the textual representation of the fault code's QName. This representation is of the form{namespace}localpart
. (To convert it back into a QName, use thejavax.xml.namespace.QName.valueOf(String)
method.) - Fault detailsESB message body part:
org.jboss.soa.esb.message.fault.detail.detail
This body part contains the textual representation of the message content associated with the fault.
Chapter 10. SAML Support
10.1. Security Assertion Markup Language (SAML)
10.2. PicketLink
10.3. SAML Token
10.4. SAML Support in BPEL
<action name="action2" class="org.jboss.soa.esb.actions.bpel.BPELInvoke"> <property name="service" value="{http://simple_invoke/helloworld}HelloHeaderWSService"/> <property name="operation" value="sayHi" /> <property name="requestPartName" value="sayHello" /> <property name="responsePartName" value="sayHelloResponse" /> <property name="requestSAMLPartName" value="Security" /> </action>
requestSAMLPartName
identifies the name of a message part. You must define this part as a WS-Security element:
<part name="Security" element="wsse:Security" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" />
Appendix A. Revision History
Revision History | |||
---|---|---|---|
Revision 5.3.1-93.400 | 2013-10-31 | Rüdiger Landmann | |
| |||
Revision 5.3.1-93 | Tue Feb 05 2013 | David Le Sage | |
|