A Web Service Client APIs and JARs

This appendix contains high-level descriptions of the Web services client API packages. It also identifies the JAR files that are required to run a Web service client.

This appendix contains these sections:

Web Services API Packages
Setting the Classpath for a Web Service Proxy

Web Services API Packages

Table A-1 lists the public Oracle APIs available in the current release of Oracle Application Server Web Services. The provider package can be used only in the OC4J container. The other APIs can be used in the container or in a Web services client.

Package Name	Description
oracle.webservices	Contains the Oracle specific extension classes and interfaces that are common for all modules.
oracle.webservices.attachments	Contains classes and interfaces to support streaming attachments. For more information on using this package, see "Working with Message Attachments" in the Oracle Application Server Advanced Web Services Developer's Guide.
oracle.webservices.databinding	Contains the `SOAPElementSerializer` interface which you can use for custom serialization. For more information on using the functionality provided by the `databinding` package, see "Custom Serialization of Java Value Types" in the Oracle Application Server Advanced Web Services Developer's Guide.
oracle.webservices.management-portability	Web services platform portability layer.
oracle.webservices.provider	Contains the interfaces and classes needed to implement provider-based endpoints. For more information on using the `provider` package, see "Using Web Service Providers" in the Oracle Application Server Advanced Web Services Developer's Guide.
oracle.webservices.reliability	Contains the interfaces and classes needed to implement reliable SOAP message exchange using WS-Reliability. For more information see "Dynamically Configuring Client Side Reliability" in the Oracle Application Server Advanced Web Services Developer's Guide.
oracle.webservices.security.callback	Provides classes to support Web Services security call back.
oracle.webservices.soap	Contains the Oracle extension classes and interfaces to support SOAP 1.2. For more information on this API, see "Understanding the OraSAAJ APIs".
oracle.webservices.transport	Contains the classes and interfaces to support multiple transport bindings. "Writing Client Code to Support JMS Transport" in the Oracle Application Server Advanced Web Services Developer's Guide provides information on how classes in this package are used in JMS transport.
oracle.webservices.wsdl	Contains the Oracle specific interface to support SOAP 1.2 operations in WSDL 1.1. For more information on this interface, see Appendix B, "Oracle Implementation of the WSDL 1.1 API".

Setting the Classpath for a Web Service Proxy

When you build a Web service client, you must enter the correct classpath to run it. The following sections list the JAR files that can be included on the classpath. The tables in this section use the OC4J_HOME environment variable to specify the location where the Oracle Application Server or the standalone OC4J is installed.

Simplifying the Classpath with wsclient_extended.jar
Classpath Components for Clients using a Client-Side Proxy
WS-Security-Related Client JAR Files
Reliability-Related Client JAR File
JMS Transport-Related Client JAR File

Simplifying the Classpath with wsclient_extended.jar

To simplify your configuration of J2SE environments, OracleAS Web Services provides a wsclient_extended.jar file that contains all the classes necessary to compile and run a Web service client. This file can be listed on the classpath as an alternative to listing individual JARs.

The wsclient_extended.jar file contains these class files:

core Web service client class files in the individual JAR files listed in Table A-2
OC4J Security-related class files in the JARs listed in Table A-3
WS-Security-related class files in the JARs listed in Table A-4
WS-Reliability-related class files in the JARs listed in Table A-5
JMS transport-related class files in the JAR listed in Table A-6

You do not have to include any of these JAR files on the classpath if you run the client with the wsclient_extended.jar file.

The wsclient_extended.jar file is available as a separate download from the Oracle Technology network:

http://download.oracle.com/otn/java/oc4j/10131/wsclient_extended.zip

The file can also be installed from the OC4J companion CD. In this case, you will find it in the ORACLE_HOME/webservices/lib directory.

Classpath Components for Clients using a Client-Side Proxy

Table A-2 lists the JAR files that can be included in the classpath for a J2SE Web services client.

Note:

The wsclient.jar listed in this table contains only the core Web service client classes. At compilation and runtime, the Web service client requires many other classes such as those for the XML parser, the WSDL parser, and quality of service (QOS). All of these required classes are packaged into wsclient_extended.jar to simplify classpath set up.
Not all JAR files are required in all cases.

Table A-2 Classpath Components for a Client Using a Client-Side Proxy

Component JAR	Description
ORACLE_HOME/diagnostics/lib/ojdl.jar and ORACLE_HOME/diagnostics/lib/ojdl2.jar	ODL implements APIs to be used by Oracle products to emit error diagnostics and a LogLoader tool that collects error diagnostic logs for analysis.
ORACLE_HOME/j2ee/home/oc4j-api.jar	Contains the public OC4J APIs.
ORACLE_HOME/j2ee/home/oc4jclient.jar	Contains the files needed by the OC4J client.
ORACLE_HOME/j2ee/home/lib/activation.jar	Usually, this component is available in the JRE. If it is not, then include it in the classpath. This JAR is needed only for processing attachments.
ORACLE_HOME/j2ee/home/lib/adminclient.jar	Contains J2EE APIs for platform management and application deployment.
OC4J_HOME/j2ee/home/lib/ejb.jar	Contains class files for Enterprise Java Beans.
OC4J_HOME/j2ee/home/lib/http_client.jar	Contains the Oracle HTTP client transport implementation.
OC4J_HOME/j2ee/home/lib/javax77.jar	Contains the J2EE management specification (JSR 77) APIs.
OC4J_HOME/j2ee/home/lib/jax-qname-namespace.jar	Contains the QName definition.
OC4J_HOME/j2ee/home/lib/jmxri.xml	Contains the JMX APIs.
OC4J_HOME/j2ee/home/lib/jmx_remote_api.jar	Contains the JMX Remote APIs.
OC4J_HOME/j2ee/home/lib/mail.jar	Contains the JavaMail API and all service providers. Usually, this component is available in the JRE. If it is not, then include it in the classpath.
OC4J_HOME/j2ee/home/lib/oc4j-schemas.jar	Contains the OracleAS Web Services public schemas.
OC4J_HOME/j2ee/home/lib/servlet.jar	Contains the servlet implementation.
OC4J_HOME/lib/dms.jar	Contains the DMS implementation for Oracle Diagnostics and Monitoring.
OC4J_HOME/lib/xml.jar	Contains the JAXB implementation.
OC4J_HOME/lib/xmlparserv2.jar	Contains the Oracle XML parser JAR.
OC4J_HOME/lib/xsu12.jar	Contains the Oracle XDK SQL utility.
OC4J_HOME/webservices/lib/commons-logging.jar	Contains a logging library package.
OC4J_HOME/webservices/lib/jaxrpc-api.jar	Contains the JAX-RPC API, including `javax.xml.rpc` and `java.xml.namespace`.
OC4J_HOME/webservices/lib/orasaaj.jar	Contains the Oracle implementation of the SAAJ API.
OC4J_HOME/webservices/lib/orawsdl.jar	Contains the Oracle implementation (OraWSDL) of the Java APIs for the WSDL specification (JSR 110).
OC4J_HOME/webservices/lib/relaxngDatatype.jar	Contains the RELAX NG data type library shared by several JAX* technologies.
OC4J_HOME/webservices/lib/saaj-api.jar	Contains the SAAJ API 1.1 for processing messages with attachments.
OC4J_HOME/webservices/lib/wsclient.jar	Contains the classes that are required by the Web service client runtime.
OC4J_HOME/webservices/lib/wsdl-api.jar	Contains the Java APIs for WSDL (JSR 110).
OC4J_HOME/webservices/lib/wsif.jar	Contains the Oracle WSIF implementation.
OC4J_HOME/webservices/lib/xsdlib.jar	Contains the XML Schema type library shared by several JAX* technologies.

OC4J Security-Related Client JAR Files

Table A-3 lists the JAR files that must be included in the classpath when a J2SE Web service client supports OC4J Security. The wsclient_extended.jar file contains the OC4J Security-related class files in the JARs listed in this table. There is no need to include these JARs if you run the client with the wsclient_extended.jar file.

Table A-3 OC4J Security CLASSPATH Components for a Client Using a Client-Side Proxy

Component Name	Description
OC4J_HOME/j2ee/home/lib/jta.jar	Contains JTA (Java Transaction API) Specification APIs.
OC4J_HOME/j2ee/home/lib/jaas.jar	Contains the Java Authorization and Authentication Specification (JAAS) APIs.
OC4J_HOME/j2ee/home/lib/jazn.jar	Contains the JAZN (Oracle JAAS provider) implementation.
OC4J_HOME/j2ee/home/lib/jazncore.jar	Contains the JAZN (Oracle JAAS provider) implementation.

WS-Security-Related Client JAR Files

Table A-4 lists the JAR files that must be included in the classpath when a J2SE Web service client supports WS-Security. The wsclient_extended.jar file contains the WS-Security-related class files in the JARs listed in this table. There is no need to include these JARs if you run the client with the wsclient_extended.jar file.

Table A-4 WS-Security CLASSPATH Components for a Client Using a Client-Side Proxy

Component Name	Description
OC4J_HOME/jlib/javax-ssl-1_1.jar	Contains transport-level security support.
OC4J_HOME/jlib/jaxen.jar	Contains the classes that define Jaxen—a Java XPath Engine capable of evaluating XPath expressions across multiple modes (such as dom4j, JDOM, and so on).
OC4J_HOME/jlib/ojpse.jar	Contains the core encryption implementation.
OC4J_HOME/jlib/oraclepki.jar	Contains the Oracle orapki keytool utility.
OC4J_HOME/jlib/osdt_core.jar	Contains the Oracle Security Developer's Toolkit (OSDT) APIs.
OC4J_HOME/jlib/osdt_cert.jar	Contains the Oracle Security Developer's Toolkit cryptography APIs.
OC4J_HOME/jlib/osdt_saml.jar	Contains Oracle Security Developer's Toolkit Security Assertion Markup Language (SAML) APIs.
OC4J_HOME/jlib/osdt_wss.jar	Contains Oracle Security Developer's Toolkit Web services security (WS-Security) APIs.
OC4J_HOME/jlib/osdt_xmlsec.jar	Contains Oracle Security Developer's Toolkit XML signing and encryption APIs.
OC4J_HOME/webservices/lib/wssecurity.jar	Contains the WS-Security APIs.

Reliability-Related Client JAR File

Table A-5 lists the JAR files that must be included in the classpath when a J2SE Web service client supports WS-Reliability. The wsclient_extended.jar file contains the WS-Reliability-related class files in the JAR listed in this table. There is no need to include this JAR if you run the client with the wsclient_extended.jar file.

Table A-5 Reliability CLASSPATH Components for a Client Using a Client-Side Proxy

Component Name	Description
OC4J_HOME/webservices/lib/orawsrm.jar	Contains Web service Reliability (WS-Reliability) APIs and their implementation.

JMS Transport-Related Client JAR File

Table A-6 lists the JAR file that must be included in the classpath when a J2SE Web service client supports JMS as a transport mechanism. The wsclient_extended.jar file contains the JMS transport-related class files in the JAR listed in this table. There is no need to include this JAR if you run the client with the wsclient_extended.jar file.

Table A-6 CLASSPATH Components for a Client Using JMS as a Transport Mechanism

Component Name	Description
J2EE_HOME/j2ee/home/lib/jms.jar	Contains the JMS APIs.

Database Web Services-Related Client JAR Files

The JAR files listed in Table A-7 must be included in the classpath when a J2SE Web service client wants to invoke a service that uses parameters or returns in SQL/XML format, or are of type WebRowSet. The client must also include these libraries when invoking a database Web service using a native WSIF binding.

Note:

The class files in the JARs listed in this table are not included in the wsclient_extended.jar file. If the client needs the functionality provided by these files, then they must be listed explicitly on the classpath.

Table A-7 Database-Related CLASSPATH Components for a Client Using a Client-Side Proxy

Component Name	Description
ORACLE_HOME/rdbms/jlib/aqapi.jar	Contains the Oracle Advanced Queueing API
ORACLE_HOME/jdbc/lib/ocrs12.jar	Contains the Oracle WebRowSet implementation
ORACLE_HOME/jdbc/lib/ojdbc14dms.jar	Contains the Oracle JDBC driver
OC4J_HOME/lib/xsu12.jar	Contains the Oracle SQL/XML format implementation

Sample Classpath Commands

Example A-1 provides sample Windows platform set CLASSPATH commands for all of the Oracle Application Server Web Services client JAR files. The classpath on the UNIX platform would be set in a similar manner.

Example A-1 set CLASSPATH Commands for the Windows Platform

set CLASSPATH=%ORACLE_HOME%\j2ee\home\oc4jclient.jar;%CLASSPATH%
set CLASSPATH=%ORACLE_HOME%\j2ee\home\lib\adminclient.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\j2ee\home\lib\ejb.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\j2ee\home\lib\mail.jar;%CLASSPATH%
set CLASSPATH=%ORACLE_HOME%\j2ee\home\lib\activation.jar;%CLASSPATH%
set CLASSPATH=%J2EE_HOME%\j2ee\home\lib\jms.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\j2ee\home\lib\http_client.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\j2ee\home\lib\jaas.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\j2ee\home\lib\jazn.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\j2ee\home\lib\javax77.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\j2ee\home\lib\jax-qname-namespace.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\j2ee\home\lib\jta.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\j2ee\home\lib\jazncore.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\j2ee\home\lib\servlet.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\j2ee\home\lib\jmx_remote_api.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\j2ee\home\lib\jmxri.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\j2ee\home\lib\oc4j-schemas.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\lib\xmlparserv2.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\xdk\lib\xml.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\webservices\lib\orawsrm.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\webservices\lib\xsdlib.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\webservices\lib\relaxngDatatype.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\lib\dms.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\webservices\lib\commons-logging.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\webservices\lib\jaxrpc-api.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\webservices\lib\wsclient.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\webservices\lib\wsdl-api.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\webservices\lib\wsif.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\webservices\lib\wssecurity.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\webservices\lib\saaj-api.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\webservices\lib\orasaaj.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\webservices\lib\orawsdl.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\jlib\osdt_wss.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\jlib\osdt_xmlsec.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\jlib\ojpse.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\jlib\osdt_saml.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\jlib\oraclepki.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\jlib\osdt_core.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\jlib\osdt_cert.jar;%CLASSPATH% 
set CLASSPATH=%OC4J_HOME%\jlib\jaxen.jar;%CLASSPATH%
set CLASSPATH=%OC4J_HOME%\jlib\javax-ssl-1_1.jar;%CLASSPATH%