This chapter includes the following sections:
For more information about using a REST adapter, see "Defining a Shipping Resource with a REST Service" of Understanding Oracle SOA Suite.
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
Oracle SOA Suite components, services, and reference can be selected and exposed as a REST service. This section describes how to perform the following tasks:
Add REST support as a service binding component in an existing SOA composite application
Add REST support as a reference binding component that can be invoked from a SOA composite application
Configure REST support through shortcuts
Generate REST schemas
Use global token variables for host, port, and protocol values
Note:
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.
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:
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 appears.
Table 36-1 describes the fields on this page.
Table 36-1 Resources Page
Field | Description |
---|---|
Configuration Shortcut | Provides configuration shortcuts based on the context.
|
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 The REST Operation Binding dialog appears. See REST Operation Binding Dialog for detailed information on configuring the fields that appear in the 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 appears. See REST Method Definition Dialog for detailed information on the fields that appear in the REST Method Definition dialog. |
Click Finish to complete your REST binding configuration.
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-2 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.
|
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. |
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-3 REST Operation Binding Dialog
Field | Description |
---|---|
Operation |
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 verb to be bound to the WSDL operation (for example, GET, PUT, POST, or DELETE). This selection populates the URI Parameters table with mappings from the incoming REST query parameters to the WSDL schema. The HTTP verb for the operation is also added to the Operation Bindings section of the Create REST Binding dialog after clicking OK. |
Description |
Enter an optional description. Reference binding components have the Base URI field. |
Request |
The Schema section displays the request schema being used.
The Payload section enables you to specify the format of the request payload: XML (default selection), JSON, URL-encoded, or no payload. 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.
|
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, or no payload. 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.
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. |
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 appears.
Select Service will invoke components using WSDL interfaces.
Click Next.
Under Configuration Shortcut, select REST enable component or service.
The Service Explorer dialog appears.
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 provides details.
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
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 provides details.
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. REST Operation Binding Dialog describes the fields of this 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.
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 > REST.
The REST Binding Configuration Wizard appears.
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 appears.
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 Step 7.
or
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 provides details.
Select the WADL file, and click OK.
Go to Step 7.
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 step based on the type of WADL file selected. Table 36-4 provides details.
Table 36-4 WADL File Status
If the Selected WADL File Was Provided By... | Then... | See 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. |
|
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. |
View the Resources page and its contents, and click OK.
Review the list of recommended corrective actions in the WADL Parsing Issues dialog shown in Figure 36-5, 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, such as in Figure 36-5, 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.
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 .
You can configure the REST adapter through several shortcuts based on WSDL or WADL files.
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
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
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
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
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.
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
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.
You can generate schemas from sample files, including JSON interchange format.
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.
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:
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
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.
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. |
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.
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.
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
However, there are several cases in which the conversion cannot be handled.
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>
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.
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 . . . . . .
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.
The Receive activity of the BPEL process is automatically configured to use a JSON object variable in order to receive the input payload data.
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.
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.
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.
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"/>
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.
You can test the REST adapter with the HTTP Analyzer.
To test the REST adapter with the HTTP Analyzer:
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 Section "Initiating a SOA Composite Application Test Instance" of 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 Section "Configuring Properties for REST Adapters" of Administering Oracle SOA Suite and Oracle Business Process Management Suite.