RiftSaw Deployment Mechanism

Version 3

    This section describes how the RiftSaw deployment mechanism works, and how it differs from the approach used in Apache ODE.



    BPEL Deployment Unit


    The first place to start is the BPEL deployment unit. This is common to both RiftSaw and ODE in structure, with the only difference being the name of the deployment descriptor.


    In Apache ODE, they use the file name deploy.xml to contain the XML based deployment descriptor. As RiftSaw is deploying the BPEL processes into a JEE container, it was felt that this filename was too generic, in an environment where there are many technologies that use a deployment descriptor.


    Therefore RiftSaw uses the slightly different filename bpel-deploy.xml, which helps to distinguish it from other JEE components. However the content is exactly the same structure.


    The other slight difference is that the BPEL deployment units are packaged as jars in RiftSaw, although they can be expanded as folders. In Apache ODE, if the BPEL deployment unit is manually copied into the runtime location (discussed further below), then it will be stored in its expanded form, but if loaded via the Apache ODE BPEL console, then it will be uploaded packaged as a zip file.



    Deployment Location


    Apache ODE has a single location within its runtime environment where the BPEL deployment units can be placed (in their expanded form). This is usually within the $ODE/WEB-INF/processes folder, although the location can be changed through configuration. Whether the deployment units are manually placed in this location, or deployed via the BPEL console as a zip, which results in the deployment unit being automatically unpacked and placed in this folder, all of the ODE BPEL processes are deployed into this one location.


    However the JBossAS architecture operates based on deployable components (e.g. as EJBs, WARs, ESB services, etc) that are potentially placed in multiple locations. There is a default deploy folder within each server, but other locations can also be monitored for deployment components.


    The other reason for supporting multiple locations, is that the BPEL deployment unit may be packaged as a sub-module within another deployment unit (e.g. an ESB service). Therefore, we need to be able to locate that BPEL deployment unit, without expecting it to be contained within the top level deploy folder.



    Using the JBossAS Deployment Framework


    Once the BPEL deployment unit has been placed in an approprpiate location, whether as a jar or exploded folder, the next step is to get the JBossAS deployment framework to detect it and deploy it within the server. The actual mechanism used to place the deployment unit in the appropriate location is not relevant here - whether manually copied, an ant script used, or the Eclipse WTP deployment mechanism has been used.


    For those new to the JBossAS Deployment Framework, some useful links may be:


    JBoss Microcontainer project - see Deployers and VFS documentation

    JBoss5 Deployment Framework

    Administration and Configuration Guide

    To get the deployment framework to identify a BPEL deployment unit, we defined a org.jboss.soa.bpel.deployer.BPELStructureDeployer (derived from the AbstractStructureDeployer) which simply checked for a structure context with the name of bpel-deploy.xml - and once found, creates a sub-context (within the scope of the supplied parent context) to represent a deployment unit of interest.


    Once the deployment framework has identified a deployment unit, it will check with a pre-defined set of deployers (located in the server's deployers folder), to determine which one can handle the deployment unit. Naturally, RiftSaw provides a deployer (org.jboss.soa.bpel.deployer.BPELDeployer) that can recognize a deployment unit associated with the name bpel-deploy.xml.


    This deployer provides a listener mechanism to enable other components to register interest in being informed when a BPEL deployment is deployed or undeployed.


    In RiftSaw, there is one component currently that registers with the deployer, to be informed of deploy and undeploy events. This is a RiftSaw derived ProcessStore implementation, in the class org.apache.ode.store.RiftSawProcessStore. This class is defined in the runtime/engine module, but has the Apache ODE package due to accessing package protected methods.


    When informed of a new BPEL deployment unit to deploy, the RiftSawProcessStore explodes the BPEL deployment unit into a folder in the tmp location of the JBossAS server. If the BPEL deployment unit had previously been deployed to ODE, the internal path to the deployment is updated to reference the new tmp path. This will occur if the server is restarted, as the previously temporary working area is only relevant when the server is running, and is re-initialised when the server is restarted.


    If the BPEL deployment unit is new or has been updated (as judged by the last modification time on the deployment descriptor), then the deployment unit is deployed as usual - which includes compiling the BPEL process into an internal representation stored in a .odp file.


    If the BPEL deployment unit has not been updated, and the server has just been restarted, then it will be necessary to re-compile the BPEL process, to make sure the relevant .odp file is present in the tmp area associated with the BPEL deployment unit.


    The final point to make is about the .odp file. As mentioned, this contains a compiled version of the BPEL process, used to execute the process within the ODE engine. This compiled version also includes a Global Unique ID (GUID). The Apache ODE engine by default checks that the GUID associated with any process instances match the GUID of the process definition. However if the BPEL process needs to be re-compiled each time the server starts, the GUID changes each time.


    Therefore a configuration switch has been added to enable this GUID check to be disabled.



    Versioning Support


    RiftSaw uses the same versioning approach as ODE. To be able to deploy a new version of a BPEL process, while enabling older versions of the process to still continue against the older version of the process, it is necessary for all relevant versions of the BPEL process to remain deployed.


    In Apache ODE, versioning is only supported when deploying a BPEL process through the Apache ODE BPEL console. This is because the deployment mechanism used from the console assigns a unique version number to the BPEL deployment unit, and expands the zip file into a folder (under the $ODE/WEB-INF/processes location) that has the version as a suffix. Therefore each separate version of the same deployment unit can co-exist within the deployment folder.


    RiftSaw takes a similar approach, except that it is the responsibility of the person, or software, placing the BPEL deployment unit in the JBossAS deploy folder to append a suitable version number to the jar or folder name. If the Eclipse WTP deployment mechanism is used, then it will automatically assign an appropriate version (based on the date and timestamp). If the ant scripts are used, similar to those in the samples folder, then these will place a version suffix on the deployed jar.


    When a version number is included as a suffix of the deployment unit jar/folder name, then RiftSaw will extract that version number and use it in place of the auto-generated version number used within ODE. This is to ensure that the same version is used, making it easier to associate entries in the BPM console with the deployment unit.