Migrating WebSphere Business Integration Server Foundation BPEL Java snippets

IBM BPM, V8.0.1, All platforms > Migrating and upgrading your IBM BPM environment > Migrating from other products > Migrating from WebSphere Studio Application Developer Integration Edition > Additional migration information > Migrating to the SCA programming model
Migrating WebSphere Business Integration Server Foundation BPEL Java snippets

For any BPEL processes that contain Java™ snippets, this section details how to migrate from the old Java snippet API to the new Java snippet API, where the data flowing through the application is stored as Eclipse Service Data Objects (SDOs).

See the section "Migrating from the WSIFMessage API calls to SDO APIs" for migration steps to perform specific to the WSIFMessage to SDO transition.
Whenever possible, the snippets are automatically migrated by the migration wizard, but there are snippets that the migration wizard cannot fully migrate. This requires extra manual steps to complete the migration. See the topic "Limitations of source artifact migration" for details on the types of Java snippets that must be migrated manually. Whenever one of these snippets is encountered, the Migration wizard will explain why it cannot be automatically migrated and issue a warning or error message.
The following table details the changes in the BPEL Java snippet programming model and API from Process Choreographer version 5.1 to 6.x and later:
Changes and solutions for migrating WebSphere Business Integration Server Foundation BPEL Java snippets
Change Solution
WSIFMessage-based wrapper classes are no longer generated for WSDL message types, nor are the Java bean helper classes generated for complex schema types. BPEL variables can be directly accessed by name. If that for BPEL variables whose WSDL message definition has a single part, these variables will now directly represent the part instead of having a wrapper around the actual data. Variables whose message type has multiple parts will have a DataObject wrapper around the parts (where the wrapper in WebSphere Application Developer Integration Edition was a WSIFMessage).
Because BPEL variables can be used directly in 6.x and later snippets, there is less need for local variables than there was in 5.1.
The strongly-typed getters for the BPEL variables implicitly initialized the WSIFMessage wrapper object around the message parts. There is no ‘wrapper' object for BPEL variables whose WSDL message definition has only a single part: in this case the BPEL variables directly represent the part. (In the case where the single part is an XSD simple type, the BPEL variable will be represented as the Java object wrapper type such as java.lang.String, java.lang.Integer, and so on.) BPEL variables with multi-part WSDL message definitions are handled differently: there is still a wrapper around the parts and this DataObject wrapper must be explicitly initialized in the 6.x and later Java snippet code if it has not already been set by a previous operation.
If any local variables from the 5.1 snippets had the same name as the BPEL variable, there might be conflicts, so try to remedy this situation if possible.
WSIFMessage objects are no longer used to represent BPEL variables. If any custom Java classes invoked from the Java snippets have a WSIFMessage parameter, they will need to be migrated so that they accept/return a DataObject.
Strongly-typed getter methods for BPEL variables are no longer available. The variables can be directly accessed by name. If that for BPEL variables whose WSDL message definition has a single-part, these variables will now directly represent the part instead of having a wrapper around the actual data. Variables whose message type has multiple parts will have a DataObject wrapper around the parts (where the wrapper in WebSphere Application Developer Integration Edition was a WSIFMessage).
Strongly-typed setter methods for BPEL variables are no longer available. The variables can be directly accessed by name. If that for BPEL variables whose WSDL message definition has a single part, these variables will now directly represent the part instead of having a wrapper around the actual data. Variables whose message type has multiple parts will have a DataObject wrapper around the parts (where the wrapper in WebSphere Application Developer Integration Edition was a WSIFMessage).
Weakly-typed getter methods for BPEL variables that return a WSIFMessage are no longer available.
The variables can be directly accessed by name. If that for BPEL variables whose WSDL message definition has a single part, these variables will now directly represent the part instead of having a wrapper around the actual data. Variables whose message type has multiple parts will have a DataObject wrapper around the parts (where the wrapper in WebSphere Application Developer Integration Edition was a WSIFMessage).
If that there were two variations of the getVariableAsWSIFMessage method:
getVariableAsWSIFMessage(String variableName)
getVariableAsWSIFMessage(String variableName, boolean forUpdate)
For a Java snippet activity, the default access is read-write. You can change this to read-only by specifying @bpe.readOnlyVariables with the list of names of the variables in a comment in the snippet.
For example, you could set variable B and variable D to read only as follows:
variableB.setString("/x/y/z", variableA.getString("/a/b/c")); 
// @bpe.readOnlyVariables names="variableA"
variableD.setInt("/x/y/z", variableC.getInt("/a/b/c")); 
// @bpe.readOnlyVariables names="variableC"
Additionally, if you have a Java snippet in a condition, the variables are read-only by default, but you can make them read-write by specifying @bpe.readWriteVariables....
Weakly-typed setter methods for BPEL variables are no longer available. The variables can be directly accessed by name. If that for BPEL variables whose WSDL message definition has a single part, these variables will now directly represent the part instead of having a wrapper around the actual data. Variables whose message type has multiple parts will have a DataObject wrapper around the parts (where the wrapper in WebSphere Application Developer Integration Edition was a WSIFMessage).
Weakly-typed getter methods for BPEL variables message parts are not appropriate for single-part messages and have changed for multi-part messages.
Migrate to the weakly-typed getter method for BPEL variables (DataObject's) properties.
If that for BPEL variables whose WSDL message definition has a single-part, the BPEL variable directly represents the part and the variable should be accessed directly without using a getter method.
There were two variations of the getVariablePartAsObject method:
getVariablePartAsObject(String variableName, String partName)
getVariablePartAsObject(String variableName, String partName,boolean 
forUpdate)
For multi-part messages, equivalent functionality is provided by this method in 6.x and later releases:
getVariableProperty(String variableName, QName propertyName);  		
In 6.x and later releases, there is no notion of using a variable for read-only access (which was the case in 5.1 for the first method described in the previous section, as well as the second method with forUpdate='false').
The variable is directly used in the 6.x and later snippet and it is always able to be updated.
Weakly-typed setter methods for BPEL variables' message parts are not appropriate for single-part messages and have changed for multi-part messages.
Migrate to the weakly-typed setter method for BPEL variables' (DataObject's) properties.
If that for BPEL variables whose WSDL message definition has a single-part, the BPEL variable directly represents the part and the variable should be accessed directly without using a setter method.
Calls to the following method must be migrated:
setVariableObjectPart(String variableName, String partName, 
Object data)  
For multi-part messages, equivalent functionality is provided by this method in 6.x and later releases:
setVariableProperty(String variableName, QName propertyName, Serializable value);
Strongly-typed getter methods for BPEL partner links are no longer available. Migrate to the weakly-typed getter methods for BPEL partner links.
Strongly-typed setter methods for BPEL partner links are no longer available. Migrate to the weakly-typed setter methods for BPEL partner links.
Strongly-typed getter methods for BPEL correlation sets are no longer available.
V5.1 Snippet:
String corrSetPropStr = 
getCorrelationSetCorrSetAPropertyCustomerName();
int corrSetPropInt = 
getCorrelationSetCorrSetBPropertyCustomerId();
V6.x and later Snippet:
String corrSetPropStr = (String) getCorrelationSetProperty
(“CorrSetA”, new QName(“CustomerName”));
int corrSetPropInt = ((Integer) getCorrelationSetProperty 
(“CorrSetB”, new QName(“CustomerId”))).intValue();
Additional parameter needed for the weakly-typed getter methods for BPEL activity custom properties.
V5.1 Snippet:
String val = getActivityCustomProperty(“propName”);
V6.x and later Snippet:
String val = getActivityCustomProperty
(“name-of-current-activity”, “propName”);
Additional parameter needed for the weakly-typed setter methods for BPEL activity custom properties.
V5.1 Snippet:
String newVal = “new value”;
setActivityCustomProperty(“propName”, newVal); 
V6.x and later Snippet:
String newVal = “new value”;
setActivityCustomProperty(“name-of-current-activity”, 
“propName”, newVal);
The raiseFault(QName faultQName, Serializable message) method no longer exists. Migrate to the raiseFault(QName faultQName, String variableName) where possible; otherwise migrate to the raiseFault(QName faultQName) method or create a new BPEL variable for the Serializable object.
: Migrating to the SCA programming model

Change	Solution
WSIFMessage-based wrapper classes are no longer generated for WSDL message types, nor are the Java bean helper classes generated for complex schema types.	BPEL variables can be directly accessed by name. If that for BPEL variables whose WSDL message definition has a single part, these variables will now directly represent the part instead of having a wrapper around the actual data. Variables whose message type has multiple parts will have a DataObject wrapper around the parts (where the wrapper in WebSphere Application Developer Integration Edition was a WSIFMessage). Because BPEL variables can be used directly in 6.x and later snippets, there is less need for local variables than there was in 5.1. The strongly-typed getters for the BPEL variables implicitly initialized the WSIFMessage wrapper object around the message parts. There is no ‘wrapper' object for BPEL variables whose WSDL message definition has only a single part: in this case the BPEL variables directly represent the part. (In the case where the single part is an XSD simple type, the BPEL variable will be represented as the Java object wrapper type such as java.lang.String, java.lang.Integer, and so on.) BPEL variables with multi-part WSDL message definitions are handled differently: there is still a wrapper around the parts and this DataObject wrapper must be explicitly initialized in the 6.x and later Java snippet code if it has not already been set by a previous operation. If any local variables from the 5.1 snippets had the same name as the BPEL variable, there might be conflicts, so try to remedy this situation if possible.
WSIFMessage objects are no longer used to represent BPEL variables.	If any custom Java classes invoked from the Java snippets have a WSIFMessage parameter, they will need to be migrated so that they accept/return a DataObject.
Strongly-typed getter methods for BPEL variables are no longer available.	The variables can be directly accessed by name. If that for BPEL variables whose WSDL message definition has a single-part, these variables will now directly represent the part instead of having a wrapper around the actual data. Variables whose message type has multiple parts will have a DataObject wrapper around the parts (where the wrapper in WebSphere Application Developer Integration Edition was a WSIFMessage).
Strongly-typed setter methods for BPEL variables are no longer available.	The variables can be directly accessed by name. If that for BPEL variables whose WSDL message definition has a single part, these variables will now directly represent the part instead of having a wrapper around the actual data. Variables whose message type has multiple parts will have a DataObject wrapper around the parts (where the wrapper in WebSphere Application Developer Integration Edition was a WSIFMessage).
Weakly-typed getter methods for BPEL variables that return a WSIFMessage are no longer available.	The variables can be directly accessed by name. If that for BPEL variables whose WSDL message definition has a single part, these variables will now directly represent the part instead of having a wrapper around the actual data. Variables whose message type has multiple parts will have a DataObject wrapper around the parts (where the wrapper in WebSphere Application Developer Integration Edition was a WSIFMessage). If that there were two variations of the getVariableAsWSIFMessage method: getVariableAsWSIFMessage(String variableName) getVariableAsWSIFMessage(String variableName, boolean forUpdate) For a Java snippet activity, the default access is read-write. You can change this to read-only by specifying @bpe.readOnlyVariables with the list of names of the variables in a comment in the snippet. For example, you could set variable B and variable D to read only as follows: variableB.setString("/x/y/z", variableA.getString("/a/b/c")); // @bpe.readOnlyVariables names="variableA" variableD.setInt("/x/y/z", variableC.getInt("/a/b/c")); // @bpe.readOnlyVariables names="variableC" Additionally, if you have a Java snippet in a condition, the variables are read-only by default, but you can make them read-write by specifying @bpe.readWriteVariables....
Weakly-typed setter methods for BPEL variables are no longer available.	The variables can be directly accessed by name. If that for BPEL variables whose WSDL message definition has a single part, these variables will now directly represent the part instead of having a wrapper around the actual data. Variables whose message type has multiple parts will have a DataObject wrapper around the parts (where the wrapper in WebSphere Application Developer Integration Edition was a WSIFMessage).
Weakly-typed getter methods for BPEL variables message parts are not appropriate for single-part messages and have changed for multi-part messages.	Migrate to the weakly-typed getter method for BPEL variables (DataObject's) properties. If that for BPEL variables whose WSDL message definition has a single-part, the BPEL variable directly represents the part and the variable should be accessed directly without using a getter method. There were two variations of the getVariablePartAsObject method: getVariablePartAsObject(String variableName, String partName) getVariablePartAsObject(String variableName, String partName,boolean forUpdate) For multi-part messages, equivalent functionality is provided by this method in 6.x and later releases: getVariableProperty(String variableName, QName propertyName); In 6.x and later releases, there is no notion of using a variable for read-only access (which was the case in 5.1 for the first method described in the previous section, as well as the second method with forUpdate='false'). The variable is directly used in the 6.x and later snippet and it is always able to be updated.
Weakly-typed setter methods for BPEL variables' message parts are not appropriate for single-part messages and have changed for multi-part messages.	Migrate to the weakly-typed setter method for BPEL variables' (DataObject's) properties. If that for BPEL variables whose WSDL message definition has a single-part, the BPEL variable directly represents the part and the variable should be accessed directly without using a setter method. Calls to the following method must be migrated: setVariableObjectPart(String variableName, String partName, Object data) For multi-part messages, equivalent functionality is provided by this method in 6.x and later releases: setVariableProperty(String variableName, QName propertyName, Serializable value);
Strongly-typed getter methods for BPEL partner links are no longer available.	Migrate to the weakly-typed getter methods for BPEL partner links.
Strongly-typed setter methods for BPEL partner links are no longer available.	Migrate to the weakly-typed setter methods for BPEL partner links.
Strongly-typed getter methods for BPEL correlation sets are no longer available.	V5.1 Snippet: String corrSetPropStr = getCorrelationSetCorrSetAPropertyCustomerName(); int corrSetPropInt = getCorrelationSetCorrSetBPropertyCustomerId(); V6.x and later Snippet: String corrSetPropStr = (String) getCorrelationSetProperty (“CorrSetA”, new QName(“CustomerName”)); int corrSetPropInt = ((Integer) getCorrelationSetProperty (“CorrSetB”, new QName(“CustomerId”))).intValue();
Additional parameter needed for the weakly-typed getter methods for BPEL activity custom properties.	V5.1 Snippet: String val = getActivityCustomProperty(“propName”); V6.x and later Snippet: String val = getActivityCustomProperty (“name-of-current-activity”, “propName”);
Additional parameter needed for the weakly-typed setter methods for BPEL activity custom properties.	V5.1 Snippet: String newVal = “new value”; setActivityCustomProperty(“propName”, newVal); V6.x and later Snippet: String newVal = “new value”; setActivityCustomProperty(“name-of-current-activity”, “propName”, newVal);
The raiseFault(QName faultQName, Serializable message) method no longer exists.	Migrate to the raiseFault(QName faultQName, String variableName) where possible; otherwise migrate to the raiseFault(QName faultQName) method or create a new BPEL variable for the Serializable object.