52 Customizing SOA Composite Applications
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:
52.2.2 How to Create the Customizable Composite
To create the customizable composite:
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.
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:
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:
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:
-
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" -
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
-
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 valueCommunications
to theindustry
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).
-
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.
-
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:
-
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.
-
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 valuesNorth America
andAsia Pacific
to thesite
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).
-
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.