Integrating REST Operations in SOA Composite Applications

36 Integrating REST Operations in SOA Composite Applications

This chapter describes how to integrate Representational State Transfer (REST) operations as service binding components and reference binding components in SOA composite applications. It also describes how to use a Web Application Description Language (WADL) file during binding component configuration.

This chapter includes the following sections:

For more information about using a REST adapter, see Defining a Shipping Resource with a REST Service in Understanding Oracle SOA Suite.

36.1 Introduction to REST Support

REST is an architecture for designing network applications. RESTful applications use HTTP requests to post data (create and update), get data (for example, make queries), update data, and delete data. REST provides an alternative to using web services.

Starting in 12.2.1, your SOA composites can use end-to-end JSON. This means that the REST service can receive the REST request and route it to the BPEL engine without translating it to XML. The BPEL component can use the JavaScript action, and also use JavaScript in conditional and iterative constructs, to work on JSON objects directly. The REST reference can receive the REST message from the BPEL engine and route it to an external REST endpoint without translation.

Note:

The REST interfaces and BPEL component support end-to-end JSON. However, if you are using other service components, like the Mediator, you need to use the 12.1.3–style composite that internally maps REST resources and verbs to WSDL operations and XML schemas, and translates the incoming payload into XML.

Oracle SOA Suite provides the following REST support:

Support in SOA composite applications:
- Enable End-to-End JSON
- Enable REST support in new or existing services.
- Integrate with external REST APIs.
- Orchestrate a set of RESTful state transitions (RPC/Hypermedia as the Engine of Application State (HATEOAS) approach).
- Support for XML, JavaScript Object Notation (JSON) (with automatic translation to and from XML), text, opaque (binary), and URL-encoded payload data.
- Generation of sample URI for REST service operations.
- Support for WADL services. The WADL can be provided by a deployed Oracle SOA Suite or Oracle Service Bus service or a non-Oracle SOA Suite or Oracle Service Bus service such as a Jersey REST service.
Ease of development:
- Oracle JDeveloper wizard provides several options for modeling REST interfaces and WSDL operation bindings:
  - Manually define resource paths and REST operations to generate an underlying WSDL that contains the mapping from the REST definition to the WSDL.
  - Select the WSDL of the service component or external reference from which to map WSDL operations to resource paths and HTTP verbs.
  - Select a WSDL from many sources (for example, the application server or SOA-MDS) from which to automatically populate the REST adapter with operation mappings.
- Readable API that publishes each method used upon deployment.
- Ability to browse and consume Oracle REST endpoints (including Oracle Service Bus) from within Oracle JDeveloper.
Oracle Web Service Manager (OWSM) policy support for REST security.
Support for the following use cases:
- Get a list of customers
- Create a new customer
- Get customer details
- Update customer details
- Delete a customer
- Create a new address for a customer
- Get an address of a customer
- Update the address of a customer

36.2 Creating REST Support in Service and Reference Binding Components

Oracle SOA Suite components, services, and references can be selected and exposed as a REST service. This section describes:

Note:

Follow Java naming conventions for query, path, and template parameter names while creating Inbound REST bindings (REST service). A REST reference does not require any naming conventions as runtime does not create a Java stub for REST references (outbound REST binding).
You cannot attach a REST binding to an asynchronous component (for example, an asynchronous BPEL process). If you attempt this attachment, a message is displayed that indicates this is not supported and suggests a workaround of placing an Oracle Mediator between the REST adapter and the service that has a one-way interface and routing the service callback to another (outbound) REST adapter service.
You cannot connect a REST service binding component to a REST reference binding component.

36.2.1 How to Configure the REST Binding Component in a SOA Composite Application

This section describes how to add a REST binding component to a SOA composite application. You can add the REST binding component as a service or reference binding component.

To configure the REST adapter as a service or reference binding component in a SOA composite application:

Add a REST service or reference component to the appropriate swimlane of your composite view in JDeveloper. You can also drag a REST component from the Components window.
- To add a REST service component, right-click the Exposed Services swimlane in the SOA Composite Editor, and select Insert > REST. This action adds REST support as a service binding component to interact with the appropriate service component.
- To add a REST reference component, right-click the External References swimlane in the SOA Composite Editor, and select Insert > REST. This action adds REST support as a reference binding component to interact with the external REST endpoint.
The REST Binding Configuration Wizard appears.
Enter a Name for your REST service or reference.

The Type field displays the type of your REST binding. This is Service for a REST service and Reference for a REST reference.
Optionally select the Service will invoke components using WSDL interfaces or Reference will be invoked by components using WSDL interfaces option.
- For REST service, select Service will invoke components using WSDL interfaces if your composite will internally use XML schemas and WSDL operations.
- For REST reference, select Reference will be invoked by components using WSDL interfaces if your composite will internally use XML schemas and WSDL operations.
Starting in 12.2.1, your SOA composites can use end-to-end JSON. This means that the REST service can receive the REST request and route it to the BPEL engine without translating it to XML. The BPEL component can use the JavaScript action, and also use JavaScript in conditional and iterative constructs, to work on JSON objects directly. The REST reference can receive the REST message from the BPEL engine and route it to an external REST endpoint without translation.

By default, the new REST service/reference binding uses WADL. However, select this option if you need to use the 12.1.3–style composite that internally maps REST resources and verbs to WSDL operations and XML schemas, and translates the incoming payload into XML. You would also want to select this checkbox if your composite uses components like the Mediator, which supports only WSDL-based operations.
- If you select this option, then the Enforce XML Schema Ordering option appears.
  
  Select Enforce XML Schema Ordering to enforce the ordering of the XML schema.
  
  When selected, this reorders JSON payloads to match the order of elements in the XML schema. This includes inbound request payloads and responses from outbound requests. This option may add a performance overload.
  
  Selecting this check box sets the REST service binding property reorderJsonAsPerXmlSchema to true in the composite.xml file.

Click Next.

The Resources page is displayed.

Table 36-1 Resources Page

Field	Description
Configuration Shortcut	Provides configuration shortcuts based on the context. For REST Service interfaces: If you are creating a WADL-based REST service, you can choose to Add resources and methods from a WADL service. This enables you to use an existing WADL service to add resources and methods to your REST service. If your service will invoke components using WSDL interfaces, you get options to REST enable a component or service and REST enable external web service.This means that the fault bindings for the selected component or service is automatically generated based on faults defined in the WSDL file. The selected WSDL is read and the WSDL operations are mapped to resource paths and HTTP verbs in the Operation Bindings section of the Resources page. If an operation binding requires additional configuration mapping, this is indicated by the value of no in the Complete column. For REST Reference interfaces: Add resources and operation mappings based on WADL Service enables you to add resources and operation mappings from a WADL resource. The WADL resource can be in your local file system or project, in the design-time Oracle Metadata Services Repository (MDS Repository), or on an application server.
Description	This field appears for REST services. Enter a description for the REST service. The description is published as part of the readable API used during deployment.
Base URI	This field appears for REST references. Base URI connection information for all resources supported by the interface. For example: `http://search.mydomain.com/search.format`
Resource Path	Double-click the default resources path (/) to update the resource path or click Add to add a new resource path. In the Relative Path field, enter the resource path (for example, `/orders`), and click OK.
Operation Bindings	This section appears if you are creating a 12.1.3–style composite that internally maps REST resources and verbs to WSDL operations and XML schemas, and translates the incoming payload into XML. Click Add to add a new operation binding. You can also select an existing operation binding and click Edit. When you click Add or Edit, the REST Operation Binding dialog is displayed. See REST Operation Binding Dialog.
Methods	This section appears if you are creating a WADL-based service or reference that uses untyped payload without schemas. Click Add to add a new method. You can also select an existing method and click Edit. When you click Add or Edit, the REST Method Definition dialog is displayed. See REST Method Definition Dialog.

Click Finish to complete your REST binding configuration.

36.2.1.1 REST Operation Binding Dialog

Use the REST Operation Binding dialog to define REST operations for a REST service that invokes components using WSDL interfaces. You can define resource paths and REST operations. An underlying WSDL is generated that contains the mapping from the REST definition to the WSDL.

Table 36-2 REST Operation Binding Dialog

Field	Description
Method	Displays the WSDL operation name that is being mapped. You can specify the name that is used in the generated WSDL.
Resource	Select an existing URL resource path from the list or click the Add icon to add a new resource path. The selected resource path is added to the URI Parameters table of the Request section at the bottom of this dialog. If the selected resource contains a template variable, such as {var}, the variable is added to the URI parameters.
HTTP Verb	Select the operation to perform (for example, GET, PATCH, PUT, POST, DELETE). When you pick a schema for the request, actions are taken based on the verb. URI parameters are added if the verb does not have a payload (GET, DELETE). The URI Parameters table is populated with mappings from the incoming REST query parameters to the WSDL schema. The PATCH verb is used to partially update a resource, and the PUT verb is used to replace resource entirely. The HTTP verb for the operation is also added to the Operation Bindings section of the Create REST Binding dialog.
Description	Enter an optional description. Reference binding components have the Base URI field.
Request	The Schema section displays the request schema being used. Schema URL: Displays the request schema to use. If you selected REST enable component or reference in the Create REST Binding dialog, this field is read-only because the schema is obtained from the service's operation WSDL. If you selected Add operation binding in the Create REST Binding dialog, you must browse for a schema or create a new schema from a sample using the Native Format Builder wizard. Element: Displays the element to use. The Payload section enables you to specify the format of the request payload: XML (default selection), JSON, URL-encoded, Text, Opaque or no payload. You can choose Other option and define custom payload type. Click Generate Sample Payload to view a sample of the selected request payload. The URI Parameters section enables you to specify the mapping from the REST query parameters to the WSDL schema. This section is automatically populated when a schema is specified (depending on the verb) in the HTTP Verb list. For GET and DELETE verbs, the parameters are bound to the WSDL schema. For POST and PUT verbs, the inbound payload is mapped to the WSDL schema. Click the Generate Sample URL for operation icon (first icon) to generate a sample URL based on all previously entered binding information. This option is typically selected after all parameters are configured. Click the Add parameter icon (second icon) to manually add a mapping parameter. In the Style column, click a specific row to invoke a list that enables you to select query or template. Template variables are typically used for POST and PUT operations. Query parameters are typically used for GET and Delete operations. In the Type column, select the data type of the parameter. All XSD primitive types are supported. In most case, when the parameter is automatically generated from a schema, the type is already set for you. If you create a new parameter, the Type column enables you to select the type from the list. In the Default Value column, you can set a default value at design time for a parameter. If a URI parameter is missing in the REST request, the corresponding default value is used by the REST service. In the Expression column, click a specific row to invoke the Expression Builder dialog for adding an XPath expression function. If there is no schema defined for an operation, the Expression Builder parameter only shows property variables and no message variables. The expression binds a parameter to a field in the WSDL schema. In all cases in which the parameter has been automatically generated (based on an existing or generated schema), this expression is already generated for you. You only add an expression if you want to add a new parameter and bind it to something else, such as a runtime property. The XPath expression specifies the location in which to insert the particular URI parameter in the normalized message. To assign values to query parameters: Double-click the invoke action that calls the REST binding component. Select Properties > To. Select the query parameter from the dropdown list and assign a variable or expression to it. For more information about the invoke activity, see Invoke Activity.
Response	The HTTP Statuses section enables you to specify the HTTP status code. You can enter multiple statuses, separated by spaces. For a reference, these are the possible statuses that are interpreted as successful. For a service, these are the possible successful statuses that can be returned (as set by a service component such as BPEL). The Payload section enables you to specify the possible response payloads: XML (default), JSON, URL-Encoded, Text, Opaque or no payload. You can choose Other option and define custom payload type. The output returned at runtime depends on the incoming requests. Click Generate Sample Payload to view a sample of the selected response payload. The Schema section displays the response schema being used if a possible payload type has been selected. If no payload has been selected, this field is not displayed. Schema URL: Displays the response schema to use. If you have not specified a schema, you can select to browse for an existing schema or create a new schema from a sample with the Native Format Builder wizard. This wizard enables you to create a schema from a JSON interchange format, XML sample, URI-encoded format, or URI sample. For more information, see How to Generate Schemas from Samples. Element: Displays the element to use. The Fault Bindings section displays the response fault name, type, status, and schema. If fault details are defined in the WSDL file, a fault binding is automatically created in this section. You can also manually define fault bindings.by clicking the Add icon. For more information about faults, see What You May Need to Know About REST Fault Binding.

36.2.1.2 REST Method Definition Dialog

Use the REST Method Definition dialog to define REST methods for a SOA REST service or reference that uses WADL and untyped payloads without schemas.

Table 36-3 REST Method Definition Dialog

Field	Description
Method	Enter a name for the REST method being defined.
Resource	Select an existing URL resource path from the list or click the Add icon to add a new resource path.
HTTP Verb	Select the verb to be bound to the WSDL operation (for example, GET, PUT, POST, or DELETE).
Description	Enter an optional description. This is the description text to be published for the method.
Request	The Payload section enables you to specify the format of the request payload: JSON (default selection), XML, URL-encoded, Text, Opaque, or No payload. Click Generate Sample URL for Method to view a sample URL for the method operation. The URI Parameters section enables you to specify the mapping from the REST query or template parameters to the corresponding runtime property. Click the Generate Sample URL for Method icon (first icon) to generate a sample URL based on all previously entered binding information. This option is typically selected after all parameters are configured. Click the Add parameter icon (second icon) to manually add a mapping parameter. Under Style, select query or template. Template variables are typically used for POST and PUT operations. Query parameters are typically used for GET and Delete operations. Under Type, select the data type of the parameter. All XSD primitive types are supported. Under Default Value, you can set a default value at design time for a parameter. If a URI parameter is missing in the REST request, the corresponding default value is used by the REST service. The Runtime Property displays the name of the runtime property to which the method parameter gets mapped. To assign values to query parameters: Double-click the invoke action that calls the REST binding component. Select Properties > To. Select the query parameter from the dropdown list and assign a variable or expression to it. For more information about the invoke activity, see Invoke Activity.
Response	The Success and Failure sections enable you to select the response Payload and Status for the method. The default response payload is No Payload. The default HTTP status code for a successful operation is 204 and that for a failed operation is 500.

36.2.1.3 Example: REST Enable an Existing Service Component

You can REST enable an existing service component by using the REST enable component or service option from the Configuration Shortcut found in the REST Binding Configuration Wizard.

Right-click the Exposed Services swimlane in the SOA Composite Editor, and select Insert > REST

The REST Binding Configuration Wizard is displayed.
Select Service will invoke components using WSDL interfaces.
Click Next.
Under Configuration Shortcut, select REST enable component or service.

The Service Explorer dialog is displayed.
Expand the navigator to select the WSDL of the service component (for this example, a BPEL process), and click OK. This action enables you to map WSDL operations to resource paths and HTTP verbs.

Figure 36-1 WSDL Selected to Map REST Operations to Resource Paths and HTTP Verbs

Description of "Figure 36-1 WSDL Selected to Map REST Operations to Resource Paths and HTTP Verbs"

The REST Binding Configuration Wizard Resources page is updated to appear as shown in Figure 36-2.

The selected WSDL is read and the WSDL operation is mapped to resource paths and HTTP verbs in the Operation Bindings section. Note that the Resource Path and HTTP Verb sections require additional configuration mapping. This is also indicated by the value of no in the Complete column.

Figure 36-2 Resources Page of the REST Binding Configuration Wizard

Description of "Figure 36-2 Resources Page of the REST Binding Configuration Wizard"

The resource path and HTTP verb for each of the operations now require configuration. For this example, there is only one operation. Depending upon your WSDL, multiple operations can be displayed in the Operation column.
In the Resource Path table of the Resources section, double-click the default path entry of /. You can also define the resource path before starting the operation bindings. In this case, the selected resource is used for the new bindings.

This invokes the Update REST Resource dialog.
In the Relative Path field, enter the resource path (for this example, /orders), and click OK.

Figure 36-3 Update REST Resource Dialog

Description of "Figure 36-3 Update REST Resource Dialog"

Operation mappings that have the old resource path are updated with the new resource path in the Resources section and Operation Bindings section (for this example, /orders). If you are updating an existing component, all operations are typically updated.

You can create additional resource paths as needed by clicking the Add icon in the Resources section to display the Create REST Resource dialog.

The HTTP Verb column of the Operation Bindings section now requires configuration.
In the Operation Bindings section, select an operation and click Edit.

The REST Operation Binding dialog is displayed. This dialog enables you to select the HTTP verb for the operation and populate the URI Parameters section in order to bind an HTTP verb and resource to a WSDL operation and map REST parameters to the WSDL schema of the component service. See REST Operation Binding Dialog.
From the Resource list, select the new resource, as needed.

The URI Parameters section is updated with your selection.
From the HTTP Verb list, select the operation (for this example, GET).

The URI Parameters section is updated with your selection.

The style (query or template) is automatically selected in the Style column of the URI Parameters section.

If you select or create a new REST resource that contains a template variable, Oracle JDeveloper attempts to create the template parameter with the same name. If a parameter with that name already exists, it is reused (and made into a template parameter if it was a query parameter). Duplicate parameter names are never created. You receive an error if a duplicate parameter is manually created.
Click the Response tab to view HTTP status code, payload output type, schema, and fault binding details. Since the schema was already defined in this example, those sections are disabled from editing.
Double-click the fault name to invoke the REST Fault Binding dialog. For more details about this dialog, click the Help icon or see What You May Need to Know About REST Fault Binding.
Edit as necessary, and click OK.
Click OK to return to the Resources page. The HTTP verb you added is displayed.
In the Operation Bindings section, select an operation and click Edit to define resources and HTTP verbs for any remaining operations.
Click OK to return to the SOA Composite Editor.

The REST service is wired to the BPEL process service component.

36.2.1.4 Example: Adding Resources and Operations from a WADL Service to a REST Reference

You can add resources and operations to a REST reference from a WADL service using the Configuration Shortcut found in the REST Binding Configuration Wizard.

Right-click the External References swimlane in the SOA Composite Editor, and select Insert, then REST.

The REST Binding Configuration Wizard is displayed.
Enter a Name for your REST service or reference.

The Type field displays Reference.
Select Service will be invoked by components using WSDL interfaces.
Click Next.
Under Configuration Shortcut, select Add resources and operation mappings based on WADL Service.

The WADL Location dialog is displayed.
Specify a WADL file through one of the following methods:
- In the WADL URL field, specify the URL of the WADL file, then go to the next step.
or
1. Click the Search icon to invoke the WADL Chooser dialog for selecting the WADL file. Options are provided for finding WADLs in the local file system or project, in the design-time Oracle Metadata Services Repository (MDS Repository), or by connecting to an application server to find WADLs associated with deployed Oracle SOA Suite or Oracle Service Bus services.
  
  Figure 36-4 WADL Chooser Dialog
  
  Description of "Figure 36-4 WADL Chooser Dialog"
2. Select the WADL file, and click OK.
Click OK.
Select copy schema artifacts into the project to copy schemas referenced in the WADL file to the local project because they are used by the new REST adapter reference. This is the recommended method.

See the table below for the next step based on the type of WADL file selected.

Table 36-4 WADL File Status

If the Selected WADL File Was Provided By...	Then...	Next Step...
An Oracle SOA Suite or Oracle Service Bus REST service	The Resources page is completely configured with information from the WADL file. All operations, resource paths, and verbs are displayed in the Operation Bindings section. A complete configuration is indicated by a value of yes in the Complete column of the Operation Bindings section.	View the Resources page and its contents, and click OK.
A non-Oracle SOA Suite or Oracle Service Bus REST service such as a Jersey service.	The WADL Parsing Issues dialog indicates that additional configuration is required.	Review the list of recommended corrective actions in the WADL Parsing Issues dialog, then click OK. The same information is written to the Oracle JDeveloper Log window for later reference. A WADL file for a non-Oracle SOA Suite or Oracle Service Bus service typically does not include all required information. You must manually complete configurations. In many cases, the WADL file used does not supply the schemas required to bind the REST reference to a WSDL operation. The schemas can often be generated using the Native Format Builder wizard using a sample payload provided by the REST service provider. Figure 36-5 WADL Parsing Issues Description of "Figure 36-5 WADL Parsing Issues" The Resources page is displayed. For a REST binding that requires further configuration, a value of no is displayed in the Complete column of the Operation Bindings section. Tool tips in the Complete column for each no value identify what is missing so that you can perform corrective actions. The OK button is disabled as long as at least one operation has a value of no in the Complete column. Note: All error and warnings are also displayed in more detail in the Log window in Oracle JDeveloper. For example, the Log window contains entries such as the following: ERROR at [resource path: containers/{container}, method name: PUT, request/response: response, representation mediaType: application/xml ] - No schema information is available for containers/{container}.PUT response. Please specify a schema. Perform the corrective actions indicated by the tool tips. When configuration has been successfully completed, a value of yes is displayed for all operations in the Complete column of the Operation Bindings section. For more information about the SOA design-time MDS Repository, see Managing Shared Data with the Design-Time MDS Repository.

36.2.2 How to Consume REST-Based Integrations Created in Oracle Integration in SOA Composite Applications

The REST Adapter can connect to REST-based integrations created in Oracle Integration through the Oracle Integration Connect plugin, which allows you to browse integrations created in Oracle Integration (in Oracle Cloud) and select them for use in on-premises SOA composite applications.

This type of integration may be called a hybrid integration—an integration developed in the cloud that can be used in on-premises applications. The integration must meet the following criteria to be used in SOA composite applications:

Have a REST endpoint
Be deployed and activated
Have a Swagger document for the integration

To consume an integration in a SOA composite application, perform the following tasks:

36.2.2.1 Create an Oracle Integration Connection

To create an Oracle Integration connection:

In the Oracle JDeveloper Resources window, click the New icon, select IDE Connections, then select Oracle Integration Connection.
In the Create Oracle Integration Connection dialog, enter a name for the connection in the Connection Name field.
In the URL field, enter the hostname and port number of the Oracle Integration instance.
Enter the User Name and Password of the Oracle Integration instance.
Click Test Connection and accept the security certificate.
Click OK.

36.2.2.2 Create a REST Binding

To create a REST binding:

In Oracle JDeveloper, right-click in the project design window (in the External References swimlane), select Insert, then REST.
In Step 1 of the REST Binding Configuration Wizard, enter a name for the REST binding.
Click Next.
In Step 2 of the REST Binding Configuration Wizard, select the integration in one of two ways:

Description of the illustration rest-binding-configuration-wizard-2.png
- Create a REST binding by selecting an integration:
  - In the WADL or Swagger Chooser dialog, with the Oracle Integration Connect plugin highlighted, select the connection that you created for the Oracle Integration instance.
    
    Description of the illustration rest-binding-configuration-select-flows.png
    If a connection does not exist for the Oracle Integration instance you need, you can create a new connection. To create a connection, either click the Create new connection icon or follow the steps in Create an Oracle Integration Connection to open the Create Oracle Integration Connection dialog.
  - Select the integration you want to use.
    
    Click the Information icon to display details about the integration, including name, version, description, and a View Swagger button to view the Swagger document for the integration.
  - Click OK.
  - Click Finish in the wizard.
- Create a REST binding using the Swagger Document URL:
  - In the WADL or Swagger Document URL field, enter the URL of the Swagger document for the integration you want to use.
    
    You can find this URL through the WADL method described above, where selecting the integration shows the Swagger document URL in the Selection field at the bottom of the wizard. You can also obtain the Swagger URL in Oracle Integration by clicking the How to run icon next to the integration name, and clicking the Endpoint URL link.
    
    The wizard fetches the contents of the Swagger document, converts it into WADL, and displays the resources.
  - Click Finish.

36.2.2.3 Configure OWSM Policies on the REST Reference

If the Oracle Integration endpoint has configured policies, configure appropriate SOA OWSM policies on the REST reference:

Right-click the created REST business object and select Configure Policy.
In the Policy Configuration screen, select From OWSM Policy Store.
Click the + icon for the policy type you wish to configure.
Select the policy.
Click Save.

36.2.2.4 Configure and Deploy the Application

To configure and deploy your application to use the integration:

Complete your application by adding Inbound and BPEL Process to invoke the REST reference.
Deploy your application to the SOA server.
Test your application.

36.2.3 How to Configure the REST Adapter Through Shortcuts

You can configure the REST adapter through several shortcuts based on WSDL or WADL files.

36.2.3.1 To generate a REST service based on a web service deployed on an application server:

From the Oracle JDeveloper main menu, select Window > Application Servers.
Right-click a WSDL service and select SOA > Expose as REST. Figure 36-6 provides details.

Figure 36-6 Automatic REST Adapter Service Binding Component Configuration

Description of "Figure 36-6 Automatic REST Adapter Service Binding Component Configuration"

The Create REST Binding dialog is invoked and prepopulated with operation mappings from the selected WSDL file.
Complete any necessary configuration by following the procedures in How to Configure the REST Adapter as a Service Binding Component in a SOA Composite Application.

Note:

You are prompted to make a local copy of the selected WSDL and its dependent artifacts. If you select to make a local copy, the binding.ws section for the SOAP reference binding component contains the original concrete WSDL/endpoint location that was selected and the copied WSDL is used as the abstract WSDL (in the composite import, and so on).

When configuration is complete, a REST service binding component is wired to a SOAP reference binding component. Figure 36-7 provides details.

Figure 36-7 REST Service Binding Component and SOAP Reference Binding Component Configuration

Description of "Figure 36-7 REST Service Binding Component and SOAP Reference Binding Component Configuration"

36.2.3.2 To generate a REST reference based on a REST service deployed on an application server:

From the Oracle JDeveloper main menu, select Window > Application Servers.
Right-click a REST/WADL service and select SOA > Generate REST Reference. Figure 36-8 provides details.

Figure 36-8 Automatic REST Adapter Reference Binding Component Configuration

Description of "Figure 36-8 Automatic REST Adapter Reference Binding Component Configuration"

The Create REST Binding dialog is invoked and prepopulated with information from the selected WADL file.
Complete any necessary configuration by following the procedures in How to Configure the REST Adapter as a Reference Binding Component in a SOA Composite Application.

When configuration is complete, a REST reference binding component is displayed, as shown in Figure 36-9.

Figure 36-9 REST Adapter Reference Component

Description of "Figure 36-9 REST Adapter Reference Component"

36.2.3.3 To generate a REST service based on a SOA component's WSDL service:

In the SOA Composite Editor, right-click a SOA component service or an external reference, and select the Expose as REST option. Figure 36-10 provides details.

Figure 36-10 Expose as REST Option

Description of "Figure 36-10 Expose as REST Option"

The Create REST Binding dialog is invoked and prepopulated with information from the selected WADL file.
Complete any necessary REST adapter configuration.

When configuration is complete, REST support (for this example, a service binding component) is created and automatically wired to the interface on which you clicked. Figure 36-11 provides details.

Figure 36-11 REST Adapter Service Binding Component

Description of "Figure 36-11 REST Adapter Service Binding Component"

36.2.4 How to Generate Schemas Manually

If you do not have a schema or sample data to generate a schema, you can manually enter the parameters for which to generate a schema. To manually define a schema, click the Add icon, and select Add operation binding in the Operation Bindings section of the Create REST Binding dialog.

Note the following guidelines:

In the URI Parameters section of the REST Operation Binding page, enter the necessary query or template parameters. You can select a data type for each parameter, but you do not need to enter an expression. If there is no schema and payload specified, when you click OK, the parameter schema is automatically generated (embedded in the WSDL). Parameters that have an expression that is mapped to a runtime property are not included in the generated schema.
If there is no schema defined for an operation, the Expression Builder dialog that is accessible from the Expression column only shows property variables and no message variables.

For complete instructions about creating REST support, see How to Configure the REST Adapter as a Service Binding Component in a SOA Composite Application and How to Configure the REST Adapter as a Reference Binding Component in a SOA Composite Application.

36.2.5 How to Generate Schemas from Samples

You can generate schemas from sample files, including JSON interchange format.

In the Request section of the REST Operation Binding dialog, click the Define Schema for Native Format icon to the right of the Schema URL field. Figure 36-12 provides details.

Figure 36-12 Define Schema for Native Format Icon

Description of "Figure 36-12 Define Schema for Native Format Icon"

The Native Format Builder wizard is displayed.
Proceed through the initial pages of the wizard until you access the Choose Type page.

This page enables you to select to generate schemas from different format types. Figure 36-13 provides details.

Figure 36-13 Types From Which to Generate Schemas

Description of "Figure 36-13 Types From Which to Generate Schemas"
Select an appropriate type.

Each type provides an area in which to paste a JSON, XML, or URL sample or select a sample file to import.

For more information about JSON interchange formats, see What You May Need to Know About Converting a JSON Interchange Format to a REST Schema.

36.2.6 How to Use Global Token Variables

You can assign global token variables for the host name, port number, and protocol in the Base URI field of the Create REST Binding dialog.

To use global token variables:

Above the SOA Composite Editor, click the Binding URL Tokenizer icon.
Select the REST external reference, and click the Edit icon.
Specify the mdm-url-resolver.xml file or manually enter values for host, port, and protocol (http or https), and click OK.

The values that you assign to the tokens are then substituted in place of the hard-coded HTTP host and port values in the location attribute of the binding.ws element of the composite.xml file. For more information, see Creating Tokens for Use in the Binding URLs of External References.

36.2.7 How to Set REST Header Properties

Normalized message properties are available for certain standard HTTP headers. These properties are displayed for selection in the Properties tab of receive and reply activities in a BPEL process in Oracle JDeveloper, as shown in Figure 36-14. These header properties are not propagated by default across the service engines. You must manually propagate them by providing the appropriate assignment logic.

Figure 36-14 Normalized Message Properties in Receive and Reply Activities

Description of "Figure 36-14 Normalized Message Properties in Receive and Reply Activities"

36.2.7.1 Inbound and Outbound Headers

For inbound cases in which an external client is interacting with a SOA REST service, you can configure the service to send a hyperlink to the next resource with which the client interacts. This hyperlink can be sent in the payload of the response or the HTTP link response header. The following normalized message properties build and return the next link:

rest.binding.requestBaseURI

This property is available on the request message. It holds the base URI of the REST service. In the SOA composite application, this can be combined with the path of another resource in the same REST service to build an absolute URL linking back to that resource.
rest.binding.http.Link

When this property is set on the response message, a link header is added to the HTTP response. The value of this header is the value of the normalized message property.

For outbound cases in which the SOA composite application is invoking an external REST service, the service may return a response with the next link either in the link header or the payload. The following normalized message properties are available to help get the next link and invoke the resource located at that link:

rest.binding.http.Link

If the HTTP response from the external REST service contains a link header, a rest.binding.http.Link property is added to the response message. The value of this property is the value in the link header.
rest.binding.requestURI

The resource located at the next link can be invoked by setting the rest.binding.requestURI property on the request message. If set, the URL in this property overrides the URL provided at design time. It invokes the external REST service.

There are several preconditions that must be satisfied when a SOA composite application is invoking REST resources based on the next link it receives from the external REST service:

The potential resources that can be invoked must be designed in the REST reference binding component at design time.
The structure of the request and response must be known and modeled at design time.

For information about setting normalized message properties in the Properties tab, see Propagating Normalized Message Properties Through Message Headers.

36.2.7.2 Custom Header Support

REST services and references are capable of handling custom HTTP headers. Table 36-5 provides details.

Table 36-5 Custom Header Support

Direction	Service Side	Reference Side
Request	Any HTTP headers that come in the request are propagated as normalized message properties. The headers are appended with rest.binding.http.header-name. These headers are available in the service engine as part of normalized message properties. For example, any individual header can be obtained with the BPEL process in the receive and reply activity properties.	All normalized message properties prefixed with rest.binding.http.* are added as HTTP headers to the HTTP request. The REST service removes the prefix rest.binding.http. from the header name. before attaching the headers to the HTTP request.
Response	All normalized message properties prefixed with rest.binding.http.* are added as HTTP headers to the HTTP response. The REST service removes the prefix rest.binding.http. from the header name before attaching the headers to the HTTP response.	Any HTTP headers coming in the response are propagated as normalized message properties. The headers are appended with rest.binding.http.header-name. These headers are available in the service engine as part of normalized message properties. For example, any individual header can be obtained with the BPEL process in the receive and reply activity properties.

36.2.8 What You May Need to Know About REST Fault Binding

You define REST fault binding response details in the REST Fault Binding dialog, as shown in Figure 36-15. If fault details are already defined in the WSDL file, a fault binding is automatically created in the Fault Bindings section of the REST Operation Binding dialog. You can also manually define fault bindings.by clicking the Add fault binding icon in the Fault Bindings section.

Figure 36-15 REST Fault Binding Dialog

Description of "Figure 36-15 REST Fault Binding Dialog"

By default, the fault status is 400 when there is a fault payload and 404 when there is no fault payload.

Fault binding details are based on your selection in the Create REST Binding dialog:

If you selected REST enable component or reference, fault bindings are automatically generated based on faults defined in the WSDL file.
If you selected Add operation binding, you must configure the fault bindings to be supported, which are added to the WSDL being generated.

The Fault Bindings section of the REST Operation Binding dialogs shows the response fault name, type, status, and schema. Figure 36-16 provides details.

Figure 36-16 Fault Bindings Definition

Description of "Figure 36-16 Fault Bindings Definition"

36.2.9 What You May Need to Know About Converting a JSON Interchange Format to a REST Schema

You can select to create a REST schema from a JSON interchange format sample in the Choose Type dialog of the Native Format Builder wizard, as shown in Figure 36-13. During schema generation, the wizard attempts to do the following:

Generate a REST schema with no namespace information
Consume a JSON interchange format sample with no namespace information and generate an XML with the correct namespaces

Note:

Use the JVM property soa.rest.nillable.support to turn on nillable support for SOA REST service. Values are:

false (default): always returns null for an empty string in the response. For example, if the payload includes data "mileage" : "", the response returns "mileage" : null
true: differentiates between "" and null. For example, if the payload includes data "mileage" : "", the response returns "mileage" : ""

To set soa.rest.nillable.support to true:

include attribute nillable="true" in the NXSD element
include attribute xsi:nil="true" in the XML element

Example:

When soa.rest.nillable.supported is true, the mileage element returns "" or null, matching what is provided as input ("" or null).

{
  "sampleData" : {
    "dateTime" : "2022-04-07 10:58:30",
    "mileage" : ""
  },
  "userInfo" : {
    "user" : "Davidson",
    "ctryCode" : "IN"
  }
}

When soa.rest.nillable.supported is false (default), the mileage element always returns null, regardless of what is provided as input ("" or null).

{
  "sampleData" : {
    "dateTime" : "2022-04-07 10:58:30",
    "mileage" : null
  },
  "userInfo" : {
    "user" : "Davidson",
    "ctryCode" : "IN"
  }
}

There are cases in which the conversion cannot be handled.

Sibling elements with duplicate names under a sequence group element cannot be converted because this translates to an object with duplicate keys in JSON, which is not valid.

Namespace information is retained to enable the JSON interchange format sample, shown in the following example, to be converted. This is because the underlying schema has elements and attributes from multiple namespaces.

<schema xmlns:us="http://xmlns.oracle.com/addresses/us"
xmlns:india="http://xmlns.oracle.com/addresses/india"
targetNamespace="http://xmlns.oracle.com"
xmlns="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
   <import ...>
   <element name="Person">
       <complexType>
           <choice>
                <element ref="us:Address"/>
                <element ref="india:Address"/>
           </choice>
       </complexType>
   </element>
</schema>
<schema targetNamespace="http://xmlns.oracle.com/addresses/us"
xmlns="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
   <element name="Address">
       <complexType>
           <sequence>
                <element name="Street" type="xsd:string"/>
                <element name="City" type="xsd:string"/>
                <element name="State" type="xsd:string"/>
                <element name="ZipCode" type="xsd:integer" minOccurs="0"/>
           </sequence>
       </complexType>
   </element>
</schema>
<schema targetNamespace="http://xmlns.oracle.com/addresses/india"
xmlns="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
   <element name="Address">
       <complexType>
           <sequence>
                <element name="Street" type="xsd:string"/>
                <element name="City" type="xsd:string"/>
                <element name="District" type="xsd:string" minOccurs="0"/>
                <element name="State" type="xsd:string"/>
                <element name="PinCode" type="xsd:integer" minOccurs="0"/>
           </sequence>
       </complexType>
   </element>
</schema>

36.2.10 What You May Need to Know About REST References Calling REST Services in the Same Node

The SOAIncomingRequests_maxThreads property by default is configured based in the SOADataSource data source in Oracle WebLogic Server Administration Console. This setting may be not enough for REST services under a heavy load (for example, if you have 200 concurrent users in a scenario in which a REST reference is calling a REST service within the same node). You must increase the SOAIncomingRequests_maxThreads value to 400 to avoid the exception error shown in the following example:

<May 2, 2014 10:16:11 AM PDT> <Error> <oracle.soa.bpel.system> <BEA-000000>
<cube engineJTA transaction is not in active state.
The transaction became inactive when executing activity "" for instance
"30,023", bpel engine can not proceed further without an active transaction.
please debug the invoked subsystem on why the transaction is not in active
status. the transaction status is "MARKED_ROLLBACK".
The reason was The execution of this instance "30023" for process
"BuyCoffeeBPELProcess" is supposed to be in an active jta transaction, the
current transaction status is "MARKED_ROLLBACK", the underlying exception is
"Service Unavailable" .
Consult the system administrator regarding this error.
, Cikey=30023, FlowId=20014, Current Activity Key=30023-BpInv0-BpSeq0.3-3,
Current Activity Label=InvokeCreateOrder,
ComponentDN=default/CoffeeShopClient!1.0*soa_19d4a881-115b-42c5-824d-1af3fa766
62d/BuyCoffeeBPELProcess
oracle.fabric.common.FabricInvocationException: Service Unavailable
        at
. . .
. . .

36.3 Using JavaScript and JSON in BPEL Components

The BPEL component can work both with XML and JSON variables. You can use JavaScript at all places where you can use XPath expressions. JavaScript can be used for predicates, expressions, and within the JavaScript BPEL activity.

Using JSON Variables

You can choose to create a BPEL process based on an existing REST Service and add the methods from the REST service. This is illustrated in the following image.

Create BPEL Process dialog with REST Service selected

The Receive activity of the BPEL process is automatically configured to use a JSON object variable in order to receive the input payload data.

Variable Chooser dialog.

You can create additional schema-less JSON variables for your BPEL process, as required.

Setting the Expression Language for Your BPEL Process

In BPEL Designer, right-click a blank area in the BPEL process area. The Edit Process dialog appears. Set the Query Language and Expression Language fields, as required. To use JavaScript you can use js.

Edit Process dialog

Using JavaScript Expressions

You can use JavaScript at all places where you can use XPath expressions. You can use these expressions in BPEL activities and conditional and iterative constructs. This section provides some examples.

The following example shows a JavaScript expression used in an Assert activity. The expression checks to see if the type of process input is an object.

Edit Assert dialog

The process variable is a global variable that is accessible to the JavaScript context during execution.

The following code shows a JavaScript condition that might be used in a While activity:

process.counter < 10

The following code shows a JavaScipt expression that might appear in a Wait activity:

bpel.until(process.counter + 3)

The following code shows a JavaScript expression that might appear in a branch of the Switch activity, and helps to test for odd numbers:

process.counter % 2 == 1

Using the JavaScript Activity

You can use the JavaScript activity in a BPEL process to add JavaScript code snippets or blocks of code. To add a JavaScript activity, drag the JavaScript icon from the Components window to the appropriate place in your BPEL process. You can double-click the added JavaScript activity to edit it. The following image shows JavaScript code that calls xpath and bpel object functions.

Edit Javascript dialog

xpath is a global object that binds to all XPath functions. So, for example, var o = process.output.xpath creates a new xpath object, and o.refid = xpath.ora.getECID() calls the getECID function for the ora namespace prefix.

The following JavaScript code might appear in a JavaScript activity to write output to the server console and BPEL audit log:

console.log("input: ", process.input)
console.log("output: ", process.output)
audit.log("output: ", process.output)

Importing JavaScript Files in Your BPEL Process

You can import external JavaScript files, containing JavaScript functions, into your BPEL process. The JavaScript functions contained in these files then become available to be used within your BPEL process. The following lines use the import and include statements to fetch the main.js and one.js files into a BPEL process:

<bpelx:js include="jslib/main.js"/>
<bpelx:js import="jslib/one.js"/>
<import location="jslib/lib.js" importType="javascript"/>

The difference between include and import is that the import statement ensures that the file is included only once irrespective of the number of imports.

The following image shows the source window of a BPEL process with the include/import statements. Notice where the JavaScript files appear under the project folder.

including javascript files in BPEL

36.4 Testing the REST Adapter with the HTTP Analyzer

You can test the REST adapter with the HTTP Analyzer.

To test the REST adapter with the HTTP Analyzer:

Copy the WADL file URL from the home page of the SOA composite application in Oracle Enterprise Manager Fusion Middleware Control, as shown in Figure 36-17.

Figure 36-17 WADL File URL in Oracle Enterprise Manager Fusion Middleware Control

Description of "Figure 36-17 WADL File URL in Oracle Enterprise Manager Fusion Middleware Control"
In the HTTP Analyzer, click the Open URL icon, enter the WADL URL copied from Oracle Enterprise Manager Fusion Middleware Control, and press Return.

The WADL file is included with the POST method. Figure 36-18 provides details.

Figure 36-18 WADL File and POST Method

Description of "Figure 36-18 WADL File and POST Method"
Click Test.
Copy and paste a sample request XML payload into the Request HTTP Headers section and click Send Request. You can also specify JSON formats. Figure 36-19 provides details.

Figure 36-19 Request Message

Description of "Figure 36-19 Request Message"

After processing completes, a response message is displayed. For this example, a message with an order status of Shipped is displayed. Figure 36-20 provides details.

Figure 36-20 Response Message

Description of "Figure 36-20 Response Message"

36.5 Testing and Configuring REST Reference Binding Components in Oracle Enterprise Manager Fusion Middleware Control

You can initiate instances of SOA composite applications that include REST binding components from the Test Instances page in Oracle Enterprise Manager Fusion Middleware Control. This page enables you to test any WSDL or WADL. For more information, see Initiating a Test Instance of a Business Flow in Administering Oracle SOA Suite and Oracle Business Process Management Suite.

You can configure properties for REST reference binding components in Oracle Enterprise Manager Fusion Middleware Control. For more information, see Configuring Properties for REST Adapters in Administering Oracle SOA Suite and Oracle Business Process Management Suite.