[riftsaw-commits] riftsaw SVN: r1075 - in trunk/docs/docbook: gettingstartedguide/src/main and 5 other directories.

Author: objectiser Date: 2010-11-02 06:32:39 -0400 (Tue, 02 Nov 2010) New Revision: 1075 Added: trunk/docs/docbook/gettingstartedguide/src/main/en-US/ trunk/docs/docbook/gettingstartedguide/src/main/en-US/images/ trunk/docs/docbook/gettingstartedguide/src/main/en-US/master.xml trunk/docs/docbook/gettingstartedguide/src/main/en-US/module/ trunk/docs/docbook/gettingstartedguide/src/main/en-US/xslt/ trunk/docs/docbook/userguide/src/main/en-US/ trunk/docs/docbook/userguide/src/main/en-US/images/ trunk/docs/docbook/userguide/src/main/en-US/master.xml trunk/docs/docbook/userguide/src/main/en-US/module/ trunk/docs/docbook/userguide/src/main/en-US/module/admin.xml trunk/docs/docbook/userguide/src/main/en-US/module/esb.xml trunk/docs/docbook/userguide/src/main/en-US/xslt/ Removed: trunk/docs/docbook/gettingstartedguide/src/main/images/ trunk/docs/docbook/gettingstartedguide/src/main/master.xml trunk/docs/docbook/gettingstartedguide/src/main/module/ trunk/docs/docbook/gettingstartedguide/src/main/xslt/ trunk/docs/docbook/userguide/src/main/en-US/module/admin.xml trunk/docs/docbook/userguide/src/main/en-US/module/esb.xml trunk/docs/docbook/userguide/src/main/images/ trunk/docs/docbook/userguide/src/main/master.xml trunk/docs/docbook/userguide/src/main/xslt/ Modified: trunk/docs/docbook/gettingstartedguide/pom.xml trunk/docs/docbook/userguide/pom.xml Log: RIFTSAW-310 - updated docbook plugin to support maven3. Modified: trunk/docs/docbook/gettingstartedguide/pom.xml =================================================================== --- trunk/docs/docbook/gettingstartedguide/pom.xml 2010-10-29 00:17:19 UTC (rev 1074) +++ trunk/docs/docbook/gettingstartedguide/pom.xml 2010-11-02 10:32:39 UTC (rev 1075) @@ -23,7 +23,7 @@ <plugin> <groupId>org.jboss.maven.plugins</groupId> <artifactId>maven-jdocbook-plugin</artifactId> - <version>2.1.2</version> + <version>2.2.3</version> <extensions>true</extensions> <executions> <execution> @@ -54,13 +54,13 @@ <imageResource> <directory>${basedir}/src/main</directory> <includes> - <include>images/**/*</include> + <include>**/images/**/*</include> </includes> </imageResource> <formats> <format> <formatName>pdf</formatName> - <stylesheetResource>file:///${basedir}/src/main/xslt/pdf.xsl</stylesheetResource> + <stylesheetResource>file:///${basedir}/src/main/en-US/xslt/pdf.xsl</stylesheetResource> <finalName>GettingStartedGuide.pdf</finalName> </format> <format> Copied: trunk/docs/docbook/gettingstartedguide/src/main/en-US/images (from rev 1038, trunk/docs/docbook/gettingstartedguide/src/main/images) Copied: trunk/docs/docbook/gettingstartedguide/src/main/en-US/master.xml (from rev 1038, trunk/docs/docbook/gettingstartedguide/src/main/master.xml) =================================================================== --- trunk/docs/docbook/gettingstartedguide/src/main/en-US/master.xml (rev 0) +++ trunk/docs/docbook/gettingstartedguide/src/main/en-US/master.xml 2010-11-02 10:32:39 UTC (rev 1075) @@ -0,0 +1,16 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % RH-ENTITIES SYSTEM "Common_Config/rh-entities.ent"> +]> + +<book lang="en"> + <bookinfo> + <title>RiftSaw 2.2.0-SNAPSHOT</title> + <subtitle>Getting Started Guide</subtitle> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/author_group.xml"/> + </bookinfo> + + <toc/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/installation.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/examples.xml"/> +</book> Copied: trunk/docs/docbook/gettingstartedguide/src/main/en-US/module (from rev 1038, trunk/docs/docbook/gettingstartedguide/src/main/module) Copied: trunk/docs/docbook/gettingstartedguide/src/main/en-US/xslt (from rev 1038, trunk/docs/docbook/gettingstartedguide/src/main/xslt) Deleted: trunk/docs/docbook/gettingstartedguide/src/main/master.xml =================================================================== --- trunk/docs/docbook/gettingstartedguide/src/main/master.xml 2010-10-29 00:17:19 UTC (rev 1074) +++ trunk/docs/docbook/gettingstartedguide/src/main/master.xml 2010-11-02 10:32:39 UTC (rev 1075) @@ -1,16 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % RH-ENTITIES SYSTEM "Common_Config/rh-entities.ent"> -]> - -<book lang="en"> - <bookinfo> - <title>RiftSaw 2.2.0-SNAPSHOT</title> - <subtitle>Getting Started Guide</subtitle> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/author_group.xml"/> - </bookinfo> - - <toc/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/installation.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/examples.xml"/> -</book> Modified: trunk/docs/docbook/userguide/pom.xml =================================================================== --- trunk/docs/docbook/userguide/pom.xml 2010-10-29 00:17:19 UTC (rev 1074) +++ trunk/docs/docbook/userguide/pom.xml 2010-11-02 10:32:39 UTC (rev 1075) @@ -23,7 +23,7 @@ <plugin> <groupId>org.jboss.maven.plugins</groupId> <artifactId>maven-jdocbook-plugin</artifactId> - <version>2.1.2</version> + <version>2.2.3</version> <extensions>true</extensions> <executions> <execution> @@ -54,13 +54,13 @@ <imageResource> <directory>${basedir}/src/main</directory> <includes> - <include>images/**/*</include> + <include>**/images/**/*</include> </includes> </imageResource> <formats> <format> <formatName>pdf</formatName> - <stylesheetResource>file:///${basedir}/src/main/xslt/pdf.xsl</stylesheetResource> + <stylesheetResource>file:///${basedir}/src/main/en-US/xslt/pdf.xsl</stylesheetResource> <finalName>UserGuide.pdf</finalName> </format> <format> Copied: trunk/docs/docbook/userguide/src/main/en-US/images (from rev 1038, trunk/docs/docbook/userguide/src/main/images) Copied: trunk/docs/docbook/userguide/src/main/en-US/master.xml (from rev 1038, trunk/docs/docbook/userguide/src/main/master.xml) =================================================================== --- trunk/docs/docbook/userguide/src/main/en-US/master.xml (rev 0) +++ trunk/docs/docbook/userguide/src/main/en-US/master.xml 2010-11-02 10:32:39 UTC (rev 1075) @@ -0,0 +1,22 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % RH-ENTITIES SYSTEM "Common_Config/rh-entities.ent"> +]> + +<book lang="en"> + <bookinfo> + <title>RiftSaw 2.1.0-SNAPSHOT</title> + <subtitle>User Guide</subtitle> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/author_group.xml"/> + </bookinfo> + + <toc/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/introduction.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/admin.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/deploy.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/wsconfig.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/uddi.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/esb.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/clustering.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/db.xml"/> +</book> Copied: trunk/docs/docbook/userguide/src/main/en-US/module (from rev 1038, trunk/docs/docbook/userguide/src/main/module) Deleted: trunk/docs/docbook/userguide/src/main/en-US/module/admin.xml =================================================================== --- trunk/docs/docbook/userguide/src/main/module/admin.xml 2010-10-13 04:42:02 UTC (rev 1038) +++ trunk/docs/docbook/userguide/src/main/en-US/module/admin.xml 2010-11-02 10:32:39 UTC (rev 1075) @@ -1,215 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -]> -<chapter id="admin"> - <title>Administration</title> - - <section> - <title>Overview</title> - - <para> - This section describes the administration capabilities associated with RiftSaw. - </para> - - </section> - - <section> - <title>BPEL Console</title> - - <section> - <title>Overview</title> - <para> - This section provides an overview of the BPEL Console. - The console provides the ability to view: - </para> - - <itemizedlist> - <listitem> - The process definitions deployed to the BPEL engine - </listitem> - <listitem> - The process instances executing in the BPEL engine - </listitem> - </itemizedlist> - - </section> - - <section> - <title>Logging in</title> - - <para> - The BPEL console can be located using the URL: - <ulink url="http://localhost:8080/bpel-console">http://localhost:8080/bpel-console</ulink>. - </para> - - <para> - The first screen that is presented is the login screen: - </para> - - <imageobject> - <imagedata fileref="images/BPELConsole-login.png" align="center" width="6in" /> - </imageobject> - - <para> - The default username is <emphasis>admin</emphasis> with password - <emphasis>password</emphasis>. - </para> - - <para> - The Access Control mechanism used by the admin console is configured - in the <filename>$deployFolder/bpel-console/bpel-identity.sar/META-INF/jboss-service.xml</filename>. - The JAAS login module is initially set to use a property file based - access mechanism, but can be replaced to use any appropriate alternative - implementation. - </para> - - <para> - The users for the default mechanism are configured in the property file - <filename>$deployFolder/bpel-console/bpel-identity.sar/bpel-users.properties</filename>. - The entries in this file represent <emphasis>username=password</emphasis>. - </para> - - <para> - The user roles for the default mechanism are configured in the property file - <filename>$deployFolder/bpel-console/bpel-identity.sar/bpel-roles.properties</filename>. - The entries in this file represent <emphasis>username=role</emphasis>. The - only role of interest currently is <emphasis>administrator</emphasis>. - </para> - </section> - - <section> - <title>Deployed Process Definitions</title> - - <para> - Once logged in, the 'Process Overview' tab shows the currently deployed - BPEL processes and their versions. - </para> - - <imageobject> - <imagedata fileref="images/BPELConsole-processes.png" align="center" width="6in" /> - </imageobject> - - </section> - - <section> - <title>Process Instances</title> - - <para> - When a process definition is selected, the list of active process instances for - that process definition (and version) will be displayed in the right hand - panel. - </para> - - <imageobject> - <imagedata fileref="images/BPELConsole-process-instances.png" align="center" width="6in" /> - </imageobject> - - <para> - When a process instance is selected, its details will be displayed in the lower - <emphasis>Execution Details</emphasis> - window. The <emphasis>Instance Data</emphasis> button will also become enabled, allowing - further detail about the process to be displayed. - </para> - - <imageobject> - <imagedata fileref="images/BPELConsole-process-instance-data.png" align="center" width="6in" /> - </imageobject> - - </section> - - <section> - <title>Retiring and Reactivating Process Definitions</title> - - <para> - When a process definition is initially deployed (i.e. the first version of the process), - it automatically becomes the active process definition. If that BPEL process definition - is subsequently change and redeployed, then the previous version is <emphasis>retired</emphasis>, - and the new version becomes the <emphasis>active</emphasis> version. - </para> - - <para> - The only difference between an <emphasis>active</emphasis> and <emphasis>retired</emphasis> - process definition is that a <emphasis>retired</emphasis> process definition can no longer - create new process instances. However if there are current process instances associated - with the <emphasis>retired</emphasis> process definition version, then these will continue - to execute. - </para> - - <para> - On some occasions, the administrator may wish to change which version of a process definition - is considered the <emphasis>active</emphasis> version. Or they may simply want to - <emphasis>retire</emphasis> the currently active process definition, so that no more - process instances can be created, only allowing the already running process instances to - continue until completed. - </para> - - <para> - To change the status of a process definition, the administrator should select the - <emphasis>Runtime</emphasis> tab from the lefthand panel, and then select the - <emphasis>Deployments</emphasis> option. This will show the process definitions, their - versions and their current status (active or retired). - </para> - - <imageobject> - <imagedata fileref="images/ActivateRetire.png" align="center" width="6in" /> - </imageobject> - - <para> - To change a particular version from <emphasis>retired</emphasis> to <emphasis>active</emphasis>, - simply select the <emphasis>retired</emphasis> version and press the <emphasis>Activate</emphasis> - button in the bottom right. - </para> - - <para> - To retire a currently active process definition, simply select the particular version and - then press the <emphasis>Retire</emphasis> button in the bottom right. - </para> - - </section> - - </section> - - <section> - <title>BPEL Properties</title> - - <para> - When RiftSaw has been installed within the JBossAS environment, there is a property file - located at <filename>${JBossAS}/server/default/deploy/riftsaw.sar/bpel.properties</filename>. - </para> - - <para> - This property file contains a number of properties that are specific to ODE, and if interested - in these properties, then you should refer to the ODE documentation. Only one point to note, - the name of the property in this file maybe prefixed with <emphasis>bpel.</emphasis>, however - in the ODE documentation the prefix would be <emphasis>ode.</emphasis>. - </para> - - <para> - This section will present the properties that are specific to RiftSaw. - </para> - - <table frame="all"> - <title>RiftSaw specific properties</title> - <tr> - <td>bpel.uddi.*</td> - <td>These properties relate to the UDDI support, which is discussed in a subsequent chapter.</td> - </tr> - <tr> - <td>bpel.jaxws.client.initializer.impl</td> - <td>This property is automatically set upon installation, based on the JAXWS stack being used. - This value should not be changed.</td> - </tr> - <tr> - <td>bpel.ws.stableInterface (default false)</td> - <td>This property determines whether the Web Service interface, associated with a BPEL process, - will be updated when a new version of the BPEL process is deployed. The benefit of setting this - to <emphasis>false</emphasis> is that changes to the WSDL will be made active with the BPEL - process. However the issue is that during the transition between the interfaces, the web service - will momentarily be unavailble - which may cause heavily used services to reject requests. By - setting this value to <emphasis>true</emphasis>, then the web service will remain available - while the BPEL process is updated, however any changes in the WSDL will not be made available.</td> - </tr> - </table> - </section> - -</chapter> Copied: trunk/docs/docbook/userguide/src/main/en-US/module/admin.xml (from rev 1073, trunk/docs/docbook/userguide/src/main/module/admin.xml) =================================================================== --- trunk/docs/docbook/userguide/src/main/en-US/module/admin.xml (rev 0) +++ trunk/docs/docbook/userguide/src/main/en-US/module/admin.xml 2010-11-02 10:32:39 UTC (rev 1075) @@ -0,0 +1,222 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> +<chapter id="admin"> + <title>Administration</title> + + <section> + <title>Overview</title> + + <para> + This section describes the administration capabilities associated with RiftSaw. + </para> + + </section> + + <section> + <title>BPEL Console</title> + + <section> + <title>Overview</title> + <para> + This section provides an overview of the BPEL Console. + The console provides the ability to view: + </para> + + <itemizedlist> + <listitem> + The process definitions deployed to the BPEL engine + </listitem> + <listitem> + The process instances executing in the BPEL engine + </listitem> + </itemizedlist> + + </section> + + <section> + <title>Logging in</title> + + <para> + The BPEL console can be located using the URL: + <ulink url="http://localhost:8080/bpel-console">http://localhost:8080/bpel-console</ulink>. + </para> + + <para> + The first screen that is presented is the login screen: + </para> + + <imageobject> + <imagedata fileref="images/BPELConsole-login.png" align="center" width="6in" /> + </imageobject> + + <para> + The default username is <emphasis>admin</emphasis> with password + <emphasis>password</emphasis>. + </para> + + <para> + The Access Control mechanism used by the admin console is configured + in the <filename>$deployFolder/bpel-console/bpel-identity.sar/META-INF/jboss-service.xml</filename>. + The JAAS login module is initially set to use a property file based + access mechanism, but can be replaced to use any appropriate alternative + implementation. + </para> + + <para> + The users for the default mechanism are configured in the property file + <filename>$deployFolder/bpel-console/bpel-identity.sar/bpel-users.properties</filename>. + The entries in this file represent <emphasis>username=password</emphasis>. + </para> + + <para> + The user roles for the default mechanism are configured in the property file + <filename>$deployFolder/bpel-console/bpel-identity.sar/bpel-roles.properties</filename>. + The entries in this file represent <emphasis>username=role</emphasis>. The + only role of interest currently is <emphasis>administrator</emphasis>. + </para> + </section> + + <section> + <title>Deployed Process Definitions</title> + + <para> + Once logged in, the 'Process Overview' tab shows the currently deployed + BPEL processes and their versions. + </para> + + <imageobject> + <imagedata fileref="images/BPELConsole-processes.png" align="center" width="6in" /> + </imageobject> + + </section> + + <section> + <title>Process Instances</title> + + <para> + When a process definition is selected, the list of active process instances for + that process definition (and version) will be displayed in the right hand + panel. + </para> + + <imageobject> + <imagedata fileref="images/BPELConsole-process-instances.png" align="center" width="6in" /> + </imageobject> + + <para> + When a process instance is selected, its details will be displayed in the lower + <emphasis>Execution Details</emphasis> + window. The <emphasis>Instance Data</emphasis> button will also become enabled, allowing + further detail about the process to be displayed. + </para> + + <imageobject> + <imagedata fileref="images/BPELConsole-process-instance-data.png" align="center" width="6in" /> + </imageobject> + + </section> + + <section> + <title>Retiring and Reactivating Process Definitions</title> + + <para> + When a process definition is initially deployed (i.e. the first version of the process), + it automatically becomes the active process definition. If that BPEL process definition + is subsequently change and redeployed, then the previous version is <emphasis>retired</emphasis>, + and the new version becomes the <emphasis>active</emphasis> version. + </para> + + <para> + The only difference between an <emphasis>active</emphasis> and <emphasis>retired</emphasis> + process definition is that a <emphasis>retired</emphasis> process definition can no longer + create new process instances. However if there are current process instances associated + with the <emphasis>retired</emphasis> process definition version, then these will continue + to execute. + </para> + + <para> + On some occasions, the administrator may wish to change which version of a process definition + is considered the <emphasis>active</emphasis> version. Or they may simply want to + <emphasis>retire</emphasis> the currently active process definition, so that no more + process instances can be created, only allowing the already running process instances to + continue until completed. + </para> + + <para> + To change the status of a process definition, the administrator should select the + <emphasis>Runtime</emphasis> tab from the lefthand panel, and then select the + <emphasis>Deployments</emphasis> option. This will show the process definitions, their + versions and their current status (active or retired). + </para> + + <imageobject> + <imagedata fileref="images/ActivateRetire.png" align="center" width="6in" /> + </imageobject> + + <para> + To change a particular version from <emphasis>retired</emphasis> to <emphasis>active</emphasis>, + simply select the <emphasis>retired</emphasis> version and press the <emphasis>Activate</emphasis> + button in the bottom right. + </para> + + <para> + To retire a currently active process definition, simply select the particular version and + then press the <emphasis>Retire</emphasis> button in the bottom right. + </para> + + <para> + <note> + If you deploy a process definition version into RiftSaw server, the previous version of that process definition will go to 'retire' process automatically. + Also please noted that if you undeploy a process, the associated endpoints get deactivated only if it doesn't have any previous version of that process. + </note> + </para> + + </section> + + </section> + + <section> + <title>BPEL Properties</title> + + <para> + When RiftSaw has been installed within the JBossAS environment, there is a property file + located at <filename>${JBossAS}/server/default/deploy/riftsaw.sar/bpel.properties</filename>. + </para> + + <para> + This property file contains a number of properties that are specific to ODE, and if interested + in these properties, then you should refer to the ODE documentation. Only one point to note, + the name of the property in this file maybe prefixed with <emphasis>bpel.</emphasis>, however + in the ODE documentation the prefix would be <emphasis>ode.</emphasis>. + </para> + + <para> + This section will present the properties that are specific to RiftSaw. + </para> + + <table frame="all"> + <title>RiftSaw specific properties</title> + <tr> + <td>bpel.uddi.*</td> + <td>These properties relate to the UDDI support, which is discussed in a subsequent chapter.</td> + </tr> + <tr> + <td>bpel.jaxws.client.initializer.impl</td> + <td>This property is automatically set upon installation, based on the JAXWS stack being used. + This value should not be changed.</td> + </tr> + <tr> + <td>bpel.ws.stableInterface (default false)</td> + <td>This property determines whether the Web Service interface, associated with a BPEL process, + will be updated when a new version of the BPEL process is deployed. The benefit of setting this + to <emphasis>false</emphasis> is that changes to the WSDL will be made active with the BPEL + process. However the issue is that during the transition between the interfaces, the web service + will momentarily be unavailble - which may cause heavily used services to reject requests. By + setting this value to <emphasis>true</emphasis>, then the web service will remain available + while the BPEL process is updated, however any changes in the WSDL will not be made available.</td> + </tr> + </table> + </section> + +</chapter> Deleted: trunk/docs/docbook/userguide/src/main/en-US/module/esb.xml =================================================================== --- trunk/docs/docbook/userguide/src/main/module/esb.xml 2010-10-13 04:42:02 UTC (rev 1038) +++ trunk/docs/docbook/userguide/src/main/en-US/module/esb.xml 2010-11-02 10:32:39 UTC (rev 1075) @@ -1,268 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -]> -<chapter id="esb"> - <title>JBoss ESB Integration</title> - - <section> - <title>Overview</title> - - <para> - This section outlines the support provided for the direct integration between RiftSaw - and JBossESB. - </para> - - <para> - Bi-directional loose integration is available through the use of web services. - For example, an ESB action may invoke a BPEL process running within RiftSaw - by invoking the appropriate web service represented by a WSDL interface. - Similarly, a BPEL process can invoke an ESB managed service that is capable - of presenting itself as a web service. - </para> - - <para> - However this section will describe how integration between RiftSaw and JBossESB actions - can be achieved without the use of web services (i.e. WSDL and SOAP). - </para> - </section> - - <section> - <title>Using the <emphasis>BPELInvoke</emphasis> ESB action</title> - - <para> - The <emphasis>BPELInvoke</emphasis> ESB action can be used within a - <emphasis>jboss-esb.xml</emphasis> to request an invocation on a BPEL - process running inside RiftSaw. The only constraints are that RiftSaw is - installed within the same Java VM and that the requested BPEL process must - have been deployed to the local RiftSaw engine. - </para> - - <para> - The following example illustrates the <emphasis>BPELInvoke</emphasis> ESB action - being used as part of the <emphasis>bpel_helloworld</emphasis> sample. - </para> - - <informalexample> - <programlisting role="XML" ><![CDATA[ -<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> - ]]></programlisting> - </informalexample> - - <para> - The ESB action class is <emphasis>org.jboss.soa.esb.actions.bpel.BPELInvoke</emphasis>. - </para> - - <para> - The properties for this ESB action are: - </para> - - <itemizedlist> - <listitem> - <para> - service - </para> - <para> - This property is mandatory, and defines the service name registered in the WSDL associated - with the deployed BPEL process. - </para> - </listitem> - <listitem> - <para> - port - </para> - <para> - This property is optional, and defines the port name registered in the WSDL associated - with the deployed BPEL process. This parameter is only required if port specific endpoint - configuration information has been registered as part of the BPEL process deployment. - </para> - </listitem> - <listitem> - <para> - operation - </para> - <para> - This property is mandatory, and represents the WSDL operation that is being invoked. - </para> - </listitem> - <listitem> - <para> - requestPartName - </para> - <para> - This optional property can be used to define the WSDL message part that the inbound - ESB message content should be mapped to. This property should be used where the - ESB message does not already represent a multi-part message. - </para> - </listitem> - <listitem> - <para> - responsePartName - </para> - <para> - This optional property can be used to extract the content of a response multi-part - WSDL message, and place this in the ESB message being passed to the next ESB - action in the pipeline. If this property is not defined, then the complete multi-part - message value will be placed in the ESB message. - </para> - </listitem> - <listitem> - <para> - abortOnFault - </para> - <para> - This optional property can be used 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', causing the ESB service to abort. - </para> - </listitem> - </itemizedlist> - - <para> - This ESB action supports inbound messages with content defined as either: - </para> - - <itemizedlist> - <listitem> - <para>DOM</para> - <para> - If the message content is a DOM document or element, then this can either be - used as the complete multi-part message, or as the content of a message part - defined using the <emphasis>requestPartName</emphasis> property. - </para> - <para> - If the message content is a DOM text node, then this can ONLY be used if a - multi-part name has been defined in the <emphasis>requestPartName</emphasis> - property. - </para> - </listitem> - <listitem> - <para>Java String</para> - <para> - If the message content is a string representation of an XML document, then - the <emphasis>requestPartName</emphasis> is optional. If not specified, then - the document must represent the multipart message. - </para> - <para> - If the message content is a string that does not represent an XML document, then - the <emphasis>requestPartName</emphasis> must be specified. - </para> - </listitem> - </itemizedlist> - - <para> - When the message content represents the complete multipart message, this must be defined as - a top level element (whose name is irrelevant) with immediate child elements that - represent each of the multiple parts of the message. Each of these elements must then - have a single element/node, that represents the value of the named part. - </para> - - <informalexample> - <programlisting role="XML" ><![CDATA[ -<message> - <TestPart> - Hello World - </TestPart> -</message> - ]]></programlisting> - </informalexample> - - <para> - This shows an example of a multipart message structure. The top element (i.e. <emphasis>message</emphasis>) - is unimportant. The elements at the next level represent the part names - in this case - there is only a single part, with name <emphasis>TestPart</emphasis>. The value of this - part is defined as a text node, with value "Hello World". However this could have been an - element representing the root node of a more complex XML value. - </para> - - <para> - The following diagram illustrates the inter-relationship of the JBossESB bpel_helloworld - quickstart and the RiftSaw BPEL process configuration files. - </para> - - <imageobject> - <imagedata fileref="images/BPELInvokeRelationship.jpg" align="center" width="6in" /> - </imageobject> - - <section> - <title>Fault Handling</title> - - <para> - The normal response from a WSDL operation will be returned from the <emphasis>BPELInvoke</emphasis> - ESB action as a normal message and placed on the action pipeline ready for processing by the next - ESB action, or alternatively if no further actions have been defined, then returned back to the - service client. - </para> - - <para> - Faults, associated with a WSDL operation, are handled slightly differently. Depending on configuration - it is possible to receive the fault as an ESB message or for the fault to be treated as an - exception which aborts the action pipeline. The configuration property used to determine which - behaviour is used is called <emphasis>abortOnFault</emphasis>. The default value for this property - is "true". As an example, from the loan fault quickstart sample, - </para> - - <informalexample> - <programlisting role="XML" ><![CDATA[ -<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> - ]]></programlisting> - </informalexample> - - <para> - A WSDL fault has two relevant pieces of information, the fault type (or code) and the fault details. - These are both returned in specific parts of ESB message's body. - </para> - - <orderedlist> - <listitem> - Fault code (as javax.xml.namespace.QName) - <para> - ESB message body part: <emphasis>org.jboss.soa.esb.message.fault.detail.code</emphasis> - </para> - <para> - This body part identifies the specific WSDL fault returned by the BPEL process, associated with - the WSDL operation that was invoked. - </para> - <warning> - The specific version of the QName used by the JBoss server is from the stax-api.jar found in the - server's lib/endorsed directory. If the client does not also include this jar in a folder that is - in its endorsed directories, then a class version exception will occur when this ESB message - part is accessed. - </warning> - </listitem> - <listitem> - Fault code (as textual representation of QName) - <para> - ESB message body part: <emphasis>org.jboss.soa.bpel.message.fault.detail.code</emphasis> - </para> - <para> - This body part will return the textual representation of the QName for the fault code. The textual - representation is of the form "{namespace}localpart" and can be converted back into a QName using the - <emphasis>javax.xml.namespace.QName.valueOf(String)</emphasis> method. - </para> - </listitem> - <listitem> - Fault details - <para> - ESB message body part: <emphasis>org.jboss.soa.esb.message.fault.detail.detail</emphasis> - </para> - <para> - This body part will contain the textual representation of the message content associated - with the fault. - </para> - </listitem> - </orderedlist> - </section> - </section> - -</chapter> Copied: trunk/docs/docbook/userguide/src/main/en-US/module/esb.xml (from rev 1046, trunk/docs/docbook/userguide/src/main/module/esb.xml) =================================================================== --- trunk/docs/docbook/userguide/src/main/en-US/module/esb.xml (rev 0) +++ trunk/docs/docbook/userguide/src/main/en-US/module/esb.xml 2010-11-02 10:32:39 UTC (rev 1075) @@ -0,0 +1,303 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> +<chapter id="esb"> + <title>JBoss ESB Integration</title> + + <section> + <title>Overview</title> + + <para> + This section outlines the support provided for the direct integration between RiftSaw + and JBossESB. + </para> + + <para> + Bi-directional loose integration is available through the use of web services. + For example, an ESB action may invoke a BPEL process running within RiftSaw + by invoking the appropriate web service represented by a WSDL interface. + Similarly, a BPEL process can invoke an ESB managed service that is capable + of presenting itself as a web service. + </para> + + <para> + However this section will describe how integration between RiftSaw and JBossESB actions + can be achieved without the use of web services (i.e. WSDL and SOAP). + </para> + </section> + + <section> + <title>Using the <emphasis>BPELInvoke</emphasis> ESB action</title> + + <para> + The <emphasis>BPELInvoke</emphasis> ESB action can be used within a + <emphasis>jboss-esb.xml</emphasis> to request an invocation on a BPEL + process running inside RiftSaw. The only constraints are that RiftSaw is + installed within the same Java VM and that the requested BPEL process must + have been deployed to the local RiftSaw engine. + </para> + + <para> + The following example illustrates the <emphasis>BPELInvoke</emphasis> ESB action + being used as part of the <emphasis>bpel_helloworld</emphasis> sample. + </para> + + <informalexample> + <programlisting role="XML" ><![CDATA[ +<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> + ]]></programlisting> + </informalexample> + + <para> + The ESB action class is <emphasis>org.jboss.soa.esb.actions.bpel.BPELInvoke</emphasis>. + </para> + + <para> + The properties for this ESB action are: + </para> + + <itemizedlist> + <listitem> + <para> + service + </para> + <para> + This property is mandatory, and defines the service name registered in the WSDL associated + with the deployed BPEL process. + </para> + </listitem> + <listitem> + <para> + port + </para> + <para> + This property is optional, and defines the port name registered in the WSDL associated + with the deployed BPEL process. This parameter is only required if port specific endpoint + configuration information has been registered as part of the BPEL process deployment. + </para> + </listitem> + <listitem> + <para> + operation + </para> + <para> + This property is mandatory, and represents the WSDL operation that is being invoked. + </para> + </listitem> + <listitem> + <para> + requestPartName + </para> + <para> + This optional property can be used to define the WSDL message part that the inbound + ESB message content should be mapped to. This property should be used where the + ESB message does not already represent a multi-part message. + </para> + </listitem> + <listitem> + <para> + responsePartName + </para> + <para> + This optional property can be used to extract the content of a response multi-part + WSDL message, and place this in the ESB message being passed to the next ESB + action in the pipeline. If this property is not defined, then the complete multi-part + message value will be placed in the ESB message. + </para> + </listitem> + <listitem> + <para> + abortOnFault + </para> + <para> + This optional property can be used 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', causing the ESB service to abort. + </para> + </listitem> + </itemizedlist> + + <para> + This ESB action supports inbound messages with content defined as either: + </para> + + <itemizedlist> + <listitem> + <para>DOM</para> + <para> + If the message content is a DOM document or element, then this can either be + used as the complete multi-part message, or as the content of a message part + defined using the <emphasis>requestPartName</emphasis> property. + </para> + <para> + If the message content is a DOM text node, then this can ONLY be used if a + multi-part name has been defined in the <emphasis>requestPartName</emphasis> + property. + </para> + </listitem> + <listitem> + <para>Java String</para> + <para> + If the message content is a string representation of an XML document, then + the <emphasis>requestPartName</emphasis> is optional. If not specified, then + the document must represent the multipart message. + </para> + <para> + If the message content is a string that does not represent an XML document, then + the <emphasis>requestPartName</emphasis> must be specified. + </para> + </listitem> + </itemizedlist> + + <para> + When the message content represents the complete multipart message, this must be defined as + a top level element (whose name is irrelevant) with immediate child elements that + represent each of the multiple parts of the message. Each of these elements must then + have a single element/node, that represents the value of the named part. + </para> + + <informalexample> + <programlisting role="XML" ><![CDATA[ +<message> + <TestPart> + Hello World + </TestPart> +</message> + ]]></programlisting> + </informalexample> + + <para> + This shows an example of a multipart message structure. The top element (i.e. <emphasis>message</emphasis>) + is unimportant. The elements at the next level represent the part names - in this case + there is only a single part, with name <emphasis>TestPart</emphasis>. The value of this + part is defined as a text node, with value "Hello World". However this could have been an + element representing the root node of a more complex XML value. + </para> + + <para> + The following diagram illustrates the inter-relationship of the JBossESB bpel_helloworld + quickstart and the RiftSaw BPEL process configuration files. + </para> + + <imageobject> + <imagedata fileref="images/BPELInvokeRelationship.jpg" align="center" width="6in" /> + </imageobject> + + <section> + <title>Fault Handling</title> + + <para> + The normal response from a WSDL operation will be returned from the <emphasis>BPELInvoke</emphasis> + ESB action as a normal message and placed on the action pipeline ready for processing by the next + ESB action, or alternatively if no further actions have been defined, then returned back to the + service client. + </para> + + <para> + Faults, associated with a WSDL operation, are handled slightly differently. Depending on configuration + it is possible to receive the fault as an ESB message or for the fault to be treated as an + exception which aborts the action pipeline. The configuration property used to determine which + behaviour is used is called <emphasis>abortOnFault</emphasis>. The default value for this property + is "true". As an example, from the loan fault quickstart sample, + </para> + + <informalexample> + <programlisting role="XML" ><![CDATA[ +<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> + ]]></programlisting> + </informalexample> + + <para> + A WSDL fault has two relevant pieces of information, the fault type (or code) and the fault details. + These are both returned in specific parts of ESB message's body. + </para> + + <orderedlist> + <listitem> + Fault code (as javax.xml.namespace.QName) + <para> + ESB message body part: <emphasis>org.jboss.soa.esb.message.fault.detail.code</emphasis> + </para> + <para> + This body part identifies the specific WSDL fault returned by the BPEL process, associated with + the WSDL operation that was invoked. + </para> + <warning> + The specific version of the QName used by the JBoss server is from the stax-api.jar found in the + server's lib/endorsed directory. If the client does not also include this jar in a folder that is + in its endorsed directories, then a class version exception will occur when this ESB message + part is accessed. + </warning> + </listitem> + <listitem> + Fault code (as textual representation of QName) + <para> + ESB message body part: <emphasis>org.jboss.soa.bpel.message.fault.detail.code</emphasis> + </para> + <para> + This body part will return the textual representation of the QName for the fault code. The textual + representation is of the form "{namespace}localpart" and can be converted back into a QName using the + <emphasis>javax.xml.namespace.QName.valueOf(String)</emphasis> method. + </para> + </listitem> + <listitem> + Fault details + <para> + ESB message body part: <emphasis>org.jboss.soa.esb.message.fault.detail.detail</emphasis> + </para> + <para> + This body part will contain the textual representation of the message content associated + with the fault. + </para> + </listitem> + </orderedlist> + </section> + + <section> + <title>SAML Support</title> + + <para> + If the ESB service uses PicketLink to obtain a SAML token, then this assertion + can be passed to the invoked BPEL process, using the <emphasis>requestSAMLPartName</emphasis> + property. + </para> + + <informalexample> + <programlisting role="XML" ><![CDATA[ +<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> + ]]></programlisting> + </informalexample> + + <para> + The part name identified by the <emphasis>requestSAMLPartName</emphasis> must be + defined as a WS-Security Security element, e.g. + </para> + + <informalexample> + <programlisting role="XML" ><![CDATA[ +<part name="Security" element="wsse:Security" + xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-... /> + ]]></programlisting> + </informalexample> + + </section> + </section> + +</chapter> Copied: trunk/docs/docbook/userguide/src/main/en-US/xslt (from rev 1038, trunk/docs/docbook/userguide/src/main/xslt) Deleted: trunk/docs/docbook/userguide/src/main/master.xml =================================================================== --- trunk/docs/docbook/userguide/src/main/master.xml 2010-10-29 00:17:19 UTC (rev 1074) +++ trunk/docs/docbook/userguide/src/main/master.xml 2010-11-02 10:32:39 UTC (rev 1075) @@ -1,22 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % RH-ENTITIES SYSTEM "Common_Config/rh-entities.ent"> -]> - -<book lang="en"> - <bookinfo> - <title>RiftSaw 2.1.0-SNAPSHOT</title> - <subtitle>User Guide</subtitle> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/author_group.xml"/> - </bookinfo> - - <toc/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/introduction.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/admin.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/deploy.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/wsconfig.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/uddi.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/esb.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/clustering.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/db.xml"/> -</book>