9 Creating and Configuring Business Services

This chapter describes how to create, configure, and manage business services using the Oracle Service Bus Console and JDeveloper. Service Bus business services, along with proxy services, provide the means for managing services, transforming messages, and routing messages through the enterprise.

9.1 Introduction to Business Services

Business services are Service Bus definitions of the enterprise services with which you want to exchange messages. They define enterprise web services to which Service Bus is a client. Those external web services are implemented in and hosted by external systems. Service Bus must know what to invoke, how to invoke it, and what to expect as a result. Business services model those interfaces so that Service Bus can invoke the external services.

You define business services using WSDL (Web Services Definition Language) or Web Application Definition Language (WADL), just as you would define a proxy service. A business service configuration includes its interface, transport settings, and security settings. If the business service is based on a WSDL document, the configuration also includes a WSDL port or a WSDL binding. (See Working with WSDL Documents.)

You can base business services on existing WSDL and WADL documents, including documents imported from a UDDI registry, SOA Oracle Metadata Services (MDS) Repository, an application server, or the file system. Service Bus also supports business services that use the REST binding (see Creating REST Services with Oracle Service Bus ). These services are based on WADL documents and can only be created using the Service Bus Overview Editor in JDeveloper.

9.1.1 Business Service Definitions

Each business service is defined by whether it is based on a WSDL web service or a Service Bus transport. A WSDL-based service is a SOAP or XML business service whose interface is described by a WSDL document. A transport-typed service is a business service based on a Service Bus transport, including the JCA transport, which provides support for configuring business services for Oracle JCA-compliant adapters. It also includes REST business services, which use the HTTP transport. Each type of business service supports transport protocols specific to its definition. Service Bus supports several standard transport protocols as well as custom transports.

You can use either the Create Business Service wizard or the Service Bus Overview Editor in JDeveloper to create business services with either a WSDL-based or transport-typed service. Using the Service Bus Overview Editor, you can also generate business services directly from a JCA adapter to create a business service already configured for that adapter type. Both the wizard and the editor let you generate business services from proxy services.

9.1.2 Service Types and Protocols for Business Services

Service Bus supports various service types ranging from conventional web services (using XML or SOAP bindings in WSDL files) to non-XML (generic) services. When you create a transport-typed business service, you also need to further define the service by specifying and configuring the service type. The service types you can select are restricted based on the transport used to communicate with the service endpoint. For information about the transports supported with each service type, see Transports, Adapters, and Bindings.

A business service can have one of the following service types, identified by the types of messages it processes:

  • WSDL Based Service: This service type is generated from an existing WSDL document or one that you create at the same time you create the business service. When creating a WSDL-based service, you need to specify the port or binding to use.

  • Messaging Service: This service type can receive messages of one data type and respond with messages of a different data type. Supported data types include XML, Message Format Language (MFL), text, untyped, binary, Java, and attachments where the interface is not described by WSDL

  • Any SOAP Service: This service type exchanges SOAP messages. SOAP messages are constructed by wrapping the contents of the header and body variables inside a <soap:Envelope> element. If the body variable contains a piece of reference XML, it is sent as is; that is, the referenced content is not substituted into the message. If attachments are defined in the attachments variable, a MIME package is created from the main message and the attachment data. Content handling for each attachment part is similar to how it is handled for messaging services.

  • Any XML Service (non-SOAP): With this service type, messages to XML-based services are XML, but can be of any type the business service configuration allows. In messages that include attachments, their content is a MIME package that includes the primary XML payload as one of its parts (typically the first part or the one identified by the top-level content-type header).

  • REST Service: This type of service is based on the REST binding, and can be generated from an existing WADL or one that you create at the same time you create the proxy service (Typed REST), or can be created without a WADL or schema (Untyped REST). For more information, see Creating REST Services with Oracle Service Bus .

9.1.3 Binding Definitions and Runtime Variables for Business Service Types

Each business service type is modeled following the same pattern, which must be configured for the service. These models are the same as those for proxy services. For more information, see Binding Definitions and Runtime Variables for Proxy Service Types.

9.1.4 Business Service Transport Protocol Configuration

Much of the configuration for business services involves the transport protocol. Transports are the communication layer between the external systems and the business services. The available transport protocols for a business service vary depending on the service type you are creating. Each transport protocol has its own configuration requirements. For more information about transport protocols and their configuration requirements, see Working with JCA Adapters, Transports, and Bindings and click the link to the specific protocol you are interested in.

Based on the transport and WSDL file or interface, the transport mode is automatically selected, but you can overwrite it using the routing options action for a route or publish action.

You can configure the following parameters for each business service:

  • List of weighted endpoint URIs in the format <string URI, integer weight>; for example, <http://www.oracle.com, 100>. For a random-weighted list, the list should contain at least one element.

  • Load-balancing algorithm, which can be round-robin, random, or random-weighted. If you select random-weighted, the weights are applicable for each URI.

  • Retry Count

  • Retry Iteration Interval

  • Retry Application Errors

The transport you select must be able to support the transport mode (that is, request/response, one-way or both) required by the binding definition, and be configured accordingly.

For services exchanging messages in both modes (request/response and one-way), you must configure the binding layer so it can select the transport mode accordingly. This occurs automatically when the service is a concrete type, as it is described in the binding definition. When it is not a concrete type, to configure the binding layer, you must use the routing options action in the pipeline to set the mode for a route or publish.

For a Tuxedo transport-based service, if the service type is XML, an FML32 buffer with an FLD_MBSTRING field from a Tuxedo client will not be transformed to XML For information about configuring business services based on various transport protocols, see Working with JCA Adapters, Transports, and Bindings.

9.1.4.1 About the Load Balancing Algorithm

The load balancing algorithm defines the order in which the endpoint URIs are selected at runtime. Service Bus supports the following algorithms:

  • Round-robin: Dynamically orders the URIs that you define for a business service. If the first one fails, it tries the next one, and so on until the retry count is exhausted. For every new message, there is a new order of URIs.

  • Random: Randomly orders the list of URIs that you define for a business service. If the first one fails, it tries the next one, and so on until the retry count is exhausted.

  • Random-weighted: Randomly orders the list of URIs that you define for a business service, but some are retried more than others based on the value you enter in the Weight field.

  • None: Orders the list of URIs that you define for a business service from top to bottom.

9.1.4.2 About Business Service URI Retries

The retry option for business services specifies the maximum number of times a business service can attempt to access endpoint URIs after an initial failure. For example, consider the behavior of a business service B with endpoint URIs eu1, eu2, and eu3, when the retry count is set to 1, 2, and 4.

When Retry Count = 1: If business service B fails to process a request or is unable to access the endpoint URI eu1, it tries to process the request with eu2 (retry 1). If the retry fails then the business service returns failure. The business service does not retry the third endpoint URI eu3.

When Retry Count = 2: If business service B fails to process a request or is unable to access the endpoint URI eu1, it tries to process the request with eu2 (retry 1). If the retry fails then the business service tries to process the request with eu3 (retry 2). If the retry fails then the business service returns failure.

When Retry Count = 4: If business service B fails to process a request or is unable to access the endpoint URI eu1, it tries to process the request with eu2 (retry 1). If the retry fails then the business service tries to process the request with eu3 (retry 2). Then the business service waits for a interval you have configured for retry iteration interval (in seconds) before trying eu1 (retry 3). If this fails the business service retries eu2 (retry 4). If the retry fails then the business service returns failure.

If the retry count is set to 0, then the business service does not retry after the failure.

Note:

The order in which a business service retries the endpoints is controlled by the load balancing algorithm.

9.1.4.3 Suppressing Retries in Case of Application Errors

A business service might fail to process a request due to communication or application errors. Communication errors occur due to random network problems. Retrying such requests with another endpoint URI can be successful. Application errors occur when a request is malformed or other errors, and cannot be processed by any of the endpoints. You can turn off retry behavior for the application errors by clearing the Retry Application Errors option in the Transport Configuration page for a business service, depending on the transport used.

9.1.5 Message Handling for Business Services

Business services include properties that define how the service processes message contents, including MTOM/XOP support, MIME attachments, checking for WS-I compliance, and the XQuery version to use.

9.1.5.1 XOP/MTOM Support

A business services enabled for XOP/MTOM support can encode outbound messages in MTOM/XOP format. SOAP Message Transmission Optimization Mechanism (MTOM) is a method of sending binary data to and from web services. MTOM uses XML-binary Optimized Packaging (XOP) to transfer the binary data.

Service Bus supports XOP/MTOM using the following transports:

  • HTTP/S

  • Local

  • SB

Binary data in the $header and $body message context variables can be handled in either of two ways:

  • Include Binary Data by Reference: (Default) In an outbound response message, replace xop:Include elements with ctx:binary-content elements when setting up the $body message context variable.

  • Include Binary Data by Value: In an outbound response message, replace xop:Include elements with Base64-encoded text versions of corresponding binary data when setting up the $body message context variable.

Note that if XOP/MTOM support is enabled for a business service, it is not required that every outbound message be in the MTOM format. Instead, this setting specifies that the business service is capable of handling an MTOM payload. Since Service Bus does not support a combination of MTOM and SwA, the system issues a runtime error when Service Bus attempts to dispatch an outbound request to a business service and the business service is both enabled for MTOM/XOP and the $attachments message context variable is not null.

9.1.5.2 Attachments

Service Bus supports streaming MIME attachments using the HTTP/S transport. This feature lets you store attachments in outbound response messages to a disk file and then process the data in a streaming fashion without buffering the attachment contents in memory. This enables the business service to process large attachments robustly and efficiently.

Note that if you enable XOP/MTOM support and choose the Include Binary Data by Value option, a warning appears if you try to select Page Attachments to Disk. These two options are not compatible. Note also that payloads that contain attachments must conform to RFC 822. Specifically, lines containing internet headers need to be terminated with CRLF (carriage return line feed).

9.1.5.3 Web Services Interoperability Compliance

In a business service's message handling properties, you can specify whether the service must conform to the Basic Profile defined by the Web Services Interoperability Organization (WS-I). This option is available for or SOAP 1.1 services only. When a service is marked WS-I compliant, checks are performed against the messages sent to and from that service.

9.2 Using Proxy Servers

You can configure business services to route messages through a proxy server by creating a proxy server resource.

This resource specifies one or more proxy servers together with the necessary credentials. You can then associate the proxy server resource with a business service. This association instructs Service Bus to connect to the business service through the configured proxy server.

Adding multiple proxy servers to a resource enables Service Bus to perform load balancing and offer fault tolerance among the configured proxy servers. The credentials are used when opening a connection to the proxy server. If a particular proxy server is not reachable, Service Bus attempts to use the next proxy server in the configuration. If all proxy servers are unreachable, Service Bus tries to connect to the back end service directly. If that too fails, a fault is raised and sent back to the caller.

For information about proxy server resources, see Working with Proxy Server Resources.

9.3 Service Level Agreement Alert Rules

Service Level Agreement (SLA) alert rules define conditions under which an alert is generated.

These conditions are typically indicators of the overall health of the Service Bus application or of a specific service component. For information about defining SLA alert rules for a business service, see "Creating Service Level Agreement Alert Rules" in Administering Oracle Service Bus.

9.4 Security and Security Policies for Business Services

You can secure business services through multiple methods, including Oracle Web Services Manager (OWSM) policies and access control at the transport level.

Outbound transport-level security applies to the connections between proxy services and business services. OWSM policies are bound by reference, not inlined in the effective WSDL file. When you secure business services with OWSM, you can also specify policy overrides.

For more information about transport-level security, see Configuring Transport-Level Security. For more information about securing business services, see Securing Business and Proxy Services.

9.5 Creating Business Services

You can create business services using Oracle JDeveloper or the Oracle Service Bus Console.

You can use various methods to create a business service, including generating it from an existing service, a JCA resource, or WSDL document. When you create a business service, the Create Business Service wizard provides a series of pages where you can configure certain business service properties.

If you are using any system resources, such as SMTP servers, MQ connections, or UDDI servers, make sure to create those resources before creating a business service. Configuring the business service includes specifying or selecting those resources, and you cannot complete the business service configuration until the required resources exist in Service Bus.

If you are working in JDeveloper, create or open the application and project to which you want to add the business service. If you are working in the Oracle Service Bus Console, make sure that you are in an active session and the project to which you want to add the business service exists.

The following topics provide additional information about creating business services:

9.5.1 How to Create a SOAP Business Service Using the Service Bus Console

You can create a SOAP business service in the Service Bus Console using the Create Business Service wizard, which is accessed from the Resource Gallery.

To create a SOAP business service:
  1. In the Project Navigator, right-click the project or folder in which you want to create the service, point to Create, and then select Resource.
    The Resource Gallery is displayed.
  2. In the Resource Gallery, click Business Service, then Web Service, then SOAP. Click OK.
  3. Enter a name for the service and, optionally, a description.

    Note:

    For naming requirements, see Naming Guidelines for Service Bus Components.

  4. To generate a SOAP business service configuration from an existing WSDL file, select the WSDL Based Service option, then click the Search icon in the Name field to display the Search and Select: WSDL Resource dialog. Use this dialog to search for and select a WSDL resource from which to generate this service. Once you specify the WSDL file, select the port or binding to use from the Port/Binding field.
  5. Click Next.
  6. If the protocol you want to use is not already selected, select a new protocol from the list.
  7. Specify the endpoint URI. For required URI formats, see the online help.

    Note:

    In the console, you can add multiple URIs to the list. Click Add and then modify the new URI that appears. Use the up and down arrows to reorder the URIs.

  8. Click Create.

The Business Service Definition Editor displays the general configuration of the new business service.

After you create the business service, configure it as described in Configuring Business Services.

9.5.2 How to Create a Typed or Untyped REST Business Service Using the Service Bus Console

You can create a typed or untyped REST business service in the Service Bus Console using the Create Business Service wizard, which is accessed from the Resource Gallery.

To create a typed or untyped REST business service:
  1. In the Project Navigator, right-click the project or folder in which you want to create the service, point to Create, and then select Resource.
    The Resource Gallery is displayed.
  2. In the Resource Gallery, click Business Service, then Web Service, then Typed/Untyped REST. Click OK.
  3. Enter a name for the service and, optionally, a description.

    Note:

    For naming requirements, see Naming Guidelines for Service Bus Components.

  4. Configure the following options:
    • To generate a WADL-based REST business service, select WADL Based REST Service, then click the Search icon in the Name field to display the Search and Select: WADL Resource dialog. Use this dialog to search for and select a WADL resource from which to generate this service. This creates a native typed REST service. Leave the WADL Name field empty to create a native untyped REST service.

    • To generate a Swagger-based untyped REST business service, select Swagger Based REST Service, then enter the URL to the Swagger document in the Swagger Link field.
  5. Click Next.
  6. If the protocol you want to use is not already selected, select a new protocol from the list.
  7. Specify the endpoint URI. For required URI formats, see the online help provided with Service Bus.

    Note:

    In the console, you can add multiple URIs to the list. Click Add and then modify the new URI that appears. Use the up and down arrows to re-order the URIs.

  8. Click Create.

The Business Service Definition Editor displays the general configuration of the new business service.

After you create the business service, configure it as described in Configuring Business Services.

9.5.3 How to Create a Typed REST Business Service Specifying WADL Details Using the Service Bus Console

You can create a native typed REST business service with the Create Native REST Business Service wizard. You specify the resources and methods of the service in the wizard; the wizard creates a WADL file describing the service and detailing the resources and methods available.

See REST Implementation in Service Bus for additional information about typed REST services.

To create a native typed REST business service in the console:

  1. In the Project Navigator, right-click the project or folder in which you want to create the service, point to Create, and then select Resource.
    The Resource Gallery is displayed.
  2. In the Resource Gallery, click Business Service, then Web Service, then Typed REST from wizard (with WADL). Click OK.
    The Create Native REST Business Service wizard is displayed.
  3. From the Basic Information page, provide basic details for the service:
    1. Enter a name for the service in the Name field.
    2. (Optional) Enter a description into the Description field.
    3. Enter a base URI for the service, such as http://example.com:7002/reservationservice, into the Base URI field.
    4. (Optional) If you want to create a proxy service targeting this business service, select the Virtualize option.
    5. Click Next.
  4. From the Resources page, specify the resources to be included with the service:

    Note:

    Each service must have at least one resource.

    1. Enter a unique resource path into the URI field, such as /makeReservation.
    2. (Optional) Enter a description of the resource path into the Description field.
    3. Click Add Resource.
    4. To add additional resources, repeat steps a through c.

      Tip:

      To add a resource as a child to a resource that you’ve already added, click the Add icon next to that resource instead of the Add Resource button, as shown in the following image.

      Description of add_child_resource.png follows
      Description of the illustration add_child_resource.png
    5. Click Next when you are finished adding resources.
  5. From the Methods page, specify the methods available for each resource:
    1. To add a method to a resource, click the arrow next to Methods, and then click an HTTP verb to add a method using that HTTP verb.

      Note:

      The available HTTP verbs are GET, PUT, POST, and DELETE. Each resource can have multiple GET methods, but only one method for each of the PUT, POST, and DELETE verbs.

    2. Enter a name for the method into the Name field.
    3. (Optional) Enter a description of the method into the Description field.
    4. On the Request tab, configure the request for this method.

      The options available on this tab differ depending on the HTTP Verb you chose for the method.

      • Configure the payload. Select None to send no payload. Select Media, and then select a media type to display the payload in that format: XML, JSON, URL-Encoded, Text, Opaque, or Other. If you choose Other, enter the name for the custom media type.

      • Click Add Parameter to add additional parameter to the request. Provide the parameter name, type, and default value by populating the fields that appear, repeating for each parameter that you want to add:

        • Enter a name for the parameter into the Parameter Name field.

        • Select a type for the parameter (like string or integer) from the Type list.

        • Enter a default value for a parameter in the Default Value field.

    5. On the Response tab, configure the response for this method:
      • For the success payload, select None to display no payload, or select Media, and then select media types in which the payload can be displayed: XML, JSON, URL-Encoded, Text, Opaque, or Other. If you choose Other, enter the name for the custom media type.

      • For the failure payload, select None to display no payload, or select Media, and then select media types in which the payload can be displayed: XML, JSON, URL-Encoded, Text, Opaque, or Other. If you choose Other, enter the name for the custom media type.

    6. Click Done when you are finished configuring a method.
    7. Repeat steps a through f to add additional methods to resources. Each resource must have at least one method.
  6. Click Create to create the service.
The Business Service Definition editor is displayed.

After you create the business service, configure it as described in Configuring Business Services.

9.5.4 How to Create a REST Business Service Based on a SOAP Service Using the SOAP to REST Wizard

You can expose operations from a SOAP XML schema to a REST service.

To create a typed REST business service based on a SOAP service in the console:
  1. In the Project Navigator, right-click the project or folder in which you want to create the service, point to Create, and select Resource.
    The Resource Gallery is displayed.
  2. In the Resource Gallery, click Business Service, then Web Service, then SOAP to REST. Click OK.
    The Create REST Business Service wizard is displayed.
  3. From the Basic Information page, provide basic details for the service:
    1. Enter a name for the service in the Name field.
    2. (Optional) Enter a description in the Description field.
    3. Enter a base URI for the service, such as http://example.com:7002/reservationservice, in the Base URI field.
    4. (Optional) If you want to create a proxy service targeting this business service, select the Virtualize option.
    5. Click Next.
  4. From the Resources page, specify the resources to be included with the service:

    Note:

    Each service must have at least one resource.

    1. Enter a unique resource path into the URI field, such as /makeReservation.
    2. (Optional) Enter a description of the resource path into the Description field.
    3. Click Add Resource.
    4. To add additional resources, repeat steps a through c.

      Tip:

      To add a resource as a child to a resource that you’ve already added, click the Add icon next to that resource instead of the Add Resource button, as shown in the following image.

      Description of add_child_resource.png follows
      Description of the illustration add_child_resource.png
    5. Click Next when you are finished adding resources.
  5. From the Methods page, specify the methods available for each resource:
    1. To add a method to a resource, click the arrow next to Methods, and then click an HTTP verb to add a method using that HTTP verb.

      Note:

      The available HTTP verbs are GET, PUT, POST, and DELETE. Each resource can have multiple GET methods, but only one method for each of the PUT, POST, and DELETE verbs.

    2. Enter a name for the method into the Name field.
    3. (Optional) Enter a description of the method into the Description field.
    4. On the Request tab, configure the request for this method:

      Note:

      The options available on this tab differ depending on the HTTP Verb you chose for the method.

      • From the Schema field, click the Choose an XML Schema icon to search for and select the XML schema containing the operation you want to map to the request.

      • From the Element list, select the element corresponding with the request operation. Service Bus automatically populates parameters, and a parameter name, type, expression, and default value for each parameter, if applicable, based on the element you select.

      • Configure the payload. Select None to send no payload. Select Media, and then select a media type to display the payload in that format: XML, JSON, URL-Encoded or Other. If you choose Other, enter the name for the custom media type.

      • Click Add Parameter to add additional parameter to the request. Provide the parameter name, type, XPath expression, and default value by populating the fields that appear, repeating for each parameter that you want to add:

        Note:

        You can also edit values for parameters populated from schema elements.

        • Enter a name for the parameter into the Parameter Name field.

        • Select a type for the parameter (like string or integer) from the Type list.

        • Enter an XPath expression function for the parameter into the Expression field. An expression editor window will not display, so you must know the XPath expression for a given parameter.

        • Enter a default value for a parameter in the Default Value field.

    5. On the Response tab, configure the response for this method:
      • Enter HTTP Statuses to be sent with the response (separated by spaces) into the HTTP Statuses field.

      • For the payload, select None to display no payload, or select Media, and then select media types in which the payload can be displayed: XML, JSON, URL-Encoded or Other. If you choose Other, enter the name for the custom media type.

      • From the Schema field, click the Choose an XML Schema icon to search for and select the XML schema containing the operation you want to map to the response.

      • From the Element list, select the element to map to the response.

    6. (Optional) On the Fault tab, configure faults for this method:
      • Click Add Fault to add a fault for this method.

      • Enter a name for the fault into the Fault Name field.

      • Enter HTTP Statuses to be sent with the fault (separated by spaces) into the HTTP Statuses field.

      • For the fault payload, select None to display no payload, or select Media, and then select media types in which the payload can be displayed: XML, JSON, URL-Encoded or Other. If you choose Other, enter the name for the custom media type.

      • Repeat these steps to add additional faults, if necessary.

    7. Click Done when you are finished configuring a method.
    8. Repeat steps a through g to add additional methods to resources. Each resource must have at least one method.
  6. Click Create to create the service.
The Business Service Definition editor is displayed.

After you create the service, configure it as described in Configuring Business Services.

9.5.5 How to Create a Business Service That Connects to Oracle Integration Using the Service Bus Console

The REST Adapter can connect to REST-based integrations created in Oracle Integration from either the Service Bus Console or JDeveloper, which allows you to browse integrations created in Oracle Integration (in Oracle Cloud) and select them for use in on-premises Service Bus applications.

This type of integration is called a hybrid integration—an integration developed in the cloud that can be used in on-premises applications. A hybrid integration must meet the following criteria to be used in Service Bus applications:

  • Have a REST endpoint

  • Be deployed and activated

  • Have a Swagger document for the integration

To consume integrations created in Oracle Integration using the Service Bus console, perform one of the following tasks:

To consume integrations created in Oracle Integration using JDeveloper, refer to:

9.5.5.1 Consuming an Integration in the Service Bus Console By Browsing
Before you perform this procedure, you must have a service account that contains credentials to access the Oracle Integration server. If you create a new service account with these credentials, the session must be activated, or the service account will not be available in the Integrations screen.

To consume an Oracle Integration REST-based integration by browsing:

  1. In the Service Bus Console, right-click the project or folder to contain the integration, point to Create, and click Resource.
  2. In the Resource Gallery, click Business Service then Web Service, then Oracle Integration Connect. Click OK.
  3. Enter a name for the resource and, optionally, a description.

    Note:

    For naming requirements, see Naming Guidelines for Service Bus Components.

  4. Click Next.
  5. On the Integrations page, enter the URL of the Oracle Integration server.
  6. Select the Service Account containing credentials to access the Oracle Integration server.
  7. Click Get Integrations.
  8. Click the desired integration.
    You can click Swagger Doc Contents to view the Swagger document.
  9. Click Next.
  10. On the Transport page, the endpoint URI for the Oracle Integration server should already be filled in. Click Create.
    The business service and a WADL resource are created. You can click the WADL definition resource and click View/Edit to see the WADL file.
  11. Open the Business Service definition and click Transport Details.
  12. In the Authentication section, click Basic.
  13. Select a service account with credentials for runtime access to the Oracle Integration server, and click OK.
9.5.5.2 Consuming an Integration in the Service Bus Console Using a Direct Link

If you know the Swagger URL of the integration, you can consume it using a direct Swagger link.

To consume an Oracle Integration REST-based integration using a direct Swagger link:
  1. In the Service Bus Console, right-click the project or folder to contain the integration, point to Create, and click Resource.
  2. In the Resource Gallery, click Business Service then Web Service, then Typed/Untyped REST. Click OK.
  3. Enter a name for the resource and, optionally, a description.

    Note:

    For naming requirements, see Naming Guidelines for Service Bus Components.

  4. Select Swagger Based REST Service and enter the URL of the Swagger document in the Swagger Link field.
    You can 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.
  5. Click Next.
  6. Click Create.
    The business service and a WADL resource are created. You can click the WADL definition resource and click View/Edit to see the WADL file.
  7. Open the Business Service definition and click Transport Details.
  8. In the Authentication section, click Basic.
  9. Select a service account with credentials for runtime access to the Oracle Integration server, and click OK.

9.5.6 How to Create a Business Service Using JDeveloper

You create business services based on WSDL files, based on transports, and native untyped REST services using the Create Business Service wizard in JDeveloper.

To create native typed REST business services and REST business services based on WSDL files, see How to Create Typed REST Services for Service Bus Using JDeveloper and How to Create WSDL-Based REST Services for Service Bus Using JDeveloper.

To create a business service:
  1. In the Application Navigator, right-click the project, point to New, and then select Business Service.

    The Create Business Service wizard appears.

  2. Enter a name for the service and, optionally, a description.

    Note:

    • JDeveloper lets you modify the location where the business service file is stored on the server. The file should be stored under the application and project folders, which is the default location.

    • For naming requirements, see Naming Guidelines for Service Bus Components.

  3. Do one of the following:
    • To generate a native untyped REST service, select REST.

    • To generate the business service by configuring its transport, select Transport, and then select the type of transport from the list.

    • To generate the business service configuration from an existing WSDL file, select WSDL and then enter the name of the WSDL file or click the Search icon to search for a WSDL resource. Once you specify the WSDL file, select the port or binding to use from the Port/Binding field.

  4. Click Next.

    The fields on the remaining pages in the wizard depend on your selections from the first page. The options described in the following steps might not be available for all configurations.

  5. If you chose WSDL or REST definition on the first page, skip to step 8.
  6. If you chose a Transport definition on the first page, select one of the following service types:
    • REST: This option requires no additional configuration.

    • WSDL: If you select this option, enter the WSDL file name or click Choose a WSDL to browse to and select a WSDL file to use. Select the port or binding type from the list of options.

    • Any SOAP: If you select this option, select the SOAP version to use.

    • Any XML: This option requires no additional configuration.

    • Messaging: If you select this option, select the data type for the request message and the response message. If you select MFL, you must also select the schema file. If you select XML, you can optionally select the schema file.

  7. Click Next.

    The Transport page appears.

  8. If the protocol you want to use is not already selected, select a new protocol from the list.
  9. Specify the endpoint URI. For required URI formats, see the online help provided with Service Bus.

    Note:

    In JDeveloper, you can add multiple URIs when you configure the business service.

  10. Click Finish.

    The Business Service Definition Editor displays the general configuration of the new business service.

  11. Configure the business service, as described in Configuring Business Services.

9.5.7 How to Create a Business Service That Connects to Oracle Integration Using JDeveloper

The REST Adapter can connect to REST-based integrations created in Oracle Integration from either JDeveloper or the Service Bus Console. This allows you to browse integrations created in Oracle Integration (in Oracle Cloud) and select them for use in on-premises Service Bus 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 Service Bus applications:

  • Have a REST endpoint

  • Be deployed and activated

  • Have a Swagger document for the integration

To consume an Oracle Integration REST-based integration using JDeveloper, perform the following tasks:

To consume integrations created in Oracle Integration using the Service Bus Console, see:

9.5.7.1 Create an Oracle Integration Connection

To create an Oracle Integration connection:

  1. In the Oracle JDeveloper Resources window, click the New New icon icon, select IDE Connections, then select Oracle Integration Connection.

  2. In the Create Oracle Integration Connection dialog, enter a name for the connection in the Connection Name field.

  3. In the URL field, enter the hostname and port number of the Oracle Integration instance.

  4. Enter the User Name and Password of the Oracle Integration instance.

  5. Click Test Connection and accept the security certificate.

  6. Click OK.

9.5.7.2 Create a REST Binding

To create a REST binding:

  1. In Oracle JDeveloper, right-click in the project design window (in the External References swimlane), select Insert, then REST.

  2. In Step 1 of the REST Binding Configuration Wizard, enter a name for the REST binding.

  3. Click Next.

  4. In Step 2 of the REST Binding Configuration Wizard, select the integration in one of two ways:

    Description of rest-binding-configuration-wizard-2.png follows
    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 rest-binding-configuration-select-flows.png follows
        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 Create new connection icon 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 Information icon 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.

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

  1. Right-click the created REST business object and select Configure Policy.

  2. In the Policy Configuration screen, select From OWSM Policy Store.

  3. Click the + icon for the policy type you wish to configure.

  4. Select the policy.

  5. Click Save.

9.5.7.4 Configure and Deploy the Application

To configure and deploy your application to use the integration:

  1. Complete your application by adding Inbound and BPEL Process to invoke the REST reference.

  2. Deploy your application to the SOA server.

  3. Test your application.

9.5.8 How to Generate a Business Service from a JCA Binding Resource

With Service Bus, you can generate a business service from an outbound JCA binding resource. JCA services, which use the Service Bus JCA transport, communicate with Enterprise Information Systems (EIS) through a JCA adapter framework and JCA-compliant adapters. For more information on JCA binding resources, see Using the JCA Transport and JCA Adapters.

Before You Begin:

Create the JCA file, its associated abstract WSDL file, and any other required resources, such as a TopLink mapping file in JDeveloper. For more information, see Using the JCA Transport and JCA Adapters and Understanding Technology Adapters.

Note:

  • If you select an inbound JCA binding instead of an outbound one, the option to generate a business service is not available.

  • In JDeveloper, you can also generate a business service when you create the JCA adapter if you create it from the Service Bus Overview Editor. For more information, see How to Create a Business Service.

9.5.8.1 Generating a Business Service from a JCA Binding in JDeveloper

To generate a business service from a JCA binding in JDeveloper:

  1. In the Application Navigator, right-click the outbound JCA file, point to Service Bus, and then select Generate Business Service.

    The Create Business Service wizard appears, configured for the selected JCA binding.

  2. On the wizard, keep the default service name and location, or specify new ones. The location must be in the current application's directory structure.
  3. Click Next.

    The Type page appears.

  4. Select a WSDL binding if necessary, and then click Next again.

    The Transport page appears.

  5. Update the endpoint URI if necessary, and then click Finish.

    Service Bus generates the business service and the concrete WSDL file that is used by the business service.

  6. Configure the business service, as described in Configuring Business Services.
9.5.8.2 Generating a Business Service from a JCA Binding in the Console

Before you begin, import the JCA resource files from JDeveloper to the console so all references to dependencies are maintained. For more information, see Working with JCA Binding Resources. and Importing and Exporting Resources and Configurations .

To generate a business service from a JCA binding in the console:

  1. In the Project Navigator, right-click the outbound JCA file, and select Generate WSDL and Service.

    The Generate WSDL and Service dialog appears.

  2. Optionally, modify the names of the WSDL file and the service you want to generate, and select a location for these new resources.
  3. Click Generate.

    Service Bus generates the service and its corresponding WSDL file.

  4. In the Project Navigator, navigate to the new resources, and open the business service in the Business Service Definition Editor.
  5. Configure the business service, as described in Configuring Business Services.

9.5.9 How to Generate a Business Service from a Proxy Service in JDeveloper

In JDeveloper, you can generate business services from the proxy services you create. The configuration of the business service is based on that of the proxy service.

To generate a business service from a proxy service in JDeveloper:

  1. In the Application Navigator, right-click the existing proxy service, point to Service Bus, and then select Generate Business Service.

    The Create Business Service wizard appears.

  2. Configure the name, description, and file location for the service, and then click Next.

    The Type page appears.

  3. If the service is a WSDL service, select the binding to use and then click Next.
  4. On the Transport page, select the transport protocol and update the endpoint URI. For required URI formats, see the online help provided with Service Bus.
  5. Click Finish.
  6. Configure the business service, as described in Configuring Business Services.

9.5.10 How to Generate a Business Service from a WSDL Document in JDeveloper

You can use an existing WSDL document to generate a proxy service, business service, pipeline, or split-join.

To generate a business service from a WSDL document in JDeveloper:

  1. In the Application Navigator, right-click the existing WSDL document, point to Service Bus, and then select Generate Business Service.

    The Create Business Service wizard appears.

  2. Configure the name, description, file location, and WSDL binding for the service, and then click Next.
  3. On the Transport page, select the transport protocol and update the endpoint URI. For required URI formats, see the online help provided with Service Bus.
  4. Click Finish.
  5. Configure the business service, as described in Configuring Business Services.

9.6 Configuring Business Services

Once you create a business service, you can edit the configuration, add security policies, modify security settings, and set up SLA alert rules.

The information you can modify depends on how the service was originally configured. For a list of all the configurable properties for business services, see the online help available for each Business Service Definition Editor page.

If you are working in the Oracle Service Bus Console, make sure that you are in an active session before performing any of the tasks in this section.

9.6.1 How to Configure General Information for a Business Service

The General tab of the Business Service Definition Editor displays information about the service such as a description of the service, the transport used by the service, the service type, and any WSDL ports or bindings. You can only modify the description on this page. The following figure shows the General tab in the Oracle Service Bus Console.

Figure 9-1 Business Service General Configuration Page in the Console

Description of Figure 9-1 follows
Description of "Figure 9-1 Business Service General Configuration Page in the Console"

To configure general information for a business service:

  1. In the Project or Application Navigator, right-click the business service to edit, and click Open.
  2. Click the General tab if it is not already the visible page.
  3. Enter or update the description for the service.
  4. If the service references any resources, such as a WSDL or MFL document, click the name of the resource to view the document in its own editor.
  5. When you are done making changes, click Save All.
  6. If you are working in the Oracle Service Bus Console, click Activate to end the session and deploy the configuration to the runtime.

9.6.2 How to Configure a Business Service Transport

Use the Transport and Transport detail page to configure the transport for the business service. The available properties vary for each transport. The following figure shows the Transport tab in the Oracle Service Bus Console.

Figure 9-2 Business Service Transport Configuration Page in the Console

Description of Figure 9-2 follows
Description of "Figure 9-2 Business Service Transport Configuration Page in the Console"

To configure a business service transport:

  1. In the Project or Application Navigator, right-click the business service to edit, and click Open.
  2. Click the Transport tab, and do any of the following:
    • To change the load-balancing algorithm, select a new algorithm from the list of available options.

      For more information, see About the Load Balancing Algorithm .

    • Update or add endpoint URIs. For more information, see the online help provided for this page.

    • In the Retry Count field, specify the number of times to retry URI endpoints.

    • In the Retry Iteration Interval field, specify the amount of time in seconds to wait after trying all URIs before trying again.

    • Select or clear Retry Application Errors to specify whether to retry application errors.

  3. Click the Transport Detail tab.

    The properties you can configure here are based on the transport for the business service. For information about specific transports, see Working with JCA Adapters, Transports, and Bindings or the online help for the Transport Detail tab.

  4. When you are done making changes, click Save All.
  5. If you are working in the Oracle Service Bus Console, click Activate to end the session and deploy the configuration to the runtime.

9.6.3 How to Configure Business Service Message Handling

On the Message Handling page, you can configure how the business service processes message contents, including MTOM/XOP support, attachments, checking for WS-I compliance, and the XQuery version to use. The following figure shows the Message Handling tab in the Oracle Service Bus Console.

Figure 9-3 Business Service Message Handling Page in the Console

Description of Figure 9-3 follows
Description of "Figure 9-3 Business Service Message Handling Page in the Console"

To configure message handling for a business service:

For information about message handling properties, see Message Handling for Business Services.

  1. In the Project or Application Navigator, right-click the business service to edit, and click Open.
  2. Click the Message Handling tab.
  3. To enable XOP/MTOM support, select XOP/MTOM Enabled, and select whether to include binary data by reference or value.
  4. To specify how MIME attachments are handled, select or clear Page Attachments to Disk.
  5. To check messages for WS-I compliance, select the check box for Enforce WS-I Compliance.
  6. Select the version of XQuery to use for processing, either 2004 or 1.0.

    Note:

    XQuery 1.0 is the recommended version. Support for XQuery 2004 will be deprecated in future releases.

  7. (Optional) If you are configuring a WSDL-based REST service, select the Enforce XML Schema Ordering option to reorder JSON payloads to match the order of the elements in the XML schema. This includes inbound request payloads and responses from outbound requests.
  8. When you are done making changes, click Save All.
  9. If you are working in the Oracle Service Bus Console, click Activate to end the session and deploy the configuration to the runtime.

9.6.4 How to Configure Performance for a Business Service

On the Performance tab, you can configure result caching to improve the performance of the business service. For more information, see Improving Performance by Caching Business Service Results. For instructions, see How to Configure a Business Service for Result Caching.

9.6.5 How to Configure Security for a Business Service

You can secure business services through multiple methods, including Oracle Web Services Manager (WSM) policies and access control at the transport level. For more information about securing business services, see Security and Security Policies for Business Services and Securing Business and Proxy Services.

9.6.6 How to Configure Service Level Agreement Alerts for a Business Service

SLA alerts let system administrators know when certain conditions are met that indicate the health of a business service. For information about defining SLA alerts, see "Creating Service Level Agreement Alert Rules" in Administering Oracle Service Bus.

9.7 Deleting a Business Service

If resources reference a business service, you can still delete it. The deletion could result in conflicts due to unresolved references to the deleted resource.

Check for dependencies before removing a business service. In the Oracle Service Bus Console, open the business service in the Business Service Definition Editor. Click the Tools icon in the upper right, and then select References to find out whether any services are using it. In JDeveloper, right-click the business service and select Explore Dependencies.

To delete a business service:
  1. In the Project or Application Navigator, right-click the business service to delete, and select Delete.

    A confirmation dialog appears.

  2. In JDeveloper, if other resources reference this business service the confirmation dialog displays the number of references. To view information about the reference, click Show Usages
  3. To confirm that you want to delete the service, click Yes on the confirmation message.

    The business service is deleted.

  4. If you are working in the Oracle Service Bus Console, click Activate to end the session and deploy the configuration to the runtime.

9.8 Improving Performance by Caching Business Service Results

If you use business services that return results that do not change often, you can configure those business services to cache results. When you enable result caching, the service returns results from the cache rather than invoking the external service. This configuration improves performance by reducing network overhead to access the external service. Result caching also helps improve scalability by reducing the load on the back-end servers that host the external service.

In this section, the term result cache refers to the cache itself, which all business services share to store their respective results. The term cached result refers to a single result in the result cache. For business services that use result caching, you can control the time to live for the cached result. After the cached result expires, the next business service call results in invoking the back-end service to get the result. This result is then stored in the cache for future requests to access.

Service Bus uses the result caching mechanism of Oracle Coherence, which is included with WebLogic Server. The Service Bus implementation of result caching includes global enable/disable, cache message variables, configuration fields on each business service, and cache options for service statistics, debugging, and alert rules.

9.8.1 How Result Caching Works

Figure 9-4 illustrates a client invoking a business service and receiving a response that contains cached results.

Note:

Result caching works only with request/response operations.

Figure 9-4 Business Service Result Caching

Description of Figure 9-4 follows
Description of "Figure 9-4 Business Service Result Caching"

Each cached result is uniquely identified by a cache key that is made up of the ServiceRef (the unique identifier for the service which is the fully qualified path name of the service), the operation being invoked, and a cache token string. The cache token helps to uniquely identify a single cache result among other cache results for one business service. You control the value of the cache token. You can set the cache token either by configuring the cache token expression in the result caching configuration for the business service or by using the cache-token metadata element in $transportMetaData using the pipeline.

If the business service locates cached results through a cache key, it returns those cached results to the client instead of invoking the external service directly.

In Figure 9-4, the solid arrows represent the message path between the client and a cached result. The dotted arrows show the message path if no cached result exists. If no cached result exists, the business service invokes the external service directly, returns the result to the client, and stores the result in cache. A result cache could be empty for a number of reasons, such as for a first-time invocation where no cache exists yet, a caching error, or the cache was flushed.

For cache expiration, cached results have a time-to-live (TTL) attribute. You can configure cache expiration either with the Expiration Time property in the result caching configuration on the business service or the cache-ttl element in $transportMetaData using the pipeline. If Coherence finds that the TTL has expired, it flushes the cache, and the business service invokes the external service for a result. That result is then stored in the cache (if there is no error in the result), and the result is available in the cache so that it can be returned to the next request.

9.8.1.1 Flushing Cached Results

Service Bus with Coherence can flush an individual cached result or all cached results for a business service. The following events illustrate how the cache is flushed:

  • Cache TTL has expired. Each cached result has its own TTL. When a TTL is reached, Coherence flushes that individual cached result.

  • Disable result caching on a single business service. When you disable result caching on a business service, Service Bus triggers flushing of all cached results for that business service in Coherence.

  • Update, rename, or delete a business service. These actions trigger the flushing of all cached results for that business service from Coherence.

  • Update a dependent resource. Updating a dependent resource, such as a WSDL document, triggers the flushing of all cached results for that business service from Coherence. However, changes to the following dependent resources do not cause cache flushing: service provider, UDDI registry, and alert destination.

  • Globally disable result caching. Globally disabling result caching, triggers the flushing of the entire result cache (all cached results for all business services) from Coherence.

9.8.2 Result Caching Best Practices

Because cached results bypass the security of invoking an external service directly, do not use result caching with business services that provide security with a non-static service account or a WS-Security policy. Before deploying a Service Bus environment that will use result caching in production, you should plan and implement Coherence setup and configuration to allow for best performance, as described in Understanding Configuration in Developing Applications with Oracle Coherence.

9.8.3 How to Delete Entries in the Result Cache

Oracle Service Bus provides APIs for deleting entries from the OSB result cache. The APIs can be use to delete a single entry or delete all entries for a specific business service. The APIs will be exposed through JMX interfaces (MBean).

The ResultCacheRuntimeMBean provides the APIs to delete cached entries from the result cache. There is one instance of this MBean per domain. You can invoke the ResultCacheRuntimeMBean from a Java callout. The interface contains the following methods:

/**
 * MBean for deleting result cache entry
 */
public interface ResultCacheRuntimeMBean {
   /**
     * Method to remove an entry from the resultcache
     *
     * @param ref
     *            the reference for the resource
     * @param operation
     *            Applicable for WSDL based services
                  NULL for any Xml type.
     * @param token
     *            the token
     * @throws Exception
     *             thrown if there are semantic validation errors
     */
    public void deleteCacheEntry (Ref ref,String operation, String token) throws Exception;
     /**
     * Method to delete all cached service data for a specific business service.
     *
     * @param ref
     *            the reference for the resource to remove cache entries from
     *
     * @throws Exception
     *             thrown if there are semantic validation errors
     */
    public void deleteAllCacheEntriesFromServiceRef (Ref ref) throws Exception;

The API takes the service reference (the business service Ref object on which the result caching is configured), the operation name (the service method invoked in case of WSDL based services, NULL for XML type messages), and the cache token to delete a single entry from the result cache.

Result Cache Configuration shows a sample of the result cache configuration for a WSDL based business service. The customer id is used as the cache token to cache the results returned from the FindCustomer webservice call. This configuration caches the webservice response returned against the xquery expression evaluated.

Figure 9-5 Result Cache Configuration

Description of Figure 9-5 follows
Description of "Figure 9-5 Result Cache Configuration"

The code snippet below shows how to invoke the MBean API to delete the cached result corresponding to customer id = 10, for example. You can use a java callout and invoke it from a pipeline to pass the business service name, webservice operation name, and the cache token to delete the cached entry.

//Initialize the JMXConnector
JMXConnector conn =  initConnection(machine,Integer.parseInt(adminPort),username,password);
MBeanServerConnection mbconn = conn.getMBeanServerConnection();
ObjectName resultCacheObj = new ObjectName(ResultCacheRuntimeMBean.OBJECT_NAME);
ResultCacheRuntimeMBean resultCacheRuntimeMBean
            = (ResultCacheRuntimeMBean) MBeanServerInvocationHandler.newProxyInstance(mbconn,
                             mbconn.queryNames(resultCacheObj, null).iterator().next(),
                             ResultCacheRuntimeMBean.class, false);
String cacheBizRefPath =  "resultcache/CacheBiz";
String[] arrayOfRef =  cacheBizRefPath.split("/");
Ref cacheBizRef = new Ref("BusinessService", arrayOfRef);
// Removes the result cached entry corresponding to the customer id 10
resultCacheRuntimeMBean. deleteCacheEntry(cacheBizRef, “FindCustomer”, “10”); 

9.8.4 Result Cache Metadata

The result cache uses a cache key to identify cached results, and an expiration time to determine when to flush cached results.

9.8.4.1 Cache Token

Service Bus uses cache keys to identify cached results for retrieval or population, and the cache token portion of the cache key provides the unique identifier. You can use an expression, the cache token expression, to generate the cache token part of the cache key to uniquely identify a cached result for the business service. To generate the cache token from a value in the request (in the pipeline or split-join that invokes the business service), use an expression that gets the value from the pipeline $body, $header, $operation, or $transportMetaData ($outbound/ctx:transport/ctx:request or $outbound/ctx:transport/ctx:response). For example, you can populate the cache-token from a customer ID in the message $body.

The cache token expression must resolve to a String or the value of simple content, such as an attribute or an element with no child elements. If the expression evaluates to null or causes an error, results are not cached. You can also generate the cache token from the request, without setting a cache token expression in the business service configuration. To do this, include a value in $outbound/ctx:transport/ctx:request/ctx:cache-token in the pipeline. Any value in that cache-token overrides the cache token expression in the business service configuration.

9.8.4.2 Expiration Time

The expiration time, or time to live (TTL), determines when an entry in the business service's result cache is flushed. You can use the default expiration time, define a duration of time before the result cache is flushed, or define an expression that generates the expiration time from a value in the request or response. The default expiration time is defined in the expiry-delay value in the osb-coherence-cache-config.xml file in resultcache.gar. You can define the duration directly in the business service configuration.

To generate the expiration time from a value in the request or response, use an expression that gets the value from the pipeline or split-join $body, $header, $operation, or $transportMetaData ($outbound/ctx:transport/ctx:request or $outbound/ctx:transport/ctx:response). For example, use a value you have set in the Cache-Control HTTP header.

The expiration time must resolve to an integer (representing seconds), an XQuery dayTimeDuration (XSD type), or the integer value of simple content representing seconds, such as an attribute or an element with no child elements. If the expression evaluates to null or causes an error, results are not cached.

You can also generate the expiration from the request, without setting an expiration time in the business service configuration. To do this, include a value in $outbound/ctx:transport/ctx:request/ctx:cache-ttl in the pipeline or split-join. Any value in the cache-ttl element overrides the expiration time in the business service configuration.

9.8.4.3 Request Metadata

The request metadata used with result caching include cache-token and cache-ttl, both String values. You can configure both in the business service configuration. You can also leave the cache token or TTL undefined in the business service and provide the cache token or TTL in the request with these metadata. When you set the cache token or TTL in the request, those values override any cache token or TTL you have defined in the business service configuration.

When using expressions to configure result caching, whether with the cache token expression, the TTL, or both, you can enter the namespaces and corresponding prefixes to use in the expressions. This field also lets you view a list of existing namespaces.

9.8.4.4 Response Metadata

The response metadata used with result caching include the following:

  • cache-token: Contains the cache token that was used to retrieve content from the result cache or add content to the result cache after invoking the external service.

  • cache-originated: Contains a boolean value, true or false. A value of true means the returned content came from the result cache. A value of false means the returned value came from invoking the external service.

9.8.5 Testing Result Caching

Result caching takes effect only when the business service configured with result caching is invoked (for example, with a route or service callout activity) from a pipeline or split-join. Therefore, in order to test result caching, do not invoke the business service directly from the Test Console. Instead, use the Test Console to test the pipeline or the split-join that invokes the business service.

9.8.6 How to Configure a Business Service for Result Caching

If you invoke business services whose results seldom change, result caching improves business service performance by returning cached results to the client instead of invoking an external service directly. You can only configure result caching for a business service using the Oracle Service Bus Console.

For both cache token expressions and expiration time expressions, you use the Expression Editor to define the expression. For more information about working with the Expression Editor, see Transforming Data with XQuery. The following image shows the Performance tab in the Oracle Service Bus Console, where you configure result caching.

Figure 9-6 Business Service Performance Page in the Console

Description of Figure 9-6 follows
Description of "Figure 9-6 Business Service Performance Page in the Console"

To configure result caching:

  1. In the Oracle Service Bus Console Project Navigator, navigate to and open the business service you want to configure.
  2. On the Business Service Definition Editor, select the Performance subtab.
  3. Select Result Caching Support.

    Note:

    Even though result caching is enabled here, you must also enabled it in Fusion Middleware Control as described in "Configuring Operational Settings at the Global Level" in Administering Oracle Service Bus.

  4. To define an expression to generate the cache token part of the cache key, click the Expression Editor icon next to the Cache Token Expression field.

    For more information about the cache token expression, see Cache Token.

  5. To define an expiration time for the business service's result cache, select one of the following:
    • Default: This option uses the expiry-delay value in the osb-coherence-cache-config.xml file in resultcache.gar. The default is 5 minutes.

    • Duration: This option lets you specify a length of time to live. Use the Days and hr:min:sec fields to define the duration.

    • XQuery Expression: This option uses an XQuery expression that gets an expiration time from the request or response. To define the expression, click the Expression Editor icon next to the Expression field. After you define the expression, select whether to evaluate the expression against the request or response in the Evaluate Against field.

    Note:

    A duration of zero (0) means no expiration. A negative duration means do not cache.

    For more information about the expiration time, see Expiration Time.

9.8.7 Result Caching Advanced Configuration

In each Service Bus domain, you can modify how the domain uses Coherence for business service result caching. Service Bus provides its own default Coherence configuration for the servers in a domain by providing two files, resultcache.gar and resultcache.ear, both located in MW_HOME/osb/lib/apps. The GAR file defines the Coherence cache to use for result caching. In order to set up the results cache, you deploy resultcache.gar to WebLogic Server and specify the servers or clusters to which the cache is targeted. You can then configure the cache using the console (or WLST commands, if you prefer).

The default cache configuration is embedded in the GAR file. You can define your own configuration for the cache by extracting osb-coherence-cache-config.xml from the GAR file and modifying the properties as needed. By default, a distributed cache scheme is used for the result cache. For more information, see "Cache Configuration Elements" in Developing Applications with Oracle Coherence.

To use a different cache configuration, you need to create a new Cache Configuration for the Coherence cluster in the WebLogic Server Administration Console. The Cache Configuration must be named /osb/service/ResultCache, the JNDI name must be servicebus/result-cache, and it must be in the same Coherence Cluster used by Service Bus. You can use a different configuration on different servers in your domain.

9.8.7.1 Working with Unicast and Multicast

You can configure unicast settings to restrict Coherence cache access to only the local server. With this configuration, nodes started on different servers do not join the same Coherence cluster to share cached information. Alternatively, you can configure multicast values to create a Coherence cluster that is shared by any WebLogic Server node on the same subnet created from the same template. You configure these properties on the General Configuration tab of the Coherence cluster in the WebLogic Server Administration Console.

A best practice is to configure the Coherence cluster to use a unicast listener with an explicit list of nodes for the Coherence cluster. For information about multicast and unicast properties, see the online help provided with WebLogic Server. Also see "Using Well Known Addresses" in Developing Applications with Oracle Coherence.

You can specify overrides using system properties. Use the following guidelines when configuring the Coherence cluster to ensure the correct sharing of a Coherence cluster among multiple servers:

  • If you want to switch from a multicast listener to a unicast listener in a cluster, configure well-known addresses.

  • If you have multiple WebLogic Server clusters in the same subnet, modify the relevant Coherence address and port properties to ensure correct sharing of a Coherence cluster. Do not use the same address and port as those used for the WebLogic Server cluster.

  • If you have multiple Admin Servers with Managed Servers in the same subnet, modify the relevant Coherence address and port properties to ensure correct sharing of a Coherence cluster.

  • If you have any combination of WebLogic Server clusters and Admin Servers with Managed Servers in the same subnet, modify the relevant Coherence address and port properties to ensure correct sharing of a Coherence cluster.

  • If multiple Coherence clusters are running in the same subnet, modify the Multicast Address and Multicast Port to specify which Coherence cluster a node should connect to.

9.8.7.2 How to Disable Coherence for Service Bus

To prevent Service Bus from using Coherence completely, perform the following steps:

  1. Delete all Coherence cluster resources targeted to the servers that are running Service Bus.
  2. Undeploy the Service Bus result cache enterprise application (resultcache.ear).
  3. Disable global result caching.
9.8.7.3 About Out-of-Process Coherence Servers

The following figure illustrates an out-of-process Coherence server.

Figure 9-7 Out-of-Process Coherence Cluster

Description of Figure 9-7 follows
Description of "Figure 9-7 Out-of-Process Coherence Cluster"

In the above example, there are two WebLogic Server clusters. The first WebLogic Server cluster contains Managed Servers 1 and 2 and also has the following:

  • Service Bus running

  • Service Bus results cache enterprise application deployed (resultcache.ear)

  • Storage disabled

The second WebLogic Server cluster contains Managed Servers 3 and 4 and also has the following:

  • Service Bus result cache grid archive deployed (resultcache.gar)

  • Storage enabled

All the cached entries will be stored in Managed Servers 3 and 4.

9.8.7.4 How to Use an Out-of-Process Coherence Cache Server

If you plan to use result caching heavily with Service Bus and want to avoid using too much heap space for result caching, you can set up a Coherence cache server to run on its own JVM rather than sharing a Service Bus domain JVM. Running a Coherence cache server outside of a Service Bus JVM—out of process—lets the Coherence cache server use its own heap space without affecting the heap space Service Bus uses to process messages.

Note:

Any out-of-process Coherence cache server used with Service Bus must use the same version of Coherence as the version included with Service Bus.

9.8.7.4.1 Creating an Out-of-Process Coherence Cache Server

To create an out-of-process Coherence cache server:

  1. Create new WebLogic Server nodes and clusters that use the same Coherence cluster.
  2. Deploy the MW_HOME/osb/lib/apps/resultcache.gar file to the new clusters.
9.8.7.4.2 Configuring the Servers for an Out-of-Process Coherence Cache Server

In order to use an out-of-process Coherence cache server, you need to disable local caching on each Service Bus node.

To configure the servers for an out-of-process Coherence cache server:

  1. Disable local caching on each Service Bus node by adding the following argument to the Service Bus node startup:
    -Dtangosol.coherence.distributed.localstorage=false
    
  2. Set the Coherence cluster name with the following argument.
    -DOSB.coherence.cluster=cluster_name
    
9.8.7.5 More Information on Configuring and Using Oracle Coherence

You can perform many other types of cache configuration flexibly, without changing application code, using the Oracle Coherence configuration framework. For example, you can use attributes to modify the cache type and behavior, and you can query the cache. For more information, see Using Caches in Developing Applications with Oracle Coherence.