5 Oracle BPEL Process Manager

5.7.4.1 LDAP functions in 10.1.3.x

In 10.1.3.x releases, these XPath functions are defined in the xpath-functions.xml file.

The namespace URL for the XPath functions is http://schemas.oracle.com/xpath/extension/ldap.

5.7.4.2 Configuration File

Format the directories.xml file as follows:

<?xml version="1.0" ?>
<directories>
   <directory name='people'>
     <property name="java.naming.provider.url">ldap://servername:port</property>
     <property name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory
      </property>
     <property name="java.naming.security.principal">username</property>
     <property name="java.naming.security.authentication">simple</property>
     <property name="java.naming.security.credentials">passord</property>
     <property name="entryDN">[entry dn]</property>
  </directory>
</directories>

For example:

<?xml version="1.0" ?>
<directories>
  <directory name='people'>
    <property name="java.naming.provider.url">ldap://sta0018.us.mycompany.com:7001
     </property>
    <property name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory
     </property>
    <property name="java.naming.security.principal">cn=admin</property>
    <property name="java.naming.security.credentials">weblogic</property>
    <property name="java.naming.security.authentication">simple</property>
    <property name="entryDN">ou=people,ou=myrealm,dc=soainfra</property>
  </directory>
</directories>

To call the LDAP functions, you must use directories.xml.

5.7.4.3 authenticate

This function authenticates an LDAP user and returns true or false.

Signature:

ldap:authenticate('directoryName','userId','password')

Parameters:

• directoryName — The directory name specified in directories.xml.

• userId — The LDAP server login user ID.

• password — The LDAP server login password.

Return:

true or false

Example:

ldap:authenticate('people','weblogic','weblogic')

For this XPath function, you only specify two properties in the directories.xml file:

• java.naming.provider.url

• java.naming.factory.initial

5.7.4.4 listUsers

This function returns a list of LDAP users.

Signature:

ldap:listUsers('directoryName','filter')

Parameters:

• directoryName — The directory name specified in directories.xml.

• filter — The filter expression to use for the search; this value may not be null.

Return:

An XML element that contains a list of users.

For this XPath function, all properties must be specified in the directories.xml file.

Example:

ldap:listUser('people','cn=weblogic');

Example Output:

<users xmlns="http://schemas.oracle.com/bpel/ldap">
   <user dn="uid=weblogic">
      <uid>weblogic</uid>
      <userpassword>{ssha}bHDVJRfWVt/Uwlzb4TKU+QTOLB4FLySO</userpassword>
      <objectclass>inetOrgPerson</objectclass>
      <objectclass>organizationalPerson</objectclass>
      <objectclass>person</objectclass>
      <objectclass>top</objectclass>
      <objectclass>wlsUser</objectclass>
      <description>This user is the default administrator.</description>
      <wlsMemberOf>cn=Administrators,ou=groups,ou=myrealm,dc=soainfra</wlsMemberOf>
      <orclguid>8AC1B6206FDD11DEBF9A7F3D47003274</orclguid>
      <sn>weblogic</sn>
      <cn>weblogic</cn>
   </user>
</users>

5.7.4.5 lookupUser

This function returns LDAP user information.

Signature:

ldap:lookupUser('directoryName','userId','password')

Parameters:

• directoryName — The directory name specified in directories.xml.

• userid — The user ID to be searched.

Return:

An XML element that contains the user information.

For this XPath function, all properties must be specified in the directories.xml file.

Example:

ldap:lookupUser('people','cn=weblogic');

Example of Output:

<user dn="" xmlns="http://schemas.oracle.com/bpel/ldap">
  <ou>people</ou>
  <objectclass>organizationalUnit</objectclass>
  <objectclass>top</objectclass>
  <orclguid>8ABB9BA06FDD11DEBF9A7F3D47003274</orclguid>
</user>

5.7.4.6 search

This function returns a list of LDAP entries.

Signature:

ldap:search('directoryName','filter','scope')

Parameters:

• directoryName — The directory name specified in directories.xml.

• filter — The filter expression to use for the search; this may not be null.

• scope — The scope of the search. It must be one of the following values:

  • 0 — Named object

  • 1 — One level

  • 2 — Subtree

  This parameter is optional. By default, its value is 2.

Return:

An XML element that contains the list of entries.

For this XPath function, all properties must be specified in the directories.xml file.

Example:

ldap:search('people','cn=weblogic');

Example of Output:

<searchResult xmlns="http://schemas.oracle.com/bpel/ldap">
   <searchResultEntry dn="uid=weblogic" xmlns="urn:oasis:names:tc:DSML:2:0:core">
      <attr name="uid">
         <value>weblogic</value>
      </attr>
      <attr name="userpassword">
         <value>{ssha}bHDVJRfWVt/Uwlzb4TKU+QTOLB4FLySO</value>
      </attr>
      <attr name="objectclass">
         <value>inetOrgPerson</value>
         <value>organizationalPerson</value>
         <value>person</value>
         <value>top</value>
         <value>wlsUser</value>
      </attr>
      <attr name="description">
         <value>This user is the default administrator.</value>
      </attr>
      <attr name="wlsMemberOf">
         <value>cn=Administrators,ou=groups,ou=myrealm,dc=soainfra</value>
      </attr>
      <attr name="orclguid">
         <value>8AC1B6206FDD11DEBF9A7F3D47003274</value>
      </attr>
      <attr name="sn">
         <value>weblogic</value>
      </attr>
      <attr name="cn">
         <value>weblogic</value>
      </attr>
   </searchResultEntry>
   <searchResultEntry xmlns="urn:oasis:names:tc:DSML:2:0:core"/>
</searchResult> 

5.8.4.1 Enabling Debugging for a Specific Domain

The BPEL debugger is available in preview mode only for release 10.1.3.5. For information on how to enable the BPEL debugger, contact Oracle Support Services.

After enabling the BPEL debugger, perform the following steps:

1. Log in to Oracle BPEL Control.

2. Select the Configuration tab.

   A Debug subtab now appears under both the Instances tab and the Processes tab in Oracle BPEL Control.

5.8.4.2 Process Level Debugging

You can perform the following debugging tasks at the process level:

• View a process map for a BPEL process.

• Set and clear process breakpoints on selected BPEL activities.

  When a breakpoint is reached, execution pauses and waits for you to perform debugging actions.

• Define traps on a process.

  A process trap allows control on BPEL process instances that are trapped for debugging. The process trap supports both unconditional and conditional traps with a count. You specify the number of process instances to trap for debugging. By default, the process trap is disabled for a process.

The debug state for all processes (including process traps and breakpoints) is persisted to the dehydration store. Similarly, when a domain is initialized during Oracle BPEL Server startup, the BPEL debugger loads the debug state for all processes in the domain from the dehydration store.

1. Log in to Oracle BPEL Control.

2. Click the Processes tab.

3. In the BPEL Process column, click a specific deployed process. You can only debug processes that have a life cycle setting of Active and a state setting of On.

4. Click the Debug subtab.

5. Select BPEL activities on which to set breakpoints. You can select multiple activities by pressing the Ctrl key and making additional selections.

6. In the Debugger control panel on the right side, click the Set Breakpoint icon (second icon) to set breakpoints on activities.

   
   Description of the illustration bpel_setbp.gif
   
   

   The selected breakpoints display in the Breakpoints section of the Debugger control panel. All breakpoints defined at the process level are copied to each of the instances of the process for debugging at the time of instance creation. At the instance level, you can perform debug actions (step, resume, update variable values, and so on) that only impact that specific instance.

   
   Description of the illustration bpel_setbp2.gif
   
   

7. Remove a breakpoint by selecting it in the Breakpoints section and clicking the Clear Breakpoint icon (third icon).

8. In the Debugger control panel, click the Set Trap Count icon (first icon) to set a trap count value.

   
   Description of the illustration bpel_setbp6.gif
   
   

   A dialog for entering a process trap value is displayed. If you want to trap all further process instances, then enter a value of -1, which shows the trap count as ALL. A trap count value of 0 implies that the trap is disabled.

9. Enter a value for the number of newly-created process instances to trap, and click OK.

   The process instance trap value displays in the Trap Count section and Breakpoints section of the Debugger control panel.

   
   Description of the illustration bpel_setbp3.gif
   
   

10. Remove a breakpoint by selecting it in the Breakpoints section and clicking the Clear Breakpoint icon (third icon).

11. Click the Refresh Process Debug State icon (fourth icon) to refresh the debugger state. For addition information about this icon, see the description for the Refresh Instance Debug State icon in the table.

12. Click the ? icon (fifth icon) to display online Help for the tasks that you can perform on this page.

5.8.4.3 Instance Level Debugging

You can perform the following debugging tasks at the instance level:

• Debug open BPEL instances paused on an initial breakpoint (defined at process level).

• Bring up a dehydrated instance and debug it (set a breakpoint on an activity past the dehydration point and wait for the instance to hit the breakpoint).

• Debug only one instance at a time.

When a process instance hits a breakpoint, the process map for the instance appears in the Debug tab, identifying the activity at which instance execution has paused. If there are multiple instances paused in debug state, you can selectively load specific instances and debug them.

BPEL instances on creation inherit the breakpoints defined at the corresponding process level. Post creation, instance breakpoints are independent of process breakpoints. Debug operations such as set and clear breakpoints on an instance do not impact the breakpoints defined at the process level, and vice versa.

When an instance is dehydrated, the debug state for the instance is persisted to the dehydration store. Similarly, when an instance is rehydrated, the instance debug state is also restored to enable you to continue debugging operations on the instance.

1. Log in to Oracle BPEL Control.

2. Click the Instances tab.

3. In the Instance column, click one or more specific instances. When debugging is enabled, debuggable instances are identified by a red stop sign icon. You can select one or more debuggable instances and click the Resume button to perform a bulk resume operation. Instance level debugging is only permitted for BPEL instances in a state of open.running.

4. Click the Debug subtab.

   A process map for the BPEL instance is displayed.

   The process map visually identifies BPEL activities that have a breakpoint or a current position. A current position is defined as an activity where execution is paused (immediately prior to the activity). Therefore, the initial current position gets defined when an instance hits the first breakpoint postinitiation. The breakpoint associated with a current position can be explicit (a user-defined breakpoint) or implicit (internal breakpoint; for example, when you perform a single-step operation and the following activity does not have a user breakpoint).

   An activity that has a user breakpoint may not be executed and therefore may not become a current position. This occurs when the instance being executed takes a different execution path that does not encounter the activity. Therefore, it may not encounter the breakpoint.

   
   Description of the illustration bpel_setbp4.gif
   
   

5. Right-click an activity to display a list of debug operations permissible on the activity. Note that many of these operations are context sensitive and display only when relevant.

   • View Source

     Displays the BPEL source code.

   • Set Breakpoint

     Sets a breakpoint on this activity. Only one of the Set Breakpoint or Clear Breakpoint options appears on any activity as a right-click option.

   • Clear Breakpoint

     Clears a breakpoint on this activity.

   • Forced Completion

     When an instance being debugged shows one or more asynchronous activities as being performed, you can force completion or skip the being performed activity. Execution then continues with the next activity.

     Activities identified as being performed are different from current position activities. BPEL activities such as a receive, OnAlarm branch of a pick, and wait complete asynchronously. For example, a midprocess receive activity completes when it receives a message from the associated partner link. Similarly, a wait activity completes when the timer associated with the activity expires.

     Only such asynchronous activities that have been initiated, but which are waiting on some event for completion, are marked as being performed. You can skip or force completion on such activities if you do not want to wait for the activity to complete normally.

   • Select Current Position

     If there is more than one current position, you can switch the selected one to another. This operation is only enabled when a BPEL instance is in debug mode with more than one current position. This option only appears for selection when there is more than one current position for the instance, and the selected activity is one of them, but not the selected current position.

   • Single Step

     Performs the next operation. This option displays when right-clicking a current position activity.

   • Step Block

     Performs the next structured activity. This option displays when right-clicking a current position activity that is a structured BPEL activity.

   • Resume

     Resumes execution until the next breakpoint. This option displays when right-clicking a current position activity.

   • Clear All and Run

     Resumes execution after removing all breakpoints. This option displays when right-clicking a current position activity.

6. View the list of breakpoints in the Breakpoints section of the Debugger control panel on the right side. BPEL instance execution pauses before a BPEL activity that has an active breakpoint.

   Icons at the top provide access to debugging tasks.

   
   Description of the illustration bpel_setbp7.gif
   
   

   The icons that display left to right are described in the following table.

   Icon	Icon Name	Description
   1	Show and Follow Audit Trail	Displays the audit trail associated with the instance being debugged. When you debug an instance, the audit trail for the instance shows debugger actions and interventions. Specifically, the following debugger actions are displayed in the audit trail: When an instance hits a breakpoint When an instance is resumed past a breakpoint When an instance variable is edited When an activity is force-completed
   2	Set Breakpoint	Sets a breakpoint on an instance.
   3	Clear Breakpoint	Clears a breakpoint on an instance.
   4	Step	Performs the next operation. You can resume execution of the instance one activity at a time by performing a single-step operation. Upon resumption, the instance completes the current activity, encounters an implicitly set breakpoint on the following activity, and pauses execution. As with the resume operation, a single-step operation must (implicitly or explicitly) identify a specific BPEL activity at which execution must be resumed. A single-step operation is permitted only on an activity that has a current position on it.
   5	Step Block	Performs the next structured activity. When execution has paused at a BPEL structured activity, you can perform a step-block operation on it. The step-block operation resumes execution from the identified structured activity that has a current position on it, encounters an implicitly set breakpoint on the activity following the structured activity, and pauses execution. A step-block operation must (implicitly or explicitly) identify a BPEL activity at which execution must be resumed. A step-block operation is permitted only on a structured BPEL activity that has a current position on it.
   6	Resume	Resumes execution until the next breakpoint. You can resume execution of the instance by doing a resume operation. Upon resumption, the instance execution proceeds until it encounters another breakpoint or runs its normal course to completion. A resume operation must (implicitly or explicitly) identify a specific BPEL activity at which execution must be resumed. A resume operation is permitted only on an activity that has a current position on it.
   7	Clear All Breakpoints and Run	Resumes execution after removing all breakpoints. When a BPEL instance is in debug mode, you can clear all breakpoints and resume execution of the instance. Upon resumption, all breakpoints on the instance are cleared and the instance execution runs its normal course to completion.This option is only permitted when there is at least one BPEL activity that has a current position on it.
   8	Refresh Instance Debug State	Refreshes the debugger state. When the BPEL instance being debugged is open, running, and not in debug mode (that is, it has not encountered any breakpoints), the Debugger control panel indicates that the instance is freely running and has not encountered any breakpoint. You can perform this operation to do the following: Force a refresh of the instance debug state and update the debug state of the instance from the server Check if the instance has hit any breakpoints This operation is also supported on the Debug subtab of the Processes tab to refresh breakpoints defined at the process level.
   9	Help	Displays online Help for the tasks that you can perform on this page.

   
   

7. Select options appropriate to your environment.

   The Debugger control panel displays the list of BPEL variables for the instance. You can view and edit BPEL process variables associated with the instance when execution is paused at a breakpoint.

8. Click the variable name in the list to display its contents.

   
   Description of the illustration bpel_setbp5.gif
   
   

9. Edit the contents of the selected variable:

   • Click the first icon above the variable content to create an XML skeleton of the variable or to create its content in the editor. This enables you to initialize a variable with an empty skeleton based on its XML schema type.

   • Click the second icon above the variable content to save that variable to the process instance.

   If you do not click Save after you edit the variable contents, the changes are discarded. The BPEL Debugger enforces XML schema validation for the updated variable content.

5.8.5.1 Notification Event Types and Notification Variables

Table 5-1 shows the notification event types you can configure through use of predefined templates in Oracle BPEL Control.

As you create the notification message content in the templates, there are specific predefined variables to use in the message subject and body. These variables are replaced with actual values at runtime. Table 5-2 provides details.

The XSD file (bpel_notification.xsd) is located in SOA_Home/bpel/system/xmllib.

5.8.5.2 Prerequisite: Downloading the Velocity JAR File

The e-mails generated for notifications are as per the templates configured. These templates contain predefined variables that are replaced with the actual values at runtime. To follow a standard and provide an easier format for these variables, velocity templates are used with the BPEL notification feature. Therefore, the velocity-dep-1.5.jar file is required for the notification feature to work.

The velocity-dep-1.5.jar file is not shipped with Oracle SOA Suite. Therefore, the BPEL notification feature is disabled by default. To enable the BPEL notification feature, you must explicitly download this JAR file after accepting the Apache license agreement.

Perform the following steps to download the velocity-dep-1.5.jar file.

1. Access the following URL:

   http://archive.apache.org/dist/velocity/engine/1.5/
   

2. Download velocity-dep-1.5.jar.

3. Accept the Apache licensing agreement to use the BPEL notification feature.

4. Place the JAR file in $Oracle_Home/bpel/lib for UNIX or Oracle_Home\bpel\lib for Windows.

5. Restart Oracle BPEL Server.

   This enables the BPEL notification feature to display in Oracle BPEL Control.

5.8.5.3 Creating BPEL Notifications

1. Log in to Oracle BPEL Control.

2. Click the Configuration tab.

3. Click the Notifications tab.

   The upper part of the page enables you to perform the following tasks:

   • Select the event types and templates to enable or disable. An event type can be configured to have two or more templates. However, an event type cannot have the same template twice.

   • Specify notification recipients. If you specify multiple recipients, separate each recipient with a comma.

   
   Description of the illustration bpel_notif1.gif
   
   

4. Click Apply to apply any changes.

5. Scroll down to the lower part of the page.

   The lower part of the page enables you to perform the following tasks:

   • Select a template to use in the Current Templates section. This action causes the template to display in the Template Details section. All velocity template variables are automatically replaced with the actual values from BPEL runtime by the notification service. These values are sent as e-mail content. You do not need to enter any values in these templates.

   • Click the Add or Delete icon to add or delete a template.

   
   Description of the illustration bpel_notif2.gif
   
   

6. Click the online Help link Predefined template variables for descriptions of variables and examples of values.

7. Click Apply when complete.

8. Click the Configuration tab.

9. Scroll down and configure the SMTP server with values appropriate to your environment.

   
   Description of the illustration bpel_notif3.gif
   
   

10. Click Apply when complete.

    The notification feature uses in-memory storage to collect the messages between two processing cycles (5 minutes by default) and process them periodically. The maximum number of notification messages to process is configured with the property notificationStoreMaxMessagesSize on this page. The default value is 150. In a high volume environment, a larger number of notification messages must be collected and processed. In this scenario, you must increase the value for this property to avoid messages not being collected and processed. If the default value of 150 is exceeded, the following null pointer exception may appear in the logs, which causes the BPEL notification service to become disabled.

    <NotificationAgent::execute>  Domain :default NotificationJob: Number of 
    notification messages to be processed : 150 
    <NotificationAgent::processNotification>  Domain :default, Processing 
    @ instance.complete notification  for channel: email 
     Unable to handle email notifications for the domain default 
    java.lang.NullPointerException 
            at 
    com.collaxa.bpel.services.notification.channel.ChannelHandler.constructMessage 
    . . .
    . . .
    

    If this occurs, perform either of the following workarounds:

    1. Go to Configuration > Notification in Oracle BPEL Control.

    2. Disable notifications, and click Apply.

    3. Enable notifications, and click Apply.

    or

    1. Restart Oracle BPEL Server.

5.8.5.4 Consolidated Notifications

Notification events are triggered whenever a significant change occurs in BPEL instances, dispatcher messages, BPEL processes, and so on. These accumulated events are processed periodically (five minutes by default) and e-mails are dispatched one per notification event type. During this execution, a set of identical notification messages collected between any two notification periodic cycles are processed and sent as a single mail. For example, in a domain, the set of BPEL instances that faulted is consolidated and sent as a single e-mail.

5.8.5.5 Periodic Processing of Notifications

Processing of notification messages is performed periodically. The default duration is 5 minutes. You can change this value to reflect the requirements of your environment. Perform the following steps to change this property.

1. Open the SOA_HOME\bpel\domains\domain_name\config\domain.xml file for the domain in which to change this property.

2. Manually add the notificationScheduleDuration property and set it to an appropriate integer value.

   <property id="notificationScheduleDuration">
     <name>Notification schedule duration property</name>
     <value>5</value>
     <comment/>
   </property>
   

3. Save and close the file.

4. Restart Oracle BPEL Server.

   The property now displays under Configuration > Domain in Oracle BPEL Control. Subsequent changes to this value do not require a restart of Oracle BPEL Server.

5.8.5.6 Event Notification Samples

This section provides samples of event notification messages.

Example 5-1 provides an example of message content sent during an engine (Oracle BPEL Server) notification.

E-mail Subject Engine Notification: Started

Email Content Server host      : myhost.us.oracle.com:9999
              Server instance  : oc4j_soa
              Domain name      : tests
       
              Server status    : Stopped
              Timestamp        : Wed April 08 00:42:23 PDT 2009

Example 5-2 provides an example of message content sent during a process notification. Note that in this example, notifications with similar content can be combined into a single notification.

E-mail Subject Process Notification: Retired

Email Content Server host      : myhost.us.oracle.com:9999
              Server instance  : oc4j_soa
              Domain name      : tests

              Process name     : SyncEmbedProcess
              Revision tag     : 1.0
              Process Status   : Retired
              Timestamp        : Wed April 08 10:42:23 PDT 2009

              Process name     : SyncXPathProcess
              Revision tag     : 1.0
              Process Status   : Retired
              Timestamp        : Wed April 08 05:12:24 PDT 2009

Example 5-3 provides an example of message content sent during an instance notification.

E-mail Subject Instance Notification: Faulted

Email Content Server host      : myhost.us.oracle.com:9999
              Server instance  : oc4j_soa
              Domain name      : tests

              Process name     : SyncEmbedProcess
              Revision tag     : 1.0
              Instance ID      : Retired
              Conversation ID  : bpel://localhost/tests/Tests-1.0/6567403-BpSeq1.3
              Instance status  : Faulted
              Timestamp        : Wed April 08 04:22:29 PDT 2009

Example 5-4 provides an example of message content sent during a recovery notification. Note that in this example, notifications with similar content can be combined into a single notification.

E-mail Subject Attempted Invoke messages recovery and faulted

Email Content Server host      : myhost.us.oracle.com:9999
              Server instance  : oc4j_soa
              Domain name      : tests

              Process name     : SyncEmbedProcess
              Revision tag     : N/A
              Instance ID      : N/A
              Activity name    : 
              Conversation ID  : bpel://localhost/tests/Tests-1.0/6567402-BpSeq1.3
              Receive date     : 03/11/09 06:37:51 AM
              Recovery status  : Pending recovery
              Timestamp        : Wed April 08 01:26:34 PDT 2009
              Error code       : ORABPEL-92181
              Exception        : Fauled due to unhandled BPEL fault

              Process name     : SyncJavaEmbed
              Revision tag     : N/A
              Instance ID      : N/A
              Activity name    : 
              Conversation ID  : bpel://localhost/tests/Tests-1.0/6567434-BpSeq1.3
              Receive date     : 03/11/09 06:37:51 AM
              Recovery status  : Pending recovery
              Timestamp        : Wed April 08 07:21:03 PDT 2009
              Error code       : ORABPEL-92181
              Exception        : Fauled due to unhandled BPEL fault

Example 5-5 provides an example of message content sent during an instance recovery notification. This notification is triggered when a message or activity moves to recovery.

E-mail Subject Invoke message fail and move to recovery

Email Content Server host      : myhost.us.oracle.com:9999
              Server instance  : oc4j_soa
              Domain name      : tests

              Process name     : SyncJavaEmbed
              Revision tag     : 1.0
              Instance ID      : N/A
              Activity name    : N/A
              Conversation ID  : bpel://localhost/tests/Tests-1.0/6567433-BpSeq1.3
              Receive date     : 03/11/09 06:37:51 AM
              Timestamp        : Wed April 08 12:00:23 PDT 2009

Example 5-6 provides an example of message content sent during an instance recovery notification. This notification is triggered when a message or activity moves to recovery.

E-mail Subject Callback messages fail and move to recovery

Email Content Server host      : myhost.us.oracle.com:9999
              Server instance  : oc4j_soa
              Domain name      : tests

              Process name     : SyncJavaEmbed
              Revision tag     : 1.0
              Instance ID      : N/A
              Activity name    : N/A
              Conversation ID  : bpel://localhost/tests/Tests-1.0/6567913-BpSeq1.3
              Receive date     : 03/11/09 04:33:51 AM
              Timestamp        : Wed April 08 09:42:03 PDT 2009

5.8.11.1 Prerequisites

1. Create a new file named wsif-ejb-tool.xml in the SOA_HOME\bpel\system directory.

2. Copy and paste the following XML content into the file. This XML file sets up the class path variable.

   <?xml version="1.0"?>
   <project name="wsif-ejb-binding" default="" basedir=".">
       <property name="classpath"
   value=".\..\lib\xmlparserv2.jar;.\..\..\webservices\lib\saaj-api.jar;.\..\..\
   webservices\lib\wsa.jar;.\..\..\webservices\lib\wsclient.jar;.\..\..\webservice
   s\lib\wsserver.jar;.\..\..\webservices\lib\jaxrpc-api.jar;.\..\..\webservices\
   lib\orasaaj.jar;.\..\..\webservices\lib\orawsdl.jar;.\..\..\webservices\lib\
   orawsmetadata.jar;.\..\..\j2ee\home\lib\ejb30.jar;.\..\..\j2ee\home\lib\
   ejb.jar;.\..\..\j2ee\home\lib\mail.jar;.\..\..\j2ee\home\lib\http_client.jar;.
   \..\lib\wsif-ejb-design.jar"/>
       <taskdef name="BeanDefinitionGenerator"
    classname="oracle.tip.wsif.ejb.wsdlgen.tool.AntBDFGenerator"
    classpath="${classpath}"/>
       <taskdef name="WSDLGenerator"
    classname="oracle.tip.wsif.ejb.wsdlgen.tool.AntGenerateArtifacts"
    classpath="${classpath}"/>
   </project>
   

3. Create an ant file to generate the WSDL file under SOA_HOME\bpel\bin. The following build.xml file shows the contents for WSDL file generation.

   <project name="wsif-ejb-binding-design-time" default="" basedir=".">
       <import file="..\system\wsif-ejb-tool.xml"/>
       <property name="jarLocation"
    value="C:\Temp\wsif\DataBindingTestEJB\deploy\ejb1.jar"/>
       <property name="beanDefinitionLocation" value="C:\Temp\wsif\beanDefinition\"/> 
   
       <target name="GenerateBeanDefinition" depends=""> 
          <BeanDefinitionGenerator
               jarLocation="${jarLocation}"
               beanDefinitionLocation="${beanDefinitionLocation}"
               pkg="test.*,databindingtestejb.*"
               logLevel="info"
               jvmArgs="-Dhttp.proxyHost=PROXY_HOST -Dhttp.proxyPort=PROXY_PORT
                -DproxySet=true"
               failonerror="true">
           </BeanDefinitionGenerator>
       </target>
   
       <target name="GenerateWSDL" depends="">
           <WSDLGenerator
               jarLocation="${jarLocation}"
               beanDefinitionLocation="${beanDefinitionLocation}"
               artifactsLocation="C:\Temp\wsif\artifacts\"
               schemaLocation=""
               customTypeMappingLocation=""
               jndiName="CustomerEJB"
               initialContextFactory="oracle.j2ee.rmi.RMIInitialContextFactory"
               jndiProviderURL="ormi://myhost-pc.idc.oracle.com:12402/ejb1"
               logLevel="info"
               jvmArgs="-Dhttp.proxyHost=PROXY_HOST -Dhttp.proxyPort=PROXY_PORT
                -DproxySet=true"
               strictJaxrpcValidation="true"
               failonerror="true">
           </WSDLGenerator>
       </target>
   </project>
   

5.8.11.2 Bean Definition Generation

1. Create and run an ant target that generates the intermediate type definition file using the BeanDefinitionGenerator task. This target must provide all the attributes needed for the BeanDefinitionGenerator task.

   Here are definitions for the following attributes:

   • jarLocation — The location of the EJB client JAR file. The value for this attribute is already defined at the top level property jarLocation.

   • beanDefinitionLocation — The location of the directory in which the intermediate type definition file goes. The value for this attribute is already defined at the top level property beanDefinitionLocation.

   • pkg — A comma-separated list of packages for which type definition files must be generated. For example, test.*,databindingtestejb.*. Currently, the task does not support *.*.

     When you generate a bean definition with the ant task GenerateBeanDefinition, the bean definition file is generated for the class you specify and for all classes dependent on this class file; nothing is filtered. The package filter mechanism is provided primarily to include other dependent classes that have different package structures.

   • logLevel — The logging level required. Permitted values are DEBUG, INFO, WARNING, and ERROR.

   • jvmArgs — This attribute is not required for the EJB 2.1 JAR file. However, if you are using the EJB 2.0 JAR file and use a proxy server, you must add this attribute and specify a value for your PROXY_HOST (for example, www-proxy.us.mycompany.com) and PROXY_PORT (for example, 80). If you do not use a proxy server, then the jvmArgs attribute and PROXY_HOST and PROXY_PORT properties are not required. The tool automatically uses http://java.sun.com/dtd/ejb-jar_2_0.dtd.

   • failonerror — This must be set to true.

     Here is an example:

     <target name="GenerateBeanDefinition" depends=""> 
        <BeanDefinitionGenerator
             jarLocation="${jarLocation}"
             beanDefinitionLocation="${beanDefinitionLocation}"
             pkg="test.*,databindingtestejb.*"
             logLevel="info"
             jvmArgs="-Dhttp.proxyHost=PROXY_HOST -Dhttp.proxyPort=PROXY_PORT
              -DproxySet=true"
             failonerror="true">
         </BeanDefinitionGenerator>
       </target>
     

5.8.11.3 Modifying the Bean Definition File

The output of this target is the type definition files in the beanDefinitionLocation directory. The type definition files correspond to classes for the selected package. Note that type definition files are generated for classes having the following:

• A collection class as member variables

• A service endpoint/remote/local interface in the ejb-jar.xml file that uses the collection class as parameters/return type

The type definition file name is the same as that of a fully qualified class where a dot (.) is replaced with an underscore (_). For example, for a class with name databindingtestejb.CustomerEJBWebService, the corresponding type definition file name is databindingtestejb_CustomerEJBWebService.xml.

You must provide the missing information for all the type definition files in the beanDefinitionLocation directory. The required information is the contained type for the collection classes. For example, the following type definition file snippet is generated at design time.

<?xml version = '1.0' ?>
<Bean-definition xmlns="http://java.wsif.ejb.binding">
   <Class name="test.databinding.dto.customer.profile.FiledCreditCards"
     serialVersionUID="-8027792423900150501">
       <Fields>
         <Field name="customerCreditCards" type="java.util.Collection">
            <Value>XXXXX</Value>
         </Field>
         <Field name="merchants" type="java.util.TreeSet">
            <Value>XXXXX</Value>
         </Field>
         <Field name="creditCardByMerchant" type="java.util.Hashtable">
            <Key>XXXXX</Key>
            <Value>XXXXX</Value>
         </Field>
       </Fields>
   </Class>
</Bean-definition>

1. Replace the XXXXX values in this example with the collection content classes.

   The following example shows the modified version of the preceding type definition file:

   <?xml version = '1.0' ?>
   <Bean-definition xmlns="http://java.wsif.ejb.binding">
      <Class name="test.databinding.dto.customer.profile.FiledCreditCards"
    serialVersionUID="-8027792423900150501">
          <Fields>
            <Field name="customerCreditCards" type="java.util.Collection">
               <Value>test.databinding.dto.customer.profile.CustomerCreditCard
               </Value>
            </Field>
            <Field name="merchants" type="java.util.TreeSet">
               <Value>test.databinding.dto.customer.profile.Merchant</Value>
            </Field>
            <Field name="creditCardByMerchant" type="java.util.Hashtable">
               <Key>test.databinding.dto.customer.profile.Merchant</Key>
               <Value>test.databinding.dto.customer.profile.CustomerCreditCard
               </Value>
            </Field>
          </Fields>
      </Class>
   </Bean-definition>
   

5.8.11.4 WSDL File Generation

1. Create and run an ant target that generates the WSDL file using the WSDLGenerator task. This target must provide all the attributes needed for the WSDLGenerator task. See Step 3 for WSDLGenerator syntax.

   Here are definitions for the following attributes:

   • jarLocation — The location of the EJB client JAR file. The value for this attribute is already defined with the top level property jarLocation.

   • beanDefinitionLocation — The directory location for the intermediate type definition file. The value for this attribute is already defined with the top level property beanDefinitionLocation.

   • artifactsLocation — The directory location for the WSDL and JAX-RPC mapping file.

   • schemaLocation — The comma-separated list (without blank spaces) of all schema files you want to import in the WSDL file. This attribute is optional.

   • customTypeMappingLocation — The location of the custom type mapping file. This attribute is optional.

   • jndiName — The JNDI name for the EJB.

   • initialContextFactory — The initial context factory for the EJB.

   • jndiProviderURL — The JNDI provider URL for the EJB.

   • logLevel — The logging level required. Permitted values are DEBUG, INFO, WARNING, and ERROR.

   • jvmArgs — See Section 5.8.11.2, "Bean Definition Generation" for a description.

   • strictJaxrpcValidation — Determines whether the service endpoint interface, exceptions, and value types are validated according to all of the JAX-RPC validation rules. While the permitted values are true (the default) or false, this attribute must be set to true. If set to false, WSDL file generation still works, but problems occur during runtime.

   • failonerror — Must be set to true.

   Here is an example:

   <target name="GenerateWSDL" depends="">
           <WSDLGenerator
               jarLocation="${jarLocation}"
               beanDefinitionLocation="${beanDefinitionLocation}"
               artifactsLocation="C:\Temp\wsif\artifacts\"
               schemaLocation=""
               customTypeMappingLocation=""
               jndiName="CustomerEJB"
               initialContextFactory="oracle.j2ee.rmi.RMIInitialContextFactory"
               jndiProviderURL="ormi://myhost-pc.idc.oracle.com:12402/ejb1"
               logLevel="info"
               jvmArgs="-Dhttp.proxyHost=PROXY_HOST -Dhttp.proxyPort=PROXY_PORT
                -DproxySet=true"
               strictJaxrpcValidation="true"
               failonerror="true">
           </WSDLGenerator>
       </target>
   

5.8.13.1 Migration Guidelines

Before performing a migration, you must review the following guidelines to understand how instance migration works.

• Migration is only permitted between revisions of the same process name (for example, HelloWorld 1.0 to HelloWorld 2.0 or OrderBooking 3.0 to OrderBooking 7.0).

• Any two revisions should have compatible interfaces. However, no tool currently enforces this requirement. Therefore, ensure that you maintain this compatibility. For example, ensure that:

  • Changes are incremental and do not contradict definitions from earlier revisions.

  • Interfaces used for communication with external services, such as partner links, messages, types, and bindings are not changed in an incompatible way.

  • Variables have compatible types and names.

  • Partner links have compatible definitions, such as partner link names and operations.

    For example, if a partner link name has changed between the older source revision and the newer destination revision, the state from the source revision instance is not copied to the destination revision instance. Therefore, the receive activity does not know how to handle the callback message that it receives.

• You can only migrate asynchronous processes. Asynchronous processes, which are typically long running, have pauses at the dehydration points. Synchronous processes cannot be migrated because there are no dehydration points.

• Migration mapping is permitted from certain activities with dehydration points. There are two types of activities involved in migration.

  • Container activities

    Examples of containers are scopes, flows, sequences, flowNs, and so on.

  • All other activities, such as assigns, throws, receives, and so on.

  Migration mapping is subject to thread constraints that govern several activities. Oracle BPEL Server permits only one thread per activity and up to N threads per container. Containers such as scopes and sequences permit only one thread of execution at any time. Table 5-3 provides details about supported migrations of activities.

  Table 5-3 Supported Activity Migrations

  You Can Migrate From This Source Definition...	To This Target Definition...	Description
  Receive activity	Any activity except for those belonging to a flowN. Note: You can migrate to a flowN, but not inside it.	If the migrated item is inside a flow, only that branch of the flow is executed in the destination. In this case, there is only one source thread and therefore at most one thread/work item is created in the destination process. A work item is a task for Oracle BPEL Server to perform. Threads are represented by work items and governed by container activities.
  Wait activity	Any activity except for those belonging to a flowN.	The same behavior occurs as described for the receive activity.
  Pick activity	Any activity except for those belonging to a flowN.	The pick is divided into a list of onMessage and onAlarm constructs. There are N work items created in the parent process and therefore potentially N different execution points in the destination. In most cases, only the one source work item is migrated (either the first onMessage or the first onAlarm).
  Any dehydration point (receive, wait, pick, onAlarm, and onMessage)	Any activity except for those belonging to a flowN.	The N active work items in the source process can be migrated to create M active work items in the destination process. The only requirements are the following: M =< N where M represents the number of possible work items in the destination. In this example, this is M=1. However, if you migrate into another flow, potentially >1 work items can be created in each of the branches. If a container permits only one thread of execution (scope, process, sequence, and so on), you cannot migrate work items that cause a chase in that container. A chase is when you have more than the maximum number of work items allowed in a container.
  Any dehydration point (receive, wait, pick, onAlarm, and onMessage)	To a pick activity	Migration to a pick means that the pick becomes the execution point. Oracle BPEL Server simply runs the pick.
  Any dehydration point (receive, wait, pick, onAlarm, and onMessage)	Into a pick activity	Migration into a pick activity means migration into any of the onMessage or onAlarm elementary activities that comprise a pick. You can migrate to one of these.
  Any dehydration point (receive, wait, pick, onAlarm, and onMessage)	To a flow activity	Migration to a flow means that the flow becomes the execution point. Oracle BPEL Server simply runs the flow.
  Any dehydration point (receive, wait, pick, onAlarm, and onMessage)	Into a flow activity	Migration into a flow activity means that if, for example, you migrate two branches into a flow activity that has three branches, only two are run.
  Activities inside a flow activity	Into another flow activity	This migration type is supported, Several branches can be migrated.

  
  

• An instance can be migrated from inside a source while loop and also into a destination while loop. The loop counter variable is copied and the state is maintained.

• Activities inside an exception handler can be a migration source and destination. After the handler is complete, execution starts after the block in which the exception handler is defined.

• When migrating to a scope container activity, Oracle BPEL Server opens the scope and executes the first activity in the scope that is not a container.

• When migrating an instance, the new execution points can be any activity in the destination process except for an activity that belongs to a flowN activity.

• Migrating to a flow activity causes Oracle BPEL Server to open the flow and run parallel threads in it.

• Variables are automatically copied to a new process instance. Variable mapping is done by variable name and the location in the lexical scope chain. The one exception is the process scope. In that location, variables are copied between the processes regardless of how they are lexically hidden by scopes (if any).

  Note the following details about variable migration:

  • Variables are copied from process scope to process scope.

  • Variables are copied from each source stack frame according to visibility and lexical rules.

  • If a variable does not exist in the destination process, it is not copied and a warning message is issued.

  • If the destination process contains new variables, a message similar to the following appears in the log files:

    <2009-07-15 03:06:25,381> <WARN> <default.collaxa.cube.engine.migrate> 
    <CubeEngine::migrateVariables> Scope "rootScope@6" has a variable 
    "newPickService_InputVariable" which is NOT defined in the source scope(s).
    

    Note that new variables such as this are not initialized.

  • If a variable does exist in the destination process, it must be compatible for the copy to succeed.

  • Variables present in the destination process are only instantiated and initialized.

• Endpoints can be migrated. After migrating a process instance, all the pending callbacks to that instance are routed to the new, migrated instance.

5.8.13.2 Migrating Instances

This section describes how to perform instance migration from Oracle BPEL Control.

1. Log in to Oracle BPEL Control.

2. Select one of the following methods to migrate. If necessary, initiate the instance from which to migrate.

   From the Processes tab:

   This option enables you to migrate all instances of a process revision.

   1. Click the Processes tab.

   2. Select the process revision from which to migrate (for example, select MigrationTestReceive2Assign (v. 1.0). You select the destination definition on the Migration page.

      Note:

      The user interface does not restrict you from selecting multiple processes of different names (for example, OrderBooking (v. 1.0) and LoanFlow (v. 1.0)). However, this type of selection is not supported.

   3. Click Migrate Process Instances at the bottom of the page.

   4. Go to Step 3.

   From the Instances tab:

   This option enables you to migrate a single instance of a process revision or multiple instances provided that all the instances belong to the same BPEL process.

   1. Click the Instances tab.

   2. Select the instance from which to migrate. You select the destination definition on the Migration page.

      Note:

      The user interface does not restrict you from selecting multiple instances of different names (for example, instance 1001 of OrderBooking (v. 1.0) and instance 275 of LoanFlow (v. 1.0)). However, this type of selection is not supported.

   3. Click Migrate at the bottom of the page.

   4. Go to Step 3.

   From the Audit or Flow tab of a specific BPEL instance:

   1. Click Migrate.

   2. Go to Step 3.

3. View the Migration page.

   
   Description of the illustration bpel_migrate1.gif
   
   

   The source process definition displays on the left side of the page. This is the older revision. The destination process definition displays on the right side of the page. The column in the middle represents mappings from the source process to the destination process.

   The mappings represent how work items are migrated to run in the new process definition. Since processes only dehydrate in certain types of activities, only these activities are shown in the left column of the rules mappings.

   You execute the mapping to migrate the specified process instances. Upon successful migration, the source process instance is ended and the new process instance proceeds at the specified migration points. All variables, partner link states, and so on are copied (if compatible) to the new process instances.

   Note:

   When expanding branching activities such as picks, switches, and flows with Internet Explorer 7, an additional closed branch displays off to the side. This additional branch can be ignored.

4. From the dropdown list in the destination tree, select the version to which to migrate. For this example, revision 2.0 is selected.

5. From the source process definition, select activities from which to migrate. For example, select a receive activity.

6. From the destination process definition, select activities to which to migrate. For example, select an assign activity. This causes the assign activity to display in the middle column.

7. To disable activities for migration, select the plus icon for the activity in the middle column.

   
   Description of the illustration bpel_migrate5.gif
   
   

   Note:

   You must manually select activities to migrate (for example, select to migrate a receive activity or a wait activity to an assign activity). This creates mapping rules for dehydration points in order for activities to be moved to the new revision. If you do not create mapping rules for the dehydration points, no migration is performed when you click Migrate Instances.

8. If you want to save your mapping into a migration map that can be reused at a later time, click Save. Otherwise, go to Step 9.

   The migration map defines how the threads are created in the new destination process from the old process. Each rule contains the source activity ID and a destination activity ID. The source process name, the destination process name, and an embedded list of instance IDs to migrate are also included in the migration map.

   1. Enter a name for the file to which to save the mappings, and click OK.

   2. Click OK when prompted to confirm the name and location of the template.

   3. Click Migration Maps.

      A list of saved maps is displayed.

      
      Description of the illustration bpel_migrate2.gif
      
      

   4. Select the map to use.

9. Click Migrate Instances to create the destination instance.

10. Review the message that displays and click Migrate. The migration mapping is saved for later use.

    
    Description of the illustration bpel_migrate3.gif
    
    

    The following message is displayed.

    
    Description of the illustration bpel_migrate6.gif
    
    

11. Click OK.

12. If you want to view specific details about the migration, click Show Log.

13. Click the Instances tab.

14. Click the destination instance to which you migrated.

15. Click Flow.

    Note that the destination revision includes a link to the flow trace of the old revision.

16. Click the link.

    The flow trace of the old revision is displayed. A link to the new revision is displayed at the bottom of the flow. The older process instance is marked as closed and cancelled.

5.8.13.3 Viewing Logs

You can view migration logs in either of two ways:

• Clicking Show Log & Migrate in the Confirm dialog.

• Clicking the Show Log link in the upper right section of the Migration page.

If you are attempting to migrate a single BPEL process instance or bulk instances deployed to a middle tier Oracle SOA Suite installation and attempt to view the migration logs, the log window that displays may be empty. Perform the following steps to set the Oc4jSet parameter. This enables you to receive the correct log file output. Oracle recommends that you always set the Oc4jSet parameter.

1. Open the $ORACLE_HOME/Apache/Apache/conf/mod_oc4j.conf file.

2. Add add Oc4jSet flush true inside the tag IfModule mod_oc4j.c.

   <IfModule mod_oc4j.c> 
         Oc4jSet flush true 
         </IfModule> 
   

3. Restart Oracle HTTP Server to enable the configuration change.