8 Building Clients that Use Web Services

This chapter describes the Oracle Application Server Web Services features that allow you to easily create and run a client application that uses Oracle Application Server Web Services.

This chapter contains the following topics:

Locating Web Services
Getting WSDL Files and Client-Side Proxy Jars for Web Services
Working with Client-Side Proxy Jar to Use Web Services
Working with WSDL Files and Oracle JDeveloper to Use Web Services

8.1 Locating Web Services

When you want to use Web Services you need to develop a client application. There are two types of Web Services clients: static web service clients and dynamic web service clients. A static web service client knows where a Web Service is located without looking up the service in a UDDI registry. A dynamic web service client performs a lookup to find the Web Service's location in a UDDI registry before accessing the service. Chapter 10, "Discovering and Publishing Web Services" provides detailed information on looking up Web Services in a UDDI registry.

Using a static client Oracle Application Server Web Services provides several options for locating Oracle Application Server Web Services, including:

Using a known Web Service located at a known URL.
Using Oracle Application Server Web Services and a known service URL to obtain a client-side proxy Jar, or by other means obtaining a client-side proxy Jar for a Web Service. The client-side proxy Jar that Oracle Application Server Web Services generates includes the URL to locate the associated Web Service.
Using Oracle Application Server Web Services and a known service URL to obtain a WSDL file, or by other means obtaining a WSDL file that describes a Web Service. The WSDL files that Oracle Application Server Web Services generates includes the URL to locate the associated Web Service.

After you locate a Web Service or after you obtain either the WSDL or client-side proxy Jar, you can build a client-side application that uses the Web Service.

8.2 Getting WSDL Files and Client-Side Proxy Jars for Web Services

This section covers the following:

Using the Web Service Home Page to Save WSDL and Client Side Proxies
Getting Web Service WSDL and Client-Side Proxies Directly
Generating Client-Side Proxies With WebServicesAssembler

8.2.1 Using the Web Service Home Page to Save WSDL and Client Side Proxies

To use Oracle Application Server Web Services you need to create a client-side application that accesses a Web Service. Oracle Application Server Web Services supplies the following files for deployed Web Services:

WSDL service descriptions
Client-side proxy Jar (class files)
Client-side proxy source

Oracle Application Server Web Services provides a Web Service Home Page for each deployed Web Service. To access a Home Page, enter a service endpoint of the form,

http://host:port/context-root/service

Figure 8-1 shows the Web Service Home Page for StatefulExample, at the following endpoint,

http://system1.us.oracle.com/webservices/statefulTest

A Web Service Home Page provides the following:

A Link to the WSDL file - To obtain the WSDL file for a Web Service, select the Service Description link and save the file.
Links to Web Service Test Pages for each supported operation-To test the available Web Service operations enter the parameter values for the operation, if any, and select the Invoke button.
Links to the Web Service client-side proxy Jar and the client-side proxy source - To obtain the client-side proxy Jar or the client-side proxy source, select the appropriate link, Proxy Jar or Proxy Source, and save the file.

Figure 8-1 Web Service Home Page

Web Service Home Page for StatefulExample demo.

Description of the illustration aswsvendpoint.gif

8.2.1.1 Limitations for Web Service Test Pages

Web Service Test Pages have the following limitations:

There is no support for complex input parameters for RPC style Web Services. Such pages do not support the Invoke button.
There is no support for Document Style Web Services. Such pages do not support the Invoke button.

8.2.2 Getting Web Service WSDL and Client-Side Proxies Directly

If you do not use the Web Service Home Page to get the WSDL file or client-side proxy for a Web Service, you can obtain these files directly.

This section covers the following:

Getting WSDL Service Descriptions
Getting Client-Side Proxy Jar and Client-Side Proxy Source Jar
Getting Client-Side Proxy Jar and Client-Side Proxy Source by Package

8.2.2.1 Getting WSDL Service Descriptions

To obtain the WSDL service description for a Web Service, use the Web Service URL and append a query string. The format for the URL to obtain the WSDL service description is as follows (see Table 8-1 for a description of the URL components):

http://host:port/context-root/service?WSDL

http://host:port/context-root/service?wsdl

This command returns a WSDL description in the form service.wsdl. The service.wsdl description contains the WSDL for the Web Service named service, located at the specified URL. Using the WSDL that you obtain, you can build a client application to access the Web Service.

8.2.2.2 Getting Client-Side Proxy Jar and Client-Side Proxy Source Jar

To obtain the client-side proxy Jar for a Web Service, use the Web Service URL and append a query string. The client-side proxy Jar file contains the proxy stubs class that supports building an application that communicates using SOAP to access the Web Service. The proxy class does the following:

Provides a static location for the Web Service (the service does not need to be looked up in a UDDI registry).
Provides proxy methods for each method exposed as part of the Web Service.
Performs all of the work to construct the SOAP request, including marshalling and unmarshalling parameters, and handling the response.

The format for the URL to obtain the client-side proxy Jar is as follows (see Table 8-1 for a description of the URL components):

http://host:port/context-root/service?PROXY_JAR

http://host:port/context-root/service?proxy_jar

This command returns the file service_proxy.jar. The service_proxy.jar is a Jar file that contains the client-side proxy classes that you can use to build a client-side application to access the Web Service.

To obtain the client-side proxy source Jar for a Web Service, use the Web Service URL and append a query string. The format for the URL to obtain the client-side proxy source Jar is as follows (see Table 8-1 for a description of the URL components):

http://host:port/context-root/service?PROXY_SOURCE

http://host:port/context-root/service?proxy_source

This command returns the file service_proxysrc.jar. The file service_proxysrc.jar is a Jar file that contains the client-side proxy source files. This file represents the source code for the file service_proxy.jar associated with the service.

8.2.2.3 Getting Client-Side Proxy Jar and Client-Side Proxy Source by Package

When you obtain the client-side proxy Jar file or the client-side proxy source Jar, you have the option of including a request parameter that specifies a package name for the generated client-side proxy classes or source files. If the Web Service's client-side Java class is part of a particular package, then you should specify the package name to match the client-side application's package name.

The format for the URL to obtain the client-side proxy Jar and specify the package name is as follows (see Table 8-1 for a description of the URL components):

http://host:port/context-root/service?PROXY_JAR&packageName=mypackage

http://host:port/context-root/service?proxy_jar&packageName=mypackage

This command returns the file service_proxy.jar. The service_proxy.jar is a Jar file that contains the client-side proxy classes, using the specified package, mypackage for the Java package statement.

The format for the URL to obtain the client-side proxy source Jar and specify the package name is as follows (see Table 8-1 for a description of the URL components):

http://host:port/context-root/service?PROXY_SOURCE&packageName=mypackage

http://host:port/context-root/service?proxy_source&packageName=mypackage

This command returns the file service_proxysrc.jar. As for the proxy_jar, you have the option of specifying a request parameter with a supplied package name by include a packageName=name option. The service_proxysrc.jar is a Jar file that contains the client-side source files for the client-side proxy that accesses the Web Service.

Table 8-1 URL for Accessing Client Side Proxy Stubs

URL Component	Description
context-root	The context-root is the value specified in the `<context-root>` tag for the web module associated with the Web Service. See the `META-INF/application.xml` in the Web Service's .ear file to determine this value.
host	This is the host of the Web Service's server running Oracle Application Server Web Services.
mypackage	This specifies the value that you want to use for the package name in the generated proxy Jar or proxy source.
port	This is the port of the Web Service's server running Oracle Application Server Web Services.
service	The service is the value specified in the `<url-pattern>` tag for the servlet associated with the Web Service. This is the service name. See the `WEB-INF/web.xml` in the Web Service's .war file to determine this value.

8.2.3 Generating Client-Side Proxies With WebServicesAssembler

The Oracle Application Server Web Services WebServicesAssembler tool allows you to generate client-side proxies. A client-side proxy can access a Web Service that is deployed either on an Oracle Application Server Web Services endpoint or on a third party Web Service endpoint.

To generate a client-side proxy with WebServicesAssembler, specify a <proxy-gen> tag in the configuration file. Table 8-2 describes the <proxy-gen> WebServicesAssembler configuration file sub-tags.

Note:

When you are generating client-side proxies and you are accessing an external WSDL file from behind a firewall, make sure to set the appropriate security properties shown in Table 8-4, such as http.proxyHost and http.proxyPort.

Example 8-1 shows a sample WebServicesAssembler that includes a <proxy-gen> tag.

Example 8-1 WebServicesAssembler Proxy Gen Configuration File

<?xml version="1.0"?>
<web-service>
  <proxy-gen>
    <proxy-dir>/TestArea/Hotel/proxy/outside</proxy-dir>
    <option name="include-source">true</option> 
    <option name="wsdl-location" package-name="myPackage.proxy">
          http://terraservice.net/TerraService.asmx?WSDL</option>
    <option name="wsdl-location">
        http://ws.serviceobjects.net/sq/FastQuote.asmx?WSDL</option>
  </proxy-gen>
</web-service>

Table 8-2 Proxy Generation <proxy-gen> Sub-Tags

Tag Description

Tag	Description
`<proxy-dir>` directory`</proxy-dir>`	Specifies the directory for the generated client-side proxy stubs Jar file that is included in the generated Web Service `.ear` file. This tag is required.
`<option name="include-source">` value`</option>`	Setting value to `true` tells `WebServicesAssembler` to include the classes and the source in the generated client-side proxy. When the value is false, the source is not included in the generated Jar. This tag is optional. Valid values: `true`, `false` Default value: `false`
`<option name="wsdl-location">` URL`</option>` or `<option name="wsdl-location" package-name="`package`">` URL`</option>`	This tag sets the URL to use for the source WSDL to use to generate the client-side proxy. This option also supports the optional attribute `package-name`. The `package-name` can specify the name package for the generated client-side proxy. This tag is optional. Examples: `<option name="wsdl-location">` `http://system1:8888/webservice3/TestService?WSDL` `</option>` `<option name="wsdl-location" package-name="myPackage.proxy">` `http://system1:8888/webservice3/TestService?WSDL` `</option>`

<proxy-dir> directory</proxy-dir>

Specifies the directory for the generated client-side proxy stubs Jar file that is included in the generated Web Service .ear file.

This tag is required.

<option name="include-source"> value</option>

Setting value to true tells WebServicesAssembler to include the classes and the source in the generated client-side proxy. When the value is false, the source is not included in the generated Jar.

This tag is optional.

Valid values: true, false

Default value: false

<option name="wsdl-location"> URL</option>

<option name="wsdl-location" package-name="package"> URL</option>

This tag sets the URL to use for the source WSDL to use to generate the client-side proxy.

This option also supports the optional attribute package-name. The package-name can specify the name package for the generated client-side proxy.

This tag is optional.

Examples:

<option name="wsdl-location"> http://system1:8888/webservice3/TestService?WSDL </option>

<option name="wsdl-location" package-name="myPackage.proxy"> http://system1:8888/webservice3/TestService?WSDL </option>

8.3 Working with Client-Side Proxy Jar to Use Web Services

This section describes how to use the client-side proxy Jar when you are building the client-side application to access a Web Service. The client-side proxy Jar class allows you to easily build an application that uses a Web Service.

The client side proxy Jar file contains a Java class to serve as a proxy to the Web Service implementation. The client-side proxy code constructs a SOAP request and marshalls and unmarshalls parameters for you. Using the proxy classes saves you the work of creating SOAP requests for accessing a Web Service or processing Web Service responses.

Example 8-2 shows a source code sample client-side proxy extracted from a Web Service. For each operation available on the Web Service, there is a corresponding method in the proxy class. The example shows the method helloWorld(String) that serves as a proxy to the helloWorld(String) method in the associated Web Service implementation.

Example 8-3 shows client-side application code that uses the helloWorld() method from the supplied client-side proxy shown in Example 8-2.

Note:

When you are accessing an external Web Service from behind a firewall, make sure to set the appropriate security properties shown in Table 8-4, such as http.proxyHost and http.proxyPort.

Example 8-2 Sample Client-side Proxy Method for Web Services

public class StatefulExampleProxy {

   public java.lang.String helloWorld(java.lang.String param0) throws Exception
   {
   .
   .
   .
   }
.
.
.
}

Example 8-3 Sample Client-side Application Using a Proxy Class for Web Services

import oracle.j2ee.ws_example.proxy.*;

public class Client
{
  public static void main(String[] argv) throws Exception
  {
    StatefulExampleProxy proxy = new StatefulExampleProxy();
    System.out.println(proxy.helloWorld("Scott"));
    System.out.println(proxy.count());
    System.out.println(proxy.count());
    System.out.println(proxy.count());
  }
}

8.3.1 Setting the Web Services Proxy Client CLASSPATH

When you build a Web Services clients using a proxy, you need to use the correct CLASSPATH to run the client. Table 8-3 lists jars that you need to include in the CLASSPATH.

Table 8-3 Web Services CLASSPATH Components for a Client Using a Client-side Proxy

Component Jar	Description
proxy.`jar`	The proxy jar file that provides access to the Web Service.
`$ORACLE_HOME/lib/xmlparserv2.jar`	The Oracle XML parser jar.
`$ORACLE_HOME/j2ee/home/lib/http_client.jar`	The Oracle HTTP client jar.
`$ORACLE_HOME/soap/lib/soap.jar`	The Oracle SOAP jar.
`$ORACLE_HOME/j2ee/home/lib/mail.jar`	Generally, this is available in the JRE. If this is not available in the JRE, then include it in the CLASSPATH.
`$ORACLE_HOME/j2ee/home/lib/activation.jar`	Generally, this is available in the JRE. If this is not available in the JRE, then include it in the CLASSPATH
`$ORACLE_HOME/jlib/javax-ssl-1_1.jar`	Used when the client uses SSL to connect to a Web Service that uses SSL. In this case, do not include `$ORACLE_HOME/lib/jsee.jar` in the `CLASSPATH`.
`$ORACLE_HOME/jlib/jssl-1_1.jar`	Required when the client is using SSL to connect to a Web Service that uses SSL. In this case, either `$ORACLE_HOME/jlib/javax-ssl-1_1.jar` or `$ORACLE_HOME/lib/jsse.jar` must be specified.
`$ORACLE_HOME/lib/jsse.jar`	Used when the client uses SSL to connect to a Web Service that uses SSL. In this case, do not include `$ORACLE_HOME/jlib/javax-ssl-1_1.jar` in the `CLASSPATH.`
`$ORACLE_HOME/webservices/lib/wsdl.jar`	Required when the client is using a Dynamic Proxy.
`$ORACLE_HOME/webservices/lib/dsv2.jar`	Required when the client is using a Dynamic Proxy.

8.3.2 Using Java Beans as Parameters for Web Services

When Java Beans are used as parameters to Oracle Application Server Web Services, the client-side code should use the generated Bean included with the downloaded client-side proxy. This is because the generated client-side proxy code translates SOAP structures to and from Java Beans by translating SOAP structure namespaces to and from fully qualified Bean class names. If a Bean with the specified name does not exist in the specified package, the generated client code will fail.

However, there is no special requirement for clients using Web Services Description Language (WSDL) to form calls to Oracle Application Server Web Services, rather than the client-side proxy. The generated WSDL document describes SOAP structures in a standard way. Application development environments, such as Oracle JDeveloper, which work directly from WSDL documents can correctly call Oracle Application Server Web Services with Java Beans as parameters.

8.3.3 Using Web Services Security Features

When you run a client-side application that uses Oracle Application Server Web Services, you can access secure Web Services by setting properties in the client application. Table 8-4 shows the available properties that provide credentials and other security information for Web Services clients. Table 8-3 lists jar file that need to be included in the CLASSPATH, including those required to support SSL.

In a Web Services client application, you can set the security properties shown in Table 8-4 as system properties by using the -D flag at the Java command line, or you can also set security properties in the Java program by adding these properties to the system properties (use System.setProperties() to add properties). In addition, the client side stubs include the _setTranportProperties method that is a public method in the client proxy stubs. This method enables you to set the appropriate values for security properties by supplying a Properties argument.

Table 8-4 Web Services HTTP Transport Security Properties

Property	Description
`http.authRealm`	Specifies the realm for which the HTTP authentication username/password is specified. This property is mandatory when using basic authentication.
`http.authType`	Specifies the HTTP authentication type. The case of the value specified is ignored. Valid values: `basic`, `digest` The value basic specifies HTTP basic authentication. Specifying any value other than `basic` or `digest` is the same as not setting the property.
`http.password`	Specifies the HTTP authentication password.
`http.proxyAuthRealm`	Specifies the realm for which the proxy authentication username/password is specified.
`http.proxyAuthType`	Specifies the proxy authentication type. The case of the value specified is ignored. Valid values: `basic`, `digest` Specifying any value other than `basic` or `digest` is the same as not setting the property.
`http.proxyHost`	Specifies the hostname or IP address of the proxy host.
`http.proxyPassword`	Specifies the HTTP proxy authentication password.
`http.proxyPort`	Specifies the proxy port. The specified value must be an integer. This property is only used when `http.proxyHos`t is defined; otherwise this value is ignored. Default value: `80`
`http.proxyUsername`	Specifies the HTTP proxy authentication username.
`http.username`	Specifies the HTTP authentication username.
`java.protocol.handler.pkgs`	Specifies a list of package prefixes for `java.net.URLStreamHandlerFactory` The prefixes should be separated by "\|" vertical bar characters. This value should contain: `HTTPClient` This value is required by the Java protocol handler framework; it is not defined by Oracle Application Server. This property must be set when using HTTPS. If this property is not set using HTTPS, a `java.net.MalformedURLException` is thrown. Note: This property must be set as a system property. For example, set this property as shown in either of the following: `java.protocol.handler.pkgs=HTTPClient` `java.protocol.handler.pkgs=sun.net.www.protocol\|HTTPClient`
`oracle.soap.transport. allowUserInteraction`	Specifies the allows user interaction parameter. The case of the value specified is ignored. When this property is set to `true` and either of the following are true, the user is prompted for a username and password: If any of properties `http.authType,` `http.username`, or `http.password` is not set, and a `401` HTTP status is returned by the HTTP server. If either of properties `http.proxyAuthType`, `http.proxyUsername`, or `http.proxyPassword` is not set and a `407` HTTP response is returned by the HTTP proxy. Valid values: `true`, `false` Specifying any value other than `true` is considered as `false`.
`oracle.ssl.ciphers`	Specifies a list of`:` separated cipher suites that are enabled. Default value: The list of all cipher suites supported with Oracle SSL.
`oracle.wallet.location`	Specifies the location of an exported Oracle wallet or exported trustpoints. Note: The value used is not a URL but a file location, for example: `/etc/ORACLE/Wallets/system1/exported_wallet` (on UNIX) `d:\oracle\system1\exported_wallet` (on Windows) This property must be set when HTTPS is used with SSL authentication, server or mutual, as the transport.
`oracle.wallet.password`	Specifies the password of an exported wallet. Setting this property is required when HTTPS is used with client, mutual authentication as the transport.

8.4 Working with WSDL Files and Oracle JDeveloper to Use Web Services

The Web Services WSDL allows you to manually, or using Oracle JDeveloper or another IDE, build client applications that use Web Services.

The Oracle JDeveloper IDE supports Oracle Application Server Web Services with WSDL features and provides unparalleled productivity for building end-to-end J2EE and integrated Web Services applications.

Oracle JDeveloper supports Oracle Application Server Web Services with the following features:

Allows developers to create Java stubs from Web Services WSDL descriptions to programmatically use existing Web Services.
Allows developers to create a new Web Service from Java or EJB classes, automatically producing the required deployment descriptor, web.xml, and WSDL file for you.
Provides schema-driven WSDL file editing.
Offers significant J2EE deployment support for Web Services J2EE .ear files, with automatic deployment to OC4J.

Non-Oracle Web Services IDEs or client development tools can use the supplied WSDL file to generate Web Services requests for services running under Oracle Application Server Web Services. Currently, many IDEs have the capability to create SOAP requests, given a WSDL description for the service.