36 Configuring Proxy Services and Business Services

This chapter describes the high-level aspects of configuring Oracle Service Bus business and proxy services, including the structure and use of WSDLs, service types and transports, and business service result caching with Oracle Coherence.

Oracle Service Bus proxy services and business services provide the means for managing services, transforming messages, and routing messages through the enterprise.

You can create and configure proxy services and business services using either the run-time environment (Oracle Service Bus Administration Console) or the development environment (Eclipse with Oracle Service Bus plug-ins). You can base proxy services or business services on existing Web Services Description Language (WSDL) resources, including those imported from a UDDI registry such as the Oracle Service Registry, and then further configure them in the Oracle Service Bus Administration Console or the plug-in.

This chapter contains the following sections:

• Section 36.1, "Oracle Service Bus Proxy Services"

• Section 36.2, "Oracle Service Bus Business Services"

• Section 36.3, "How WSDL is Used in Oracle Service Bus"

• Section 36.4, "Using a WSDL to Define a Service"

• Section 36.5, "Basing Services on WSDL Ports and on WSDL Bindings"

• Section 36.6, "Configuring Proxy Services"

• Section 36.7, "Configuring Business Services"

• Section 36.8, "Viewing Resource Details"

36.1 Oracle Service Bus Proxy Services

Oracle Service Bus proxy services are definitions of intermediary Web services that Oracle Service Bus implements and hosts locally. Oracle Service Bus uses proxy services to route messages between business services (such as enterprise Web services and databases) and service clients (such as presentation applications or other business services).

A proxy service configuration includes its interface, transport settings, security settings, and a message flow definition. The message flow definition defines the logic that determines how messages are handled as they flow through the proxy service. If a proxy service is based on a WSDL document, the configuration also includes a WSDL port or a WSDL binding. (See Section 36.4, "Using a WSDL to Define a Service.")

36.2 Oracle Service Bus Business Services

Oracle Service Bus business services are definitions of enterprise Web services to which Oracle Service Bus is a client. Those external Web services are implemented in and hosted by external systems, so Oracle Service Bus must know what to invoke, how to invoke it, and what to expect as a result. Oracle Service Bus business services model those interfaces so that Oracle Service Bus can invoke the external services.

A business service configuration includes its interface, transport settings, and security settings. (It does not include a message flow definition.) If the business service is based on a WSDL, the configuration also includes a WSDL port or a WSDL binding. (See Section 36.4, "Using a WSDL to Define a Service.")

36.3 How WSDL is Used in Oracle Service Bus

Oracle Service Bus defines some types of business services and proxy services using a WSDL, an XML-based specification for describing Web services. A WSDL document describes service operations, input and output parameters, and how a client application connects to the service. For the WSDL 1.1 specification, see the W3C Note, "W3C Web Services Description Language (WSDL) 1.1," at http://www.w3.org/TR/wsdl.

36.3.1 About Effective WSDLs and Generated WSDLs

In Oracle Service Bus, you can base a new proxy service or a new business service on an existing WSDL (called a "WSDL resource") and then override or add configuration properties. You can also create and configure new services that are not based on existing WSDLs.

36.3.1.1 Effective WSDLs

For WSDL-based services, Oracle Service Bus uses effective WSDLs instead of actual .wsdl files. An effective WSDL represents a service's WSDL properties as configured in Oracle Service Bus.

A source WSDL serves as a template for an effective WSDL. When you create a service based on a WSDL, Oracle Service Bus generates an effective WSDL by combining settings from the original WSDL and any transport configurations you set, plus any other configuration settings you add or change from the original WSDL. Settings from the original WSDL that are not used in the new configuration are omitted from the effective WSDL.

Oracle Service Bus can generate effective WSDLs for these types of proxy services and business services:

• SOAP services created from a WSDL

• XML services created from a WSDL

Effective WSDLs can be generated for those types of services using any transport that supports WSDL-based services, including HTTP, JMS, SB, and so on.

Oracle Service Bus cannot generate effective WSDLs for these types of proxy services and business services:

• Any SOAP

• Any XML

• Messaging type services

Effective WSDLs have different characteristics for proxy services and business services and for services based on WSDL ports and services based on WSDL bindings. Those characteristics are discussed throughout this documentation. In particular, see Section 36.5, "Basing Services on WSDL Ports and on WSDL Bindings."

36.3.1.2 Generated WSDLs

A generated WSDL is an effective WSDL that Oracle Service Bus generates for transport-type services that were not created from a WSDL resource but which can be described using a WSDL. For example, a WSDL generated from an EJB-based service is a generated WSDL.

36.3.1.3 Accessing Effective WSDLs

There are three ways to access an effective WSDL:

• In a Web browser, enter the URL for an HTTP-based proxy service, appended with ?WSDL.

  This works only for HTTP-transport-based services for which Oracle Service Bus can generate effective WSDLs.)

• In a Web browser, enter the fixed HTTP URL, for example:

  http://host:port/sbresource?PROXY/project_path/proxy_service_name

  or

  http://host:port/sbresource?BIZ/project_path/business_service_name

  This works for all services for which Oracle Service Bus can generate effective WSDLs.

• Export the WSDL from the Administration Console or from the plug-in. See:

  • Section 4.28, "Exporting a WSDL"

  • "Generating an Effective WSDL" in the Oracle Fusion Middleware Developer's Guide for Oracle Service Bus

  Exporting the WSDL generates a .zip file that contains the effective WSDL along with associated dependencies, including schemas and WS-Policies. Oracle Service Bus evaluates the dependencies, and the appropriate location is added to the location attribute of the WSDL import element.

  There is no import element for WS-policies. For WS-policies, the policy reference is retained, and the policy resource is included in the export.

  You cannot export a generated WSDL.

  For more information on accessing Oracle Service Bus resources with a URL, see Section 4.30, "Viewing Resources in a Web Browser."

36.3.2 WSDL Overview

A WSDL document describes a service, its location, its operations, and the way in which clients can communicate with it. This section provides a very brief introduction to WSDL, to provide context for discussing Oracle Service Bus features.

Table 36-1 summarizes the main elements used to define WSDL services.

Table 36-1 High-level WSDL Elements

Element	Description
<types>	Type definitions for message content.
<message>	Abstract definition of the data being exchanged. A message consists of parts, which describe the logical, abstract content of the message.
<portType>	Abstract collection of operations supported by the service.
<operation>	Abstract description of an action supported by the service.
<binding>	Concrete protocol and data format specification for a port type.
<port>	A single endpoint, consisting of a network address and a binding.
<service>	Collection of related ports, or endpoints.

WSDL specifies SOAP, HTTP, MIME, and Oracle Service Bus-specific binding extensions, which extend the WSDL binding mechanism to support protocol-specific or message format-specific features.

36.3.2.1 Types

The <types> element is a container for data type definitions. It uses a type system, such as XML Schema (XSD), to define the vocabulary of messages handled by this service. For example, a service that provides stock quotes might define an XML vocabulary, with the terms TradePriceRequest and TradePrice, as shown in Example 36-1.

Example 36-1 WSDL Types Example

<types>
    <schema targetNamespace="http://example.com/stockquote.xsd"
            xmlns="http://www.w3.org/2001/XMLSchema">
        <element name="TradePriceRequest">
            <complexType>
                <all>
                    <element name="tickerSymbol" type="string"/>
                </all>
            </complexType>
        </element>
        <element name="TradePrice">
            <complexType>
                <all>
                    <element name="price" type="float"/>
                </all>
            </complexType>
        </element>
    </schema>
</types>

36.3.2.2 Message

The <message> element provides an abstract, typed definition of the data being communicated. A message consists of parts, each of which describes one logical, abstract unit of the message. A WSDL can define one or more messages, each of which may have one or more parts. For example, the WSDL fragment in Example 36-2 defines four message types, sellerInfoMessage, buyerInfoMessage, response, and negotiationMessage, each of which has one or more parts.

Example 36-2 WSDL Message Example

<message name="sellerInfoMessage">
    <part name="inventoryItem" type="xsd:string"/>
    <part name="askingPrice" type="xsd:integer"/>
</message>

<message name="buyerInfoMessage">
    <part name="item" type="xsd:string"/>
    <part name="offer" type="xsd:integer"/>
</message>

<message name="response">
    <part name="result" type="xsd:string"/>
</message>

<message name="negotiationMessage">
    <part name="item" type="xsd:string"/>
    <part name="price" type="xsd:integer"/>
    <part name="outcome" type="xsd:string"/>
</message>

36.3.2.3 Port Type

The <portType> element defines a set of operations supported by one or more endpoints (which are defined in the <port> element). The port type provides the public interface for the operations provided by the service. Each operation is defined in an <operation> element, each of which is an abstract description of an action supported by the service.

For example, the fragment in Example 36-3 defines a port type with one operation, GetLastTradePrice, which can handle an input message, GetLastTradePriceInput, and an output message, GetLastTradePriceOuput. The concrete descriptions of these messages are defined in the WSDL binding, as shown in the <soap:operation> subelement in Example 36-4.

Example 36-3 WSDL Port Type and Operation Example

<portType name="StockQuotePortType">
    <operation name="GetLastTradePrice">
        <input message="tns:GetLastTradePriceInput"/>
        <output message="tns:GetLastTradePriceOutput"/>
    </operation>
</portType>

36.3.2.4 Binding

The <binding> element specifies a concrete data format specification and a concrete transport protocol for a port type.

The fragment in Example 36-4 specifies the binding for the StockQuotePortType port type, which is provided as the value for the type attribute. The <soap:binding> subelement signifies that the binding is bound to the SOAP protocol format. In that subelement, the style attribute specifies that the data format is SOAP document style, and the transport attribute specifies that the transport protocol is HTTP.

Example 36-4 WSDL Binding Example

<binding name="StockQuoteSoapBinding" type="tns:StockQuotePortType">
    <soap:binding style="document" 
           transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="GetLastTradePrice">
        <soap:operation 
            soapAction="http://example.com/GetLastTradePrice"/>
            <input>
                <soap:body use="literal"/>
            </input>
            <output>
                <soap:body use="literal"/>
            </output>
    </operation>
</binding>

36.3.2.5 Service and Port

The <service> element defines a collection of related endpoints, each of which is defined in a child <port> element. A port is defined as a binding associated with a network address. For example, the fragment shown in Example 36-5 defines two ports, StockQuotePort, and StockQuotePortUK. They both use the same binding, tns:StockQuoteSoapBinding, (which is concretely defined in <binding>) but have different network addresses: http://example.com/stockquote vs. http://example.uk/stockquote. These are alternative ports available for this service.

Example 36-5 WSDL service and port Example

<service name="StockQuoteService">
    <port name="StockQuotePort" binding="tns:StockQuoteSoapBinding">
       <soap:address location="http://example.com:9999/stockquote"/>
    </port>
    <port name="StockQuotePortUK" binding="tns:StockQuoteSoapBinding">
       <soap:address location="http://example.uk:9999/stockquote"/>
    </port>
</service>

36.4 Using a WSDL to Define a Service

If a service has a well defined WSDL interface, it is recommended, although not required, that you use the WSDL to define the service.

There are three types of WSDLs you can define. They are:

• Section 36.4.1, "SOAP Document Wrapped Web Services"

• Section 36.4.2, "SOAP Document Style Web Services"

• Section 36.4.3, "SOAP RPC Web Services"

36.4.1 SOAP Document Wrapped Web Services

A document wrapped Web service is described in a WSDL as a Document Style Service. However, it follows some additional conventions. Standard document-oriented Web service operations take only one parameter or message part, typically an XML document. This means that the methods that implement the operations must also have only one parameter. Document-wrapped Web service operations, however, can take any number of parameters, although the parameter values will be wrapped into one complex data type in a SOAP message. This wrapped complex data type will be described in the WSDL as the single document for the operation.

36.4.2 SOAP Document Style Web Services

You can configure proxy services as SOAP style proxy services and configure business services as SOAP style business services.

Example 36-6 provides an example of a WSDL for a sample document style Web service using SOAP 1.1.

Example 36-6 WSDL for a Sample Document Style Web Service

<definitions name="Lookup"
targetNamespace="http://example.com/lookup/service/defs"
xmlns:tns="http://example.com/lookup/service/defs"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:docs="http://example.com/lookup/docs"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns="http://schemas.xmlsoap.org/wsdl/">
  <types>
    <xs:schema targetNamespace="http://example.com/lookup/docs" elementFormDefault="qualified">
      <xs:element name="PurchaseOrg" type="xs:string"/>
      <xs:element name="LegacyBoolean" type="xs:boolean"/>
    </xs:schema>
  </types>
  <message name="lookupReq">
    <part name="request" element="docs:purchaseorg"/>
  </message>
  <message name="lookupResp">
    <part name="result" element="docs:legacyboolean"/>
  </message>
  <portType name="LookupPortType">
    <operation name="lookup">
      <input message="tns:lookupReq"/>
      <output message="tns:lookupResp"/>
    </operation>
  </portType>
  <binding name="LookupBinding" type="tns:lookupPortType">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="lookup">
      <soap:operation/>
      <input>
        <soap:body use="literal" />
      </input>
      <output>
        <soap:body use="literal"/>
      </output>
    </operation>
  </binding>
</definitions>

The service has an operation (equivalent to a method in a Java class) called lookup. The binding indicates that this is a SOAP 1.1 document style Web service.

When the WSDL shown in the preceding listing is used for a request, the value of the body variable ($body) that the document style proxy service obtains is displayed in Example 36-7.

Note:

Namespace declarations have been removed from the XML in the listings that follow for the sake of clarity.

Example 36-7 Body Variable Value

<soap-env:body>
  <req:purchaseorg>Oracle</req:purchaseorg>
</soap-env:body>

In Example 36-7, soap-env is the predefined SOAP 1.1 namespace and req is the namespace of the PurchaseOrg element (http://example.com/lookup/docs).

If the business service to which the proxy service is routing uses the above WSDL, the value for the body variable ($body) given above is the value of the body variable ($body) from the proxy service.

The value of the body variable ($body) for the response from the invoked business service that the proxy service receives is displayed in Example 36-8.

Note:

Namespace declarations have been removed from the XML in the listings that follow for the sake of clarity.

Example 36-8 Body Variable Value

<soap-env:body>
  <req:legacyboolean>true</req:legacyboolean>
</soap-env:body>

This is also the value of the body variable ($body) for the response returned by the proxy service using this WSDL.

There are many tools available (including Eclipse with Oracle Service Bus plug-ins) that take the WSDL of a proxy service (obtained by adding the ?WSDL suffix to the URL of the proxy service in the browser) and generate a Java class with the appropriate request and response parameters to invoke the operations of the service. This Java class can be used to invoke the proxy service that uses this WSDL.

36.4.3 SOAP RPC Web Services

You can configure proxy services as RPC style proxy services and configure business services as RPC style business services.

Example 36-9 provides an example of a WSDL for a sample RPC style Web service using SOAP 1.1.

Example 36-9 WSDL for a Sample RPC Style Web Service

<definitions name="Lookup"
targetNamespace="http://example.com/lookup/service/defs"
xmlns:tns="http://example.com/lookup/service/defs"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:docs="http://example.com/lookup/docs"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns="http://schemas.xmlsoap.org/wsdl/">
  <types>
    <xs:schema targetNamespace="http://example.com/lookup/docs" elementFormDefault="qualified">
      <xs:complexType name="RequestDoc">
        <xs:sequence>
          <xs:element name="PurchaseOrg" type="xs:string"/>
        </xs:sequence>
      </xs:complexType>
      <xs:complexType name="ResponseDoc">
        <xs:sequence>
          <xs:element name="LegacyBoolean" type="xs:boolean"/>
        </xs:sequence>
      </xs:complexType>
    </xs:schema>
  </types>
  <message name="lookupReq">
    <part name="request" type="docs: RequestDoc"/>
  </message>
  <message name="lookupResp">
    <part name="result" type="docs: ResponseDoc"/>
  </message>
  <portType name="LookupPortType">
    <operation name="lookup">
      <input message="tns:lookupReq"/>
      <output message="tns:lookupResp"/>
    </operation>
  </portType>
  <binding name="LookupBinding" type="tns:lookupPortType">
    <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="lookup">
      <soap:operation/>
      <input>
        <soap:body use="literal" namespace="http://example.com/lookup/service"/>
      </input>
      <output>
        <soap:body use="literal" namespace="http://example.com/lookup/service"/>
      </output>
    </operation>
  </binding>
</definitions>

The service described in the preceding listing includes an operation (equivalent to a method in a Java class) called lookup. The binding indicates that this is a SOAP RPC Web service. In other words, the Web service's operation receives a set of request parameters and returns a set of response parameters. The lookup operation has a parameter called request and a return parameter called result. The namespace of the operation in the binding is:

http://example.com/lookup/service/defs

When the WSDL shown in Example 36-9 is used for a request, the value of the body variable ($body) that the SOAP RPC proxy service obtains is displayed in Example 36-10.

Note:

Namespace declarations have been removed from the XML in the listings that follow for the sake of clarity.

Example 36-10 Body Variable Value

<soap-env:body>
  <ns:lookup>
    <request>
      <req:purchaseorg>Oracle</req:purchaseorg>
    </request>
  </ns:lookup>
<soap-env:body>

Where soap-env is the predefined SOAP 1.1 name space, ns is the operation namespace (<http://example.com/lookup/service>) and, req is the namespace of the PurchaseOrg element (http://example.com/lookup/docs).

If the business service to which the proxy service routes the messages uses the WSDL shown in Example 36-10, the value for the body variable ($body), shown in Example 36-11, is the value of the body variable ($body) from the proxy service.

When this WSDL is used for a request, the value of the body variable ($body) for the response from the invoked business service that the proxy service receives is displayed in Example 36-10.

Example 36-11 Body Variable Value

<soap-env:body>
  <ns:lookupResponse>
    <result>
      <req:legacyboolean>true</req:legacyboolean>
    </result>
  </ns:lookupResponse>
<soap-env:body>

This is also the value of the body variable ($body) for the response returned by the proxy service using this WSDL.

There are many tools available (including Eclipse with Oracle Service Bus plug-ins) that take the WSDL of a proxy service (obtained by adding the ?WSDL suffix to the URL of the proxy in the browser) and generate a Java class with the appropriate request and response parameters to invoke the operations of that service. You can use such Java classes to invoke the proxy services that use this WSDL.

The benefits of using a WSDL include the following:

• The system can provide metrics for each operation in a WSDL.

• Operational branching is possible in the pipeline. For more information, see Section 37.2, "Branching in Message Flows."

• For SOAP 1.1 services, the SOAPAction header is automatically populated for services invoked by a proxy service. For SOAP 1.2 services, the action parameter of the Content-Type header is automatically populated for services invoked by a proxy service.

• A WSDL is required for services using WS-Security. WS-Policies are attached to WSDLs.

• The system supports the <url>?WSDL syntax, which allows you to dynamically obtain the WSDL of a HTTP proxy service. This is useful for a number of SOAP client generation tools, including Eclipse with Oracle Service Bus plug-ins. For more information, see Section 4.30, "Viewing Resources in a Web Browser."

• In the XQuery and XPath editors and condition builders, it is easy to manipulate the body content variable ($body) because the editor provides a default mapping of $body to the request message in the WSDL of a proxy service. See Chapter 39, "Message Context."

• The run-time contents of $body for a specific action can be different from the default mapping displayed in the editor. This is because Oracle Service Bus is not a programming language in which typed variables are declared and used. Instead, variables are untyped and are created dynamically at run time when a value is assigned. In addition, the type of the variable is the type that is implied by its contents at any point in the message flow. To enable you to easily create XQuery and XPath expressions, the design time editor allows you to map the type for a given variable by mapping the variable to the type in the editor. To learn about using the XQuery and XPath editor to create expressions, see Section 37.11, "Working with Variable Structures."

36.5 Basing Services on WSDL Ports and on WSDL Bindings

When you create a service based on a WSDL resource, you must base the service on a WSDL port or on a WSDL binding:

• When you create a new service based on a binding in a WSDL resource, you are choosing the protocol and data format defined in the selected <binding> element in the WSDL resource.

• When you create a new service based on a port in a WSDL resource, you are choosing the binding and the network address defined in the <port> element.

When creating or modifying the service, you can change the transport, but you cannot override the data format.

The port and binding definitions from the original WSDL resource are modified in the effective WSDL depending on a number of factors, as described below.

36.5.1 Characteristics of Effective WSDLs Generated for Proxy Services

The following characteristics apply to effective WSDLs generated for proxy services:

• The effective WSDL has one and only one wsdl:service section.

• The wsdl:service section has one and only one wsdl:port section.

• For SOAP services, any existing <wsdl:service> definition is removed, and a new service definition containing a single <wsdl:port> is created.

• For SOAP binding over any of the supported transports the wsdl:binding section contains the standard WSDL SOAP binding elements along with a unique transport URI that identifies the transport.

• For XML binding over HTTP, the wsdl:binding section uses the standard binding elements specified in the WSDL 1.1 specification.

• For XML binding over any of the other supported transports the wsdl:binding section uses Oracle (Oracle Service Bus) proprietary WSDL XML binding elements.

• If the service is based on a binding:

  • If the service is generated from binding Y in the WSDL resource, the effective WSDL defines a new service and port (<bindingname>QSService and <bindingname>QSPort). None of the ports defined in the WSDL resource are included in the effective WSDL.

  • There may be multiple ports in that WSDL associated with that binding. Each port can use a different URL. Therefore, the effective WSDL uses the binding but generates an artificial port from the configuration on the service for that binding. All other ports will be removed.

• If the service is based on a port:

  • If the service is generated from port X in the WSDL resource, then port X is also defined in the effective WSDL. Any other ports defined in the WSDL resource are not included. Furthermore, if you base the proxy service on a WSDL port, the effective WSDL uses that port name. The binding is determined from the port, and in turn, the port type is determined from the binding.

  • The effective WSDL preserves any WS-Policies associated with the port defined in the resource WSDL.

  • The transport address specified in the port definition in the resource WSDL is never used as the address for a proxy service in the effective WSDL:

    For HTTP services, you must specify a transport address when configuring the transport in the Administration Console or the plug-in. That address is used in the port definition in the effective WSDL.

    The URL specified as the transport address for a proxy service is always relative to a path in an Oracle Service Bus domain, because Oracle Service Bus always hosts proxy services.

  • For SOAP-protocol-based WSDL services, the transport URI in the SOAP binding depends on the transport implementation. For standard transports (like HTTP and JMS), this value is as per the SOAP specification or another universally accepted value. For transports for which SOAP does not define a standard value, Oracle Service Bus sets one consisting of a predefined namespace with the transport ID appended at the end: http://www.oracle.com/transport/2007/05/.

  • There is one service element in the effective WSDL, and the port address contains a URL whose syntax and semantic is defined by the transport selected in the binding.

36.5.1.1 Characteristics of Effective WSDLs Generated for Non-Transport-Type Business Services

The following characteristics apply to effective WSDLs generated for non-transport-type business services:

• The effective WSDL has one and only one wsdl:service section.

• The wsdl:service section may have more than one wsdl:port sections. This is generally true when load balancing is used and there are multiple end point addresses that can be used using one of the load-balance algorithms supported.

• For SOAP binding over any of the supported transports, the wsdl:binding section contains the standard WSDL SOAP binding elements along with a unique transport URI that identifies the transport.

• For XML binding over any of the supported transports, the wsdl:binding section contains the Oracle WSDL XML binding elements.

• The URL specified as the transport address is a remote location where the remote service is hosted.

• If the service is based on a port:

  • The effective WSDL defines a port with the same name as the port in the template on which the new service is based. If multiple endpoint addresses are configured for the business service, the effective WSDL generated from it defines ports for all the endpoints, with the names <portname_in_template>_1, <portname_in_template>_2,...

  • The binding for the new service is determined from the port, and the port type is in turn determined from the binding.

  • The transport address URL is a remote location where the remote service is hosted.

• If the service is based on a binding:

  • The effective WSDL defines a new service and port, based on the port in the WSDL resource. None of the ports defined in the WSDL resource are included in the effective WSDL.

  • A binding in the WSDL resource may be associated with multiple ports. Each port can use a different URL and have a different WS-Policy attached to it. Therefore, the generated WSDL uses the binding but generates an artificial port for that binding with no WS-Policy.

  • For XML-based WSDL services, standard HTTP binding is used only if the service uses HTTP transport. For all other services created from an XML-based WSDL, the effective WSDL uses Oracle binding.

36.5.1.2 Characteristics of Effective WSDLs Generated for Transport-Type Business Services

Oracle Service Bus does not guarantee one and only one wsdl:service section in effective WSDLs generated for transport-type business services. Because the WSDL is generated by the transport, Oracle Service Bus does not generate nor does it clean up extra service-port sections. Oracle Service Bus does, however, evaluate dependencies and sets their references during export.

36.5.1.3 Generating Effective WSDLs in Clustered Domains

When generating the effective WSDL in a clustered domain, Oracle Service Bus rewrites the endpoint URL based on the server or cluster configuration. If a front-end HTTP host/port (or a front-end HTTPS host/port for HTTPS endpoints) has been specified, it will be used; otherwise, the Managed Server host or port will be used. It is strongly advised that a front-end HTTP or HTTPS host/port is assigned in clustered domains.

36.5.1.4 Examples of Proxy Services Based on a Port and on a Binding

Example 36-12 shows fragments of port and binding definitions in a WSDL resource.

Example 36-12 WSDL resource

<portType name="StockQuotePortType">
...
</portType>
<binding name="StockQuoteSoapBinding" type="tns:StockQuotePortType">
    <soap:binding style="document"
      transport="http://schemas.xmlsoap.org/soap/http"/>
...
</binding>
<service name="StockQuoteService">
   <port name="StockQuotePort" binding="tns:StockQuoteSoapBinding">
     <soap:address location="http://example.com:9999/stockquote"/>
   </port>
   <port name="StockQuotePortUK" binding="tns:StockQuoteSoapBinding">
      <soap:address location="http://example.uk:9999/stockquote"/>
   </port>
</service>

36.5.1.4.1 Basing the Service on a Port

If you create a proxy service based on the StockQuotePort port in Example 36-12, the effective WSDL will look something like the fragment in Example 36-13.

Example 36-13 Effective WSDL for a Proxy Service Based on a Port

<binding name="StockQuoteSoapBinding" type="ns:StockQuotePortType">
    <soap:binding style="document"
      transport="http://schemas.xmlsoap.org/soap/http"/>
...
</binding>
<service name="StockQuoteService">
  <port name="StockQuotePort" binding="ns:StockQuoteSoapBinding">
    <soap:address location="http://host:port/project/proxyname"/>
  </port>
</service>

Notice the following about the above example:

• The service name, StockQuoteService, is the same in both the template and the effective WSDL.

• The binding is the same in both the template and the effective WSDL. In this example, it specifies that the service will use the HTTP transport protocol for SOAP document style messages. (The binding also specifies the same binding operation in both the template and the effective WSDL, but that is not shown in this example.)

• The second port defined in the WSDL resource, StockQuotePortUK, is not defined in the effective WSDL.

• The transport address (URI) defined in the WSDL resource's port, http://example.com:9999/stockquote, is different from the address generated in the effective WSDL's port, http://host:port/project_path/proxy_service_name. The effective WSDL uses the address specified for the transport configuration in the Oracle Service Bus Administration Console or Eclipse with Oracle Service Bus plug-ins.

36.5.1.4.2 Basing the Service on a Binding

If you create a proxy service based on the StockQuoteBinding binding in Example 36-12, the effective WSDL will look something like the fragment in Example 36-14.

Example 36-14 Effective WSDL for a Proxy Service Based on a Binding

<binding name="StockQuoteSoapBinding" type="ns:StockQuotePortType">
    <soap:binding style="document"
      transport="http://schemas.xmlsoap.org/soap/http"/>
...
</binding>
<wsdl:service name="StockQuoteSoapBindingQSService"
   <wsdl:port name="StockQuoteSoapBindingQSPort"
            binding="ns:StockQuoteSoapBinding">
      <soap:address location="http:/host:port/project/proxyname"/>
   </wsdl:port>
</wsdl:service>

Notice the following about the above example:

• The service and the port in the WSDL resource are different from the service and the port generated in the effective WSDL.

• The service name in the WSDL resource and the effective WSDL are different: StockQuoteService in the template and StockQuoteSoapBindingQSService in the effective WSDL.

• The binding is the same in both the WSDL resource and effective WSDL. In this example, it specifies that the service will use the HTTP transport protocol for SOAP document style messages.

• The binding also specifies the same binding operation in both the template and the effective WSDL, but that is not shown in this example.

• The transport address (URI) defined in the WSDL resource's port, http://example.com:9999/stockquote, is different from the address generated in the effective WSDL's port, http://host:port/project/stockquote.

36.5.2 Using Any SOAP or Any XML Service Types

If you want to expose one port to clients for a variety of enterprise applications, use Any SOAP or Any XML service types. For Any SOAP, you must specify if it is SOAP 1.1 or SOAP 1.2.

36.5.3 Using the Messaging Service Type

If one of the request or response messages is non-XML, you must use the messaging service type.

Oracle Service Bus does not automatically perform "misunderstand" SOAP header checking. However, you can use XQuery conditional expressions and validate actions to explicitly perform this type of check. For more information on the validate action, see Section 22.24, "Adding Validate Actions" or "Validate Action Properties" in the Oracle Fusion Middleware Developer's Guide for Oracle Service Bus. For more information on conditional XQuery expressions, see Chapter 23, "Proxy Services: XQuery and XPath Editors" or "Condition Editor" in the Oracle Fusion Middleware Developer's Guide for Oracle Service Bus.

You can use Oracle Service Bus to configure a validate action and use XQuery conditional expressions to perform validation checks explicitly in the message flow.

For more information on service types, see "General Configuration page" in Section 20.1, "Creating and Configuring Proxy Services.".

36.6 Configuring Proxy Services

The following sections provide an overview of proxy service configuration. For specific instructions for configuring proxy services, see:

• Chapter 20, "Proxy Services: Creating and Managing"

• "Working with Proxy Services" in the Oracle Fusion Middleware Developer's Guide for Oracle Service Bus

36.6.1 Proxy Service Types and Transports

Each proxy service is of a certain type, and each can be used with the transport protocols appropriate for that type. Oracle Service Bus supports several standard transports plus custom transports. The service types are described in Table 36-2, including the standard transports available for each type.

Table 36-2 Proxy Service Types and Transports Supported by Oracle Service Bus

Service Type	Description	Standard Transport Protocols Supported for this Service Type
WSDL Web service	A SOAP or XML proxy service whose interface is described by a WSDL document.	HTTP JCA JMS Local SB WS
Transport Typed Service (no WSDL)	A service that uses a JEJB transport.	JEJB
Messaging service (no WSDL)	A messaging service where the request message and the response message can be of different data types, including binary, text, MFL, and XML.	EMAIL FILE FTP HTTP JMS LOCAL MQ SFTP TUXEDO
Any SOAP service (no WSDL)	A SOAP service that does not have an explicitly defined, concrete interface.	HTTP JMS LOCAL SB
Any XML service (non-SOAP, no WSDL)	An XML service that does not have an explicitly defined, concrete interface.	EMAIL FILE FTP HTTP JMS LOCAL MQ SB SFTP TUXEDO

Note:

All service types can send and receive attachments using MIME.

36.6.2 Transport and Security Configuration for Proxy Services

You must configure transport settings for all proxy service types in the Oracle Service Bus Administration Console or Eclipse with the Oracle Service Bus plug-ins. Configuration details vary, depending on the transport type. For specific configuration settings, see Section 20.2.3, "Transport Configuration Page" and Section 20.2.4, "Protocol-Specific Transport Configuration Pages."

The transport you select should support the transport mode (request/response, one-way, or both) required by the binding definition, and it should be configured accordingly.

For services exchanging messages in both modes, you must configure the binding layer to choose the transport mode accordingly (for any transport implementing the request/response as two asynchronous calls, for example, JMS). 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 set the mode in the $outbound variable.

Based on the transport and WSDL, the transport mode is automatically selected, but you can overwrite it in $inbound or $outbound.

You can specify security for proxy services, using service providers. A service provider is required if the proxy service routes messages to HTTPS services that require client-certificate authentication and may be required in some message-level security scenarios.

A service account can be created to provide authentication when connecting to a business service. It acts as an alias resource for the required username and password pair.

Oracle WebLogic Server can be used to directly manage security credentials for a business service requiring credential-level validation.

For more information, see Chapter 18, "Service Key Providers." See also Section 36.6.5, "Security-Related Validation for Proxy Services."

36.6.3 Configuration Settings For Each Proxy Service Type

Each proxy service type is modeled following the same pattern. Each service type must define these configurations:

• Binding definition

• Run-time configuration

• Run-time variables ($operation, $body, $header, $attachments)

Configuration properties specific to individual proxy service types are described in Table 36-3:

Table 36-3 Configuration Properties for Different Proxy Service Types

Proxy Service Type	Configuration Properties
WSDL Web service	Binding Definition: See Section 36.4, "Using a WSDL to Define a Service." Run-Time Variables: For SOAP-based WSDL services, the variables are similar to Any SOAP service except that $operation is initialized based on the Operation Selection algorithm (See Section 20.2.17, "Operation Selection Configuration Page.". For XML-based WSDL services, the variables are similar to Any XML service except that the $operation will be initialized based on the Operation Selection algorithm.
Transport Typed	Transport typed services have an empty binding definition. A WSDL is not specified. The Transport Typed Service is an inbound transport that lets EJBs make invocations through Oracle Service Bus. It is a self-described transport that generates a WSDL to describe its service interface. The JEJB transport features transaction and security context propagation.
Messaging Service	Binding Definition: The binding definition for messaging services consists of configuring the content-type of the messages that are exchanged. The content-type for the response does not need to be the same as for the request; therefore, the response is configured separately (for example, the service could accept an MFL message and return an XML acknowledgment receipt) and could also be set to None. As per their definition, messaging-based services do not have any WSDL definition. It is not possible to request a WSDL document for those services. Following are the content types to choose from for the request and response: None Binary Text MFL XML Java Note: If you are using a Reply action in the pipeline to propagate success or failure messages from a service to the calling client, select an option other than None. The None option blocks the reply. Run-Time Variables: This service type is message-based. There is no concept of multiple "operations" as for Web services. Therefore, the $operation variable is left empty. The $body variable holds the incoming message wrapped in a <soap:Body> element. (For SOAP 1.1 proxies, $body uses the SOAP 1.1 namespace Body; for SOAP 1.2 proxies, it uses SOAP 1.2 namespace Body.) The $header variable is not applicable to this service type, and is set to its default value. The $attachments variable contains message attachments if there are any. To learn more about the message context variables, see Section 39.3, "Message-Related Variables" and Section 39.9, "Constructing Messages to Dispatch."
Any SOAP service	Binding Definition: The only information this service type defines is that the service is receiving or sending SOAP messages—regardless of their WSDL binding definition. Therefore the binding configuration for this type is empty. In addition, as there is no binding configuration, the combination of this type and the content-type of the message is sufficient to determine whether or not there are attachments to the message. As per their definition, "any" services (SOAP or XML) do not have any WSDL definition. It is not possible to generate or view a WSDL document for those services. Run-Time Variables: The $body and $header variables respectively hold the <soap:Body> and <soap:Header> of the incoming SOAP message. (For SOAP 1.1 proxies, $body and $header use SOAP 1.1 namespace Body and namespace; for SOAP 1.2 proxies, they use SOAP 1.2 namespace Body and namespace.) The $attachments variable contains the SOAP message attachments, if any. The $operation variable is not applicable to this service type as you do not define a port type. To learn more about the message context variables, see Section 39.3, "Message-Related Variables" and Section 39.9, "Constructing Messages to Dispatch."
Any XML service	Binding Definition: The only information this service type defines is that the service is receiving/sending XML messages—regardless of their WSDL binding definition. Therefore, the binding configuration for this type is empty. In addition, as there is no binding configuration, the combination of this type and the content-type of the message is sufficient to determine whether or not there are attachments to the message. As per their definition, "any" services (SOAP or XML) do not have any WSDL definition. It is not possible to request a WSDL document for those services. Run-Time Variables: The $body variable holds the incoming XML message wrapped in a <soap:Body> element. (For SOAP 1.1 proxies, $body and $header use SOAP 1.1 namespace Body and namespace; for SOAP 1.2 proxies, they use SOAP 1.2 namespace Body and namespace.) The $attachments variable contains message attachments, if there are any. The $header variable is not applicable to this service type and is set to its default value. The $operation variable is not applicable to this service type as you do not define a port type. To learn more about the message context variables, see Section 39.3, "Message-Related Variables" and Section 39.9, "Constructing Messages to Dispatch."

36.6.4 Configuring Message Flow

A proxy service's message flow definition defines the logic that determines how messages are handled as they flow through the proxy service. A message flow definition transforms messages, as needed, to map the message data to the format required by a business service (for outbound messages) or the originating client (for inbound messages). They then route the messages to the appropriate location. For information about configuring message flows, see Chapter 37, "Modeling Message Flow in Oracle Service Bus."

36.6.5 Security-Related Validation for Proxy Services

When you activate a session that contains changes to an active proxy service, Oracle Service Bus validates the changes to ensure that you have created all of the credentials that the proxy service's static endpoints require. For example, if you configured a proxy service to have a Web service as a static endpoint and the Web service requires a digital signature, Oracle Service Bus verifies that you have associated a service key provider with the proxy service and that the service key provider contains a key-pair binding that can be used as a digital signature.

If a session contains a change to the key-pair bindings of a service key provider, Oracle Service Bus validates the change against all of the proxy services that use the service key provider. For example, if you remove the encryption key-pair, Oracle Service Bus reports a validation error for any proxy service that references the service key provider and whose endpoint requires encryption.

The following criteria determine when Oracle Service Bus performs this security-related validation and the actions that it takes during validation:

• If a proxy service specifies a static route and operation, Oracle Service Bus determines which credentials the static route and operation require. If the proxy service is missing the required credentials, Oracle Service Bus will not commit the session until you add the missing credentials.

• If a proxy service specifies a static route but the operation is passed through from the inbound request, Oracle Service Bus determines which credentials the static route and each of the route's operations require. If the proxy service is missing the required credentials, Oracle Service Bus issues a validation warning but allows you to commit the session.

• If a proxy service specifies a dynamic route and operation, Oracle Service Bus cannot validate the security requirements and you risk the possibility of runtime errors. For information about dynamic routing, see Section 37.8, "Using Dynamic Routing."

36.7 Configuring Business Services

The following sections provide an overview of business service configuration.

This section includes the following topics:

• Section 36.7.1, "Business Service Types and Transport"

• Section 36.7.2, "Configuration Settings for All Business Service Types"

• Section 36.7.3, "Configuration Settings For Each Business Service Type"

• Section 36.7.4, "Using Proxy Servers"

• Section 36.7.5, "Improving Performance by Caching Business Service Results"

For specific instructions for configuring business services, see:

• Chapter 19, "Business Services: Creating and Managing"

• "Working with Business Services" in the Oracle Fusion Middleware Developer's Guide for Oracle Service Bus

36.7.1 Business Service Types and Transport

Each business service is of a certain type, and each can be used with the transport protocols appropriate for that type. Oracle Service Bus supports several standard transports plus custom transports. The service types are described in Table 36-4, including the standard transports available for each type.

Table 36-4 Business Service Types and Transports Supported by Oracle Service Bus

Service Type	Description	Transport Protocols
WSDL Web service	A SOAP or XML business service whose interface is described by a WSDL document.	BPEL-10g DSP HTTP JCA JMS LOCALFoot 1  SB SOA-DIRECT WS
Transport Typed Service (no WSDL)	A service that uses an EJB, JEJB, or Flow (Split-Join) transport.	EJB FLOW JEJB
Messaging Type Service (no WSDL)	A messaging service where the request message and the response message can be of different data types, including binary, text, MFL, and XML.	EMAIL FILE FTP HTTP JMS LOCAL MQ SFTP TUXEDO
Any SOAP Service (no WSDL)	A SOAP service that does not have an explicitly defined, concrete interface.	DSP HTTP JMS LOCAL SB
Any XML Service (no WSDL)	An XML service that does not have an explicitly defined, concrete interface.	DSP EMAIL FILE FTP HTTP JMS LOCAL MQ SB SFTP TUXEDOFoot 2

^Footnote 1 Oracle recommends using the local transport for communication between two proxy services. For more information on local transport, see "Local Transport" in the Oracle Fusion Middleware Developer's Guide for Oracle Service Bus.

^Footnote 2 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 proxy and business services based on various transport protocols, see "Transports" in the Oracle Fusion Middleware Developer's Guide for Oracle Service Bus.

36.7.2 Configuration Settings for All Business Service Types

Each business service type is modeled following the same pattern. Each service type must define these configurations:

• Binding definition

• Run-time configuration

• Run-time variables ($operation, $body, $header, $attachments)

The business service configuration properties described in Table 36-5, below, are common to all service types. Properties specific to individual service types are described in Section 36.7.3, "Configuration Settings For Each Business Service Type."

Table 36-5 Common Configuration Properties for Business Services

Property	Description
Resource Definition	The resource definition consists of: The service name (that is, project, path, and local name) An optional description for the service The service type
Transport Configuration	You can configure the following parameters for each business service: List of <string URI, integer weight> pairs—for example, <http://www.oracle.com, 100>. For a random-weighted list, the list should contain at least one element. Load-balancing algorithm—enumeration, one of 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 (i.e., request/response and one-way), you must configure the binding layer so that 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 message flow to set the mode for a route or publish. Based on the transport and WSDL or interface, the transport mode is automatically selected, but you can overwrite it using the routing options action for a route or publish action.
Result Caching	All business services let you determine if and how to cache the results of business service invocations. This feature, available in the Message Handling section of a service configuration, improves performance on services whose results seldom change. When you enable result caching, service results are returned to the client from the cache instead of invoking the external service to obtain results. For more information, see Section 36.7.5, "Improving Performance by Caching Business Service Results."

36.7.3 Configuration Settings For Each Business Service Type

Configuration properties specific to individual business service types are described in Table 36-6:

Table 36-6 Configuration Properties for Different Business Service Types

Property	Description
WSDL Web service	See Section 36.4, "Using a WSDL to Define a Service."
Any SOAP Service	Binding Definition: The only information this service type defines is that the service is receiving or sending SOAP messages—regardless of their WSDL binding definition. Therefore the binding configuration for this type is empty. In addition, as there is no binding configuration, the combination of this type and the content-type of the message is sufficient to determine whether or not there are attachments to the message. As per their definition, any services (SOAP or XML) do not have any WSDL definition. Run-Time Variables: The $body and $header variables respectively hold the <soap:Body> and <soap:Header> of the SOAP message to the business service being routed to or published. (For SOAP 1.1 proxies, $body and $header use SOAP 1.1 namespace Body and namespace; for SOAP 1.2 proxies, they use SOAP 1.2 namespace Body and namespace.) The $attachments variable contains the SOAP message attachments if any. To learn more about the message context variables, see Section 39.3, "Message-Related Variables."
Transport Typed	Transport-typed services have an empty binding definition. A WSDL is not specified. Instead the transport automatically defines the WSDL for the service. A zip containing this WSDL can be exported from the Oracle Service Bus Administration Console or the Oracle Service Bus plug-ins for Eclipse. This WSDL will not have a port defined. The EJB/JEJB Transport-Typed Service is an outbound transport to access EJBs from Oracle Service Bus. It is a self-described transport that generates a WSDL to describe its service interface. The EJB and JEJB transport features include transaction and security context propagation. Business services built using an EJB or JEJB transport can be used for publish, service callout, and service invocation.
Any XML Service	Binding Definition: The only information this service type defines is that the service is receiving/sending XML messages—regardless of their WSDL binding definition. Therefore, the binding configuration for this type is empty. In addition, as there is no binding configuration, the combination of this type and the content-type of the message is sufficient to determine whether or not there are attachments to the message. As per their definition, any services (SOAP or XML) do not have any WSDL definition. Run-Time Variables: The $body variable holds the incoming XML message wrapped in a <soap:Body> element. (For SOAP 1.1 proxies, $body uses SOAP 1.1 namespace Body; for SOAP 1.2 proxies, it uses SOAP 1.2 namespace Body.) The $attachments variable contains message attachments if there are any. The $header variable is not applicable to this service type and is set to its default value. To learn more about the message context variables, see Section 39.3, "Message-Related Variables."
Messaging Service	Binding Definition: The binding definition for messaging services consists of configuring the content-type of the messages that are exchanged. The content-type for the response does not need to be the same as for the request; therefore, the response is configured separately (for example, the service could accept an MFL message and return an XML acknowledgment receipt). By definition, messaging-based services do not have any WSDL definition. It is not possible to request a WSDL document for those services. The following content types are available for the request and response: None Binary Text MFL XML Java Run-Time Variables: This service type is message based. The $body variable holds the incoming message wrapped in a <soap:Body> element. (For SOAP 1.1 proxies, $body uses SOAP 1.1 namespace Body; for SOAP 1.2 proxies, it uses SOAP 1.2 namespace Body.) The $header variable is not applicable to this service type, and is set to its default value. The $attachments variable contains message attachments if there are any. To learn more about the message context variables, see Section 39.3, "Message-Related Variables."

If a business service requires Web service security, make sure the WSDL you specify has the necessary WS-Policies attached when you create the business service. Furthermore, if the WS-Policy of the business service requires encryption, make sure the public certificate of the business service is embedded in the WSDL. If the business service is an Oracle WebLogic Server 9.0 or later Web service, you can retrieve its WSDL using the http://<host>:<port>/<service url>?WSDL URL, the public certificate will be automatically embedded for you if necessary. For more information, see Section 4.30, "Viewing Resources in a Web Browser."

36.7.4 Using Proxy Servers

You can configure business services to route messages through a proxy server. You do this by creating a proxy server resource that specifies one or more proxy servers together with the necessary credentials. You can then associate this proxy server resource with a business service. This instructs Oracle Service Bus to connect to the business service through the configured proxy server.

Adding multiple proxy servers to a resource enables Oracle 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, Oracle Service Bus attempts to use the next proxy server in the configuration. If all proxy servers are unreachable, Oracle 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.

When configuring a proxy server, you can specify the clear text or SSL port number for the server, in addition to the host name or IP address. Note that the port specified in the proxy server resource configuration corresponds to the actual physical port of the Web proxy server and not the port of the back end service. The end point configuration on the business service, however, corresponds to the actual end point of the back end service. This is true even in the case of SSL/TLS Tunneling using HTTP CONNECT command.

NOTE: While some Web proxy servers support HTTP CONNECT using both clear text and SSL sockets, other servers support HTTP CONNECT using only clear text sockets. For example, Sun Proxy Server 4.0 supports HTTP CONNECT using clear text and SSL sockets while Apache Web Server 2.2 in proxy server mode supports HTTP CONNECT using only clear sockets.

Typically, for SSL/TLS Tunneling support, you do not need to install server or Certificate Authority (CA) certificates on the physical proxy server. Instead, the Web proxy server uses the certificate received from the caller (Oracle Service Bus, in this case) to open a secure socket. Similarly, when the server hosting the business application requires a client certificate, the certificate of the server hosting the proxy service (Oracle Service Bus) is used for authentication.

36.7.5 Improving Performance by Caching Business Service Results

If you use business services that return somewhat static 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 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 that all business services share to store their respective results, and "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.

The result caching mechanism that Oracle Service Bus uses is Oracle Coherence (Enterprise Edition), which is included with Oracle WebLogic Server. If a license for Oracle WebLogic Server is available for a certain processor, Coherence can be used on that machine.

The Oracle 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, alert rules, and smart search.

This section describes the Oracle Service Bus implementation of result caching.

36.7.5.1 How Result Caching Works

Figure 36-1 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 36-1 Business Service Result Caching

Description of "Figure 36-1 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 proxy service message flow.

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 36-1, 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, including: a first-time invocation where no cache yet exists, a caching error, or because 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 proxy service message flow. If Oracle 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.

36.7.5.1.1 Flushing Cached Results

Oracle Service Bus/Coherence can flush an individual cached result, all cached results for a business service, or the entire result cache (all cached results for all Oracle Service Bus business services). The following events illustrate how Oracle Service Bus/Coherence flush cache:

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

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

• Update, Rename, or Delete a business service – If you update, rename, or delete a business services, Oracle Service Bus triggers flushing of all cached results for that business service from Oracle Coherence.

• Update dependent resource – When you update a dependent resource, such as a WSDL, Oracle Service Bus triggers flushing all cached results for that business service from Oracle Coherence. However, changes to the following dependent resources do not cause cache flushing: Service Provider, UDDI Registry, Alert Destination.

• Globally disable result caching – When you globally disable result caching, Oracle Service Bus triggers flushing the entire result cache (all cached results for all business services) from Oracle Coherence.

For more information on working with and configuring result caching, see:

• Section 27.2.11, "Enabling Result Caching Globally"

• Section 19.1, "Creating and Configuring Business Services"

• "Business Service Message Handling Configuration Page" in the Oracle Fusion Middleware Developer's Guide for Oracle Service Bus

36.7.5.2 Result Caching Best Practices

This section describes best practices for using result caching.

36.7.5.2.1 Security Best Practices with Result Caching

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.

36.7.5.2.2 Production Best Practices with Result Caching

Before deploying an Oracle 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 the "Production Checklist" in the Oracle Coherence Developer's Guide at https://download.oracle.com/docs/cd/E15357_01/coh.360/e15723/deploy_checklist.htm#CHDJEJEI.

36.7.5.3 Result Cache Metadata

Following are the metadata used for result caching:

36.7.5.3.1 Request Metadata

Following are the request metadata used with result caching: 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.

For more information, see Section 19.2.23, "Message Handling Configuration Page" for business service configuration.

36.7.5.3.2 Response Metadata

Following are the response metadata used with result caching:

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

36.7.5.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) from a proxy service. 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 proxy service that invokes the business service.

You can, however, invoke Split-Join business services directly to test result caching.

36.7.5.5 Result Caching Advanced Configuration

In each Oracle Service Bus domain, you can modify how the domain uses Oracle Coherence for business service result caching. This section describes default settings and when you should change them.

36.7.5.5.1 Result Cache Setup and Tuning

You can tune cache schemes for the Oracle Service Bus result cache by modifying DOMAIN_HOME/config/osb/coherence/osb-coherence-cache-config.xml. By default, a distributed cache scheme is used for the Oracle Service Bus result cache. For more information, see "Cache Configuration Elements" in the Oracle Coherence Developer's Guide at https://download.oracle.com/docs/cd/E15357_01/coh.360/e15723/appendix_cacheconfig.htm.

36.7.5.5.2 Working with Unicast and Multicast

Oracle Service Bus provides its own default Oracle Coherence configuration for the servers in a domain. The configuration file, located at DOMAIN_HOME/config/osb/coherence/osb-coherence-override.xml, provides different properties that control server access to Oracle Coherence cache.

This section describes the default Oracle Coherence configuration settings for Oracle Service Bus single- and multi-server domains, and describes scenarios in which you need to modify the default settings.

Table 36-7 shows the default system property values in osb-coherence-override.xml for a single-server domain created with the Oracle Service Bus for developers template. These unicast settings restrict Oracle Coherence cache access to only the local server. With this configuration, nodes started on different servers do not join the same Oracle Coherence cluster to share cached information.

You can modify the system properties either in osb-coherence-override.xml (requires server restart) or by specifying the system properties on server startup.

Table 36-7 osb-coherence-override.xml Default Settings for an "Oracle Service Bus for developers" Domain Topology

Server Details	Element/Property Name in the File	System Property	Default Value
Unicast Address	<address>	OSB.coherence.localhost	127.0.0.1
Unicast Port	<port>	OSB.coherence.localport	7890
Well-Known Address	<address>	OSB.coherence.wka	127.0.0.1
Well-Known Port	<port>	OSB.coherence.wka.port	7890
Network Time to Live (TTL)	<time-to-live>	OSB.coherence.ttl	0 For more information on this setting, see "Network" in the Oracle Coherence Developer's Guide at https://download.oracle.com/docs/cd/E14526_01/coh.350/e14509/appproductcheck.htm#COHDG305.

Table 36-8 shows the default system property values in osb-coherence-override.xml for a multi-server domain created with the Oracle Service Bus template. The default multicast values create an Oracle Coherence cluster that is shared by any Oracle WebLogic Server node on the same subnet created from the same template.

You can modify the system properties either in osb-coherence-override.xml (requires server restart) or by specifying the system properties on server startup.

Table 36-8 osb-coherence-override.xml Default Settings for an "Oracle Service Bus" Domain Topology

Server Details	Element/Property Name in the File	System Property	Default Value
Unicast Address	<address>	OSB.coherence.localhost	127.0.0.1
Unicast Port	<port>	OSB.coherence.localport	7890
Unicast well-known address placeholders	<address>	OSB.coherence.wkaN	The file provides placeholders for 9 well-known addresses (with no address values) for you to configure and use as needed.
Unicast well-known address port placeholders	<port>	OSB.coherence.wkaN.port	The file provides placeholders for 9 well-known address ports (with no port values) for you to configure and use as needed.
Multicast Listener Address	<address>	OSB.coherence.clusteraddress	228.8.8.8
Multicast Listener Port	<port>	OSB.coherence.clusterport	9888

The Multicast Address and Multicast Port properties determine how member nodes of the Oracle Coherence cluster are located. This combination must be unique for each Oracle Coherence cluster that is running within the same subnet.

Note:

Even though the Oracle Service Bus template is configured to use a multicast listener by default, a best practice is to configure the Oracle Coherence cluster to use a unicast listener with an explicit list of nodes for the Oracle Coherence cluster.

To switch to unicast, delete the multicast values and enter well-known addresses for unicast listeners. For example:

<well-known-addresses>
<socket-address id="1">
<address system-property="OSB.coherence.wka1">127.0.0.1</address>
<port system-property="OSB.coherence.wka1.port">7890</port>
</socket-address>
...

For more information, see "well-known-addresses" at http://coherence.oracle.com/display/COH35UG/well-known-addresses.

You can also provide overrides using system properties, as described in "Configure Oracle Coherence for the Oracle Service Bus Result Cache" in the Oracle Fusion Middleware High Availability Guide.

The following configurations require manual modification of osb-coherence-override.xml (or providing system property overrides as described in the previous note) to ensure the desired sharing of an Oracle Coherence cluster among multiple servers:

• If you want to switch from a multicast listener to a unicast listener with well-known addresses in a cluster, as described in the previous note.

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

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

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

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

36.7.5.5.3 Using an Out-of-Process Coherence Cache Server

If you plan to use result caching heavily with Oracle 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 an Oracle Service Bus domain JVM. Running a Coherence cache server outside of an Oracle Service Bus JVM—out of process—lets the Coherence cache server use its own heap space without affecting the heap space Oracle Service Bus uses to process messages.

Oracle Service Bus provides support for out-of-process Coherence caching with the following JAR file: OSB_ORACLE_HOME/lib/osb-coherence-client.jar.

The following steps describe how to use an out-of-process Coherence cache server:

Note:

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

1. Configure the Oracle Service Bus domain to support the out-of-process Coherence cache server.

   1. Disable local caching on each Oracle Service Bus node by adding the following argument to the Oracle Service Bus node startup:

      -Dtangosol.coherence.distributed.localstorage=false
      

   2. Set the Coherence cluster name with the following argument.

      -DOSB.coherence.cluster=cluster_name
      

2. Configure the out-of-process Coherence cache server startup:

   1. Make sure osb-coherence-client.jar is on the Coherence cache server classpath. For example:

      -classpath coherence.jar:OSB_ORACLE_HOME/lib/osb-coherence-client.jar
      

      Note:

      The path in this example shows osb-coherence-client.jar in the default location in an Oracle Service Bus installation. In an out-of-process Coherence cache server that does not have Oracle Service Bus installed, copy this file from the Oracle Service Bus domain to the Coherence cache domain and reference it in the startup argument for all Coherence nodes.

   2. Use osb-coherence-override.xml by adding the following argument to the Coherence cache server startup:

      -Dtangosol.coherence.override=DOMAIN_HOME/config/osb/coherence/osb-coherence-override.xml
      

      This step ensures that the same networking configuration is used for both the Oracle Service Bus Coherence nodes and the out-of-process Coherence cache server. For more information on this file, see Section 36.7.5.5.2, "Working with Unicast and Multicast."

      Note:

      The path in this example shows the osb-coherence-override.xml file in the default location in an Oracle Service Bus installation. In an out-of-process Coherence cache server that does not have Oracle Service Bus installed, copy this file from the Oracle Service Bus domain to the Coherence cache domain and reference it in the startup argument for all Coherence nodes.

   3. Use osb-coherence-cache-config.xml by adding the following argument to the Coherence cache server startup:

      -Dtangosol.coherence.cacheconfig=DOMAIN_HOME/config/osb/coherence/osb-coherence-cache-config.xml
      

      See the previous note.

   4. Add the following arguments to the Coherence cache server startup to set the host and port:

      -DOSB.coherence.localhost=HOSTNAME and -DOSB.coherence.localport=PORT where host:port is unique in the cluster.

   5. If you use a unicast listener for cluster membership (recommended), and you do not include well-known listeners in the osb-coherence-override.xml file as described in Table 36-8, add as many well-known addresses as needed to the Coherence cache server startup using the following arguments:

      -DOSB.coherence.wka[1-9] and -DOSB.coherence.wka[1-9].port

      For more information on using unicast for Oracle Coherence with Oracle Service Bus, see "Configure Oracle Coherence for the Oracle Service Bus Result Cache" in the Oracle Fusion Middleware High Availability Guide.

   6. Make sure the Coherence cluster name is the same for the out-of-process Coherence cache server as it is for the Oracle Service Bus server by using the following startup argument:

      -Dtangosol.coherence.cluster=OSB-cluster
      

      The Oracle Service Bus cluster is always called "OSB-cluster".

Starting the Servers

When using an out-of-process Coherence cache server, which involves disabling local caching on the Oracle Service Bus server as described at the beginning this procedure, be sure to start the out-of-process Coherence cache server before starting the Oracle Service Bus server.

One way to start the Coherence cache server is to use a Java command with the desired arguments. The following example startup command assumes osb-coherence-override.xml contains the proper configurations for host, port, and well-known addresses (unicast listener):

java
-classpath coherence.jar:C:/oracle/Oracle_OSB1/lib/osb-coherence-client.jar
-Dtangosol.coherence.override=C:/oracle/user_projects/domains/osb_domain/config/osb/coherence/osb-coherence-override.xml
-Dtangosol.coherence.cacheconfig=C:/oracle/user_projects/domains/osb_domain/config/osb/coherence/osb-coherence-cacheconfig.xml
-Dtangosol.coherence.cluster=OSB-cluster
com.tangosol.net.DefaultCacheServer

For more information on starting a Coherence cache server, see the Oracle Coherence documentation at https://download.oracle.com/docs/cd/E15357_01/index.htm.

36.7.5.5.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 modify cache type and behavior, and you can query cache. For more information, see:

• "Configure Oracle Coherence for the Oracle Service Bus Result Cache" in the Oracle Fusion Middleware High Availability Guide

• Oracle Coherence documentation at https://download.oracle.com/docs/cd/E15357_01/index.htm

36.8 Viewing Resource Details

Oracle Service Bus provides a resource servlet that is used to expose the resources registered in Oracle Service Bus through a URL. For more information, see Section 4.30, "Viewing Resources in a Web Browser."