52 Customizing SOA Composite Applications

This chapter describes how to customize SOA composite applications with the customization feature available with a BPEL process service component. It describes how to create a customizable application, customize the vertical version of the application, and customize the customer version of the application. It also describes how to upgrade to the next version of the application.

This chapter includes the following sections:

52.1 Introduction to Customizing SOA Composite Applications

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.

Layer values are the values for a given customization layer. It is a one-to-many relationship from a layer to its layer values. You select a layer value from a layer to perform customizations. For example, assume you specify a customization class representing a customization layer called Country. You can then specify countries for its values, such as USA, China, and India. When you restart Oracle JDeveloper in the Customization Developer role to perform customizations, you must select one of the layer values (that is, a country) of the layer from the Oracle JDeveloper Customization Context window such as USA, which means you want to create the customization for that country.

52.2 Creating the Customizable Composite

This section provides an overview of the steps required for creating the customizable, base SOA composite application.

52.2.1 How to Create Customization Classes

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 > From Gallery > General > Java.

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");
    }
}

For the customization class to have the correct customization layer, the customization layer name must be set 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.

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();
    }
}

To make the customization class effective, compile the customization class by building the SOA project.

In the Applications window, right-click the SOA project and select Build SOA_project_name.jpr.
Ensure that the build succeeds by reviewing the output in the Log window at the bottom of Oracle JDeveloper.

52.2.2 How to Create the Customizable Composite

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.
In the Configure SOA Settings dialog of the Create SOA Application wizard (Step 3 of 3), select both Composite With BPEL Process and the Customizable check box, and click Finish.
Design the BPEL process.
Note:

If you design a transformation, note the following customization restrictions in the XSLT Map Editor:
- The Create in Template option that is displayed by right-clicking a node in the target panel is disabled.
- The Test XSL Map option is disabled for the call templates and apply templates for imported XSL files. This option works for named templates, but not for template rules with a match attribute.
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 the composite.xml file, .bpel file (for Oracle BPEL Process Manager), .xsl map file, and .mplan file (for Oracle Mediator) when logged into Oracle JDeveloper with the Customization Developer role.
Right-click the scope and select Customizable. If you expand the scope and right-click it, you do not see the Customizable option.
In the Applications window, expand Application Resources > Descriptors > ADF META_INF.
Open the adf-config.xml file and select the MDS tab.
Click the Add icon to add the required customization classes, as shown in Figure 52-1.

In real environments, the customization classes are provided by the core applications team, as described in the example scenario in Introduction to Customizing SOA Composite Applications. 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.

Figure 52-1 Customization Classes

Description of "Figure 52-1 Customization Classes"
Right-click the SOA project and select Deploy.

Note:

You can receive a compilation error if your scope activity is empty. You can drag an empty activity into the scope activity to pass compilation.
On the Deployment Action page, select Generate SAR File. 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 Developing Fusion Web Applications with Oracle Application Development Framework.

52.2.3 How to Add an XSD or WSDL File

To add an XSD or WSDL file:

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 Applications window.
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.

52.2.4 How to Search for Customized Activities in a BPEL Process

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 52-2.

Figure 52-2 Customization Search Option

Description of "Figure 52-2 Customization Search Option"

The search results display in the Search for Customizations tab of the Log window at the bottom of the designer.

52.2.5 What You May Need to Know About Resolving Validation Errors in Oracle JDeveloper

In the customization role, the Oracle Metadata Services (MDS) Repository merges customizations with the base metadata. The merging can result in an invalid XML document against its schema. MDS Repository 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 customizable 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. The following example provides details:

<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. The following example provides details.

<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.

52.2.6 What You May Need to Know About Resolving a Sequence Conflict

This section provides an example of how to resolve a sequence conflict.

To resolve a sequence complex:

Customize version 1 of a SOA composite application.

For example, while logged into Oracle JDeveloper with 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 the Customization Developer role.
The following error is displayed:
```
Sequence element is not expected
```

52.2.6.1 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.

52.2.7 What You May Need to Know About Compiling and Deploying a Customized Application

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 the following example. 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.

[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.

52.3 Customizing the Vertical Application

This section provides an overview of the steps required for customizing the vertical SOA composite application.

Note:

Do not customize the same SOA composite application for different layer values. Layer values are the customizations made to the base composite, as described in Introduction to Customizing SOA Composite Applications. 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.

52.3.1 How to Customize the Vertical Application

To customize the vertical application:

Add the layer values for the customization layers through either of the following methods:
1. To add application-specific layer values, click the Configure Design Time Customization Layer Values link, as shown in Figure 52-3.
  
  Figure 52-3 Configure Design Time Customization Layer Values Link
  
  Description of "Figure 52-3 Configure Design Time Customization Layer Values Link"
2. 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. The customization class provides the layer name and the CustomizationLayerValues.xml file provides the layer values. Both are required. You can double-click the file in this location to open an editor for making additional modifications.
or
1. 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 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 check box.
In the Applications window, right-click the project, and select SOA > Customizable.
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 52-4 (for this example, layer industry and value Communications are selected).

Figure 52-4 Customization Context

Description of "Figure 52-4 Customization Context"
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 52-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.

Figure 52-5 One Customizable Scope

Description of "Figure 52-5 One Customizable Scope"
Right-click the SOA project in the Applications window 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 logged into Oracle JDeveloper with the Customization Developer role. In the Applications window, right-click the project name and select SOA > Create WSDL Document or SOA > Create XML Schema.

52.4 Customizing the Customer Version

This section provides an overview of the steps required for customizing the customer version of the SOA composite application.

52.4.1 How to Customize the Customer Version

How to customize the customer version:

Add the layer values for the customization layers through either of the following methods:
1. To add application-specific layer values, click the Configure Design Time Customization Layer Values link, as shown in Step 1 of Customizing the Vertical Application.
2. 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
1. 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 Customizing the Vertical Application.
Select the Import for Customization check box.
From the Tools menu, select Switch 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 52-6 (for this example, the layer site and value North America are selected).

Figure 52-6 Customization Context

Description of "Figure 52-6 Customization Context"
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.

52.5 Upgrading the Composite

This section provides an overview of the steps required for upgrading the SOA composite application to the next version.

52.5.1 How to Upgrade the Core Application Team Composite

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 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.

52.5.2 How to Upgrade the Vertical Applications Team Composite

The vertical applications team customizes the new base composite to create a version of the JAR file.

To upgrade the vertical applications team composite:

Check out the application created in 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 Applications window 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 How to Upgrade the Core Application Team Composite.
From the Tools menu, select Switch Roles > Customization Developer.
Restart Oracle JDeveloper.
In the Customization Context dialog, select a layer and value to customize (for example, select the 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.

52.5.3 How to Upgrade the Customer Composite

The customer follows the same procedures as the vertical applications team in How to Upgrade the Vertical Applications Team Composite to apply their layers to the new base composite.