This chapter describes how to customize SOA composite applications with the customization feature available with a BPEL process service component.
This chapter includes the following sections:
This section describes the life cycle for customizing SOA composite applications. For example, assume the following organizations require use of the same composite, but with slight modifications:
A core applications development team
A vertical applications team
A customer
The core applications development team creates a base customizable composite and delivers it to a vertical applications team that customizes it for a certain industry (for example, telecommunications). The tailored solution is then sold to a telecommunications customer that further customizes the composite for their specific geographic business needs. Essentially, there is a base composite and several layers of customized composites. At a later time in the composite life cycle, the core applications development team creates the next version of the base composite, triggering an upgrade cycle for the vertical applications team and the customer.
Note:
Do not customize the same SOA composite application for different layer values. Only a single layer value for customization is supported. If you must support another layer value, always import the base composite into a different project and change the composite name to be specific to the layer value you want to customize. This approach is also useful for deployments in which you do not want to deploy different layer values with the same composite name.This section provides an overview of the steps required for creating the customizable, base SOA composite application.
To create the customizable composite:
Start Oracle JDeveloper and select the Default Role.
From the File menu, select New > Applications > SOA Application, and click OK.
Follow the steps in the Create SOA Application wizard.
On the Create SOA Application dialog, select both Composite With BPEL Process and the Customizable checkbox.
Design the BPEL process.
Customize the BPEL process by creating a scope activity. This action is required because by default the BPEL process is not customizable.
Note:
You can only customize thecomposite.xml
file, .bpel
file (for Oracle BPEL Process Manager), .mplan
file (for Oracle Mediator), and .componentType
file when using Oracle JDeveloper in the Customization Developer role.Right-click the scope and select Customizable.
In the Application Navigator, expand Application Resources > Descriptors > ADF META_INF.
Open the adf-config.xml file and select the MDS Configuration tab.
Click the Add icon to add the required customization classes, as shown in Figure 43-1.
In real environments, the customization classes are provided by the core applications team. When you use your own customization classes, you must add your customization class JAR file to your project to make the classes available for the adf-config.xml file.
Right-click the SOA project and select Deploy. This creates a JAR file package. This JAR is also known as a SOA archive (SAR).
Check the application into a source code control system. The file is now ready for delivery to the vertical applications team.
For information on how to write customization classes, see Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
This section describes how to create customization classes. In this example, you create a class for a customization layer named MyCustomizationLayer
.
To create customization classes:
Invoke the Create Java Class Wizard in Oracle JDeveloper by selecting File > New > General > Java > Java Class. If this selection does not appear, ensure that the All Technologies tab is selected at the top of the New Gallery dialog.
Create a Java class extending from the following class:
oracle.tip.tools.ide.fabric.custom.GenericSOACustomizationClass
Provide the following content for the customization class.
package myCustomizationPackage; import oracle.tip.tools.ide.fabric.custom.GenericSOACustomizationClass; public class MyCustomizationClass extends GenericSOACustomizationClass { public MyCustomizationClass() { super(); // set the customization layer name setName("MyCustomizationLayer"); } }
Note that the Create Java Class Wizard automatically generates the following content:
package myCustomizationPackage; import oracle.tip.tools.ide.fabric.custom.GenericSOACustomizationClass; public class MyCustomizationClass extends GenericSOACustomizationClass { public MyCustomizationClass(String string, String string1) { super(string, string1); } public MyCustomizationClass() { super(); } }
For the customization class to have the correct customization layer, set the customization layer name by adding the following to the constructor without parameters.
// set the customization layer name setName("MyCustomizationLayer");
You can also optionally remove the constructor with parameters.
To make the customization class effective, compile the customization class by building/making the SOA project.
Ensure that the build succeeds.
You can add an XML schema or WSDL document in Oracle JDeveloper when logged in with the Customization Developer role.
Right-click the Oracle SOA Suite project in the Application Navigator.
Select SOA.
Select the artifact to create:
Create XML Schema
Invokes the Create XML Schema dialog for adding a new XML schema file in the project. When complete, the new schema file automatically opens.
Create WSDL Document
Invokes the Create WSDL dialog to add a new WSDL file in the project.
You can search for customized activities in a BPEL process in Oracle JDeveloper.
To search for customized activities:
Access Oracle JDeveloper using the Customization Developer role.
In the Search menu for the BPEL process at the top of the designer, select Customization Search, as shown in Figure 43-2.
The search results display in the Search for Customizations tab of the Log window at the bottom of the designer.
The source of any artifact in Oracle JDeveloper (except for new artifacts created in the Customization Developer role) is editable in the Customization Developer role of another application.
For example:
Create a SOA composite application with the Customization Developer option selected.
Edit a composite.xml
property in the composite (as an example, add the passThroughHeader
property for an Oracle Mediator service component included in the composite).
Deploy the composite to a SAR file, and import the SAR file into another new composite.
Restart Oracle JDeveloper and open the new composite using the Customization Developer role.
Go to the Source view of the composite.xml
file, and from the Property Inspector attempt to modify the passThroughHeader property value.
Note that the property is editable.
In the customization role, the metadata repository (MDS) merges customizations with the base metadata. The merging can result in an invalid XML document against its schema. MDS merging does not invoke a schema validation to ensure that the merging always creates a valid XML document. This can cause a problem for MDS clients that rely on the validity of the metadata to render their metadata UI editors.
Whenever a SOA file such as composite.xml
becomes invalid, you must switch to Source view in Oracle JDeveloper to directly fix the XML source. If Source view is not editable (for example, you have accessed Oracle JDeveloper using the Customization Developer role), you must use the Structure window in Oracle JDeveloper to fix the XML source.
For example, assume you created a base SOA composite application with a BPEL process that included a customized scope. The SAR file for the base application was then imported into a new application in which the following components were added when accessing Oracle JDeveloper with the Customization Developer role:
An outbound file adapter
An invoke activity (added to the customizable scope) for invoking the file adapter
When version two of the base SOA composite application was created, a synchronous Oracle Mediator service component was added, which caused the routing rules to the BPEL process service component to be updated.
The SAR file for version two of the base application was then imported into the customized application. When the user accessed Oracle JDeveloper with the Customization Developer role, an invalid composite error was displayed. The composite.xml
file in the Structure window showed the following invalid structure for the sequence of service components and reference binding components.
<component> </component> <reference> </reference> <component> </component>
The <reference>
component (in this case, the outbound file adapter added when the user accessed Oracle JDeveloper with the Customization Developer role in version one of the base application) should have displayed last.
<component> </component> <component> </component> <reference> </reference>
To resolve this error, go to the Structure window and copy and paste these components into the correct order. This action resolves the composite validation error.
Assume you perform the following steps.
Customize version 1 of a SOA composite application.
For example, while using Oracle JDeveloper in the Customization Developer role, you add new activities into a customizable scope activity of the BPEL process. The BPEL process creates a sequence activity into which the new activities are added.
Create version 2 of the SOA composite application.
In the version 2 composite, if new activities are added into the same customizable scope, a new sequence activity is created.
Import version 2 of the SOA composite application into a customized application.
Open Oracle JDeveloper in Customization Developer role.
The following error is displayed:
Sequence element is not expected
Perform the following steps to resolve the conflict:
Go to the Structure window.
Expand the sequence.
Copy each component and paste it into another sequence.
Delete the components in the sequence from which they were copied.
Delete the sequence when it is empty.
When you deploy or compile a customized application at the core application, vertical application, or customer level, warning messages describing unexpected ID attributes are displayed, as shown in Example 43-1. You can safely ignore these messages. These messages display because the schema definition does not include these simple-type elements, which is expected behavior. These messages do not prevent the customized composite from being successfully deployed.
Example 43-1 Deployment or Compilation Errors
[scac] warning: in /scratch/qizhong/my-jdev/mywork/CompositeTestApp2/Project2/composite.xml(22,32): Schema validation failed for /scratch/qizhong/my-jdev/mywork/CompositeTestApp2/Project2/composite.xml<Line 22, Column 32>: XML-24535: (Error) Attribute 'http://www.w3.org/XML/1998/namespace:id' not expected. [scac] warning: in /scratch/qizhong/my-jdev/mywork/CompositeTestApp2/Project2/composite.xml(23,32): Schema validation failed for /scratch/qizhong/my-jdev/mywork/CompositeTestApp2/Project2/composite.xml<Line 23, Column 32>: XML-24535: (Error) Attribute 'http://www.w3.org/XML/1998/namespace:id' not expected.
This section provides an overview of the steps required for customizing the vertical SOA composite application.
To customize the vertical application:
Add the layer values for the customization layers through either of the following methods:
To add application-specific layer values, click the Configure Design Time Customization Layer Values link, as shown in Figure 43-3.
Figure 43-3 Configure Design Time Customization Layer Values Link
Add the layer values.
After you specify the values and save the file, the CustomizationLayerValues.xml file is displayed in the MDS DT folder under Application Resources. You can double-click the file in this location to open an editor for making additional modifications.
or
To add global values applicable to all applications, open the CustomizationLayerValues.xml
file in $JDEV_HOME/jdeveloper/jdev
and add the layer values for the customization layers. For example, add the value Communications
to the industry
layer.
<cust-layers xmlns="http://xmlns.oracle.com/mds/dt"> <cust-layer name="industry"> <cust-layer-value value="communications" display-name="Communications"/> </cust-layer> </cust-layers>
Start Oracle JDeveloper and select the Default Role.
Create a new SOA application with a different name than the core application.
From the File menu, select Import > SOA Archive Into SOA Project.
Click Browse to select the composite archive JAR file created by the core application team in Section 43.2, "Creating the Customizable Composite."
In the Composite Name field, enter a different name than the core SOA project.
Note:
Do not select any SOA project. You must create a new SOA project for the JAR file that you import.Select the Import for Customization checkbox.
From the Tools menu, select Preferences -> Roles > Customization Developer.
Restart Oracle JDeveloper.
The Customization Context dialog displays the available customization layers and layer values.
Select a layer and value to customize, as shown in Figure 43-4 (for this example, layer industry and value Communications are selected).
In the SOA Composite Editor, double-click the BPEL process to access Oracle BPEL Designer.
You can only edit scope activities that have been set to customizable. In the example shown in Figure 43-5, the core applications team set only one scope to be customizable. The other activities in the BPEL process are disabled and cannot be edited.
Right-click the SOA project in the Application Navigator and select Deploy to create a JAR file of the customized composite (SAR).
Since deployment is invoked with the customization role enabled, the base composite with the appropriate layers based on the current customization context is automatically merged.
Check in the application to a source code control system.
The JAR file contains a merged composite that in turn acts as a base process for the next level of customization. The JAR file can now be delivered to the customer.
Note:
You can create WSDL and XSD files while running Oracle JDeveloper in the Customization Developer role. In the Application Navigator, right-click the project name and select SOA > Create WSDL or SOA > Create XSD.This section provides an overview of the steps required for customizing the customer version of the SOA composite application.
How to customize the customer version:
Add the layer values for the customization layers through either of the following methods:
To add application-specific layer values, click the Configure Design Time Customization Layer Values link, as shown in Step 1 of Section 43.3, "Customizing the Vertical Application."
Add the layer values.
After you specify the values and save the file, the CustomizationLayerValues.xml file is displayed in the MDS DT folder under Application Resources. You can double-click the file in this location to open an editor for making additional modifications.
or
To add global values applicable to all applications, open the CustomizationLayerValues.xml
file in $JDEV_HOME/jdeveloper/jdev
and add the layer values for the customization layers. For example, add the values North America
and Asia Pacific
to the site
layer.
<cust-layers xmlns="http://xmlns.oracle.com/mds/dt"> <cust-layer name="site"> <cust-layer-value value="communications" display-name="North America"/> <cust-layer-value value="communications" display-name="Asia Pacific"/> </cust-layer> </cust-layers>
Start Oracle JDeveloper and select the Default Role.
Create a new SOA application with a different name than the core application or customized application.
From the File menu, select Import > SOA Archive Into SOA Project.
Click Browse to select the composite archive JAR file created by the vertical applications team in Section 43.3, "Customizing the Vertical Application."
Select the Import for Customization checkbox.
From the Tools menu, select Preferences -> Roles > Customization Developer.
Restart Oracle JDeveloper.
The Customization Context dialog displays the available customization layers and layer values.
Select a layer and value to customize, as shown in Figure 43-6 (for this example, layer site and value North America are selected).
Customize the BPEL process.
Right-click the SOA project and select Deploy to create a JAR file (SAR) for the North American region.
Check the application into a source code control system.
This section provides an overview of the steps required for upgrading the SOA composite application to the next version.
The core application team fixes bugs, makes product enhancements. and creates the next version of the composite.
To upgrade the core application team composite:
Check out the application created in Section 43.2, "Creating the Customizable Composite" from source control.
Start Oracle JDeveloper and select the Default Role.
Make bug fixes and product enhancements.
Deploy the composite to create the next revision of the JAR file.
Deliver the JAR file to the vertical applications team.
The vertical applications team customizes the new base composite to create a version of the JAR file.
To upgrade the vertical application team composite:
Check out the application created in Section 43.3, "Customizing the Vertical Application" from source control.
Start Oracle JDeveloper and select the Default Role.
Open the checked-out application.
Select the project node in the Application Navigator to set the current project context. This is important because the import command in the next step imports the SOA archive into the selected project to upgrade the base.
From the File menu in Oracle JDeveloper, import the new revision of the JAR file created in Section 43.5.1, "How to Upgrade the Core Application Team Composite."
From the Tools menu, select Preferences -> Roles > Customization Developer.
Restart Oracle JDeveloper.
In the Customization Context dialog, select a layer and value to customize (for example, select layer industry and value Communications).
Open the BPEL process to see if the new base composite can be merged with layers for the above selected context.
Review the log window for potential warnings and errors.
If required, fix errors and warnings by modifying the process. This edits the layers behind the scenes.
Deploy the composite to create the next revision of the customized JAR file and deliver it to the customer for an upgrade.
The customer follows the same procedures as the vertical applications team in Section 43.5.2, "How to Upgrade the Vertical Application Team Composite" to apply their layers to the new base composite.