Fusion Middleware Documentation
Advanced Search


Developing Services with Oracle Service Bus
Close Window

Table of Contents

Show All | Collapse

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, so 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 Chapter 11, "Working with WSDL Documents.")

You can base business services on existing WSDL and WADL documents, including those 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 Chapter 26, "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 proxy 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 Section 1.3.3, "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 business service. This type of service can only be created in the Service Bus Overview Editor in JDeveloper, and is not an option on the Create Business Service wizard. For more information, see Chapter 26, "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 Chapter 8, "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 Part V, "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 Part V, "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 that specifies one or more proxy servers together with the necessary credentials. You can then associate the proxy server resource with a business service. This 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 Section 7.3, "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 Chapter 51, "Configuring Transport-Level Security." For more information about securing business services, see Chapter 49, "Securing Business and Proxy Services."

9.5 Creating Business Services

This section describes how to create business services using Oracle JDeveloper or the Oracle Service Bus Console. For information about creating Service Bus applications and projects, see Section 3.3, "Creating Service Bus Applications and Projects in JDeveloper" or Section 2.4.3, "How to Create New Projects and Folders". For information about working with projects, applications, and other components in JDeveloper, see Developing Applications with Oracle JDeveloper.

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. This section describes how to use the Create Business Service wizard to create business services. For information on using the Service Bus Overview Editor, see Chapter 5, "Developing Oracle Service Bus Applications in JDeveloper."

Before You Begin:

If you are using any system resources, such as SMTP servers, MQ connections, or UDDI servers, make sure to create those resources before beginning to create a business service. Configuring the business service includes specifying or selecting those resources, and you will not be able to 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 you are in an active session and the project to which you want to add the business service exists.

9.5.1 How to Create a Business Service

When you create a business service, you need to specify certain information, such as the service type and whether to use a WSDL file or Service Bus transport. The following topics provide additional information about creating business services:

To create a business service: 

  1. In the Project or Application Navigator, right-click the project, point to New or Create, and then select Business Service.

    The Create Business Service wizard appears.

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

    Notes:

  3. Do one of the following:

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

    • 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 optionally the response message. If you select MFL or XML, you must also 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. If you are working in the Oracle Service Bus Console, select a load balancing algorithm for the business service.

  10. Specify the endpoint URIs. 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. In JDeveloper, you can do this when you configure the business service.

  11. Click Finish or Create.

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

  12. Configure the business service, as described in Section 9.6, "Configuring Business Services."

9.5.2 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 Chapter 25, "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 Chapter 25, "Using the JCA Transport and JCA Adapters" and Understanding Technology Adapters.

Notes:

  • 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 Section 5.2.6, "How to Create a Business Service."

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.

    See Section 1.8, "Naming Guidelines for Service Bus Components" for naming guidance.

  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 Section 9.6, "Configuring Business Services."

To generate 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 Section 25.3, "Working with JCA Binding Resources." and Chapter 44, "Importing and Exporting Resources and Configurations."

  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.

    See Section 1.8, "Naming Guidelines for Service Bus Components" for naming guidance.

  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 Section 9.6, "Configuring Business Services."

9.5.3 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 Section 9.6, "Configuring Business Services."

9.5.4 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 Section 9.6, "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 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 Section 9.1.4.1, "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 Part V, "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 Section 9.1.5, "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. When you are done making changes, click Save All.

  8. 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 Section 9.8, "Improving Performance by Caching Business Service Results." For instructions, see Section 9.8.5, "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 Section 9.4, "Security and Security Policies for Business Services" and Chapter 49, "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 Business Services

You can delete a business service even if it is referenced by other resources, though this might result in conflicts due to unresolved references to the deleted resource.

9.7.1 How to Delete a Business Service

Check for dependencies before removing a business service. In the Oracle Service Bus Console, open the business service in the Business Service Definition Editor and click the References icon in the upper right 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. Click Show Usages to view information about the reference.

  3. On the confirmation dialog, click Yes to confirm you want to delete the service.

    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 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, and 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, all cached results for a business service, or the entire result cache (all cached results for all business services). 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 Developing Applications with Oracle Coherence.

9.8.3 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.3.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.3.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.3.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.3.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.4 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.5 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 Chapter 19, "Transforming Data with XQuery." The following image shows the Performance tab in the Oracle Service Bus Console, where you configure result caching.

Figure 9-5 Business Service Performance Page in the Console

Description of Figure 9-5 follows
Description of "Figure 9-5 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 Section 9.8.3.1, "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 Section 9.8.3.2, "Expiration Time."

9.8.6 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.6.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.6.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.6.3 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.

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.

To configure 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.

  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
    

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

Figure 9-6 Out-of-Process Coherence Cluster

Description of Figure 9-6 follows
Description of "Figure 9-6 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.6.4 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 Developing Applications with Oracle Coherence.