E Deployment Descriptor Properties

This appendix discusses deployment descriptor preference properties and deployment descriptor configuration properties.

This appendix contains the following topics:

Deployment Descriptor Preference Properties
Deployment Descriptor Configuration Properties
Summary

E.1 Deployment Descriptor Preference Properties

Preferences are simple name-value pair properties that are defined in the deployment descriptor of a BPEL process, and which are accessed at run time by the BPEL process. You can change the value of a preference from Oracle BPEL Console at run time, without having to redeploy the BPEL process.

Preferences enable BPEL process designers to externalize literal values from a process, enabling them to be altered without having to redeploy the entire BPEL process.

For example, if you design a process that automatically rejects expense requests that exceed 1000 dollars, and business requirements later change so that the maximum amount is increased to 1500 dollars, then you normally need to edit the process definition and redeploy. By defining a preference for the maximum amount in the deployment descriptor, the change can be performed at run time, without redeploying the process.

E.1.1 Defining a Preference Property

You can define preference values at run time from JDeveloper BPEL Designer. Click the Deployment Descriptor Properties icon shown in Figure E-1. This icon is located just above and to the left of the Diagram View.

Figure E-1 Deployment Descriptor Properties Icon

Description of "Figure E-1 Deployment Descriptor Properties Icon"

In the Deployment Descriptor Properties window, click the Preferences tab, as shown in Figure E-2.

Figure E-2 Deployment Descriptor Preference Properties in Oracle BPEL Console

Description of "Figure E-2 Deployment Descriptor Preference Properties in Oracle BPEL Console"

Click Create and enter a preference name. Edit the value in the Property Value field and click OK. The change takes effect immediately. Preferences you create in this way are reflected in bpel.xml, inside the preferences tag, as follows:

...
<preferences>
   <property name="MAX_AMOUNT">1000</property>
   <property name="DEFAULT_COSTCENTER">US23</property>
</preferences>
...

E.1.2 Updating a Preference at Run Time

You can update preference values at run time in Oracle BPEL Console, as shown in Figure E-3. Select the process, then select the Descriptor tab to display the deployment descriptor for the process, including any preferences. Update the preference value, and click Update descriptor. The change takes effect immediately.

Figure E-3 Updating BPEL Process Preferences at Run Time

Description of "Figure E-3 Updating BPEL Process Preferences at Run Time"

E.1.3 Getting the Value of a Preference within a BPEL Process

The value of a preference can be read by a BPEL process using the XPath extension function ora:getPreference(String preferenceName). This function can be used as part of a simple assign statement, used in condition expressions, or used as part of a more complex XPath expression.

E.1.4 Encrypting a Preference Value

You can encrypt the contents of a preference property. Encryption uses DES with the sunJCE security provider. The contents do not appear encrypted in JDeveloper BPEL Designer. The contents are encrypted at deployment only. The Encryption list (see Figure E-2) provides the following options:

No Need to Specify—Do not encrypt the contents.
Plain Text—The contents remain in plain text.
Encrypt—The contents are encrypted.

The property is also shown as a password field in the Configurations tab of the deployment descriptor.

The following example shows the XML code without encryption set and then with encryption set.

Without encryption set:

...
<preferences>
   <property name="secret">mySecretValue</property>
</preferences>
...

Or the XML without encryption can look as follows, although properties are stored as plaintext by default, so plaintext need not be specified explicitly.

...
<preferences>
   <property name="secret" encryption="plaintext">mySecretValue</property>
</preferences>
...

To tell the compiler and Oracle BPEL Server to encrypt a property, the XML looks like this:

...
<preferences>
   <property name="secret" encryption="encrypt">mySecretValue</property>
</preferences>
...

After the BPEL project is compiled, the compiler updates the copy of the bpel.xml file in the compiled JAR file (not the copy in the JDeveloper BPEL Designer project), so that the XML looks like this:

...
<preferences>
   <property name="secret" encryption="encrypted">ZAv9lfntAgy=</property>
</preferences>
...

Encryption works for any property tag in the descriptor, not just those in the preferences section, in case you want to encrypt properties in other sections.

Note:

Values of preferences can still be inferred by inspecting the audit trails of instances that contain values derived from the preference.

E.1.5 Use Case for Preference Properties

The Payment Processor demo (or PayDemo) demonstrates the use of a preference property.

E.2 Deployment Descriptor Configuration Properties

Configuration properties are specific properties used by the server, Oracle BPEL Console, or both. In Oracle BPEL Console, for example, the configuration properties are used to display a description of the process and default data in the test process window.

E.2.1 Defining a Configuration Property

You can define configuration properties at run time from JDeveloper BPEL Designer. Click the Deployment Descriptor Properties icon, located just above and to the left of the diagram view. (See Figure E-1.) In the Deployment Descriptor Properties window, click the Configurations tab, as shown in Figure E-4.

Figure E-4 Deployment Descriptor Configuration Properties in the Oracle BPEL Console

Description of "Figure E-4 Deployment Descriptor Configuration Properties in the Oracle BPEL Console"

Click Create and enter a configuration name. Edit the value in the Property Value field and click OK. The change takes effect immediately. Preferences you create in this way are reflected in bpel.xml.

See "Encrypting a Preference Value" for information about encrypting the contents of configuration properties.

Table E-1 lists the property names of the configurations deployment descriptor. For each configuration property, a description is provided, as well as the expected behavior of the server when it is changed.

Table E-1 Configuration Properties for the configurations Deployment Descriptor

Property Name	Description	On Change
`completionPersistLevel`	Sets the portion of the instance information that you want to save after the instance is completed. The default value is `all`, meaning the instance is saved in both `cube_instance` and `cube_scope` tables. The other value is `instanceHeader`, meaning only the metadata of the instances are saved in the `cube_instance` table. Note that this property can only be set if the `inMemoryOptimization` property is set to `True`.	NA
`completionPersistPolicy`	Configures how the instance data is saved. The default value is `on`, meaning the completed instance is saved normally. If this value is set to `deferred`, then the completed instance is saved, but with a different thread and in another transaction. If this value is set to be faulted, then only the faulted instances are saved. If this value is set to `off`, then no instances of this process are saved.	NA
`defaultInput`	The XML document that you want to use as input to test the process from Oracle BPEL Console.	Takes effect immediately
`initializeVariables`	Default value is `True`. If set to `False`, Oracle BPEL Console does not initialize the variables based on to-spec queries.	NA
`inMemoryOptimization`	Default value is `False`. This property can only be set to `True` if it does not have dehydration points. Activities like wait, receive, onMessage, and onAlarm create dehydration points in the process. If this property is set to `True`, Oracle BPEL Server tries to do `inMemory` optimization on the instances of this process on `to-spec` queries.	NA
`loadSchema`	Default value is `True`. If set to `False`, XML schemas are not loaded and Oracle BPEL Console becomes typeless.	NA
`noAlterWSDL`	Default value is `False`. If set to `True`, the compiler does not try to modify the process WSDL to add binding and service information.	NA
`optimizeVariableCopy`	Default value is `True`. If set to `False`, Oracle BPEL Server does not enable copy-on-write for an assign copy.	NA
`relaxTypeChecking`	Default value is `False`. If set to `True`, the compiler does not check type compatibility with an assign activity.	NA
`relaxXPathQName`	Default value is `False`. If set to `True`, the compiler throws exceptions for unqualified steps in the query. For example, where the correct form must be: `query="/ns1:payload/ns1:name"`, the following form passes compilation, if this flag is turned on: `query="/payload/name"`.	NA
`sensorActionLocation`	Location of the sensor action XML file that is used by Oracle BPEL Process Manager. The sensor action XML file configures the action rule for the events.	NA
`sensorLocation`	Location of the sensor XML file. The sensor XML file defines the list of sensors into which Oracle BPEL Process Manager logs events.	NA
`testIntroduction`	Introduction text that appears in the test console.	Takes effect immediately
`transaction`	When set to `participate`, the process produces a fault that is not handled by fault handlers, which calls the transaction to be rolled back.	Takes effect immediately
`serviceLevelAgreement`	Service Level Agreement (Process Completion Time) - Threshold for a commitment within which a process is completed for a specified time period. Value is an XML duration.	NA
`xpathValidation`	Default value is `True`. If set to `False`, the compiler does not validate the XPath queries.	NA

Table E-2 lists the configuration properties of sections of the partnerLinkBinding deployment descriptor. For each configuration property, a description is given as well as the expected behavior of Oracle BPEL Server when it is changed.

Table E-2 Configuration Properties for the partnerLinkBinding Deployment Descriptor

Property Name	Description	On Change
`callbackBindings`	List of bindings that the compiler generates for the `callback` `portType`. The default value is `soap`. You set multiple bindings separated by commas, for example: `jms, soap`. The first item is used as the preferred binding when calling back.	Recompile (not implemented)
`correlation`	Default value is `wsAddressing`. If this is set to `correlationSet`, this partner link is using the BPEL `correlationSet`.	If this is the process `partnerLink`, recompile (not implemented)
`contentType`	Sets special HTTP `contentType`. Example: `text/xml`	Takes effect immediately
`httpPassword`	For HTTP username/password authentication	Takes effect immediately
`httpUsername`	For HTTP username/password authentication	Takes effect immediately
`keepAlive`	If the server permits `keepAlive` connections, then this Boolean property can be turned on to take advantage of it. Thus, connections to the same server are shared between invocations.	Takes effect immediately
`location`	URL that overrides the location defined in the WSDL. For SOAP over HTTP binding, this value overrides the `SOAPAddress`.	Takes effect immediately
`nonBlockingInvoke`	Default value is `False`. When this is set to `True`, Oracle BPEL Server spawns a separate thread to do the invocation so that the invoke activity does not block the instance.	Takes effect immediately
`retryInterval`	Number of seconds that Oracle BPEL Server waits between retries.	Takes effect immediately
`retryMaxCount`	Number of retries that Oracle BPEL Server attempts, if an invoke fails because of network problems.	Takes effect immediately
`sendXSIType`	Some legacy RPC-style Web services require the `xsi:type` to be set with every element in the input message. If this value is set to `True`, Oracle BPEL Process Manager populates the `xsi:type` of all the elements.	Takes effect immediately
`serviceProperties`	--	Takes effect immediately
`timeout`	Number of seconds in which a SOAP call times out. A remote fault is thrown if this happens.	Takes effect immediately
`wsdlLocation`	URL of the WSDL file that defines this partner link. This property must be present. The BPEL compiler needs this to validate the BPEL source. This can be an abstract WSDL in that only the `portTypes` and their dependencies need to be defined in the WSDL.	Recompile (not implemented)
`wsdlRuntimeLocation`	URL to the partner link WSDL. It is used on Oracle BPEL Server, which means that the concrete WSDL with all the service, port, and binding definitions is needed. This property is optional and defaults to the `wsdlLocation` property. This property also enables multiple URLs separated by blanks (spaces, new lines, and tabs). Therefore, Oracle BPEL Server tries sequentially if any URLs are not available.	Clear WSDL cache (not implemented)

E.3 Summary

This appendix discusses deployment descriptor preference properties and deployment descriptor configuration properties, and how to set them in JDeveloper BPEL Designer.