Oracle® Application Server Web Services Developer's Guide 10g (10.1.3.5.0) Part Number E13982-01 |
|
|
View PDF |
The README.txt
file that is included at the top level of the OC4J distribution provides instructions for setting up and running OC4J. This chapter serves as an addendum to the README
. It provides information that is specific to setting up Oracle Application Server Web Services in your environment.
This chapter provides the following sections.
OracleAS Web Services is supported on the following platforms.
Redhat Linux
Solaris Sparc 32- and 64-bit
Microsoft Windows: Windows XP, Windows 2000, Windows Server 2003
Follow the instructions in the README.txt
file for installing and running OC4J. The README.txt
file can be found at the top-level of the OC4J distribution.
This section lists the software you must install and environment variables you must define to use OracleAS Web Services.
Java2 Standard Edition (J2SE) JDK version 1.4.1 or later
Java2 Standard Edition (J2SE) JDK version 5.0 or later, if you are using the JDK 5.0 Web Service Annotations feature
Jakarta Ant 1.5.x or 1.6.5 (recommended) is required if you will be using Ant tasks to assemble Web services. Jakarta Ant 1.6.5 is included in the OracleAS Web Services distribution.
If you want to have your own installation, you can obtain Ant from the following Web address.
If you are using your own installation of Ant, see "How to Set Up Ant for WebServicesAssembler" for instructions on setting up Ant to assemble Web services.
If you installed the version of Ant that is distributed with Oracle Application Server, then Ant tasks for OracleAS Web Services will already be configured. Follow the instructions under "How to Set Up Ant 1.6.5 Distributed with Oracle Application Server" to appropriately modify your environment and build files.
Define the following environment variables:
ORACLE_HOME
—define this variable to point to the OC4J installation directory.
JAVA_HOME
—define this variable to point to the J2SE SDK installation directory. OracleAS Web Services expects JAVA_HOME
/bin/java
to point to the Java VM and JAVA_HOME
/bin/javac
to point to the Java compiler executables.
Add the following files or paths to the classpath:
To make assembly of Web services and the processing of XML files more convenient, add the paths to the WebServicesAssembler JAR, ORACLE_HOME
/webservices/lib/wsa.jar
, and the XML parser JAR, ORACLE_HOME
/lib/xmlparserv2.jar
, to the classpath.
If you want to assemble and compile your Web Services programs using Ant, appropriate CLASSPATH
settings can be found in the Ant scripts accompanying the Web Services example code. If you want to invoke the WebServicesAssembler and compile generated code on the command line, you may want to add the full complement of libraries to your CLASSPATH
.
See "Sample Classpath Commands" for a sample Windows platform set CLASSPATH
command for all of the OracleAS Web Services client JAR files. The classpath on the UNIX platform would be set in a similar manner.
OracleAS Web Services provides a separate library, wsclient_extended.jar
, for running Web services clients in a J2SE environment. This library includes everything that would be required by OracleAS Web Services clients in a J2SE environment and should simplify the packaging and distribution of your J2SE client applications. You can find the wsclient_extended.jar
file at the following address on the Oracle Technology Network Web site.
http://download.oracle.com/otn/java/oc4j/10131/wsclient_extended.zip
If you installed the OC4J companion CD, then the wsclient_extended.jar
file can also be found in the ORACLE_HOME
/webservices/lib
directory.
See "Simplifying the Classpath with wsclient_extended.jar" for more information on wsclient_extended.jar
file.
If you will be enabling reliable messaging between the client and server, you must run SQL scripts that will install tables for both the client and server.
"Installing SQL Tables for the Client and Server" in the Oracle Application Server Advanced Web Services Developer's Guide for more information on how to find and run the SQL scripts.
You will need an installed, running Oracle database if you are using reliable messaging or assembling database Web services.
See "Database Requirements" for more information on this topic.
The WebServicesAssembler tool assists in assembling OracleAS Web Services. It enables you to generate the artifacts required to develop and deploy Web services, regardless of whether you are creating the service using the top down or bottom up approach. WebServicesAssembler commands can be called either from the command line or from Ant tasks.
This section describes how to set up your environment and build script files to call WebServicesAssembler commands from Ant tasks.You can use an Ant installation you have previously installed or use the Ant that is found in ORACLE_HOME
/ant
. The following sections describe how to set up Ant, depending on the version you have installed.
Note:
All of the Ant task examples in this book assume that you are using Ant version 1.6.5 or later. These versions let you use task namespaces. Hence, all of the Ant tags and subtags corresponding to WebServicesAssembler commands are prefixed with theoracle:
namespace.How to Set Up Ant 1.6.5 Distributed with Oracle Application Server
How to Set Up Ant 1.6.5 Using a Previous Installation of Ant
How to Set Up Ant 1.5.2 Using a Previous Installation of Ant
The following steps describe how to set up your environment and build files to use WebServicesAssembler with the Ant 1.6.5 installation found in ORACLE_HOME
/ant
. This is the version of Ant distributed with the Oracle Application Server.
Enter ORACLE_HOME
/ant/bin
at the front of your PATH
variable.
Edit your build script (build.xml
). Add the antlib:oracle
namespace declaration for the imported Ant tasks. In the following example, bottomup
is the name of your project.
<project name="bottomup" default="all" basedir="." xmlns:oracle="antlib:oracle">
Add the oracle:
namespace as a prefix to all WebServicesAssembler tags. For example:
<oracle:assemble ....> <oracle:port ... /> </oracle:assemble> <oracle:genProxy ..../>
(Optional) Copy the ant-oracle.properties
files to the same directory as your build script.
Although you can modify the properties file in the j2ee/utilities
directory and reference it from your build scripts, it is better to maintain this file as a template.
(Optional) Edit the ant-oracle.properties
file to reflect your installation environment.
(Optional) Edit the build script (build.xml
). Reference the ant-oracle.properties
file in the build script. For example:
<property file="ant-oracle.properties"/>
(Optional) If you will be using the junit
Ant task for reports, set the ANT_OPTS
system property to the Xalan TransformerFactoryImpl
class.
If you are using the JDK 1.5, set the ANT_OPTS
property for TransformerFactory
to com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl
. For example:
set ANT_OPTS=-Djavax.xml.transform.TransformerFactory=com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl
If you are using the JDK 1.4, set the ANT_OPTS
property for TransformerFactory
to org.apache.xalan.processor.TransformerFactoryImpl
. For example:
set ANT_OPTS=-Djavax.xml.transform.TransformerFactory=org.apache.xalan.processor.TransformerFactoryImpl
The following steps describe how to set up your environment and build files to use WebServicesAssembler with a previous installation of Ant 1.6.5 (or later).
Navigate to the directory ORACLE_HOME
/j2ee/utilities
and ensure that the following files are present:
ant-oracle.properties
—this file enables you to designate the key properties for the execution of the Oracle Ant tasks.
ant-oracle.xml
—this file enables you to use Oracle Ant tasks.
Copy the ant-oracle.properties
and ant-oracle.xml
files to the same directory as your build script (build.xml
).
Although you can modify the files in the j2ee/utilities
directory and reference them from your build scripts, it is better to maintain the source files as templates. Also, if you leave the ant-oracle.xml
file in its original location, then the import reference must be hard coded to specify the full path to the file (for example, c:/oc4j/j2ee/utilities/ant-oracle.xml
).
Edit the ant-oracle.properties
file to reflect your installation environment.
Edit the build script (build.xml
).
Import the ant-oracle.xml
file into the build script.
<!-- Import for OC4J ant integration. --> <import file="ant-oracle.xml"/>
Add the antlib:oracle
namespace reference for the imported Ant tasks. In the following example, bottomup
is the name of your project.
<project name="bottomup" default="all" basedir="." xmlns:oracle="antlib:oracle">
Include the oracle
namespace as a prefix to all WebServicesAssembler commands. For example:
<oracle:deploy ..../> <oracle:genProxy ..../>
(Optional) If you will be using the junit
Ant task for reports, set the ANT_OPTS
system property to the Xalan TransformerFactoryImpl
class.
If you are using the JDK 1.5, set the ANT_OPTS
property for TransformerFactory
to com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl
. For example:
set ANT_OPTS=-Djavax.xml.transform.TransformerFactory=com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl
If you are using the JDK 1.4, set the ANT_OPTS
property for TransformerFactory
to org.apache.xalan.processor.TransformerFactoryImpl
. For example:
set ANT_OPTS=-Djavax.xml.transform.TransformerFactory=org.apache.xalan.processor.TransformerFactoryImpl
The following steps describe how to set up your environment and build files to use WebServicesAssembler with a previous installation of Ant 1.5.2.
Ensure that your installations of Ant and the Java JDK are already included in the classpath environment variable.
Add the path to wsa.jar
to the CLASSPATH environment variable. The path will typically be:
OC4J_Home/webservices/lib/wsa.jar
In this example, OC4J_Home
is the directory where you installed OC4J.
Add the following lines to any Ant build file that will invoke the Ant tasks.
<taskdef resource="orawsa.tasks" /> <typedef resource="orawsa.types" />
These lines can appear anywhere in the build file before the first WebServicesAssembler task is called.
(Optional) If you will be using the junit
Ant task for reports, set the ANT_OPTS
system property to the Xalan TransformerFactoryImpl
class.
If you are using the JDK 1.5, set the ANT_OPTS
property for TransformerFactory
to com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl
. For example:
set ANT_OPTS=-Djavax.xml.transform.TransformerFactory=com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl
If you are using the JDK 1.4, set the ANT_OPTS
property for TransformerFactory
to org.apache.xalan.processor.TransformerFactoryImpl
. For example:
set ANT_OPTS=-Djavax.xml.transform.TransformerFactory=org.apache.xalan.processor.TransformerFactoryImpl
Ant version 1.6.5 and higher requires the oracle:
prefix at the beginning of all Ant tags and subtags for WebServicesAssembler commands. This prefix informs the Ant interpreter that this is an Oracle Ant task.
The oracle:
prefix corresponds to the prefix that is found in the project
tag at the beginning of the Ant build.xml
file.
<project name="myproject" default="all" basedir="." xmlns:oracle="antlib:oracle">
If you do not want to use oracle
as a prefix, you can change it to any valid XML QName
prefix. For example, if you want to use oracletags
as a prefix, then you must change the value of the project
tag.
<project name="myproject" default="all" basedir="." xmlns:oracletags="antlib:oracle">
If you make this change, then all Ant tags and subtags for WebServicesAssembler commands must start with oracletags:
. For example:
<oracletags:assemble ...>
You will need an installed running Oracle database (local or remote) if you will be performing any of the following tasks:
assembling any of the database Web Services. Chapter 10, "Assembling Database Web Services" provides more information on the database Web services that can be run on OracleAS Web Services.
enabling reliable messaging between the client and server. "Ensuring Web Service Reliability" in the Oracle Application Server Advanced Web Services Developer's Guide provides more information on reliable messaging.