Skip Headers

Oracle9i Application Server Web Services Developer's Guide
Release 2 (9.0.2)

Part Number A95453-01
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Go to previous page Go to next page

6
Building Clients that Use Web Services

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

This chapter contains the following topics:

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 8, "Discovering and Publishing Web Services" provides detailed information on looking up Web Services in a UDDI registry.

Using a static client Oracle9iAS Web Services provides several options for locating Oracle9iAS Web Services, including:

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.

See Also:

Chapter 8, "Discovering and Publishing Web Services"

Getting WSDL Descriptions and Client-Side Proxy Jar for Web Services

Oracle9iAS Web Services supplies client-side programmers with the following files for deployed Web Services:

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 6-1 for a description of the URL components):

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

or

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.

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:

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

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

or

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 6-1 for a description of the URL components):

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

or

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.

Getting Client-Side Proxy Jar and Client-Side Proxy Source with a Specified 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 6-1 for a description of the URL components):

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

or

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 6-1 for a description of the URL components):

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

or

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 serviceproxy_src.jar is a Jar file that contains the client-side source files for the client-side proxy that accesses the Web Service.

Table 6-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 Oracle9iAS 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 Oracle9iAS 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.

See Also:

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 on a system with Oracle9iAS. When building client-side applications to access and use services under Oracle9iAS Web Services, the Oracle9iAS Web Services client-side proxy Jar class allows you to easily build the application.

The client side proxy Jar file that you get from a Web Service contains a Java class to serve as a proxy to the Web Service implementation residing on the Oracle9iAS Web Services server. 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 6-1 shows a source code sample client-side proxy extracted from a Web Service. For each method 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 6-2 shows client-side application code that uses the helloWorld() method from the supplied client-side proxy shown in Example 6-1.

Example 6-1 Sample Client-side Proxy Method for Web Services

/**
 * Web service proxy: StatefulExample
 *     generated by Oracle WSDL toolkit (Version: 1.0). */
public class StatefulExampleProxy {


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

Example 6-2 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());
  }
}

Using Web Services Security Features

When you run a client-side application that uses Oracle9iAS Web Services, you can access secure Web Services by setting properties in the client application. Table 6-2 shows the available properties that provide credentials and other security information for Web Services clients.

In a Web Services client application, you can set the security properties shown in Table 6-2 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 6-2  Web Services HTTP Transport Security Properties
Property Description

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.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.proxyHost is defined; otherwise this value is ignored.

Default value: 80

http.proxyRealm

Specifies the realm for which the proxy authentication username/password is specified.

http.proxyUsername

Specifies the HTTP proxy authentication username.

http.realm

Specifies the realm for which the HTTP authentication username/password is specified.

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 Oracle9i 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:

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

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

Working with WSDL and JDeveloper to Use Web Services

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

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

JDeveloper supports Oracle9iAS Web Services with the following features:

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


Go to previous page Go to next page
Oracle
Copyright © 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index