Oracle® Web Services Manager Administrator's Guide 10g (10.1.3.4) Part Number E12575-01 |
|
|
View PDF |
This chapter includes the following sections:
Before you can create and edit policies for an Oracle Web Services Manager Gateway, you must first register the desired Web services. The following information provides general directions for registering Web services to a gateway.
You can register a service by specifying the Web Services Definition Language (WSDL) URL or by importing the service. Refer to "Adding a Service to an Oracle Web Services Manager Gateway", for information on registering a service by specifying the WSDL URL. For information on registering a service by importing it, refer to "Discovering Web Services".
If you import a Web service by specifying an external URL, you must set your HTTP proxy settings. For the standalone Oracle WSM installation, this is set in the OWSM_HOME/owsm/bin/coresv.properties file. If you installed Oracle WSM as part of the Oracle Application Server 10g Release 3 (10.1.3.1.0), also known as Oracle SOA Suite (10.1.3.1.0), set your proxy settings in the ORACLE_HOME/opmn/conf/ompn.xml file. See "Error When Importing WSIL" for more information.
Registering WSDLs from SSL-Enabled Sites
If you are importing WSDLs from sites enabled for Secure Sockets Layer (SSL), that is, the WSDL uses an HTTPS URL, then you must enable SSL when you start the Oracle Web Services Manager server. Add SSL system attributes to the oc4j.start target in the following file: ORACLE_HOME/owsm/scripts/oc4j.xml.
Accessing Virtualized Web Services
You can access a virtualized Web service either by using the service identifier (ID) or the Web service name. Therefore, either of the following URLs could be used to access the TimeService Web service whose service ID is SID0003006:
http://jdoe.us.oracle.com:3115/gateway/services/SID0003006?wsdl
http://jdoe.us.oracle.com:3115/gateway/services/TimeService?wsdl
The naming conventions for URLs apply.
To add a Web service to a gateway
Select Policy Management, then select Register Services from Web Services Manager Control.
Web Services Manager Control displays a list of the currently registered gateways.
Click Services for the gateway for which you want to register Web services.
Web Services Manager Control displays a list of the Web services currently registered to the gateway.
Click Add New Service.
Provide the details for the new service. Click Help to get information on the fields.
Click Next.
Web Services Manager Control displays the Configure Messenger Step for New Service page where you configure the Web service transport protocol (also known as the outgoing transport protocol) you selected. See "Oracle WSM Transport Protocols" for more information.
Configure the fields as required.
Click the question mark (?) for help on the protocol parameters. This information is also provided in "Configuring the Outgoing Transport Protocol".
Click Finish.
The Services confirmation message is displayed.
Click OK.
Once the service is added to the gateway, Commit Policy appears in red on the page listing currently registered gateways, prompting you to update the Policy Manager with new information.
To update changed policies on the gateway, click Commit.
After you have added a service to a gateway, you can edit the policy for the service. See Chapter 5, "Managing Oracle Web Services Manager Policies" for more information.
All Web services registered with an Oracle WSM Gateway are virtualized as both a SOAP and non-SOAP Web service. However, the service registration details page only displays the virtualized SOAP URL.
The non-SOAP virtualized URL can be determined from the virtualized SOAP URL by replacing the services
keyword in the URL with the xml
keyword.
For example, if the SOAP virtualized endpoint is:
http://host:port
/gateway/services/SID0003001
then, the non-SOAP XML service endpoint is:
http://host:port
/gateway/xml/SID0003001
When you register a Web service, Oracle WSM assigns a service ID for the Web service. Provide this service ID to any client that will be making requests to this Web service so that the service ID can be included in the message request. The service ID may be specified through one of the following options:
For Java Message Service (JMS) clients, use a JMS user header with the name serviceId
, and set the namespace to http://schemas.confluentsw.com
. Also, you must set the ResponseQueue
name in the JMS ReplyTo header so that the client can pick up the response message.
For MQ clients, specify the local-tag serviceID
in the SOAP header, and set the namespace to http://schemas.confluentsw.com
. Also, you must set the ResponseQueue
name in the MQ ReplyTo
header so that the client can pick up the response message.
Alternatively, you can use the Web service name instead of the service ID to identify the Web service in client requests. For example, both of the following URLs could be used to identify the TimeService Web service whose service ID is SID0003006:
http://jdoe.us.oracle.com:3115/gateway/services/SID0003006?wsdl
http://jdoe.us.oracle.com:3115/gateway/services/TimeService?wsdl
There are two places where transport protocols are used as shown in Figure 2-1. The first is between the client making the request and the Oracle WSM Gateway listening for requests. The protocol on which the gateway listens for client requests is called the incoming transport protocol. The second is between the Oracle WSM Gateway and the Web service. This is the transport protocol on which the Web service is invoked. Saying this another way, this is the transport protocol on which the gateway sends requests to the Web service. This is called the outgoing transport protocol.
Figure 2-1 Transport Protocols in Oracle WSM
The incoming and outgoing transport protocols are independent of one another. The incoming transport protocol and the outgoing transport protocols can be different, and if they are, then the gateway takes the client request and translates it to the outgoing transport protocol before passing the request to the Web service. For example, in Figure 2-1, a request coming in on JMS is translated to HTTP before the request is passed to the Web service. However, the request coming in on HTTP does not require translation because it matches the outgoing transport protocol.
The incoming and outgoing transport protocols are configured separately and through different properties files. The outgoing transport protocol is configured through Web Services Manager Control. This is described in the sections that follow.
When the Oracle WSM Gateway is created and registered, it is configured to accept requests on HTTP by default; this cannot be modified. Therefore, the gateway always accepts requests on HTTP. In addition the gateway can be configured to listen for requests on two other supported transport protocols: JMS and MQ. You must specifically configure your gateway to listen for requests for JMS and MQ if you expect to receive client requests on these protocols.
The Oracle WSM Gateway can be configured to listen to requests on JMS or MQ by manually configuring the following file:
ORACLE_HOME/owsm/config/gateway/gateway-config-installer.properties
Set the properties for one or both protocols, JMS and MQ, in this file. Then redeploy the gateway application for the settings to take effect. All services registered with the gateway will be available to requests coming in on the configured protocols as well as requests coming in on HTTP. See Oracle Web Services Manager Deployment Guide for more information on how to configure the incoming transport protocol.
You configure the outgoing transport protocol, that is, the transport protocol on which the Web service is invoked, at the time you register a service with the gateway. You specify one of the following protocols: HTTP, HTTPS, JMS, MQ, or a custom protocol.
If you specify a custom protocol, you must first create a custom policy step that implements the protocol for communicating with the Web service. Then, when you register the service, you specify this policy step in the Custom Protocol Step Template Id property. See Oracle Web Services Manager Extensibility Guide for more information on creating custom policy steps.
When more than one incoming transport protocol is configured for a gateway, then all registered Web services are exposed to all protocols. In this situation, you cannot configure your Web service to accept requests coming in only on a particular protocol. Because gateways always accept requests on HTTP, Web services are always exposed to requests on HTTP. In the example shown in Figure 2-1, the gateway is also configured to listen for client requests on JMS and MQ. Therefore, in Figure 2-1 the Web service must accept all requests coming in on the JMS and MQ protocols, in addition to HTTP.
See "Registering Web Services to an Oracle Web Services Manager Gateway" for more information on configuring the outgoing transport protocol.
When you register the Web service to the gateway and you specify the protocol used to invoke the Web service (outgoing transport protocol) as HTTP(S), you set the following properties for the protocol (Table 2-1). (See "To add a Web service to a gateway" to see the procedure where these properties are specified.)
Table 2-1 HTTP(S) Properties
Property | Description |
---|---|
Enabled |
Enables this step, if set to true. |
URL |
Endpoint URL of the Web service. |
ReplyTimeout |
Length of time, in milliseconds, that the gateway attempts to connect to the Web service before it times out. |
IsSoapService |
Specifies that the Web service supports SOAP messages, if set to true. If set to false, then the Web services accepts only XML messages. |
ForwardCredentials |
Specifies that HTTP Basic Credentials are forwarded, if set to true. |
Failover URLs |
Comma-delimited list of URLs to which the gateway tries to connect if the primary URL, specified with the URL property, cannot be reached in the number of attempts specified with the Attempts property. |
Attempts |
Number of times the gateway tries to invoke a service at a URL. |
RetryInterval |
Length of time, in seconds, between retry attempts. |
KeepAlive |
Specifies that the HTTP connection is reused, if set to true. |
The JMS request handler forwards the request to the designated Web service based on the service ID that is assigned to the JMS service when you register the service. The JMS service ID is a string that you specify in the JMS message header. The Oracle WSM Gateway reads the JMS properties specified when the service was registered and forwards the message to the specified server. Table 2-2 lists the JMS Messenger properties that get specified during registration.
When you register the Web service to the gateway and you specify the protocol to be used to invoke the Web service (outgoing transport protocol) as JMS Messenger, you set the following properties for the protocol to route service invocations to the intended JMS server. (Table 2-1). (See "To add a Web service to a gateway" to see the procedure where these properties are specified.)
Table 2-2 JMS Messenger Properties
Property | Description |
---|---|
Enabled |
Enables this step, if set to true. |
OneWay |
Specifies that the gateway sends a synchronous request to JMS and terminates the connection, if set to true. It does not care if there is a response. |
ReplyTimeout |
Length of time, in milliseconds, that the gateway attempts to connect to the Web service before it times out. |
IsSoapService |
Specifies that the Web service supports SOAP messages, if set to true. If set to false, then the Web services accepts only XML messages. |
JmsQueueName |
Name of the queue on which the Web service listens. |
JmsReplyToQueueName |
Name of the queue to which the Web Service sends the response. If the value is specified as Dynamic, the response is sent to a temporary queue. |
JmsIsPersistent |
Specifies that the message persists across JMS server restarts, if set to true. |
JmsCorrEnabled |
Specifies that the request and response are correlated, if set to true. |
UseJndi |
Specifies that Java Naming and Directory Interface (JNDI) lookups are performed, if set to true. |
JmsUrl |
URL used to connect to the JMS server. |
JmsConnectionFactory |
|
JmsUsername |
User name to be used for connections to the JMS server. |
JmsPassword |
Password to be used for connections to the JMS server. |
OwsmServiceID |
For internal use only. Do not edit this value. |
JndiProviderUrl |
JNDI provider URL for getting the JNDI context. |
JndiProviderFactory |
JNDI provider factory class used to get the JNDI context. You must specify the full path to the Java class. For example, |
JndiUrlPackagePrefix |
Prefix used to initialize the JNDI context. |
JndiUsername |
User name used to do the JNDI lookup. |
JndiPassword |
Password used to do the JNDI lookup. |
SslEnabled |
Specifies that the connection to the JMS server is through SSL, if set to true. |
SslVendor |
Vendor of SSL certificates. Valid values are: j2se (Java 2 Platform, Standard Edition) and entrust6 (Entrust for TIBCO JMS). |
SslHostname |
Host name of the JMS server SSL certificate. |
SslClientIdentity |
Full path to the client certificate. |
SslPassword |
Password to decrypt the identity file. |
SslTrustCerts |
Trust certificate of the JMS server or the path to the certificate file. |
When you register the Web service to the gateway and you specify the protocol used to invoke the Web service (outgoing transport protocol) as MQ Series, you set the following properties for the protocol to route service invocations to the appropriate MQ server (Table 2-1). (See "To add a Web service to a gateway" to see the procedure where these properties are specified.)
Table 2-3 MQ Series Properties
Property | Description |
---|---|
Enabled |
Enables this step, if set to true. |
MqServerHost |
Host name of the MQ server. |
MqServerPort |
Port on which the MQ server listens for Web service requests. |
MqUserId |
User ID to log in to the MQ server. |
MqPassword |
Password to log in to the MQ server. |
ChannelName |
Name of the channel to which to connect on the target queue manager. |
QueueManager |
Name of the queue manager on which the queue is defined. |
ReplyTimeout |
Length of time, in milliseconds, that the gateway attempts to connect to the Web service before it times out. |
IsSoapService |
Specifies that the Web service supports SOAP messages, if set to true. If set to false, then the Web services accepts only XML messages. |
MqReplyToQueueName |
Name of the queue to which the Web service sends the response. |
MqQueueName |
Name of the queue on which the Web Service listens for requests. |
MqCorrEnabled |
Specifies that the request and response are correlated, if set to true. |
MqCharacterSet |
Character set used to encode messages that are sent to the MQ server. |
If you change the transport protocol for a Web service, you must first deactivate the service, then register it with the new protocol. See "Deactivating a Web Service" for more information.
Oracle recommends that HTTPS be used to secure transmission of passwords between all communication points in the Oracle WSM environment. See "HTTP and HTTPS" for specific information on how to configure HTTPS for your Web services.
Oracle WSM supports JMS server failover for TIBCO only. There are two failover mechanisms:
Heartbeat Failover – The primary JMS server sends heartbeat messages to the backup server to verify that the backup server is operational. If a network failure prevents the servers from communicating with each other, the backup server detects the interruption in the stream of heartbeat messages, and it takes on the role of the primary server. The backup server uses the same domain name system (DNS) and Internet Protocol (IP) address as the primary server. JMS clients are unaware that there is a backup server, because both servers share the same URL. This type of failover requires hardware support, that is, network cards. No changes are required to the gateway to take advantage of a heartbeat failover. When you configure the transport protocol for the service, you specify a single URL for the JmsUrl
property.
Connection Failover – If the JMS client fails to connect to a primary server, then it tries to connect to one or more backup servers. When the Web service is registered to the gateway and the JMS protocol is configured, multiple URLs are specified for the JMS server. A comma-delimited list of URLs are specified for the JmsUrl
property. The gateway attempts to connect to the URLs in the order listed. If a connection to the first URL fails, then the gateway tries to connect using the next URL in the list, and continues through the list until it connects or all URLs have been tried. If a connection is not established after all URLs have been attempted, then the connection fails. See "Adding a Service to an Oracle Web Services Manager Gateway" and "JMS Messenger" for more information.