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:
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) and 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, 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 and can only be created using the Service Bus Overview Editor in JDeveloper.
Each proxy service is defined by whether it is based on a WSDL web service or a Service Bus transport. A WSDL-based service is a SOAP or XML proxy service whose interface is described by a WSDL document. 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 either a WSDL-based 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. This type of service can only be created in the Service Bus Overview Editor in JDeveloper, and is not an option on the Create Proxy Service wizard. 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
)
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.
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.
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.
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.
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 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 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 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.
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 Rules" in Administering Oracle Service Bus.
You can configure a proxy service to enforce WS-I compliance (for SOAP 1.1 services only) and select the selection algorithm to use 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. However, there are cases (for example, performance issues, signature/encryption issues, or the default algorithm is not applicable) when you may need to select the operation based on other means.
Service Bus provides additional algorithms. Each of them follows the same pattern and are based on the evaluation of an expression to get a value that is then used to lookup the corresponding operation in a static table.
Service Bus is generally 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 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.
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 will not be able to 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 you are in an active session and the project to which you want to add the proxy service exists.
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:
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.
To generate a proxy service from a JCA binding in JDeveloper:
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:
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:
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 you are in an active session before performing any of the tasks in this section.
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
To configure general information for a proxy service:
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
To configure a proxy service transport:
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
To configure message handling 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.
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.
Deleting a proxy service deletes all of the ACLs referenced by the proxy from the repository controlled by Service Bus, as well as from the appropriate authorization provider. You can delete the proxy service even if it is referenced by other resources, though this might result in conflicts due to unresolved references to the deleted 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 References icon in the upper right 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:
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.
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:
In JDeveloper, open or create a SOA application.
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:
Enter a name for the connection.
See Naming Guidelines for Service Bus Components for naming guidance.
Enter the credentials for one of the following Service Bus roles: Administrator, Deployer, Operator, or Monitor.
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.
Click Test Connection to verify the connection is valid.
Click OK. The WSIL connection appears in the Resources window in the hierarchy determined by the URL you entered.
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.