Each proxy service is defined by whether it is based on a WSDL web service, a REST service, or a Service Bus transport. A WSDL-based service is a SOAP or XML proxy service whose interface is described by a WSDL document. A REST service is defined in one of two ways: a Typed REST service is based on a WADL document if some information (operations) is known at design time, and an Untyped REST service is not bound to a specific WADL document or schema (operations may not be known at design time). A transport-typed service is a proxy service based on a Service Bus transport, including the JCA transport, which provides support for configuring proxy services for Oracle JCA-compliant adapters. It also includes REST proxy services, which use the HTTP transport. Each type of proxy 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 Proxy Service wizard or the Service Bus Overview Editor in JDeveloper to create proxy services with a WSDL-based, REST, or transport-typed service. Using the Service Bus Overview Editor, you can also generate proxy services directly from a JCA adapter to create a proxy service already configured for that adapter type. Both the wizard and the editor let you expose business services and pipelines as proxy 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 proxy service, you also need to further define the service by specifying and configuring the service type. The service types you can select are restricted based on the transport used to communicate with the service endpoint. For information about the transports supported with each service type, see Transports, Adapters, and Bindings.

A proxy 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 proxy 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 proxy service configuration allows. In messages that include attachments, their content is a MIME package that includes the primary XML payload as one of its parts (typically the first part or the one identified by the top-level content-type header).

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

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.

If one of the request or response messages is non-XML, you must use the messaging service type. 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 in the pipeline. For more information on the validate action, see Adding Validate Actions in the Console. For more information on conditional XQuery expressions, see Working With Expression Editors in Oracle Service Bus Console.

No matter its definition or type, each proxy service type is modeled following the same pattern. Each service type must define these characteristics:

• Binding definition

• Runtime configuration

• Runtime variables ($operation, $body, $header, $attachments)

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

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

You create proxy services in the Service Bus Console using the Create Proxy Service wizard, which is accessed from the Resource Gallery.

1. In the Project Navigator, right-click the project or folder in which you want to create the service, point to Create, and then select Resource.
   The Resource Gallery is displayed.
2. In the Resource Gallery, click Proxy Service, and then navigate to the type of service you want to create. Select it and click OK.
3. Enter a name for the service and, optionally, a description.

   Note:

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

4. Depending on the type of service you selected in step 2, you might have to configure one of the following options:

   • If generating a proxy service configuration from an existing WSDL file, from the WSDL option, 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.

   • If generating a REST proxy service, optionally click the Choose WADL Resource icon in the WADL Name field to display the Search and Select: WADL Resource dialog. Use this dialog to search for and select a WADL resource from which to generate this service. This creates a native typed REST service. Leave the WADL Name field empty to create a native untyped REST service.

   • If generating a proxy service by configuring its transport, from the Transport option, confirm that the correct transport is selected in the Protocol list. If you want to create a service with a different transport type, select it from the Protocol list.

5. Enter a new name for the pipeline generated for the proxy service (optional). If you do not want to generate a pipeline, clear the Generate Pipeline check box.

   Note:

   This option is disabled for the JEJB transport.

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

7. If creating a WSDL-based or REST-based service, skip to step 10.
8. If you chose a Transport definition on the first page, select one of the available service types:

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

   • REST: (Optional) Click the Choose WADL Resource icon in the WADL Name field to display the Search and Select: WADL Resource dialog. Use this dialog to search for and select a WADL resource from which to generate this service. This creates a native typed REST service. Leave the WADL Name field empty to create a native untyped REST service.

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

   • Any XML: This option requires no additional configuration.

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

9. Click Next.

   The Transport page appears.

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

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

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

   Note:

   Each service must have at least one resource.

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

      Tip:

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

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

      Note:

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

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

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

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

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

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

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

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

   5. On the Response tab, configure the response for this method:

      • For the success payload, select None to display no payload, or select Media, and then select media types in which the payload can be displayed: XML, JSON, URL-Encoded, Text, Opaque or Other. If you choose Other, enter the name for the custom media type. Enter an HTTP status code to be sent on success into the Success Status field.

      • For the failure payload, select None to display no payload, or select Media, and then select media types in which the payload can be displayed: XML, JSON, URL-Encoded, Text, Opaque or Other. If you choose Other, enter the name for the custom media type. Enter an HTTP status code to be sent on failure into the Failure Status field.

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

You create proxy services based on WSDL files, based on transports, and native untyped REST services using the Create Proxy Service wizard.

1. In the Application Navigator, right-click the project, point to New, and then select Proxy Service.

   The Create Proxy Service wizard appears.

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

   Note:

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

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

3. Do one of the following:

   • To generate a native untyped REST service, select REST.

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

   • To generate the proxy 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. Enter a new name for the pipeline generated for the proxy service (optional). If you do not want to generate a pipeline, clear the Generate Pipeline check box.

   Note:

   This option is disabled for the JEJB transport.

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

6. If you chose WSDL or REST definition on the first page, skip to step 9.
7. If you chose a Transport definition on the first page, select one of the following service types:

   • REST: This option requires no additional configuration.

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

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

   • Any XML: This option requires no additional configuration.

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

8. Click Next.

   The Transport page appears.

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

    The Proxy Service Definition Editor displays the general configuration of the new proxy service.

12. Configure the proxy service, as described in Configuring Proxy Services.
13. After you create a proxy service, you need to configure the message flow in a pipeline or split-join. To learn more, see Working with Pipelines in Oracle Service Bus Console and Improving Service Performance with Split-Join.

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

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

   The Create Proxy 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 proxy service, as described in Configuring Proxy Services.

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

   The Create Proxy Service wizard appears.

2. Configure the name, description, file location, and WSDL binding for the service.
3. To generate a corresponding pipeline for the proxy service, leave Generate Pipeline selected and specify a name for the pipeline (or accept the default name). Clear the Generate Pipeline check box if you do not want to create the pipeline at this time.
4. Click Next.
5. 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.
6. Click Finish.
7. Configure the proxy service, as described in Configuring Proxy Services.

The General tab of the Proxy Service Definition Editor displays information about the service such as a description of the service, the transport used by the service, the service type, any WSDL ports or bindings, the XQuery version, and the service invoked by the proxy service. The following figure shows the General tab in the Oracle Service Bus Console.

Figure 8-1 Proxy Service General Configuration Page in the Console

Description of "Figure 8-1 Proxy Service General Configuration Page in the Console"

To configure general information for a proxy service:

1. In the Project or Application Navigator, right-click the proxy 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. To change the target service for the proxy service, click Choose a Service Resource next to the Target Service name. In JDeveloper, browse to and select a new target service. In the console, search for and select a new target resource.
6. To change the XQuery version used, select a new option from the XQuery Processing list.
7. If you are working in the Oracle Service Bus Console, select Auto Publish to Registry if you want the proxy service to automatically be published to the default UDDI registry,

   In order to automatically publish proxy services, you must define a default UDDI server. For more information, see Keeping Services Synchronized.

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

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

Figure 8-2 Proxy Service Transport Configuration Page in the Console

Description of "Figure 8-2 Proxy Service Transport Configuration Page in the Console"

To configure a proxy service transport:

1. In the Project or Application Navigator, right-click the proxy service to edit, and click Open.
2. Click the Transport tab, and do any of the following:

   • Update the endpoint URI.

   • To retrieve all headers, select Get All Headers.

   • To retrieve a subset of headers, select Get Specified Headers, and specify the headers to retrieve in the Headers table. Click Add above the table to add headers.

3. Click the Transport Detail tab.

   The properties you can configure here are based on the transport for the proxy service. For information about specific transports, see Working with JCA Adapters, Transports, and Bindings. The following figure shows the HTTP transport properties in the console.

   Figure 8-3 Proxy Service Transport Details Page in the Console

   
   Description of "Figure 8-3 Proxy Service Transport Details Page in the Console"
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.

On the Message Handling page, you can configure how the proxy service processes message contents, including 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 8-4 Proxy Service Message Handling Page in the Console

Description of "Figure 8-4 Proxy Service Message Handling Page in the Console"

To configure message handling for a proxy service:

1. In the Project or Application Navigator, right-click the proxy service to edit, and click Open.
2. Click the Message Handling tab.
3. To check messages for WS-I compliance, select the check box for Enforce WS-I Compliance.
4. Select one of the following selection algorithms:

   • Transport Header: Lets you define the transport header that contains the lookup value. If you select this option, you must also specify a header name and the operational values in the new fields that appear.

   • SOAP Action Header: Specifies that operation mapping be done automatically from the WSDL file associated with this proxy service.

   • WS-Addressing: Specifies that the lookup value is contained by the WS-Addressing Action tag located in the SOAP headers of the SOAP message. If you select this option, you must also specify the operational values in the new fields that appear.

   • SOAP Header: Lets you define an XPath expression to be evaluated against the SOAP headers. This allows you to get the lookup value. If you select this option, you must also define an XPath expression and value in the new fields that appear.

   • SOAP Body Type: Uses the default algorithm defined by the WSDL specification to compute which operation is called based on the type of the SOAP message received.

   • Payload Type: This option is only available for XML services based on a WSDL port or WSDL binding.

   For more information about these algorithms, see the online help provided for this page.

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.

You can secure proxy services through multiple methods, including Oracle Web Services Manager (OWSM) policies and access control at the transport and message levels. For more information about securing proxy services, see Securing Proxy Services and Securing Business and Proxy Services.

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

1. In the Project or Application Navigator, right-click the proxy service to delete, and select Delete.

   A confirmation dialog appears.

2. In JDeveloper, if other resources reference this proxy 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 proxy 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.