Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle SOA Suite
11g Release 1 (11.1.1.7)

Part Number E10224-20
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

46 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:

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

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.

46.2 Creating the Customizable Composite

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

46.2.1 How to Create the Customizable Composite

To create the customizable composite:

  1. Start Oracle JDeveloper and select the Default Role.

  2. From the File menu, select New > Applications > SOA Application, and click OK.

  3. Follow the steps in the Create SOA Application wizard.

  4. On the Create SOA Application dialog, select both Composite With BPEL Process and the Customizable checkbox.

  5. Design the BPEL process.

  6. 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), .mplan file (for Oracle Mediator), and .componentType file when logged into Oracle JDeveloper with the Customization Developer role.

  7. Right-click the scope and select Customizable.

  8. In the Application Navigator, expand Application Resources > Descriptors > ADF META_INF.

  9. Open the adf-config.xml file and select the MDS Configuration tab.

  10. Click the Add icon to add the required customization classes, as shown in Figure 46-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.

    Figure 46-1 Customization Classes

    Description of Figure 46-1 follows
    Description of "Figure 46-1 Customization Classes"

  11. Right-click the SOA project and select Deploy. This creates a JAR file package. This JAR is also known as a SOA archive (SAR).

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

46.2.2 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:

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

  2. Create a Java class extending from the following class:

    oracle.tip.tools.ide.fabric.custom.GenericSOACustomizationClass
    
  3. 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");
        }
    }
    

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

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

  6. Ensure that the build succeeds.

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

  1. Right-click the Oracle SOA Suite project in the Application Navigator.

  2. Select SOA.

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

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

  1. Access Oracle JDeveloper using the Customization Developer role.

  2. In the Search menu for the BPEL process at the top of the designer, select Customization Search, as shown in Figure 46-2.

    Figure 46-2 Customization Search Option

    Description of Figure 46-2 follows
    Description of "Figure 46-2 Customization Search Option"

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

46.2.5 What You May Need to Know About Editing Artifacts in a Customized Composite

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.

To edit artifacts in a customized composite:

  1. Create a SOA composite application with the Customization Developer option selected.

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

  3. Deploy the composite to a SAR file, and import the SAR file into another new composite.

  4. Restart Oracle JDeveloper and open the new composite using the Customization Developer role.

  5. Go to the Source view of the composite.xml file, and from the Property Inspector attempt to modify the passThroughHeader property value.

    The property is editable.

46.2.6 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 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. Example 46-1 provides details.

Example 46-1 Invalid Structure

<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. Example 46-2 provides details.

Example 46-2 Valid Structure

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

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

Assume you perform the following steps.

To resolve a sequence complex:

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

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

  3. Import version 2 of the SOA composite application into a customized application.

  4. Open Oracle JDeveloper in the Customization Developer role.

    The following error is displayed:

    Sequence element is not expected
    

Perform the following steps to resolve the conflict:

  1. Go to the Structure window.

  2. Expand the sequence.

  3. Copy each component and paste it into another sequence.

  4. Delete the components in the sequence from which they were copied.

  5. Delete the sequence when it is empty.

46.2.8 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 Example 46-3. 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 46-3 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. 

46.3 Customizing the Vertical Application

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

46.3.1 How to Customize the Vertical Application

To customize the vertical application:

  1. 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 46-3.

      Figure 46-3 Configure Design Time Customization Layer Values Link

      Description of Figure 46-3 follows
      Description of "Figure 46-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. 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>
      
  2. Start Oracle JDeveloper and select the Default Role.

  3. Create a new SOA application with a different name than the core application.

  4. From the File menu, select Import > SOA Archive Into SOA Project.

  5. Click Browse to select the composite archive JAR file created by the core application team in Section 46.2, "Creating the Customizable Composite."

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

  7. Select the Import for Customization checkbox.

  8. From the Tools menu, select Preferences > Roles > Customization Developer.

  9. Restart Oracle JDeveloper.

    The Customization Context dialog displays the available customization layers and layer values.

  10. Select a layer and value to customize, as shown in Figure 46-4 (for this example, layer industry and value Communications are selected).

    Figure 46-4 Customization Context

    Description of Figure 46-4 follows
    Description of "Figure 46-4 Customization Context"

  11. 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 46-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 46-5 One Customizable Scope

    Description of Figure 46-5 follows
    Description of "Figure 46-5 One Customizable Scope"

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

  13. 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 Application Navigator, right-click the project name and select SOA > Create WSDL or SOA > Create XSD.

46.4 Customizing the Customer Version

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

46.4.1 How to Customize the Customer Version

How to customize the customer version:

  1. 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 Section 46.3, "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>
      
  2. Start Oracle JDeveloper and select the Default Role.

  3. Create a new SOA application with a different name than the core application or customized application.

  4. From the File menu, select Import > SOA Archive Into SOA Project.

  5. Click Browse to select the composite archive JAR file created by the vertical applications team in Section 46.3, "Customizing the Vertical Application."

  6. Select the Import for Customization checkbox.

  7. From the Tools menu, select Preferences > Roles > Customization Developer.

  8. Restart Oracle JDeveloper.

    The Customization Context dialog displays the available customization layers and layer values.

  9. Select a layer and value to customize, as shown in Figure 46-6 (for this example, the layer site and value North America are selected).

    Figure 46-6 Customization Context

    Description of Figure 46-6 follows
    Description of "Figure 46-6 Customization Context"

  10. Customize the BPEL process.

  11. Right-click the SOA project and select Deploy to create a JAR file (SAR) for the North American region.

  12. Check the application into a source code control system.

46.5 Upgrading the Composite

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

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

  1. Check out the application created in Section 46.2, "Creating the Customizable Composite" from source control.

  2. Start Oracle JDeveloper and select the Default Role.

  3. Make bug fixes and product enhancements.

  4. Deploy the composite to create the next revision of the JAR file.

  5. Deliver the JAR file to the vertical applications team.

46.5.2 How to Upgrade the Vertical Application Team Composite

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

To upgrade the vertical application team composite:

  1. Check out the application created in Section 46.3, "Customizing the Vertical Application" from source control.

  2. Start Oracle JDeveloper and select the Default Role.

  3. Open the checked-out application.

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

  5. From the File menu in Oracle JDeveloper, import the new revision of the JAR file created in Section 46.5.1, "How to Upgrade the Core Application Team Composite."

  6. From the Tools menu, select Preferences > Roles > Customization Developer.

  7. Restart Oracle JDeveloper.

  8. In the Customization Context dialog, select a layer and value to customize (for example, select the layer industry and value Communications).

  9. Open the BPEL process to see if the new base composite can be merged with layers for the above selected context.

  10. Review the Log window for potential warnings and errors.

  11. If required, fix errors and warnings by modifying the process. This edits the layers behind the scenes.

  12. Deploy the composite to create the next revision of the customized JAR file and deliver it to the customer for an upgrade.

46.5.3 How to Upgrade the Customer Composite

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