This chapter provides an overview of the WS transport and describes how to use and configure it in your services. The WS transport makes Web Services Reliable Messaging (WSRM) available in Service Bus.
This chapter includes the following sections:
The WS transport implements both inbound and outbound requests for services derived from SOAP 1.1 and SOAP 1.2 based WSDL documents with Web Services Reliable Messaging (WSRM) policy.
However, the WSRM policy can be a part of the WSDL file or can be attached to the service. In addition, security policies can also be declared in the WSDL file or can be associated with a WSDL-based service. When you configure WSDL-based services with WSRM policies in Service Bus, you must choose the WS transport for the service. Service Bus checks for the WSRM policy when you save the service configuration and throws a validation error if WSRM policies are not declared for the WSDL file associated with the service.
The Web Services Reliable Messaging is also known as WS-Reliable Messaging or just WSRM. The specification describes a protocol that allows messages to be delivered reliably between distributed applications even if a software, system, or network failure occurs. WS-ReliableMessaging is a specification co-developed by IBM, Oracle, Microsoft and TIBCO Systems. This specification is not the same as WS-Reliability (WSR), which is a competing specification developed by OASIS.
Service Bus supports the specification submitted in February 2005. For more information about the specification, see Web Services Reliable Messaging Protocol (WS-ReliableMessaging) at http://schemas.xmlsoap.org/ws/2005/02/rm/.
Below are the key features of the WS transport:
One-way and request/response message patterns. For more information, see Messaging Patterns.
Exactly-once transfer between WS transport and other transports (JMS, SB, and Tuxedo transports) that support XA transactions.
HTTPS with basic authentication, and with client certificate authentication (two-way SSL) but without client authentication,. For more information, see Authentication and Authorization of Services .
Retaining WSRM security configuration while importing resources. For more information, see Importing and Exporting Resources.
Assignment of transport-level access control policy to a WS proxy service. Only an administrator can assign this policy. For more information, see How To Configure Transport-Level Access Policies.
WS-Addressing specification submitted in August 2004. For more information, see Web Services Addressing (WS-Addressing) at http://www.w3.org/Submission/ws-addressing/.
WS-I Basic Profile compliance. For more information, see Web Services Interoperability.
Quality of Service (QoS) in Service Bus for WS proxy service is always set to Exactly Once. For more information, see Quality of Service.
You can set the QoS in the RM policy file using the <beapolicy:QOS> element. This element has one attribute, QOS, which can take any of the following values:
AtMostOnce
AtLeastOnce
ExactlyOnce
InOrder
Note:
QoS for the WS transport is different from QoS for Service Bus.
You can associate only SOAP 1.1 and SOAP 1.2 based WSDL files with WSRM policy with a proxy or business service. For more information, see Configuring Proxy Services to Use the WS Transport and Configuring Business Services to Use the WS Transport .
WSRM supports both one-way and request/response messaging patterns. The WS transport does not support reliable response. While the request is always reliable, the response is not sent reliably.
For business services, sending a request to an external web service is asynchronous. Successful invocation implies that the message is given to the RM layer successfully and it will be delivered reliably. However, successful invocation does not mean that the message is sent to the endpoint and has successfully invoked the web service.
For the request/response messaging pattern, the response is received from the external web service for a request. In this case, the request and response paths have two different transactions and run in two different threads. The response pipeline is executed evenly for one-way messaging message pattern. For the one-way pattern, response pipeline invocation means that the message reliably reached the target destination and the web service invocation is complete.
A proxy service or business service that uses the WS transport must have a WS-Policy with RM assertions. This also implies that services that use any other transport must not have any WS-Policy with RM assertions. WS-Policy with RM assertions and WSSP v1.2 transport-level security assertions are supported for the WS transport.
However, WSSP v1.2 message-level security assertions and 9.X Oracle proprietary security assertions are not supported. RM assertions should only be bound at the service level and not at the operation or operation request/response levels.
Note:
You must use only one RM assertion for a WS-Policy.
WS-Policies can be configured in any one of the following two ways:
WS-Policy configuration is specified as part of the WSDL file associated with the service. The policies specified in the WSDL file may be included in the WSDL file or referred in the WSDL file.
WS-Policy is assigned to the service when configuring the service.
Note:
You can use only one of these methods to associate a security policy with the service. If you configure a policy directly in the Service Bus service, any policies defined in the WSDL file are ignored.
The WS transport does not have streaming support for large messages because the underlying infrastructure (WLS JAX-RPC stack) uses a fully materialized payload. However, when you configure a proxy service for large message processing, the message is fully materialized into a Java object by the WS transport using the streaming optimization in Service Bus. During the proxy service configuration, you can specify if you want to stream content for large message processing by buffering content either in memory or to disk. For more information, see Streaming Body Content.
The WS transport supports web services interoperability through WS-I Basic Profile. Currently, Service Bus proxy services do not follow all the WS-I Basic Profile restrictions. However, any services configured to use this transport strictly follow the WS-I Basic Profile specification. WS proxy services do not have a WS-I Compliance check in the service configuration and always follow WS-I Basic Profile. This is valid for SOAP1.1 WSDL bindings as WS-I Basic Profile applies only to SOAP 1.1.
This section provides information about how WS proxy and business services are authenticated and authorized.
WS proxy services support both basic and client certificate (two-way SSL) authentication. When basic authentication is specified in the WS-Policy, all HTTP requests, including RM protocol messages to the WS proxy service must have a valid user name and password.
Proxy service authentication is supported as follows:
Outbound client certificate authentication using SSL key-pair assigned to the service key provider referenced by the proxy service.
User name and password identity propagation through a WS proxy service (with basic authentication) to any other outbound transport, or outbound WSS user name token.
Credential mapping between WS proxy service (with basic or two-way SSL authentication) and any other transport.
Sending asynchronous responses from WS proxy service to a RM client through HTTP or HTTPS. The default protocol used by proxy and business services is HTTP.
Asynchronous responses from a WS proxy service to an RM client connect to the AcksTo or ReplyTo endpoint references specified by the RM client. The RM client can use either HTTP or HTTPS URL. If the RM client uses HTTPS, the RM client can request a client certificate during the SSL handshake. The WS transport uses the SSL key-pair of the service key provider upon request.
Administrators can assign a transport-level access control policy to a WS proxy service. As with all transports, this policy is enforced after the inbound transport provider passes the request message to the Service Bus binding layer before invoking the request pipeline. For more information, see How To Configure Transport-Level Access Policies.
WS business services support basic authentication and client certificate authentication. Outbound basic authentication is supported by means of a service account. User name and password identity propagation and credential mapping are provided by the service account. However, a static account can also be used for authentication. The service account can be static, pass-through, or mapped. Pass-through authentication allows passing a user name and password from the client request to the back-end RM service. Mapped service accounts allow credential mapping. Static service accounts are used when fixed credentials are required.
WS business services also support SSL client certificate authentication (two-way SSL). The key-pair (private key and certificate) used for outbound two-way SSL is not configured on the WS business service, but on the service key provider referenced by the proxy service.
Routing a single message to a WS business service may involve multiple HTTP/S requests from the Service Bus server and back-end service. All such messages are subject to the authentication method configured in the WS business service. In other words, if the service is configured for basic authentication, all messages sent from Service Bus include the HTTP Authorization header with the user name and password, and, if the message is configured for client certificate authentication, Service Bus uses the key-pair to authenticate all messages.
The WS transport reliably delivers messages in a distributed network.
The WSRM functionality is available as a transport only for SOAP 1.1 and SOAP 1.2 based WSDL files with WSRM policy. Ensure that the services are associated with a SOAP 1.l or 1.2 WSDL files with RM-policy or that an RM-policy is attached to the services. You can configure the WS-Policy in a WSDL file or assign it to a service. For more information, see Configuring WS Policies.
Prior to configuring proxy and business services to use the WS transport, ensure that the required WSDL files are available in your Service Bus domain. For more information, see Importing the WSDL Document into the Oracle Service Bus Console, Configuring Proxy Services to Use the WS Transport, and Configuring Business Services to Use the WS Transport .
You can optionally configure an error queue for services so Service Bus delivers failed messages into the queue. This can be a distributed queue. This queue is not created automatically, so you must create it prior to configuring the services. For more information, see Configuring an Error Queue.
In order to create a service based on a WSDL file with WSRM policies in the Oracle Service Bus Console, you need to import the WSDL file or create the WSDL resource and the content of the file in an editor. For more information, see Working with WSDL Documents in the Oracle Service Bus Console and Importing and Exporting Resources and Configurations .
The WS transport can be used only with SOAP WSDL files that have a WSRM policy. You can configure a WS-Policy in a WSDL file or assign a WS-Policy to a service in the JDeveloper or the Oracle Service Bus Console. For more information, see WS-Policies in the WS Transport.
When no RM police assertions are specified for the WSDL file associated with a service, a validation message appears when you activate the session. To resolve this conflict, you need to update the WSDL file or attach the policy to the service. For more information, see Attaching WS Policies to a Service and Securing Oracle Service Bus Proxy and Business Services with WS-Policy.
You can attach policies to a proxy or business service on the service's definition editor in either JDeveloper or the Oracle Service Bus Console. When you attach a WS-Policy to a service, any policies defined in the WSDL file associated with the service are ignored. For information about attaching policies, see Securing Business and Proxy Services.
By default, undelivered messages are discarded after the specified number of retries. To save these messages, you can configure error queues for business services. Service Bus delivers any messages that fail in the pipeline into these queues. For errors, you must configure a JMS queue. Oracle recommends that you configure a error queue locally instead of a remote queue.
For business services, when a response timeout occurs, the response pipeline is invoked with an error. If the sequence expiration interval is reached, the message is placed in an error queue configured for the business service and the response pipeline is invoked with an error. However, if the response timeout has already occurred, the message is placed in the error queue, but the response pipeline is not invoked.
Note:
For both one-way and request-response services, putting failed messages in the error queue is only a best effort.
When an HTTP proxy server is configured, WS business services send outbound messages using the HTTP proxy server. For information about specifying the HTTP proxy server details in your client application, see "Using a Proxy Server When Invoking a Web Service" in "Invoking Web Services" in Developing JAX-RPC Web Services for Oracle WebLogic Server.
You can configure WS transport-based business services to handle application errors by specifying whether or not to retry business service endpoint URIs when application errors occur. An application error occurs when a WS-based business service receives a SOAP fault as a response and the BEA-380001 or OSB-380001 error code is generated.
When a response timeout or sequence timeout occurs for a request to a business service, the Service Bus server tries to send the message to the next URI based on the load balancing algorithm. This behavior does not depend on the Retry Application Errors option.
When a resource exists in a Service Bus domain, you can preserve the security and policy configuration details while importing that resource to Service Bus by selecting the Preserve Security and Policy Configuration option. When you select this option, the values in the existing resource are preserved when you import them, even if the security and policy configurations have been updated in the resource.
For information about importing resources, see Importing and Exporting Resources and Configurations .
When a proxy service is published to an UDDI registry, the service is converted into WS business service with the WSDL file. If present, the authentication configuration is also exported to UDDI.
When a WSDL-based business service with WSRM policy is imported from an UDDI registry to Service Bus, the service is imported as a WS business service that is automatically configured to use the WS transport. For more information, see WS-Policies in the WS Transport.
For more information, see Working with UDDI Registries..
This section describes the endpoint URL format and configuration options for the WS transport.
Endpoint configuration for a proxy service that uses the WS transport is similar to that of HTTP proxy service configuration. Specify the URI in the following format making sure that the context path is unique for proxy services that use either HTTP or the WS transport.
/contextPath
Endpoint configuration for a business service using the WS transport is also similar to that for HTTP. Specify the URI in one of the following formats:
http://host:port number/name https://host:port number/name
Business services using the WS transport must be associated with WS-Policy with RM assertions. For more information, see WS-Policies in the WS Transport. A business service acts as a client for invoking an external reliable web service. It sends a request to the service and the response is received by an application deployed by Service Bus, which invokes the response path.
The following table describes the properties you use to configure a WS-based business service. For more information, see Creating and Configuring Business Services.
Table 38-1 WS Transport Properties for Business Services
| Property | Description |
|---|---|
|
Response Timeout |
Enter the number of seconds to wait for a response before timing out. Leaving this field blank indicates that there is no response timeout. The business service will wait for the duration of the sequence timeout configured in the RM policy. If the response does not come in the defined interval after sending a request, response pipeline is invoked with an error saying that service is timed out. If you enter a zero ( |
|
Service Account |
Specify the service account that defines the credentials to use when there is an HTTP basic authentication policy on this service. For more information, see Working with Service Accounts. Note: This is only applicable if the WS business service has a WS-Policy that requires basic authentication |
|
Queue Error Messages |
Select this check box to enable sending error messages to the configured error queue. |
|
Error Queue URI |
Enter the URI of JMS queue for storing error messages using the following format: jms://host:port/connFactoryJndiName/queueJndiName This option is available only when the Queue Error Messages check box is selected. Note: While WebLogic Server allows forward slashes in JNDI names, such as "myqueues/myqueue", JNDI names with forward slashes interfere with the URI format required by Service Bus, and you cannot use those names. To work around this issue, define a JMS foreign server and reference that foreign server in the URI. For more information, see Configure Foreign Servers in the Oracle WebLogic Server Administration Console Online Help. |
|
JMS Error Queue Service Account |
Specify the service account that defines the credentials to use for JNDI lookups and sending error messages to the error queue. This option is available only when the Queue Error Messages check box is selected. For more information, see "Working with Service Accounts" in Developing Services with Oracle Service Bus. |
|
Use SSL for Error Queue |
Select the check box to use SSL for connecting to the error queue. This option is available only when the Queue Error Messages check box is selected. |
|
Send Error Message as Binary |
Select this option to send error messages as binary messages instead of |
For more information about configuring business services using the WS transport, the online help provided with Service Bus.
Proxy services using the WS transport must be associated with WS-Policy with RM assertions. For more information, see WS-Policies in the WS Transport.
A proxy service receives the requests from clients and passes it to the pipeline after the processing related to WSRM is done. The proxy service could also send the response back to the client after receiving it from the response pipeline. A proxy service using the WS transport can be invoked from any other proxy service and it follows the same behavior as when it is invoked by an external client. When an HTTP proxy server is configured, WS proxy services send asynchronous messages using the HTTP proxy server.
Proxy services based on WSDL with SOAP 1.2 binding support SOAP 1.2 messages only and throw a fault with version mismatch error for SOAP 1.1 messages. Similarly, proxy services based on WSDL with SOAP 1.1 binding support SOAP 1.1 messages only and throw a fault with version mismatch error for SOAP 1.2 messages.
The following table describes the properties you use to configure a WS-based proxy service. For more information, see Creating and Configuring Proxy Services.
Table 38-2 WS Transport Properties for Proxy Services
| Property | Description |
|---|---|
|
Dispatch Policy |
Select the instance of WebLogic Server Work Manager that you want to use for the dispatch policy for this endpoint. The default Work Manager is used if no other Work Manager exists. For information about Work Managers, see:
|
|
Retry Count |
Specify the number of times the WSRM layer tries to deliver a message to the Service Bus message flow. The default is 3. If an unhandled exception occurs in the request flow of a proxy, the incoming WS Transport message is redelivered to the message flow up to the number of times specified by this value. This is important for reliably processing the WS transport messages. Note: When the message delivery fails, the current transaction is rolled back, but the message is not removed from the queue. The server tries to send the message until the message is successfully delivered or the retry limit is reached. When the retry limit is reached, that message is removed from the queue or moved to an error queue. The error queue can be a distributed queue and can be created from the Oracle WebLogic Server Administration Console. For more information, see Configuring an Error Queue. |
|
Retry Delay |
Specify the duration in seconds that the server should wait before retrying to deliver the message. The default is 5 seconds. |
For more information about configuring proxy services using the WS transport, see the online help provided with Service Bus.