8 Creating and Configuring Proxy Services

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

This chapter includes the following sections:

• Introduction to Proxy Services

• Securing Proxy Services

• Service Level Agreement Alert Rules

• Web Services Interoperability Compliance

• Creating Proxy Services

• Configuring Proxy Services

• Deleting Proxy Services

• Consuming Proxy Services in JDeveloper with WSIL

8.1 Introduction to Proxy Services

Proxy services provide the interface that service consumers use to connect with back-end services through Service Bus. They are definitions of intermediary web services that Service Bus hosts locally.

Service Bus uses proxy services to route messages between business services, such as enterprise web services and databases. It also uses proxy services for messages between service clients, such as presentation applications or other business services.

Proxy services define the interfaces in terms of Web Services Description Language (WSDL) or Web Application Definition Language (WADL) and the type of transport used. A proxy service defines the communication interface, the type of transport, transport settings, security settings, and the associated message processing logic. It then uses a message flow definition, or pipeline, to transform and route messages to one or more business services. The pipeline defines the logic that determines how messages are handled as they flow through Service Bus. If a proxy service is based on a WSDL document, the configuration also includes a WSDL port or a WSDL binding.

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

8.1.1 Proxy Service Definitions

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.

8.1.2 Service Types and Protocols for 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 .

8.1.3 When to Use 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.

8.1.4 When to Use the Messaging Service Type

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.

8.1.5 Binding Definitions and Runtime Variables for Proxy Service Types

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)

8.1.5.1 WSDL Service Type

Runtime Variables

• For SOAP-based WSDL services, the variables are similar to Any SOAP service types except $operation is initialized based on the operation selection algorithm.

• For XML-based WSDL services, the variables are similar to Any XML service types except the $operation is initialized based on the operation selection algorithm.

8.1.5.2 Messaging Service Type

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. The response could also be set to None.

By definition, messaging-based services do not have a 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.

• Email, File, FTP, and SFTP transport proxy services with a messaging service type support one-way messaging only, so there is no response message. The content type for the response message should be None.

Runtime Variables

This service type is message-based. There is no concept of multiple operations as there is 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 proxy services, $body uses the SOAP 1.1 namespace Body; for SOAP 1.2 proxy services, 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 Message-Related Variables and Constructing Messages to Dispatch.

8.1.5.3 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. The binding configuration for this type is empty, so 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. By 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.

Runtime 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 because you do not define a port type.

To learn more about the message context variables, see Message-Related Variables and Constructing Messages to Dispatch.

8.1.5.4 Any XML Service

Binding Definition

The only information this service type defines is that the service is receiving or sending XML messages, regardless of their WSDL binding definition. The binding configuration for this type is empty, so 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 a WSDL definition. It is not possible to request a WSDL document for those services.

Runtime 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 because you do not define a port type.

To learn more about the message context variables, see Message-Related Variables and Constructing Messages to Dispatch.

8.1.6 Proxy Service Transport Protocol Configuration

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.

8.2 Securing Proxy Services

You can secure proxy services through multiple methods, including Oracle Web Services Manager (WSM) policies, authentication mappings, and service key providers.

A service provider is required if the proxy service routes messages to HTTPS services that require client certificate authentication, and could 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 user name and password pair. WebLogic Server can be used to directly manage security credentials for a business service requiring credential-level validation.

For more information about securing proxy services, see Securing Business and Proxy Services.

8.3 Service Level Agreement Alert Rules

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

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

8.4 Web Services Interoperability Compliance

You can configure a proxy service to enforce WS-I compliance (for SOAP 1.1 services only) and select the selection algorithm to determine the operation called by this proxy service. This option is only available for SOAP or XML services defined from a WSDL file.

The WSDL specification defines a default algorithm to compute which operation is called based on the type of the SOAP message received. There are cases when you might need to select the operation based on other means. For example, there could be performance or signature/encryption issues, or the default algorithm is not applicable.

Service Bus provides additional algorithms. Each follows the same pattern and is based on the evaluation of an expression to get a value that is then used to look up the corresponding operation in a static table.

Service Bus is very forgiving if an inbound message is either missing data such that the operation cannot be determined or has data that does not correspond to a valid operation. Both of these conditions result in $operation being empty. Rather than reject all such messages, Service Bus does not initialize the operation variable in the context but otherwise continues to process the message. However, security requirements are enforced if the proxy service is WSDL-based and at least one of the following conditions is true:

• The WSDL file has a WS-Security policy and the proxy is an active intermediary.

• The proxy has message-level custom authentication (either custom token or user name/password).

If these conditions are met, then there is a runtime check to make sure that the operation selection algorithm returns a valid operation name. If the operation selection returns null or an operation that is not in the WSDL file, then the message is rejected and an error is raised.

8.5 Creating Proxy Services

This section describes how to create proxy services using JDeveloper or the Oracle Service Bus Console.

For information about creating Service Bus applications and projects, see Creating Service Bus Applications and Projects in JDeveloper or, for the console, Create New Projects and Folders for Resources. For information about working with projects, applications, and other components in JDeveloper, see the User's Guide for Oracle JDeveloper.

You can use various methods to create a proxy service, including the Create Proxy Service wizard, the Service Bus Overview Editor, generating it from an existing service or JCA resource, and exposing a pipeline as a proxy service when you create the pipeline. When you create a proxy service, the Create Proxy Service wizard provides a series of pages where you can configure certain proxy service properties. This section describes how to use the Create Proxy Service wizard to create proxy services. For information on using the Service Bus Overview Editor, see Developing Oracle Service Bus Applications in JDeveloper.

Before You Begin

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

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

8.5.1 How to Create a Proxy Service

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

• For information about proxy service types, see Proxy Service Definitions

• For information about WSDL files, see Working with WSDL Documents.

• For information about the different transports you can use, see Working with JCA Adapters, Transports, and Bindings.

To create a proxy service, complete one of the following tasks, depending on whether you want to use the Service Bus Console or JDeveloper to create the service:

• How to Create a Proxy Service Using the Service Bus Console

• How to Create a Typed REST Proxy Service Using the Service Bus Console

• How to Create a Proxy Service Using JDevleoper

8.5.2 How to Create a Proxy Service Using the Service Bus Console

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

To create a proxy service:

Note:

The procedure for creating a Typed REST Service from the Wizard (with a WADL) differs from the process for creating other proxy services. See How to Create a Typed REST Proxy Service Using the Service Bus Console for the procedure for creating services of this type with the wizard.

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.

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

After you create the service:

• Configure the proxy service, as described in Configuring Proxy Services.

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

8.5.3 How to Create a Typed REST Proxy Service Using the Service Bus Console

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.

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

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

1. In the Project Navigator, right-click the project or folder in which you want to create the service, point to Create, and then select Resource.
   The Resource Gallery is displayed.
2. In the Resource Gallery, click 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 GUID-888B5AD0-E223-4B5C-BAD3-712ECCC5A5FC-default.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, or Opaque.

      • 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, or Opaque. 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, or Opaque. 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.

The Proxy Service Definition editor is displayed.

After you create the service:

• Configure the proxy service, as described in Configuring Proxy Services.

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

8.5.4 How to Create a Proxy Service Using JDevleoper

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

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

To create a proxy service:

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.

8.5.5 How to Generate a Proxy Service from a JCA Binding Resource

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.

Before You Begin:

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

Note:

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

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

8.5.5.1 Generating a Proxy Service from a JCA Binding in JDeveloper

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

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

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

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

   See Naming Guidelines for Service Bus Components for naming guidance.

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.

   The Type page appears.

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

   The Transport page appears.

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

   Service Bus generates the proxy service and the concrete WSDL file used by the proxy service.

7. Configure the proxy service, as described in Configuring Proxy Services.

8.5.5.2 Generating a Proxy Service from a JCA Binding in the Console

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

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

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

   The Generate WSDL and Service dialog appears.

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

   See Naming Guidelines for Service Bus Components for naming guidance.

3. Click Generate.

   Service Bus generates the service and its corresponding WSDL file.

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

8.5.6 How to Generate a Proxy Service from an Existing Service in JDeveloper

In JDeveloper, you can generate proxy services from other proxy services, business services, pipelines, and split-joins. The configuration of the proxy service is based on that of the existing service.

To generate a proxy service from another service in JDeveloper:

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.

8.5.7 How to Generate a Proxy Service from a WSDL Document in JDeveloper

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

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

1. In the Application Navigator, right-click the existing WSDL document, point to Service Bus, and then select Generate 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.

8.6 Configuring Proxy Services

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

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

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

8.6.1 How to Configure General Information for a Proxy Service

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.

8.6.2 How to Configure a Proxy Service Transport

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.

8.6.3 How to Configure Proxy Service Message Handling

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.

8.6.4 How to Configure Security for a Proxy Service

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.

8.6.5 How to Configure Service Level Agreement Alerts for a Proxy Service

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.

8.7 Deleting Proxy Services

Deleting a proxy service deletes all the ACLs referenced by the proxy from the repository controlled by Service Bus, as well as from the appropriate authorization provider.

If other resources reference the proxy service, you can still delete it. However, this could result in conflicts due to unresolved references to the deleted service.

8.7.1 How to Delete a Proxy Service

Before deleting a proxy service, check for any dependencies. In the Oracle Service Bus Console, open the proxy service in the Proxy Service Definition Editor and click the Tools icon in the upper right, and then select References to find out whether any services are using it. In JDeveloper, right-click the proxy service and select Explore Dependencies.

To delete a proxy service:

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.

8.8 Consuming Proxy Services in JDeveloper with WSIL

Service Bus makes its WSDL-based proxy services available through the Web Services Inspection Language (WSIL), letting you consume Service Bus WSDL proxy services in JDeveloper for service orchestration in Oracle SOA Suite.

The Service Bus WSIL servlet automatically registers WSDL-based proxy services deployed in the Service Bus runtime environment. By creating a WSIL connection in JDeveloper, you can access those proxy services through different URL patterns that map to different hierarchy levels, such as project, folder, and individual service. For example, when you connect to the Service Bus WSIL servlet with a project-level URL, you can see all the child folders and WSDL-based proxy services in that project in JDeveloper.

8.8.1 How to Consume Service Bus Proxy Services in JDeveloper with WSIL

The following procedure guides you through the process of creating a WSIL connection in JDeveloper and generating web service references out of Service Bus WSDL proxy services for use in SOA applications.

To consume proxy services in JDeveloper with WSIL:

1. In JDeveloper, open or create a SOA application.

2. Create a new WSIL connection.

   In the Resources window, click the Add icon, select IDE Connections, and select WSIL.

   On the Create WSIL Connection dialog, do the following:

   1. Enter a name for the connection.

      See Naming Guidelines for Service Bus Components for naming guidance.

   2. Enter the credentials for one of the following Service Bus roles: Administrator, Deployer, Operator, or Monitor.

   3. Enter the URL to the Service Bus WSIL in one of the following formats:

      • Domain (gets all projects, folders, and WSDL-based proxy services):

        http://host:port/sbinspection.wsil
        

      • Project (gets all child folders and WSDL-based proxy services):

        http://host:port/sbinspection.wsil?refpath=project_name
        

      • Folder (in a project, gets the folder, all child folders, and WSDL-based proxy services):

        http://host:port/sbinspection.wsil?refpath=project_name/folder_path
        

        For example:

        http://localhost:7021/sbinspection.wsil?refpath=MortgageBroker/ProxyServices
        

      • Proxy Service (gets an individual WSDL-based proxy service):

        http://host:port/sbinspection.wsil?refpath=project_name/folder_path/wsdl_proxy_service
        

        For example:

        http://localhost:7021/sbinspection.wsil?refpath=MortgageBroker/ProxyServices/loanGateway1
        

      In a cluster, the WSIL servlet is deployed on Managed Servers and not the Admin Server. Use a Managed Server host name and port in the URL.

   4. Click Test Connection to verify the connection is valid.

   5. Click OK. The WSIL connection appears in the Resources window in the hierarchy determined by the URL you entered.

3. To use a Service Bus WSDL-based proxy service in your SOA application, create a web service reference to it.

   • In the Components window, create a new web service. In the Create Web Service window, click the WSDL URL browse icon.

   • In the SOA Resource Browser, select Resources, and select the Service Bus proxy service in the WSIL connection created in the previous step.

   When you create the web service reference to a Service Bus WSDL-based proxy service, you can use it as an external reference in your SOA application.

The Service Bus WSIL servlet leverages the SBResource servlet. If the SBResource is undeployed, the WSIL connection is not available.