[jboss-svn-commits] JBossWS SVN: r875 - in branches/jbossws-1.0/docs/user-guide/project/en: . images modules modules/wsbpel
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Thu Aug 31 15:05:37 EDT 2006
Author: alex.guizar at jboss.com
Date: 2006-08-31 15:05:33 -0400 (Thu, 31 Aug 2006)
New Revision: 875
Added:
branches/jbossws-1.0/docs/user-guide/project/en/images/wsbpel-hello.png
branches/jbossws-1.0/docs/user-guide/project/en/modules/wsbpel/
branches/jbossws-1.0/docs/user-guide/project/en/modules/wsbpel/wsbpel.xml
Removed:
branches/jbossws-1.0/docs/user-guide/project/en/modules/wsbpel/wsbpel.xml
Modified:
branches/jbossws-1.0/docs/user-guide/project/en/master.template
Log:
Merged JBWS-867, r835,838,853
Copied: branches/jbossws-1.0/docs/user-guide/project/en/images/wsbpel-hello.png (from rev 835, tags/jbossws-1.0.3.GA/docs/user-guide/project/en/images/wsbpel-hello.png)
Modified: branches/jbossws-1.0/docs/user-guide/project/en/master.template
===================================================================
--- branches/jbossws-1.0/docs/user-guide/project/en/master.template 2006-08-31 15:31:21 UTC (rev 874)
+++ branches/jbossws-1.0/docs/user-guide/project/en/master.template 2006-08-31 19:05:33 UTC (rev 875)
@@ -44,12 +44,12 @@
<!ENTITY ch-wssecurity SYSTEM "modules/wssecurity/wssecurity.xml">
<!ENTITY ch-wsaddressing SYSTEM "modules/wsaddressing/wsaddressing.xml">
<!ENTITY ch-wseventing SYSTEM "modules/wseventing/wseventing.xml">
+<!ENTITY ch-wsbpel SYSTEM "modules/wsbpel/wsbpel.xml">
<!ENTITY ch-wstransaction SYSTEM "modules/wstransaction/wstransaction.xml">
<!ENTITY ch-xmlregistry SYSTEM "modules/xmlregistry/xmlregistry.xml">
<!ENTITY appendix-a SYSTEM "modules/appendix-a.xml">
]>
-
<book lang="en">
<bookinfo>
@@ -78,6 +78,7 @@
<para>Web Service Lead - Thomas Diesler</para>
<para>WS-Security, WSTools - Jason Greene</para>
<para>WS-Eventing, Standards - Heiko Braun</para>
+ <para>WS-BPEL - Alejandro Guizar</para>
</preface>
@@ -97,8 +98,9 @@
&ch-wssecurity;
&ch-wsaddressing;
&ch-wseventing;
+ &ch-wsbpel;
&ch-wstransaction;
&ch-xmlregistry;
&appendix-a;
-</book>
+</book>
\ No newline at end of file
Copied: branches/jbossws-1.0/docs/user-guide/project/en/modules/wsbpel (from rev 835, tags/jbossws-1.0.3.GA/docs/user-guide/project/en/modules/wsbpel)
Deleted: branches/jbossws-1.0/docs/user-guide/project/en/modules/wsbpel/wsbpel.xml
===================================================================
--- tags/jbossws-1.0.3.GA/docs/user-guide/project/en/modules/wsbpel/wsbpel.xml 2006-08-25 22:19:51 UTC (rev 835)
+++ branches/jbossws-1.0/docs/user-guide/project/en/modules/wsbpel/wsbpel.xml 2006-08-31 19:05:33 UTC (rev 875)
@@ -1,179 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-
-<!-- $Id$ -->
-
-<chapter id="wsbpel">
-
- <title>WS-BPEL</title>
-
- <para>This chapter is dedicated to show how to use <ulink
- url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsbpel">WS-BPEL</ulink> to
- specify business process behavior based on web services.</para>
-
- <section id="wsbpel.spec">
-
- <title>Specification</title>
-
- <para>Originally authored by a small charter of vendors in the software industry, WS-BPEL is
- under standardization at OASIS. The latest approved document as of August 22, 2006 is:</para>
-
- <para><ulink url="http://tinyurl.com/nw54b">Web Services Business Process Execution Language
- 2.0 Committee Draft</ulink></para>
-
- <para>In the Java space, JSR-207 aims at defining metadata, interfaces and a runtime model
- that enable business processes to be easily and rapidly implemented using Java and deployed
- in J2EE containers. The request submission is:</para>
-
- <para><ulink url="http://jcp.org/en/jsr/detail?id=207">JSR 207: Process Definition for Java
- </ulink></para>
-
- <para>The provided foundation would support tasks commonly encountered when programming
- business processes such as parallel execution and asynchronous messaging.</para>
-
- </section>
-
- <section id="wsbpel.define">
-
- <title>Defining a business process</title>
-
- <para>Business processes model the stateful behavior of a participant in a business interaction.
- In WS-BPEL, a process exports and imports functionality to/from participants using web
- service interfaces exclusively.</para>
-
- <para>At its simplest, WS-BPEL can be used as a scripting language for web services. Consider
- a trivial endpoint that receives a person name, composes a greeting phrase and then replies
- with the greeting.</para>
-
- <para>The flow diagram below represents the processing logic.</para>
-
- <figure id="tutorial.hello.graph">
- <title>Graphical representation of the Hello World process</title>
- <mediaobject>
- <imageobject><imagedata align="center" fileref="images/wsbpel-hello.png"/></imageobject>
- </mediaobject>
- </figure>
-
- <para>The WSDL interface our endpoint presents to the world goes like this:</para>
-
- <programlisting><definitions targetNamespace="http://jbpm.org/examples/hello"
- xmlns="http://schemas.xmlsoap.org/wsdl/"
- xmlns:tns="http://jbpm.org/examples/hello"
- xmlns:xsd="http://www.w3.org/2001/XMLSchema">
-
- <!-- <emphasis role="bold">carries the name of a person</emphasis> -->
- <message name="nameMessage">
- <part name="name" type="xsd:string"/>
- </message>
-
- <!-- <emphasis role="bold">carries the greeting</emphasis> -->
- <message name="greetingMessage">
- <part name="greeting" type="xsd:string"/>
- </message>
-
- <!-- <emphasis role="bold">describes the interface presented to callers</emphasis> -->
- <portType name="helloPT">
- <operation name="sayHello">
- <input message="tns:nameMessage"/>
- <output message="tns:greetingMessage"/>
- </operation>
- </portType>
-
-</definitions></programlisting>
-
- <para>You already know how to implement this in Java. Let's jump to the BPEL way. The document
- that defines our business process appears next. There are three major sections in it.</para>
-
- <itemizedlist>
-
- <listitem><para>The <partnerLinks> section lists the parties that interact with the
- process in the course of greeting the world. The single partner link shown here
- corresponds to the agent sending the person name (caller).</para></listitem>
-
- <listitem><para>The <variables> section defines the data items held by the process
- between message exchanges. The ability to mantain data effectively makes the backed endpoint
- stateful. The state includes received and sent messages as well as intermediate data used
- in business logic.</para></listitem>
-
- <listitem><para>The rest of the document describes the normal behavior for handling a
- greeting request. BPEL also provides the means to perform activities in response to faults.
- Our trivial endpoint does not require them, tough.</para></listitem>
-
- </itemizedlist>
-
- <programlisting><process name="helloWorld"
- targetNamespace="http://jbpm.org/examples/hello"
- xmlns="http://schemas.xmlsoap.org/ws/2003/03/business-process/"
- xmlns:tns="http://jbpm.org/examples/hello"
- xmlns:bpel="http://schemas.xmlsoap.org/ws/2003/03/business-process/"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://schemas.xmlsoap.org/ws/2003/03/business-process/
- http://schemas.xmlsoap.org/ws/2003/03/business-process/">
-
- <partnerLinks>
- <!-- <emphasis role="bold">establishes the relationship with the caller agent</emphasis> -->
- <partnerLink name="caller" partnerLinkType="tns:helloPLT"
- myRole="service"/>
- </partnerLinks>
-
- <variables>
- <!-- <emphasis role="bold">holds the incoming message</emphasis> -->
- <variable name="request" messageType="tns:nameMessage"/>
- <!-- <emphasis role="bold">holds the outgoing message</emphasis> -->
- <variable name="response" messageType="tns:greetingMessage"/>
- </variables>
-
- <sequence>
-
- <!-- <emphasis role="bold">receive the name of a person</emphasis> -->
- <receive partnerLink="caller" portType="tns:helloPT"
- operation="sayHello" variable="request"
- createInstance="true"/>
-
- <!-- <emphasis role="bold">compose a greeting phrase</emphasis> -->
- <assign>
- <copy>
- <from expression="concat('Hello, ',
- bpel:getVariableData('request', 'name'),
- '!')"/>
- <to variable="response" part="greeting"/>
- </copy>
- </assign>
-
- <!-- <emphasis role="bold">reply with the greeting</emphasis> -->
- <reply partnerLink="caller" portType="tns:helloPT"
- operation="sayHello" variable="response"/>
-
- </sequence>
-
-</process></programlisting>
-
- <para>Notice the <literal>caller</literal> partner link references a <literal>partnerLinkType
- </literal> artifact not introduced so far. Partner link types are WSDL extensibility elements
- that represent the relationship between two services. WS-BPEL uses them as the glue between
- the process and its partner services.</para>
-
- <para>In order for the process definition to be complete, we must add the partner link type to
- the WSDL document presented earlier.</para>
-
- <programlisting><definitions targetNamespace="http://jbpm.org/examples/hello"
- ...
- xmlns:plt="http://schemas.xmlsoap.org/ws/2003/05/partner-link/">
-
- <!-- <emphasis role="bold">characterizes the relationship between the greeting process
- and its caller</emphasis> -->
- <plt:partnerLinkType name="helloPLT">
- <plt:role name="service">
- <plt:portType name="tns:helloPT"/>
- </plt:role>
- </plt:partnerLinkType>
- </programlisting>
-
- </section>
-
- <section id="wsbpel.deploy">
-
- <title>Deploying a business process</title>
-
- </section>
-
-</chapter>
\ No newline at end of file
Copied: branches/jbossws-1.0/docs/user-guide/project/en/modules/wsbpel/wsbpel.xml (from rev 835, tags/jbossws-1.0.3.GA/docs/user-guide/project/en/modules/wsbpel/wsbpel.xml)
===================================================================
--- tags/jbossws-1.0.3.GA/docs/user-guide/project/en/modules/wsbpel/wsbpel.xml 2006-08-25 22:19:51 UTC (rev 835)
+++ branches/jbossws-1.0/docs/user-guide/project/en/modules/wsbpel/wsbpel.xml 2006-08-31 19:05:33 UTC (rev 875)
@@ -0,0 +1,329 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!-- $Id$ -->
+
+<chapter id="wsbpel">
+
+ <title>WS-BPEL</title>
+
+ <para>This chapter is dedicated to show how to use <ulink
+ url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsbpel">WS-BPEL</ulink> to
+ specify business process behavior based on web services.</para>
+
+ <section id="wsbpel.spec">
+
+ <title>Specification</title>
+
+ <para>Originally authored by a reduced vendor charter, WS-BPEL is currently under
+ standardization at OASIS. The latest approved document as of August 22, 2006 is:</para>
+
+ <para><ulink url="http://tinyurl.com/nw54b">Web Services Business Process Execution Language
+ 2.0 Committee Draft</ulink></para>
+
+ <para>In the Java space, JSR-207 aims at defining metadata, interfaces and a runtime model
+ that enable business processes to be easily and rapidly implemented using Java and deployed
+ in J2EE containers. The request submission is:</para>
+
+ <para><ulink url="http://jcp.org/en/jsr/detail?id=207">JSR 207: Process Definition for Java
+ </ulink></para>
+
+ <para>The provided foundation would support tasks commonly encountered when programming
+ business processes such as parallel execution and asynchronous messaging.</para>
+
+ </section>
+
+ <section id="wsbpel.definition">
+
+ <title>Defining a business process</title>
+
+ <para>Business processes model the stateful behavior of a participant in a business interaction.
+ In WS-BPEL, a process exports and imports functionality to/from participants using web
+ service interfaces exclusively.</para>
+
+ <para>At its simplest, WS-BPEL can be used as a scripting language for web services. Consider
+ a trivial endpoint that receives a person name, composes a greeting phrase and then replies
+ with the greeting.</para>
+
+ <para>The flow diagram below represents the processing logic.</para>
+
+ <figure id="tutorial.hello.graph">
+ <title>Graphical representation of the Hello World process</title>
+ <mediaobject>
+ <imageobject><imagedata align="center" fileref="images/wsbpel-hello.png"/></imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>The interface our endpoint presents to the world appears in the following WSDL document.
+ Observe no binding or service elements are present. A WS-BPEL process is defined in terms
+ of the interfaces (message and port type elements) of the participants, not their possible
+ deployments.</para>
+
+ <programlisting><definitions targetNamespace="http://jbpm.org/examples/hello"
+ xmlns="http://schemas.xmlsoap.org/wsdl/"
+ xmlns:tns="http://jbpm.org/examples/hello"
+ xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+
+ <!-- <emphasis role="bold">carries the name of a person</emphasis> -->
+ <message name="nameMessage">
+ <part name="name" type="xsd:string"/>
+ </message>
+
+ <!-- <emphasis role="bold">carries the greeting</emphasis> -->
+ <message name="greetingMessage">
+ <part name="greeting" type="xsd:string"/>
+ </message>
+
+ <!-- <emphasis role="bold">describes the interface presented to callers</emphasis> -->
+ <portType name="helloPT">
+ <operation name="sayHello">
+ <input message="tns:nameMessage"/>
+ <output message="tns:greetingMessage"/>
+ </operation>
+ </portType>
+
+</definitions></programlisting>
+
+ <para>You already know how to implement this in Java. Let's jump to the BPEL way. The document
+ that defines our business process appears next. There are three major sections in it.</para>
+
+ <itemizedlist>
+
+ <listitem><para>The <partnerLinks> section lists the parties that interact with the
+ process in the course of greeting the world. The single partner link shown here
+ corresponds to the agent sending the person name (caller).</para></listitem>
+
+ <listitem><para>The <variables> section defines the data items held by the process
+ between message exchanges. The ability to mantain data effectively makes the service
+ provided by the process stateful. The state includes received and sent messages as well as
+ intermediate data used in business logic.</para></listitem>
+
+ <listitem><para>The rest of the document describes the normal activities for handling a
+ greeting request. BPEL also provides the means to perform activities in response to faults.
+ Our trivial endpoint does not require them, tough.</para></listitem>
+
+ </itemizedlist>
+
+ <programlisting><process name="helloWorld"
+ targetNamespace="http://jbpm.org/examples/hello"
+ xmlns="http://schemas.xmlsoap.org/ws/2003/03/business-process/"
+ xmlns:tns="http://jbpm.org/examples/hello"
+ xmlns:bpel="http://schemas.xmlsoap.org/ws/2003/03/business-process/"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://schemas.xmlsoap.org/ws/2003/03/business-process/
+ http://schemas.xmlsoap.org/ws/2003/03/business-process/">
+
+ <partnerLinks>
+ <!-- <emphasis role="bold">establishes the relationship with the caller agent</emphasis> -->
+ <partnerLink name="caller" partnerLinkType="tns:helloPLT"
+ myRole="service"/>
+ </partnerLinks>
+
+ <variables>
+ <!-- <emphasis role="bold">holds the incoming message</emphasis> -->
+ <variable name="request" messageType="tns:nameMessage"/>
+ <!-- <emphasis role="bold">holds the outgoing message</emphasis> -->
+ <variable name="response" messageType="tns:greetingMessage"/>
+ </variables>
+
+ <sequence>
+
+ <!-- <emphasis role="bold">receive the name of a person</emphasis> -->
+ <receive partnerLink="caller" portType="tns:helloPT"
+ operation="sayHello" variable="request"
+ createInstance="true"/>
+
+ <!-- <emphasis role="bold">compose a greeting phrase</emphasis> -->
+ <assign>
+ <copy>
+ <from expression="concat('Hello, ',
+ bpel:getVariableData('request', 'name'),
+ '!')"/>
+ <to variable="response" part="greeting"/>
+ </copy>
+ </assign>
+
+ <!-- <emphasis role="bold">reply with the greeting</emphasis> -->
+ <reply partnerLink="caller" portType="tns:helloPT"
+ operation="sayHello" variable="response"/>
+
+ </sequence>
+
+</process></programlisting>
+
+ <para>Notice the <literal>caller</literal> partner link references a <literal>partnerLinkType
+ </literal> artifact not introduced so far. Partner link types are WSDL extensibility elements
+ that represent the relationship between two services. WS-BPEL uses them as the glue between
+ the process and its partner services.</para>
+
+ <para>In order for the process definition to be complete, we must add the partner link type to
+ the WSDL document presented earlier.</para>
+
+ <programlisting><definitions targetNamespace="http://jbpm.org/examples/hello"
+ ...
+ xmlns:plt="http://schemas.xmlsoap.org/ws/2003/05/partner-link/">
+
+ <!-- <emphasis role="bold">characterizes the relationship between the greeting process and its caller</emphasis> -->
+ <plt:partnerLinkType name="helloPLT">
+ <plt:role name="service">
+ <plt:portType name="tns:helloPT"/>
+ </plt:role>
+ </plt:partnerLinkType>
+
+</definitions></programlisting>
+
+ </section>
+
+ <section id="wsbpel.database">
+
+ <title>Storing the process definition in the jBPM database</title>
+
+ <para>In the domain of business processes, traceability is important. Process engines are
+ expected to maintain not only the current state of each process instance, but also the
+ history of performed activities and updated variables.</para>
+
+ <para>To provide these features, the JBoss BPEL implementation builds on <ulink
+ url="http://www.jboss.com/products/jbpm">JBoss jBPM</ulink>. The Graph Oriented Programming
+ (<ulink url="http://jbpm.org/gop">GOP</ulink>) foundation in jBPM allows for storing past
+ and present graph state in a database.</para>
+
+ <para>Installing the jBPM service in JBoss AS is a prerrequisite. Refer to the jBPM BPEL
+ <ulink url="http://docs.jboss.com/jbpm/bpel/getstarted.html#getstarted.setup">user guide
+ </ulink> for details.</para>
+
+ <note><para>The jBPM service comes with a preconfigured Hypersonic database, useful for
+ development purposes. In production, you can switch to the database of your choice.</para>
+ </note>
+
+ <para>Before the process can be enacted, its definition must be stored in the jBPM database.
+ To do so, package your BPEL process and related WSDL interfaces in an archive. Afterwards,
+ submit the archive to the jBPM service.</para>
+
+ <programlisting><![CDATA[<jar destfile="${build.dir}/${app.name}.par">
+ <fileset dir="${bpel.dir}" />
+ <zipfileset dir="${resources.dir}"
+ prefix="META-INF"
+ includes="bpel-definition.xml" />
+</jar>
+
+<get dest="${build.dir}/deploy-def.html"
+ src="http://localhost:8080/jbpm/deploy?archive=file://${build.dir}/${app.name}.par" />]]></programlisting>
+
+ <para>The file <literal>bpel-definition.xml</literal> tells the location of the BPEL and WSDL
+ documents inside the archive.</para>
+
+ <programlisting><![CDATA[<bpelDefinition location="hello.bpel" xmlns="http://jbpm.org/bpel">
+
+ <!-- makes WSDL interface elements available to the process -->
+ <imports>
+ <wsdl location="hello.wsdl" />
+ </imports>
+
+</bpelDefinition>]]></programlisting>
+
+ <tip><para>The definition descriptor can also reference external documents.</para></tip>
+
+ </section>
+
+ <section id="wsbpel.artifacts">
+
+ <title id="wsbpel.artifacts.title">Generating the required artifacts</title>
+
+ <para>After the process definition is stored in the database, deploying a WS-BPEL process is
+ similar to deploying a JSR-109 endpoint starting with WSDL.</para>
+
+ <para>The definition of a WS-BPEL process only includes the port types of the participants, as
+ mentioned in the previous section. On the other hand, a JSR-109 deployment requires the
+ presence of binding and service elements. JBoss BPEL supplies a tool that generates the SOAP
+ 1.1 binding and service elements required for deploying the web service provided by the
+ process.</para>
+
+ <programlisting><![CDATA[<taskdef name="servicegen" classname="org.jbpm.bpel.ant.ServiceGeneratorTask">
+ <classpath>
+ <pathelement location="${template.dir}/config" />
+ <pathelement location="${jbpm.bpel.home}/build/jbpm-bpel-${jbpm.bpel.version}.jar" />
+ <fileset dir="${jbpm.bpel.home}/lib" includes="**/*.jar" />
+ </classpath>
+</taskdef>
+
+<!-- generate binding and service elements -->
+<servicegen processfile="${build.dir}/${app.name}.par" outputdir="${web.dir}/wsdl" />]]></programlisting>
+
+ <para>The generated WSDL can be passed to <literal>wstools</literal>. Use the following
+ configuration.</para>
+
+ <programlisting><![CDATA[<configuration xmlns="http://www.jboss.org/jbossws-tools">
+ <global>
+ <package-namespace package="org.jbpm.bpel.tutorial.hello"
+ namespace="http://jbpm.org/examples/hello" />
+ </global>
+ <wsdl-java file="src/main/resources/WEB-INF/wsdl/service.wsdl">
+ <mapping file="jaxrpc-mapping.xml" />
+ </wsdl-java>
+</configuration>]]></programlisting>
+
+ <note>
+
+ <para>JBoss BPEL is agnostic to the Java mapping artifacts that <literal>wstools</literal>
+ produces. Keep in mind that variables in a BPEL process are defined in terms of XML types
+ and WSDL messages. JBoss BPEL extracts XML content from SOAP messages and puts it in process
+ variables. No need to perform expensive Java binding.</para>
+
+ <para>Nevertheless, the Java mapping artifacts still must be present for the JSR-109
+ deployment to be valid.</para>
+
+ </note>
+
+ </section>
+
+ <section id="wsbpel.config">
+
+ <title>Configuring the port component</title>
+
+ <para>Similar to the Addressing and Security components, JBoss BPEL uses <link
+ linkend="handlers">JAX-RPC handlers</link> to extract XML content from SOAP messages.</para>
+
+ <programlisting><![CDATA[<handler>
+
+ <handler-name>callerHandler</handler-name>
+ <handler-class>org.jbpm.bpel.integration.server.SoapHandler</handler-class>
+
+ <init-param>
+ <description>partner link associated to the enclosing port</description>
+ <param-name>partnerLinkHandle</param-name>
+ <param-value>caller</param-value>
+ </init-param>
+
+</handler>]]></programlisting>
+
+ <para>A separate descriptor, <literal>bpel-application.xml</literal>, specifies the name of
+ the process definition previously stored in the jBPM database.</para>
+
+ <programlisting><bpelApplication name="helloWorld" xmlns="http://jbpm.org/bpel" /></programlisting>
+
+ </section>
+
+ <section id="wsbpel.client">
+
+ <title>Consuming the published web service</title>
+
+ <para>No special configuration is needed on the client side. You consume a service provided by
+ a WS-BPEL process the same way you consume any other service.</para>
+
+ <para>You can reuse the Java mapping artifacts produced in <link linkend="wsbpel.artifacts"
+ endterm="wsbpel.artifacts.title" /> to develop a <link linkend="jsr109-clients">JSR-109 client
+ </link>.</para>
+
+ <programlisting><![CDATA[InitialContext ctx = getInitialContext();
+// lookup service interface in environment context
+service = (HelloWorldService) ctx.lookup("java:comp/env/service/Hello");
+
+// obtain dynamic proxy for web service port
+HelloPT proxy = service.getCallerPort();
+// use proxy as local java object
+String greeting = proxy.sayHello("Popeye");
+// check popeye is greeted properly
+assertEquals("Hello, Popeye!", greeting);]]></programlisting>
+
+ </section>
+
+</chapter>
\ No newline at end of file
More information about the jboss-svn-commits
mailing list