2 Developing SOA Composite Applications with Oracle SOA Suite

This chapter describes how to use Oracle JDeveloper to create a SOA composite application. It guides you through the basic steps of composite, service and reference binding component, and service component creation, security, deployment, and testing, along with describing key issues to be aware of when designing a SOA composite application.

This chapter includes the following sections:

• Section 2.1, "Creating a SOA Application"

• Section 2.2, "Adding Service Components"

• Section 2.3, "Adding Service Binding Components"

• Section 2.4, "Adding Reference Binding Components"

• Section 2.5, "Adding Wires"

• Section 2.6, "Adding Security"

• Section 2.7, "Deploying a SOA Composite Application"

• Section 2.8, "Managing and Testing a SOA Composite Application"

2.1 Creating a SOA Application

The first steps in building a new application are to assign it a name and to specify the directory in which to save source files. By creating an application using application templates provided by Oracle JDeveloper, you automatically get the organization of the workspace into projects, along with many of the configuration files required by the type of application you are creating.

2.1.1 How to Create a SOA Application and Project

You first create an application for the SOA project.

Note:

To create and deploy SOA composite applications and projects in Oracle JDeveloper, you must install the Oracle SOA Suite extension. For instructions on installing this extension for Oracle JDeveloper, see the Oracle Fusion Middleware Installation Guide for Oracle JDeveloper.

To create a SOA application and project:

1. Start Oracle JDeveloper Studio Edition Version 11.1.1.7.0.

2. If Oracle JDeveloper is running for the first time, specify the location for the Java JDK.

3. Create a new SOA composite application, as described in Table 2-1.

   Table 2-1 SOA Composite Application Creation

   If Oracle JDeveloper...	Then...
   Has no applications For example, you are opening Oracle JDeveloper for the first time.	In the Application Navigator in the upper left, click New Application.
   Has existing applications	From the File main menu or the Application menu: Select New > Applications. The New Gallery opens, where you can select different application components to create. In the Categories tree, select General > Applications. In the Items pane, select SOA Application, and click OK.

   
   

   The Create SOA Application wizard starts.

4. In the Name your application page, you can optionally change the name and location for your web project. If this is your first application, from Application Template, select SOA Application. Accept the defaults for the package prefix, and click Next.

   Notes:

   • Do not create an application name with spaces.

   • Do not create applications and projects in directory paths that have spaces (for example, c:\Program Files).

   • On a UNIX operating system, it is highly recommended to enable Unicode support by setting the LANG and LC_All environment variables to a locale with the UTF-8 character set. This action enables the operating system to process any character in Unicode. SOA technologies are based on Unicode. If the operating system is configured to use non-UTF-8 encoding, SOA components may function in an unexpected way. For example, a non-ASCII file name can make the file inaccessible and cause an error. Oracle does not support problems caused by operating system constraints.

     In a design-time environment, if you are using Oracle JDeveloper, select Tools > Preferences > Environment > Encoding > UTF-8 to enable Unicode support. This setting is also applicable for runtime environments.

5. In the Name your project page, you can optionally change the name and location for your SOA project. By default, Oracle JDeveloper adds the SOA project technology, the composite.xml file that describes the SOA composite application, and the necessary libraries to your model project.

6. Click Next.

   Note:

   Composite and component names cannot exceed 500 characters.

   A project deployed to the same infrastructure must have a unique name across SOA composite applications. The uniqueness of a composite is determined by its project name. For example, do not perform the actions described in Table 2-2. During deployment, the second deployed project (composite) overwrites the first deployed project (composite).

   Table 2-2 Restrictions on Naming a SOA Project

   Create an Application Named...	With a SOA Project Named...
   Application1	Project1
   Application2	Project1

   
   

   The Project SOA Settings page of the Create SOA Application wizard appears.

7. In the Configure SOA Settings page, click Empty Composite, and click Finish.

8. From the File main menu, select Save All.

2.1.2 What Happens When You Create a SOA Application and Project

When you create a SOA application, Oracle JDeveloper creates a project that contains all the source files related to your application. Oracle JDeveloper automatically adds the following libraries needed for your SOA project:

• SOA design time

• SOA runtime

• BPEL runtime

• Oracle Mediator runtime

• Oracle Metadata Services (MDS) Repository runtime

You can then use Oracle JDeveloper to create additional projects needed for your application.

Figure 2-1 shows the SOA Composite Editor for the OrderBookingComposite project contained within the WebLogicFusionOrderDemo application of the Fusion Order Demo.

Figure 2-1 New Workspace for a SOA Composite Application

Description of "Figure 2-1 New Workspace for a SOA Composite Application"

Table 2-3 describes the SOA Composite Editor.

Table 2-3 SOA Composite Editor

Element	Description
Application Navigator	Displays the key files for the specific service components included in the SOA project: A composite_name (composite.xml file) that is automatically created when you create a SOA project. This file describes the entire composite assembly of services, service components, references, and wires. The business rules service component file (rules_name.decs). Additional business rules files display under the Oracle > Business Rules subfolder (rules_name.rules). The Oracle Mediator service component file (mediator_name.mplan). The BPEL process service component files (process_name.bpel and process_name.wsdl). The human task service component file (task_name.task). The spring service component file (spring.xml). The componentType file that describes the services and references for each service component. This file ensures that the wiring you create between components works. Additional subfolders for class files, XSDs (schemas), XSLs (transformations), and test suites.
Structure Window	The Structure window provides a structural view of the data in the document currently selected in the active window.
Designer	You drag service components, services, and references from the Component Palette into the composite in the designer. When you drag and drop a service component into the designer, a corresponding property editor is invoked for performing configuration tasks related to that service component. For example, when you drag and drop the Oracle Mediator service component into the designer, the Mediator Editor is displayed that enables you to configure the Oracle Mediator service component. For all subsequent editing sessions, you double-click these service components to re-open their editors.
Project Name	Displays the project name of the SOA composite application.
Left Swimlane (Exposed Services)	The left swimlane is for services, such as a web services or JCA adapters, providing an entry point to the SOA composite application.
Right Swimlane (External References)	The right swimlane is for references that send messages to external services in the outside world, such as web services and JCA adapters.
Component Palette	The component palette provides the various resources that you can use in a SOA composite. It contains the following service components and adapters: Service components Displays the BPEL process, business rule, human task, Oracle Mediator, and spring components that can be dragged and dropped into the designer. Service adapters Displays the JCA adapter (AQ, file, FTP, database, JMS, MQ, Oracle Applications, Oracle User Messaging Service, socket, and third party), Oracle BAM binding component, Oracle Healthcare binding component, Oracle B2B binding component, EJB binding component, ADF-BC binding component, direct binding component, HTTP binding component, and web service binding component that can be dragged into the left or right swimlane. If the Component Palette does not display, select Component Palette from the View main menu.
Resource Palette	The Resource Palette provides a single dialog from which you can browse both local and remote resources. For example, you can access the following resources: Shared local application metadata such as schemas, WSDLs, event definitions, business rules, and so on. WSIL browser functionality that uses remote resources that can be accessed through an HTTP connection, file URL, or application server connection. Remote resources that are registered in a Universal Description, Discover, and Integration (UDDI) registry. You select these resources for the SOA composite application through the SOA Resource Browser dialog. This dialog is accessible through a variety of methods. For example, when you select the WSDL file to use with a service binding component or an Oracle Mediator service component or select the schema file to use in a BPEL process, the SOA Resource Browser dialog appears. Click Resource Palette at the top of this dialog to access available resources. If the Resource Palette does not display, then select Resource Palette from the View main menu.
Log Window	The Log window displays messages about application compilation, validation, and deployment.
Property Inspector	The Property Inspector displays properties for the selected service component, service, or reference. You can also define deployment descriptor properties for a BPEL process service component. For more information, see Section C.1.1, "How to Define Deployment Descriptor Properties in the Property Inspector." If the Property Inspector does not display, select Property Inspector from the View main menu.
Application View	The Application View shows the artifacts for the SOA composite application.

The composite_name (composite.xml) file displays as a tab in the designer and as a file in the Application Navigator. This file is automatically created when you create a new SOA project. This file describes the entire composite assembly of services, service components, and references. There is one composite.xml file for each SOA project.

When you work with the composite.xml file, you mostly use the designer, the Structure window, and the Property Inspector, as shown in Figure 2-1. The designer enables you to view many of your files in a WYSIWYG environment, or you can view a file in an overview editor where you can declaratively make changes, or you can view the source code for the file. The Structure window shows the structure of the currently selected file. You can select objects in this window, and then edit the properties for the selection in the Property Inspector.

2.2 Adding Service Components

Once you create your application, often the next step is to add service components that implement the business logic or processing rules of your application. You can use the Component Palette from the SOA Composite Editor to drag and drop service components into the composite.

2.2.1 How to Add a Service Component

To add a service component:

1. From the Component Palette, select SOA.

2. From the Service Components list, drag a component into the designer.

   Figure 2-2 shows a BPEL process being added to the designer.

   Figure 2-2 Adding BPEL Process to Composite

   
   Description of "Figure 2-2 Adding BPEL Process to Composite"
   
   

   A specific dialog for the selected service component is displayed. Table 2-4 describes the available editors.

   Table 2-4 Starting Service Component Editors

   Dragging This Service Component...	Invokes The...
   BPEL Process	Create BPEL Process dialog to create a BPEL process that integrates a series of business activities and services into an end-to-end process flow.
   Business Rule	Create Business Rules dialog to create a business decision based on rules.
   Human Task	Create Human Task dialog to create a workflow that describes the tasks for users or groups to perform as part of an end-to-end business process flow.
   Mediator	Create Mediator dialog to define services that perform message and event routing, filtering, and transformations.
   Spring Context	Create Spring dialog to create a spring context file for integrating Java interfaces into SOA composite applications.

   
   

3. Configure the settings for a service component. For help with a service component dialog, click Help or press F1. Click Finish.

   Figure 2-3 shows the BPEL Process dialog with data entered to create the OrderProcessor BPEL process for the WebLogicFusionOrderDemo application of the Fusion Order Demo. The process is selected to be asynchronous. The Expose as a SOAP Service checkbox directs Oracle JDeveloper to automatically create this service component connected to an inbound web service.

   Figure 2-3 Create BPEL Process Dialog

   
   Description of "Figure 2-3 Create BPEL Process Dialog"
   
   

4. Click OK.

   The service component displays in the designer. Figure 2-4 shows the OrderProcessor BPEL process. A SOAP service binding component called orderprocessor_client_ep in the left swimlane provides the outside world with an entry point into the SOA composite application. If the Expose as a SOAP Service option was not selected in the Create BPEL Process dialog, the orderprocessor_client_ep service would not display. Section 2.3.1, "How to Add a Service Binding Component," describes how you can later add a service.

   Figure 2-4 BPEL Process in Composite

   
   Description of "Figure 2-4 BPEL Process in Composite"
   
   

   You can more fully define the content of the service component now or at a later time. For this top-down example, the content is defined now.

5. From the File main menu, select Save All.

2.2.2 What You May Need to Know About Adding and Deleting a Service Component

Note the following details about adding service components:

• Create a service component from either the SOA Composite Editor or the designer of another component. For example, you can create a human task component from the SOA Composite Editor or the Oracle BPEL Designer.

• Use the Resource Palette to browse for service components defined in the SOA Composite Editor, and those deployed.

Note the following details about deleting service components:

• You can delete a service component by right-clicking it and selecting Delete from the context menu.

• When a service component is deleted, all references pointing to it are invalidated and all wires are removed. The service component is also removed from the Application Navigator.

• A service component created from within another service component can be deleted. For example, a human task created within the BPEL process service component of Oracle JDeveloper can be deleted from the SOA Composite Editor. In addition, the partner link to the task can be deleted. Deleting the partner link removes the reference interface from its .componentType file and removes the wire to the task.

2.2.3 How to Edit a Service Component

You edit a service component to define specific details about the service component.

To edit a service component:

1. Double-click the service component in the designer to display the appropriate editor or designer, as described in Table 2-5.

   Table 2-5 Starting SOA Service Component Wizards and Dialogs

   Double-Clicking This Service Component...	Displays The...
   BPEL Process	Oracle BPEL Designer for further designing.
   Business Rule	Business Rules Designer for further designing.
   Human Task	Human Task Editor for further designing.
   Mediator	Oracle Mediator Editor for further designing.
   Spring Context	Spring Editor for further designing.

   
   

   To return to the SOA Composite Editor from within any service component, double-click composite_name (composite.xml) in the Application Navigator or single-click composite_name (composite.xml) above the designer.

   For help with a service component editor, click Help or press F1.

2. Click Finish.

3. Modify the settings for a service component. For help with a service component editor or designer, click Help or press F1.

4. Click Finish.

5. In the Application Navigator, double-click composite_name (composite.xml) or single-click composite_name (composite.xml) above the designer.

   This action returns you to the SOA Composite Editor.

6. From the File main menu, select Save All.

2.3 Adding Service Binding Components

You add a service binding component to act as the entry point to the SOA composite application from the outside world.

2.3.1 How to Add a Service Binding Component

Notes:

• This section describes how to manually create a service binding component. You can also automatically create a service binding component by selecting Expose as a SOAP Service when you create a service component. This selection creates an inbound web service binding component that is automatically connected to your BPEL process, human task service, or Oracle Mediator service component.

• You cannot invoke a representational state transfer (REST) service from the SOA Composite Editor.

You can use the Component Palette from the SOA Composite Editor to drag and drop service binding components to the composite.

To add a service binding component:

1. From the Component Palette, select SOA.

2. From the Service Adapters list, drag a service to the left swimlane to define the service interface.

   Figure 2-5 shows a web service being added to the designer.

   Figure 2-5 Adding a Web Service to a Composite

   
   Description of "Figure 2-5 Adding a Web Service to a Composite"
   
   

   A specific dialog for the selected service displays. Table 2-6 describes the available editors.

   Table 2-6 Service Editors

   Dragging This Service...	Invokes The...
   Web service	Create Web Service dialog to create a web invocation service.
   Adapters	Adapter Configuration Wizard to guide you through integration of the service with database tables, database queues, file systems, FTP servers, Java Message Services (JMS), IBM WebSphere MQ, Oracle User Messaging Service, Oracle BAM servers, sockets, or Oracle E-Business Suite applications.
   ADF-BC Service	Create ADF-BC Service dialog to create a service data object (SDO) invocation service.
   B2B	B2B Configuration Wizard to guide you through selection of a document definition.
   Healthcare	Healthcare Configuration Wizard to guide you through integration with a healthcare system.
   EJB Service	Create EJB Service to create an Enterprise JavaBeans service for using SDO parameters or Java interfaces with Enterprise JavaBeans.
   HTTP Binding	Create HTTP Binding Wizard to create HTTP binding. This wizard enables you to invoke SOA composite applications through HTTP POST and GET operations.
   Direct Binding	Create Direct Binding Service dialog to invoke a SOA composite application and exchange messages over a remote method invocation (RMI) in the inbound direction.

   
   

3. Configure the settings for the service. For help with a service editor, click Help or press F1. When you add a web service, you must select the WSDL file to use. For information, see Section 2.3.2, "How to Define the Interface (WSDL) for a Web Service."

4. Click Finish.

   Figure 2-6 shows the Web Service dialog with data entered to create the orderprocessor_client_ep service for the OrderProcessor BPEL process.

   Figure 2-6 Create Web Service Dialog

   
   Description of "Figure 2-6 Create Web Service Dialog"
   
   

5. Click OK.

   The service binding component displays in the left swimlane. Figure 2-7 shows the orderprocessor_client_ep service binding component added to the composite.xml file.

   Figure 2-7 Web Service in Composite

   
   Description of "Figure 2-7 Web Service in Composite"
   
   

6. Select Save All from the File main menu.

2.3.2 How to Define the Interface (WSDL) for a Web Service

As described in Section 2.3.1, "How to Add a Service Binding Component," a web service is a type of binding component that you can add to a SOA composite application. You must define the interface (WSDL) file for the web service.

To define the interface (WSDL) for a web service:

1. In the Component Palette, select SOA.

2. From the Service Adapters list, drag a Web Service to the left swimlane.

   This invokes the Create Web Service dialog shown in Figure 2-6.

3. Enter the details shown in Table 2-7:

   Table 2-7 Create Web Service Dialog Fields and Values

   Field	Value
   Name	Enter a name for the service.
   Type	Select the type (message direction) for the web service. Since you dragged the web service to the left swimlane, the Service type is the correct selection, and displays by default: Service (default) Creates a web service to provide an entry point to the SOA composite application Reference Creates a web service to provide access to an external service in the outside world Since this example describes how to create an entry point to the SOA composite application, Service is selected.

   
   

4. Select the WSDL file for the service. There are three methods for selection:

   • Define a new WSDL using an existing schema or defining a new schema.

   • Select a WSDL created when defining a component interface. The WSDL can be selected from the project/application browser.

   • Automatically define a service interface WSDL from a component.

   Define a new WSDL using an existing schema or defining a new schema.

   1. To the right of the WSDL URL field, click the Find existing WSDLs (first) icon and select an existing WSDL file from the local file system (for this example, OrderProcessor.wsdl is selected). File System in the list at the top of the dialog is automatically selected. Figure 2-8 provides details.

      Figure 2-8 WSDL File Selection

      
      Description of "Figure 2-8 WSDL File Selection"
      
      

   Select a WSDL created when defining a component interface. The WSDL can be selected from the project/application browser.

   1. To the right of the WSDL URL field, click the Find existing WSDLs (first) icon and select Resource Palette from the list at the top of the dialog, as shown in Figure 2-9. This action enables you to use existing WSDL files from other applications.

      Figure 2-9 Use of Existing WSDL Files from Other Applications

      
      Description of "Figure 2-9 Use of Existing WSDL Files from Other Applications"
      
      

   Automatically define a service interface WSDL from a component.

   1. To the right of the WSDL URL field, click the Generate WSDL from schemas (second) icon to automatically generate a WSDL file from a schema. Figure 2-10 shows the Create WSDL dialog. Default values for the WSDL file name, directory location, namespace, port type, operation name, and interface type are displayed. If the specified directory is not the subdirectory of the current project, a warning message is displayed. If the specified directory does not exist, it is automatically created.

      You can modify the default values.

      Figure 2-10 Automatic Generation of WSDL File

      
      Description of "Figure 2-10 Automatic Generation of WSDL File"
      
      

5. Click the Add icon above the Input table to display the Add Message Part dialog to add a new WSDL message part. If the WSDL file contains multiple messages, you can add a message part for each one. You can select XML schema simple types, project schema files, and project WSDL files for a message part.

   For more information, click Help.

6. Click OK to return to the Create Web Service dialog.

7. Note the additional details described in Table 2-8:

   Table 2-8 Create Web Service Dialog Fields and Values

   Field	Value
   Port Type	Displays the port type.
   Callback Port Type	Disabled, since this WSDL file is for a synchronous service. This field is enabled for asynchronous services.

   
   

8. Click OK.

9. From the File main menu, select Save All.

   Notes:

   • Do not manually update the WSDL location in the WSDL file in Source View. This action is not supported. Only updates made in Design View are supported.

   • WSDL namespaces must be unique. Do not just copy and rename a WSDL. Ensure that you also change the namespaces.

2.3.3 How to View Schemas

You can view all schemas used by the interface's WSDL file and, if you want, choose a new message schema for a selected message part in the Update Interface dialog.

To view schemas:

1. Double-click the small arrow handle that appears on the specific binding component or service component. Figure 2-11 provides details.

   Figure 2-11 Selection of Inbound Interface Handle

   
   Description of "Figure 2-11 Selection of Inbound Interface Handle"
   
   

   The Update Interface dialog shown in Figure 2-12 displays all schemas currently used by the WSDL file.

   Figure 2-12 Update Interface Dialog

   
   Description of "Figure 2-12 Update Interface Dialog"
   
   

2. If you want to select a new message schema, click Help or press F1 for instructions.

2.3.4 How to Edit a Service Binding Component

After initially creating a service, you can edit its contents at a later time. Double-click the component icon to display its appropriate editor or wizard. Table 2-9 provides an overview.

Table 2-9 Starting Service Wizards and Dialogs

Double-Click This Service...	To...
Web service	Display the Update Service dialog.
Adapters	Reenter the Adapter Configuration Wizard.
ADF-BC Service	Display the Update Service dialog.
B2B	Reenter the B2B Configuration Wizard.
Healthcare	Reenter the Healthcare Configuration Wizard.
EJB Service	Display the Update Service dialog.
HTTP Binding	Reenter the HTTP Binding Wizard.
Direct Binding	Reenter the Update Service dialog.

2.3.5 What You May Need to Know About Adding and Deleting Services

Note the following detail about adding services:

• When a new service is added for a service component, the service component is notified so that it can make appropriate metadata changes. For example, when a new service is added to a BPEL service component, the BPEL service component is notified to create a partner link that can be connected to a receive or an on-message activity.

Note the following detail about deleting services:

• When a service provided by a service component is deleted, all references to that service component are invalidated and the wires are removed.

2.3.6 What You May Need to Know About Using the Same Namespace in Different WSDL Files in the Same Composite

Having two different WSDL files with the same fully-qualified namespace in the same SOA composite application is ambiguous and not supported. This causes the application to fail during compilation with duplicate definition errors. Ensure that you use unique namespaces for every WSDL file.

2.3.7 What You May Need to Know About WSDL Browsing in the Resource Palette When the SOA Infrastructure Uses Both Internal and External Oracle HTTP Servers

When the SOA Infrastructure is configured in the Server URL field of the SOA Infrastructure Common Properties page in Oracle Enterprise Manager Fusion Middleware Control to use both internal and external Oracle HTTP servers, you cannot browse for WSDL URLs using the Resource Palette. However, you can paste the correct WSDL URL in the WSDL URL field of the Update Service dialog for the web service binding component. Figure 2-13 provides details.

Figure 2-13 WSDL URL Field

Description of "Figure 2-13 WSDL URL Field"

2.4 Adding Reference Binding Components

You add reference binding components that enable the SOA composite application to send messages to external services in the outside world.

2.4.1 How to Add a Reference Binding Component

You can use the Component Palette from the SOA Composite Editor to drag and drop reference binding components to the composite.

To add a reference binding component:

1. From the Component Palette, select SOA.

2. From the Service Adapters list, drag a service to the right swimlane.

   Figure 2-14 shows a web service being added to the designer.

   Figure 2-14 Adding Web Service to Composite

   
   Description of "Figure 2-14 Adding Web Service to Composite"
   
   

   A specific dialog or wizard for the selected reference displays. Table 2-10 describes the available editors.

   Table 2-10 Reference Editors

   Dragging This Service...	Invokes The...
   Web Service	Create Web Service dialog to create a web invocation service.
   Adapters	Adapter Configuration Wizard to guide you through integration of the service with database tables, database queues, file systems, FTP servers, Java Message Services (JMS), IBM WebSphere MQ, Oracle User Messaging Service, Oracle BAM servers, sockets, or Oracle E-Business Suite applications.
   ADF-BC Service	Create ADF-BC Service dialog to create a service data object (SDO) invocation service.
   B2B	B2B Wizard to guide you through selection of a document definition.
   Healthcare	Healthcare Configuration Wizard to guide you through integration with a healthcare system.
   EJB Service	Create EJB Service dialog to create an Enterprise JavaBeans service for using SDO parameters with Enterprise JavaBeans.
   HTTP Binding	Create HTTP Binding Wizard to create HTTP binding. This wizard enables you to invoke SOA composite applications through HTTP POST and GET operations, and invoke HTTP endpoints through HTTP POST and GET operations.
   Direct Binding	Create Direct Binding Service Dialog to invoke an Oracle Service Bus (OSB) flow or another SOA composite application.

   
   

3. Configure the settings for the reference binding component. For help with a reference editor, click Help or press F1.

4. Click Finish.

   Figure 2-15 shows the Create Web Service dialog with data entered to create a reference.

   Figure 2-15 Create Web Service Dialog

   
   Description of "Figure 2-15 Create Web Service Dialog"
   
   

5. Click OK.

   The reference binding component displays in the right swimlane. Figure 2-16 shows the StoreFrontService reference added to the SOA composite application.

   Figure 2-16 Web Service in Composite

   
   Description of "Figure 2-16 Web Service in Composite"
   
   

6. From the File main menu, select Save All.

2.4.2 What You May Need to Know About Adding and Deleting References

Note the following detail about adding references:

• The only way to add a new reference in the SOA Composite Editor is by wiring the service component to the necessary target service component. When a new reference is added, the service component is notified so it can make appropriate changes to its metadata. For example, when a reference is added to a BPEL service component, the BPEL service component is notified to add a partner link that can then be used in an invoke activity.

Note the following details about deleting references:

• When a reference for a service component is deleted, the associated wire is also deleted and the service component is notified so that it can update its metadata. For example, when a reference is deleted from a BPEL service component, the service component is notified to delete the partner link in its BPEL metadata.

• Deleting a reference connected to a wire clears the reference and the wire.

2.4.3 What You May Need to Know About WSDL References

A WSDL file is added to the SOA composite application whenever you create a new component that has a WSDL (for example, a service binding component, service component (for example, Oracle Mediator, BPEL process, and so on), or reference binding component). When you delete a component, any WSDL imports used by that component are removed only if not used by another component. The WSDL import is always removed when the last component that uses it is deleted.

When a service or reference binding component is updated to use a new WSDL, it is handled as if the interface was deleted and a new one was added. Therefore, the old WSDL import is only removed if it is not used by another component.

If a service or reference binding component is updated to use the same WSDL (porttype qname), but from a new location, the WSDL import and any other WSDL reference (for example, the BPEL process WSDL that imports an external reference WSDL) are automatically updated to reference the new location.

Simply changing the WSDL location in the source view of the composite.xml file's import is not sufficient. Other WSDL references in the metadata are required by the user interface (see the ui:wsdlLocation attribute on composite and componentType services and references). There can also be other WSDL references required by runtime (for example, a WSDL that imports another WSDL, such as the BPEL process WSDL). Ensure that you change the following places in this file where a WSDL URL is referenced:

• User interface location - used only in Oracle JDeveloper.

• Import: Used during deployment.

• WSDL location in the reference definition: Used at runtime.

Always modify the WSDL location though the dialogs of the SOA Composite Editor in which a WSDL location is specified (for example, a web service, BPEL partner link, and so on). Changing the URL's host address is the exact case in which the SOA Composite Editor automatically updates all WSDL references.

2.4.4 What You May Need to Know About Mixed Message Types in a WSDL File

If a BPEL process has multiple WSDL messages declared in its WSDL file and one or more messages have their parts defined to be of some type, whereas other messages have their parts defined to be of some element, runtime behavior can become unpredictable. This is because these WSDLs are considered to have mixed type messages. For example, assume there are multiple copy actions within an assign activity. These copy actions attempt to populate an output variable that has multiple parts:

• Part 1 is declared as an xsd:string type.

• Part 2 is declared as an xsd:int type.

• Part 3 is declared as an element of a custom-designed complex type.

This behavior is not supported.

2.4.5 What You May Need to Know About Invoking the Default Revision of a Composite

A WSDL URL that does not contain a revision number is processed by the default composite application. This action enables you to always call the default revision of the called service without having to make other changes in the calling composite.

Select the default WSDL to use in the Resource Palette in Oracle JDeveloper.

To invoke the default revision of a composite:

1. In the Create Web Service dialog, click the icon to the right of the WSDL URL field to invoke the SOA Resource Browser dialog.

2. Select Resource Palette from the list at the top.

3. Expand the nodes under the Application Server connection or WSIL connection to list all deployed composites and revisions. The default revision is identified by the word Default in the title (for example, OrderBookingComposite [Default]).

4. Select the appropriate default endpoint and click OK.

2.5 Adding Wires

You wire (connect) services, service components, and references. For this example, you wire the web service and service component. Note the following:

• Since a web service is an inbound service, a reference handle displays on the right side. Web services that are outbound references do not have a reference handle on the right side.

• You can drag a defined interface to an undefined interface in either direction (reference to service or service to reference). The undefined interface then inherits the defined interface. There are several exceptions to this rule:

  • A component has the right to reject a new interface. For example, an Oracle Mediator can only have one inbound service. Therefore, it rejects attempts to create a second service.

  • You cannot drag an outbound service (external reference) to a business rule, because business rules do not support references. When dragging a wire, the user interface highlights the interfaces that are valid targets.

• The port type and the namespace are used to uniquely identify an interface.

• You cannot wire services and composites that have different interfaces. For example, you cannot connect a web service configured with a synchronous WSDL file to an asynchronous BPEL process. Figure 2-17 provides details.

  Figure 2-17 Limitations on Wiring Services and Composites with Different Interfaces

  
  Description of "Figure 2-17 Limitations on Wiring Services and Composites with Different Interfaces"
  
  

  The service and reference must match, meaning the interface and the callback must be the same. If you have two services that have different interfaces, you can place an Oracle Mediator between the two services and perform a transformation between the interfaces.

2.5.1 How to Wire a Service and a Service Component

You can wire a service binding component to a service component from the SOA Composite Editor.

To wire a service and a service component:

1. From a service reference handle, drag a wire to the service component interface, as shown in Figure 2-18.

   Figure 2-18 Wire Connection

   
   Description of "Figure 2-18 Wire Connection"
   
   

2. If the service component is a BPEL process, double-click the BPEL process and note that the service displays as a partner link in the left swimlane, as shown in Figure 2-19.

   Figure 2-19 Display of the Service as a Partner Link in the BPEL Process

   
   Description of "Figure 2-19 Display of the Service as a Partner Link in the BPEL Process"
   
   

3. Select Save All from the File main menu.

2.5.2 How to Wire a Service Component and a Reference

You can wire a service component to a reference binding component from the SOA Composite Editor.

To wire a service component and a reference:

1. In the Application Navigator, double-click composite.xml or single-click composite.xml above the designer.

2. From the service component, drag a wire to the reference, as shown in Figure 2-20.

   Figure 2-20 Wiring of a Service Component and Reference

   
   Description of "Figure 2-20 Wiring of a Service Component and Reference"
   
   

3. If the service component is a BPEL process, double-click the BPEL process and note that the reference displays as a partner link in the right swimlane, as shown in Figure 2-21.

   Figure 2-21 Display of the Reference as a Partner Link in the BPEL Process

   
   Description of "Figure 2-21 Display of the Reference as a Partner Link in the BPEL Process"
   
   

4. Select Save All from the File main menu.

5. In the Application Navigator, select the composite.xml file.

6. Click the Source tab to review what you have created.

   The orderprocessor_client_ep service binding component provides the entry point to the composite.

   <service name="orderprocessor_client_ep"    
            ui:wsdlLocation="oramds:/apps/FusionOrderDemoShared
   /services/orderbooking/OrderBookingProcessor.wsdl">
       <interface.wsdl interface= "http://www.globalcompany.example.com/ns
   /OrderBookingService#wsdl.interface(OrderProcessor)"
       <binding.adf serviceName="OrderProcessorService" registryName=""/>
       <callback>
         <binding.ws port="http://www.globalcompany.example.com/ns
   /OrderBookingService#wsdl.endpoint(orderprocessor_clientep/OrderProcessorCallback_
   pt)"/>
       </callback>
     </service>
   

   The OrderProcessor BPEL process service component appears.

   <component name="OrderProcessor">
      <implementation.bpel src="OrderProcessor.bpel"/>
   </component>
   

   A reference binding component named StoreFrontService appears. The reference provides access to the external service in the outside world.

   <reference name="StoreFrontService"
                ui:wsdlLocation="oramds:/apps/FusionOrderDemoShared
   /services/oracle/fodemo/storefront/store/service/common/serviceinterface/StoreFron
   tService.wsdl">
       <interface.wsdl
    interface="www.globalcompany.example.com#wsdl.interface(StoreFrontService)"/>
       <binding.ws
   port="www.globalcompany.example.com#wsdl.endpoint(StoreFrontService/StoreFrontServ
   iceSoapHttpPort)"
                   location="oramds:/apps/FusionOrderDemoShared/services/oracle/fodemo/storefront/sto
   re/service/common/serviceinterface/StoreFrontService.wsdl"/>
   </reference>
   

   The communication (or wiring) between service components is as follows:

   • The source orderprocessor_client_ep service binding component is wired to the target OrderProcessor BPEL process service component. Wiring enables web service message communication with this specific BPEL process.

   • The source OrderProcessor BPEL process is wired to the target StoreFrontService reference binding component. This is the reference to the external service in the outside world.

     <wire>
       <source.uri>orderprocessor_client_ep</source.uri>
       <target.uri>OrderProcessor/orderprocessor_client_ep</target.uri>
     </wire>
   
     <wire>
       <source.uri>OrderProcessor/StoreFrontService</source.uri>
       <target.uri>StoreFrontService</target.uri>
     </wire>
   

2.5.3 What You May Need to Know About Adding and Deleting Wires

Note the following details about adding wires:

• A service component can be wired to another service component if its reference matches the service of the target service component. Note that the match implies the same interface and callback interface.

• Adding the following wiring between two Oracle Mediator service components causes an infinite loop:

  • Create a business event.

  • Create an Oracle Mediator service component and subscribe to the event.

  • Create a second Oracle Mediator service component to publish the same event.

  • Wire the first Oracle Mediator to the second Oracle Mediator component service.

  If you remove the wire between the two Oracle Mediators, then for every message, the second Oracle Mediator can publish the event and the first Oracle Mediator can subscribe to it.

Note the following details about deleting wires:

• When a wire is deleted, the component's outbound reference is automatically deleted and the component is notified so that it can clean up (delete the partner link, clear routing rules, and so on). However, the component's service interface is never deleted. All Oracle SOA Suite services are defined by their WSDL interface. When a component's interface is defined, there is no automatic deletion of the service interface in the SOA Composite Editor.

  If you want to change the service WSDL interface, there are several workarounds:

  • In most cases, you just want to change the schema instead of the inbound service definition. In the SOA Composite Editor, click any interface icon that uses the WSDL. For example, you can click the web service interface icon or the Oracle Mediator service icon. This invokes the Update Interface dialog, which enables you to change the schema for any WSDL message.

  • If you are using an Oracle Mediator service component, the Refresh operations from WSDL icon of the Oracle Mediator Editor enables you to refresh (after adding new operations) or replace the Oracle Mediator WSDL. However, you are warned if the current operations are to be deleted. If you change the WSDL to the new inbound service WSDL using this icon, the wire typically breaks because the interface has changed. You can then wire Oracle Mediator to the new service.

  • In many cases, a new service requires a completely new Oracle Mediator. Delete the old Oracle Mediator, create a new one, and wire it to the new service.

  • If you are using a BPEL process service component, select a new WSDL through the Edit Partner Link dialog.

  See Section 2.3.3, "How to View Schemas" for details about the Update Interface dialog.

2.6 Adding Security

As you create your SOA composite application, you can secure web services by attaching policies to service binding components, service components, and reference binding components. For more information about implementing policies, see Chapter 42, "Enabling Security with Policies."

2.7 Deploying a SOA Composite Application

Deploying the SOA composite application involves creating a connection to an Oracle WebLogic Server and deploying an archive of the SOA composite application to an Oracle WebLogic Server managed server. For more information about deploying SOA composite applications, see Chapter 43, "Deploying SOA Composite Applications."

2.7.1 How to Invoke Deployed SOA Composite Applications

You can invoke other deployed SOA composite applications from your SOA composite application. The other applications must be deployed.

To invoke deployed SOA composite applications:

1. Create a web service or partner link through one of the following methods.

   1. In the SOA Composite Editor, drag a Web Service from the Component Palette to the External References swimlane.

   2. In Oracle BPEL Designer, drag a Partner Link from the Component Palette to the right swimlane.

2. Access the SOA Resource Browser dialog based on the type of service you created.

   1. From the Create Web Service dialog, click the Find existing WSDLs icon.

   2. From the Edit Partner Link dialog, click the SOA Resource Browser icon.

3. From the list at the top, select Resource Palette.

4. Expand the tree to display the application server connection to the Oracle WebLogic Administration Server on which the SOA composite application is deployed.

5. Expand the application server connection.

6. Expand the SOA folder and partition. Figure 2-22 provides details.

   Figure 2-22 Browse for a SOA Composite Application

   
   Description of "Figure 2-22 Browse for a SOA Composite Application"
   
   

7. Select the composite service.

8. Click OK.

For information about creating an application server connection, see Section 43.7.1.1, "Creating an Application Server Connection."

2.8 Managing and Testing a SOA Composite Application

As you build and deploy a SOA composite application, you manage and test it using a combination of Oracle JDeveloper and Oracle Enterprise Manager Fusion Middleware Control.

2.8.1 How to Manage Deployed SOA Composite Applications in Oracle JDeveloper

You can manage deployed SOA composite applications from the Application Server Navigator in Oracle JDeveloper. Management tasks consist of undeploying, activating, retiring, turning on, and turning off SOA composite application revisions.

Note:

These instructions assume you have created an application server connection to an Oracle WebLogic Administration Server on which the SOA Infrastructure is deployed. Creating a connection to an Oracle WebLogic Administration Server enables you to browse for managed Oracle WebLogic Servers or clustered Oracle WebLogic Servers in the same domain. From the File main menu, select New > Connections > Application Server Connection to create a connection.

1. From the View main menu, select Application Server Navigator.

2. Expand your connection name (for this example, named MyConnection).

   The SOA folder appears, as shown in Figure 2-23. The SOA folder displays all deployed SOA composite application revisions and services. You can browse all applications deployed on all Oracle WebLogic Administration Servers, managed Oracle WebLogic Servers, and clustered Oracle WebLogic Servers in the same domain. Figure 2-23 provides details.

   Figure 2-23 Application Server Navigator

   
   Description of "Figure 2-23 Application Server Navigator"
   
   

3. Expand the SOA folder.

4. Expand the partition in which the composite application is deployed.

   Deployed SOA composite applications and services appear, as shown in Figure 2-24.

   Figure 2-24 Deployed SOA Composite Applications

   
   Description of "Figure 2-24 Deployed SOA Composite Applications"
   
   

5. Right-click a deployed SOA composite application.

6. Select an option to perform. The options that display for selection are based upon the current state of the application. Table 2-11 provides details.

   Table 2-11 SOA Composite Application Options

   Option	Description
   Stop	Shuts down a running SOA composite application revision. Any request (initiating or a callback) to the composite is rejected if the composite is shut down. Note: The behavior differs based on which binding component is used. For example, if it is a web service request, it is rejected back to the caller. A JCA adapter binding component may do something else in this case (for example, put the request in a rejected table). This option displays when the composite application has been started.
   Start	Restarts a composite application revision that was shut down. This action enables new requests to be processed (and not be rejected). No recovery of messages occurs. This option displays when the composite application has been stopped.
   Retire	Retires the selected composite revision. If the process life cycle is retired, you cannot create a new instance. Existing instances are allowed to complete normally. An initiating request to the composite application is rejected back to the client. The behavior of different binding components during rejection is the same as with the shut down option. A callback to an initiated composite application instance is delivered properly. This option displays when the composite application is active.
   Activate	Activates the retired composite application revision. Note the following behavior with this option: All composite applications are automatically active when deployed. Other revisions of a newly deployed composite application remain active (that is, they are not automatically retired). If you want, you must explicitly retire them. This option displays when the application is retired.
   Undeploy	Undeploys the selected composite application revision. The consequences of this action are as follows: You can no longer configure and monitor this revision of the composite application. You can no longer process instances of this revision of the composite application. You cannot view previously completed processes. The state of currently running instances is changed to stale and no new messages sent to this composite are processed. If you undeploy the default revision of the composite application (for example, 2.0), the next available revision of the composite application becomes the default (for example, 1.0).
   Set Default Revision	Sets the selected composite application revision to be the default.

   
   

7. If you want to deploy a prebuilt SOA composite application archive that includes a deployment profile, right-click the SOA folder and select Deploy SOA Archive. The archive consists of a JAR file of a single application or a SOA bundle ZIP file containing multiple applications.

   You are prompted to select the following:

   • The target SOA servers to which you want to deploy the SOA composite application archive.

   • The archive to deploy.

   • The configuration plan to attach to the application. As you move projects from one environment to another (for example, from testing to production), you typically must modify several environment-specific values, such as JDBC connection strings, hostnames of various servers, and so on. Configuration plans enable you to modify these values using a single text (XML) file called a configuration plan. The configuration plan is created in either Oracle JDeveloper or from the command line. During process deployment, the configuration plan is used to search the SOA project for values that must be replaced to adapt the project to the next target environment. This is an optional selection.

   • Whether you want to overwrite an existing composite of the same revision ID. This action enables you to redeploy an application revision.

   Figure 2-25 provides details.

   Figure 2-25 Deploy SOA Archive Dialog

   
   Description of "Figure 2-25 Deploy SOA Archive Dialog"
   
   

For more information, see the following documentation:

• Chapter 43, "Deploying SOA Composite Applications" for details about creating a deployment profile and a configuration plan and deploying an existing SOA archive

• Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite for details about managing deployed SOA composite applications from Oracle Enterprise Manager Fusion Middleware Control.

2.8.2 How to Test a Deployed SOA Composite Application

After you deploy a SOA composite application, you can initiate a test instance of it from the Test Web Service page in Oracle Enterprise Manager Fusion Middleware Control to verify the XML payload data. For more information about initiating a test instance, see the Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite.

In addition to creating a test instance, you can also simulate the interaction between a SOA composite application and its web service partners before deployment in a production environment. This helps to ensure that a process interacts with web service partners as expected by the time it is ready for deployment to a production environment. For more information about creating a unit test, see Chapter 44, "Automating Testing of SOA Composite Applications."