2 Getting Started with Developing SOA Composite Applications

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:

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. When you install the Oracle SOA Suite Quick Start, the Oracle SOA Suite extensions are automatically installed in Oracle JDeveloper. This differs from previous releases in which you manually imported the Oracle SOA Suite extensions into Oracle JDeveloper. For information about the Oracle SOA Suite Quick Start installation, see Installing SOA Suite and Business Process Management Suite Quick Start for Developers.

2.1.1 Create a SOA Application and Project

  1. Start Oracle JDeveloper Studio Edition.

  2. If Oracle JDeveloper is running for the first time, specify the location for the Java JDK and the user role in which to run Oracle JDeveloper. The JDK version must be later than or equal to 1.7.0_15.

  3. Create a SOA application in any of the following ways:

    • From the File main menu:

      1. Select New > Application.

        The New Gallery opens, where you can select different application components to create.

      2. In the Categories tree, select General > Applications.

      3. In the Items pane, select SOA Application, and click OK.

    • From the Application main menu:

      1. Select New.

        The New Gallery opens, where you can select different application components to create.

      2. In the Categories tree, select General > Applications.

      3. In the Items pane, select SOA Application, and click OK.

    • From the Application menu in the Applications window:

      1. In the Applications window in the upper left, select New Application from the Applications dropdown list.

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

    Note:

    Note the following application naming conventions:

    • 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 that you 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-1. During deployment, the second deployed project (composite) overwrites the first deployed project (composite).

    Table 2-1 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 for this example, and click Finish. Table 2-2 describes all of the options on this page.

    Table 2-2 Configure SOA Settings Page

    Element Description

    Empty Composite

    Creates an empty SOA composite application. This type is selected by default.

    Composite With BPEL Process

    Automatically opens the Create BPEL Process dialog to guide you through creation of an initial BPEL process. A BPEL process enables you to design a business process that integrates a series of business activities and services into an end-to-end process flow.

    Composite With Mediator

    Automatically opens the Create Mediator dialog to guide you through creation of an initial Oracle Mediator service component. Oracle Mediator enables you to route events (messages) between different components.

    Composite With Human Task

    Automatically opens the Create Human Task dialog to guide you through creation of an initial human task service component. A human task component enables you to model a workflow that describes the tasks for users or groups to perform as part of an end-to-end business process flow. The tasks are accessed through Oracle BPM Worklist during process runtime.

    Composite With Subprocess

    Automatically creates a SOA composite application with a subprocess. A subprocess is a fragment of BPEL code that can be reused within a particular processor by separate processes.

    Composite With Business Rule

    Automatically opens the Create Business Rules dialog to guide you through creation of an initial business rule service component. A business rule enables you to design a business decision based on rules.

    Composite With Spring

    Automatically opens the Create Spring dialog to guide you through creation of a spring context service component. A spring context service component enables you to integrate components that use Java interfaces instead of WSDL files into SOA composite applications. You can also integrate components that use Java interfaces with components that use WSDL files in the same SOA composite application.

  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. You can then use Oracle JDeveloper to create additional projects needed for your application.

Figure 2-1 shows the SOA Composite Editor for a project named OrderBookingComposite.

Figure 2-1 New Workspace for a SOA Composite Application

Description of Figure 2-1 follows
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

Applications Window (Upper left)

Displays the key directories and files for the specific service components included in the SOA project. You can change the structure as necessary for your environment. The only limitation is that all files must be located under the SOA directory.

  • Service_component_directory

    Displays a directory for the artifacts of each service component you add:

    A BPEL directory is created for BPEL processes.

    A Mediators directory is created for Oracle Mediators.

    A HumanTasks directory is created for human tasks.

    An oracle/rules directory is created for business rules.

  • Events

    Displays the business event files (.edn).

  • Schemas

    Displays the BPEL process schema files (.xsd).

  • testsuites

    Displays the test suite files.

  • Transformations

    Displays the transformation XSLT (.xsl) and XQuery (.xqy) mapper files.

  • WSDLs

    Displays all WSDL files (.wsdl).

  • composite_name

    A composite_name file is automatically created when you create a SOA project. This file describes the entire composite assembly of services, service components, references, and wires.

Structure Window (Lower left)

The Structure window provides a structural view of the data in the document currently selected in the active window.

Designer (middle)

You drag service components, services, and references from the Components window 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 for configuring the Oracle Mediator service component.

For all subsequent editing sessions, you double-click these service components to re-open their editors.

Project Name (Above the designer)

Displays the project name of the SOA composite application.

Left Swimlane (Exposed Services)

The left swimlane is for services (such as web services, REST adapters, or JCA adapters) that provide 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 or JCA adapters.

Components Window (Upper right - Components tab)

The Components window provides the various resources that you can use in a SOA composite. It contains the following service components and adapters:

  • Components

    Displays the BPEL process, business rule, human task, Oracle Mediator, and spring components that can be dragged and dropped into the designer.

  • Technology

    Displays the JCA adapters (such as AQ, file, FTP, database, JMS, MQ, Oracle User Messaging Service, socket, LDAP server, and Coherence cache), third-party adapter, cloud adapter, Oracle BAM 11g binding component, Oracle Healthcare binding component, Oracle B2B binding component, EJB binding component, ADF-BC binding component, application adapters (Oracle E-Business Suite, JDE World, and SAP), direct binding component, HTTP binding component, Oracle Managed File Transfer (MFT) adapter, Representational State Transfer (REST) adapter, and web service binding component that can be dragged into the left or right swimlane.

Resources window (Upper right - Resources tab)

The Resources window provides a single dialog from which you can browse both local and remote resources. For example, you can access the following resources:

  • Shared data such as schemas and WSDLs from the MDS Repository.

  • 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 WSDL Chooser 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 Resources at the top of this dialog to access available resources.

Log Window (Lower middle)

The Log window displays messages about application compilation, validation, and deployment.

Property Inspector (Lower right)

The Property Inspector displays properties for the selected service component, service, or reference.

You can also edit BPEL activity properties and define deployment descriptor properties for a BPEL process service component.

For more information, see How to Edit BPEL Activities in the Property Inspector. and How to Define Deployment Descriptor Properties in the Property Inspector.

Application View

The Application View shows the artifacts for the SOA composite application.

The composite_name file (also known as the composite.xml file) displays as a tab in the designer and as a file in the Applications window. 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, the next step is typically to add service components that implement the business logic or processing rules of your application. You can use the Components window in 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. At the top of the Components window, click Components.
  2. From the SOA section, drag a component into the designer.

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

    Figure 2-2 Adding a BPEL Process to the SOA Composite Application

    Description of Figure 2-2 follows
    Description of "Figure 2-2 Adding a BPEL Process to the SOA Composite Application"

    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 Component

    Create Spring dialog to create a spring context file for integrating Java interfaces into SOA composite applications.

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

    Figure 2-3 shows the BPEL Process dialog with data entered to create the OrderProcessor BPEL process. The process is selected to be asynchronous. The Expose as a SOAP Service check box directs Oracle JDeveloper to automatically create this service component connected to an inbound SOAP web service.

    Figure 2-3 Create BPEL Process Dialog

    Description of Figure 2-3 follows
    Description of "Figure 2-3 Create BPEL Process Dialog"
  4. Click OK.

    Figure 2-4 shows the OrderProcessor BPEL process service component in the designer. 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 does not appear. You can add a service later by following the steps in How to Add a Service Binding Component.

    Figure 2-4 BPEL Process in Composite

    Description of Figure 2-4 follows
    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 Resources window 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 Applications window.

  • 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 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 Component

    Spring Editor for further designing.

  2. Modify the settings for the selected service component. For help with a service component editor or designer, click Help or press F1. These editors are described in later chapters.
  3. From the File main menu, select Save All.
  4. In the Applications window, double-click composite_name or single-click composite_name above the designer.

    This action returns you to the SOA Composite Editor.

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

Note:

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 can use the Components window in the SOA Composite Editor to drag and drop service binding components to the composite.

To add a service binding component:

  1. In the Components window, drag a SOAP web service to the left Exposed Services swimlane to define the service interface.

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

    Figure 2-5 Adding a SOAP Web Service to a Composite

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

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

    Table 2-6 Service Editors

    Dragging This Service... Invokes The...

    SOAP

    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 11g servers, LDAP server, Coherence cache, sockets, cloud adapters, or Oracle E-Business Suite, JDE World, or SAP applications.

    ADF-BC

    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

    Create EJB Service to create an Enterprise JavaBeans service for using SDO parameters or Java interfaces with Enterprise JavaBeans.

    HTTP

    Create HTTP Binding Wizard to create HTTP binding. This wizard enables you to invoke SOA composite applications through HTTP POST and GET operations.

    Direct

    Create Direct Binding Service dialog to invoke a SOA composite application and exchange messages over a remote method invocation (RMI) in the inbound direction.

    REST

    Create REST Binding dialog to integrate REST operations as service or reference binding components.

    MFT

    MFT Configuration Wizard to create an MFT source or target.

  2. 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 How to Define the Interface (WSDL) for a Web Service.
  3. 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 follows
    Description of "Figure 2-6 Create Web Service Dialog"
  4. 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_name file (for this example, named OrderBookingComposite).

    Figure 2-7 Web Service in Composite

    Description of Figure 2-7 follows
    Description of "Figure 2-7 Web Service in Composite"
  5. Select Save All from the File main menu.

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

As described in 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. From the Technology section, drag a SOAP web service to the left Exposed Services swimlane.

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

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

  3. Select the WSDL file for the service. There are three methods for selection:
  4. 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.

  5. Click OK to return to the Create Web Service dialog.
  6. Note the additional fields 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.

  7. Click OK.
  8. From the File main menu, select Save All.

    Note:

    • 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.2.1 Defining a New WSDL Using a Schema

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

  1. To the right of the WSDL URL field, click the Find existing WSDLs (first) icon.
  2. At the top, click File System.
  3. Select an existing WSDL file from the local file system (for this example, OrderProcessor.wsdl is selected). Figure 2-8 provides details.
2.3.2.2 Selecting an Existing WSDL

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.

  2. At the top, click SOA-MDS. This action enables you to use existing WSDL files from other applications.

2.3.2.3 Automatically Defining a Service Interface WSDL from a Component

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-9 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-9 Automatic Generation of WSDL File

    Description of Figure 2-9 follows
    Description of "Figure 2-9 Automatic Generation of WSDL File"

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-10 provides details.

    Figure 2-10 Selection of Inbound Interface Handle

    Description of Figure 2-10 follows
    Description of "Figure 2-10 Selection of Inbound Interface Handle"

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

    Figure 2-11 Update Interface Dialog

    Description of Figure 2-11 follows
    Description of "Figure 2-11 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...

SOAP

Display the Update Service dialog.

Adapters

Re-enter the Adapter Configuration Wizard.

ADF-BC

Display the Update Service dialog.

B2B

Re-enter the B2B Configuration Wizard.

Healthcare

Re-enter the Healthcare Configuration Wizard.

EJB Service

Display the Update Service dialog.

HTTP

Re-enter the HTTP Binding Wizard.

Direct

Re-enter the Update Service dialog.

REST

Re-enter the REST Binding dialog.

MFT

Re-enter the MFT Configuration Wizard.

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 Resources Window 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 Resources window. 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-12 provides details.

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 Components window from the SOA Composite Editor to drag and drop reference binding components into the composite.

To add a reference binding component:

  1. From the Components window, select SOA.
  2. From the Technology list, drag a service to the right External References swimlane.

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

    Figure 2-13 Adding a SOAP Web Service to the Composite

    Description of Figure 2-13 follows
    Description of "Figure 2-13 Adding a SOAP Web Service to the 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...

    SOAP

    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 11g servers, LDAP server, Coherence cache, sockets, cloud adapters, or Oracle E-Business Suite, JDE World, or SAP applications.

    ADF-BC

    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

    Create EJB Service dialog to create an Enterprise JavaBeans service for using SDO parameters with Enterprise JavaBeans.

    HTTP

    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

    Create Direct Binding Service Dialog to invoke an Oracle Service Bus flow or another SOA composite application.

    REST

    Create REST Binding dialog to integrate REST operations as service or reference binding components.

    MFT

    MFT Configuration Wizard to create an MFT source or target.

  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-14 shows the Create Web Service dialog with data entered to create a reference.

    Figure 2-14 Create Web Service Dialog

    Description of Figure 2-14 follows
    Description of "Figure 2-14 Create Web Service Dialog"
  5. Click OK.

    Figure 2-15 shows the StoreFrontService reference binding component added in the right swimlane of the SOA composite application.

    Figure 2-15 SOAP Web Service in the Composite

    Description of Figure 2-15 follows
    Description of "Figure 2-15 SOAP Web Service in the 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 and makes appropriate changes. 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_name (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 in the composite 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 WSDL Chooser dialog 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 WSDL Chooser dialog.
  2. At the top, select Application Server or WSIL.
  3. Expand the nodes to list all deployed composites and revisions. The default revision is identified by the word Default in the title (for example, FaultFlow [Default 1.0]).

    Figure 2-16 WSDL Chooser Dialog

    Description of Figure 2-16 follows
    Description of "Figure 2-16 WSDL Chooser Dialog"
  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 follows
    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.
  2. If the service component is a BPEL process, double-click the BPEL process to open Oracle BPEL Designer. 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 follows
    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 Applications window, double-click composite_name or single-click composite_name 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 follows
    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 to open Oracle BPEL Designer. 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 follows
    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 Applications window, select the composite_name 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 How to View Schemas for details about the Update Interface dialog.

2.6 Adding Descriptions to SOA Composite Applications

You can add a description of the SOA composite application that is displayed when you place your cursor over the TODO Tasks icon above the composite. The description can describe the actions of the services, references, and service components in the SOA composite application.

2.6.1 How to Add Descriptions to SOA Composite Applications

To add descriptions to SOA composite applications:

  1. Above the SOA Composite Editor, click the TODO Tasks icon. Figure 2-22 provides details.
  2. Double-click in the table row, and add the description.
  3. When complete, click outside the table row, then click Close.
  4. Place the cursor over the TODO Tasks icon above the SOA composite application to display the description. Figure 2-23 provides details.

    Figure 2-23 Description of SOA Composite Application

    Description of Figure 2-23 follows
    Description of "Figure 2-23 Description of SOA Composite Application"

2.7 Renaming, Deleting, and Moving Components and Artifacts

You can rename, delete, and move some components (also known as refactoring) and artifacts in the following sections of Oracle JDeveloper.

  • SOA Composite Editor

    Enables you to rename and delete components. These actions impact Oracle SOA Suite metadata (and not necessarily specific artifacts).

  • Applications window

    Enables you to rename, delete, and move artifacts such as WSDLs, schemas, and so on. These actions impact Oracle JDeveloper artifacts.

Note:

Do not perform refactoring tasks with Oracle BPEL Designer, Human Task Editor, and other editors open. If you do, ensure that you then close and reopen the editors after refactoring. For example, assume you have a BPEL process open, then rename the BPEL process WSDL file in the Applications window. This changes the underlying BPEL file, but Oracle BPEL Designer does not reflect this change and becomes unsynchronized unless you completely exit it. Close and then reopen Oracle BPEL Designer. The changes are then synchronized.

2.7.1 How to Rename and Delete Components in the SOA Composite Editor

Table 2-11 describes the refactoring tasks that you can perform in the SOA Composite Editor, along with known limitations. Carefully review these restrictions before using this feature.

Table 2-11 Refactoring Components

Action SOA Composite Editor Steps

Rename a service component or binding component

  1. Right-click a component and select Rename. Once renamed, all references to the component in the composite are updated.

Note the following restrictions:

  • You cannot rename human workflow, subprocess, or business rule components.

Delete a service component, binding component, or BPEL subprocess

  1. Right-click a component or subprocess and select Delete.

Move a service component or binding component to another folder

You cannot perform this task from the SOA Composite Editor.

2.7.2 How to Rename, Move, and Delete Artifacts in the Applications Window

Table 2-12 describes the refactoring tasks that you can perform in the Applications window, along with known limitations. Carefully review these restrictions before using this feature.

Table 2-12 Refactoring Component Artifacts

Action Applications Window Steps

Rename a service component or binding component artifact

  1. Right-click a component file, and select Refactor > Rename.

Note the following restrictions:

  • Component implementation files (.bpel, .mplan, and so on) are not renamed when the component is renamed in the SOA Composite Editor. This does not cause issues. If you want to rename the implementation files to the same name, use the Applications window.

  • You cannot rename human workflow, subprocess, or business rule components.

  • Renaming or moving of business rule and human task artifacts is not supported. For example, you can rename a human task schema file (for example, HumanTaskPayload.xsd), but references to this XSD in the .task file are not updated.

  • You cannot rename port types, operations, and elements in the WSDL and XSD editors.

  • Do not rename a directory or artifact with blank spaces. Spaces in names lead to invalid references.

  • You cannot rename SOA projects and composites.

Delete a service component, binding component, or BPEL subprocess artifact

  1. Right-click a component file, and select Refactor > Delete.

Note the following restrictions:

  • When you delete an artifact in the Applications window, you are prompted with a message that includes a Show Usages option. When Show Usages is selected, any usages or references to the artifact from within files are displayed. When the Delete option is executed, only the subprocess file is deleted and no references are removed. Ensure that you first select Show Usages and manually remove references to the file to delete.

Move a service component or binding component to another folder

  1. Right-click a component file, and select Refactor > Move.

Note the following restrictions:

  • Moving a database adapter artifact causes problems because the database adapter has many artifacts that are implicitly referenced by name and must be in the same directory.

  • You cannot move component implementation files (.mplan, .bpel, .sbpel, .task, .rules, .spring, and so on) in the Applications window. However, these files can be renamed.

  • Do not move a directory or artifact name with blank spaces. Spaces in names lead to invalid references.

  • If you move an XSLT file, you lose capabilities such as the current expansion/scrolled state and which item was last selected in the XSLT Map Editor. This is because a NonDeployedFiles directory is created in the same folder as the XSLT file. This folder is the default place for test files, dictionary files, report files, DVM/XREF test support files, and so on. This directory is not moved if an XSLT file is moved because the folder contains files used for multiple XSLT files and there is no direct connection between the XSLT file and the file names that may be in the folder. 

2.8 Viewing Component Details in the Property Inspector

The Property Inspector displays details about the selected service component or binding component in the SOA Composite Editor.

To view properties in the Property Inspector:

  1. Select a service, service component, or reference. For this example, a BPEL process service component is selected.

    The Property Inspector is refreshed to display general component details, a section for adding deployment descriptor properties, and attached security policies. Figure 2-24 provides details.

    You can also use the Property Inspector to edit BPEL activities in Oracle BPEL Designer. For more information, see How to Edit BPEL Activities in the Property Inspector. and How to Define Deployment Descriptor Properties in the Property Inspector.

2.9 Adding Security Policies

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 Enabling Security with Policies and Message Encryption.

2.10 Deploying a SOA Composite Application

Deploying a 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 Deploying SOA Composite Applications.

2.10.1 How to Invoke Deployed SOA Composite Applications

You can invoke deployed SOA composite applications from your SOA composite application.

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 SOAP icon from the Components window to the External References swimlane.

    2. In Oracle BPEL Designer, drag a Partner Link from the BPEL Constructs section of the Components window 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. The Application Server section of the WSDL Chooser dialog is displayed.

    2. From the Edit Partner Link dialog, click the SOA Resource Browser icon. The Application Server section of the WSDL Chooser dialog is displayed.

  3. Select Application Server if it is not selected.

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

  5. Expand the application server connection.

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

    Figure 2-25 Browse for a SOA Composite Application

    Description of Figure 2-25 follows
    Description of "Figure 2-25 Browse for a SOA Composite Application"
  7. Select the composite service.

  8. Click OK.

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

2.11 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.11.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 > Application > Connections > Application Server Connection to create a connection.

  1. From the Window main menu, select Application Servers.
  2. Expand your connection name (for this example, named MyConnection).

    The SOA folder appears, as shown in Figure 2-26. 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-26 provides details.

    Figure 2-26 Application Server Navigator

    Description of Figure 2-26 follows
    Description of "Figure 2-26 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-27.

    Figure 2-27 Deployed SOA Composite Applications

    Description of Figure 2-27 follows
    Description of "Figure 2-27 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-13 provides details.

    Table 2-13 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 aborted 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-28 provides details.

    Figure 2-28 Deploy SOA Archive Dialog

    Description of Figure 2-28 follows
    Description of "Figure 2-28 Deploy SOA Archive Dialog"

For more information, see the following documentation:

2.11.2 How to Test and Debug 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 Administering Oracle SOA Suite and Oracle Business Process Management Suite.

In addition to creating a test instance, you can also perform the following testing and debugging tasks in Oracle JDeveloper:

  • 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 Automating Testing of SOA Composite Applications.

  • Test and debug SOA composite applications with the SOA debugger in Oracle JDeveloper. The SOA debugger reduces the development cycle for a SOA composite application by providing a troubleshooting environment within Oracle JDeveloper. This eliminates the lengthy process of building a SOA composite application in Oracle JDeveloper, deploying it to the SOA Infrastructure, starting Oracle Enterprise Manager Fusion Middleware Control to test or view audit trails and flow traces, and then returning to Oracle JDeveloper to repeat the exercise. For more information, see Debugging and Auditing SOA Composite Applications .