Skip Headers
Oracle® Web Services Manager Administrator's Guide
10g (10.1.3.4)

Part Number E12575-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

2 Registering Web Services to an Oracle Web Services Manager Gateway

This chapter includes the following sections:

Registering Web Services to an Oracle Web Services Manager Gateway

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

Proxy Settings

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:

The naming conventions for URLs apply.

Adding a Service to an Oracle Web Services Manager Gateway

To add a Web service to a gateway

  1. Select Policy Management, then select Register Services from Web Services Manager Control.

    Web Services Manager Control displays a list of the currently registered gateways.

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

  3. Click Add New Service.

  4. Provide the details for the new service. Click Help to get information on the fields.

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

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

  7. Click Finish.

    The Services confirmation message is displayed.

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

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

Accessing a SOAP-Based Web Service as a Non-SOAP XML-Based Web Service

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

Using the Web Service ID in Client Requests

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:

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:

Oracle WSM Transport Protocols

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

Description of Figure 2-1 follows
Description of "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.

Configuring the Incoming Transport Protocol

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.

Configuring the Outgoing 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.

HTTP and HTTPS

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.


JMS Messenger

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

ConnectionFactory class name or JNDI name for opening JMS server connections.

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, com.tibco.tibjms.TibjmsQueueConnectionFactory.

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.


MQ Series

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.


Changing the Protocol for a Web Service

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.

Using HTTPS to Secure Connections

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.

JMS Server Failover

Oracle WSM supports JMS server failover for TIBCO only. There are two failover mechanisms: