4 Getting Started

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.

• Supported Platforms

• How to Install OC4J

• How to Set Up Your Environment for OracleAS Web Services

• How to Set Up Ant for WebServicesAssembler

• Database Requirements

Supported Platforms

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

How to Install OC4J

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.

How to Set Up Your Environment for OracleAS Web Services

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.

    http://jakarta.apache.org/ant/index.html

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

How to Set Up Ant for WebServicesAssembler

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 the oracle: 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

• How to Set Up the "oracle:" Namespace Prefix for Ant Tasks

How to Set Up Ant 1.6.5 Distributed with Oracle Application Server

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.

1. Enter ORACLE_HOME/ant/bin at the front of your PATH variable.

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

3. Add the oracle: namespace as a prefix to all WebServicesAssembler tags. For example:

   <oracle:assemble ....>
           <oracle:port ... />
   </oracle:assemble>
   <oracle:genProxy ..../>
   

4. (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.

5. (Optional) Edit the ant-oracle.properties file to reflect your installation environment.

6. (Optional) Edit the build script (build.xml). Reference the ant-oracle.properties file in the build script. For example:

   <property file="ant-oracle.properties"/> 
   

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

How to Set Up Ant 1.6.5 Using a Previous Installation of Ant

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

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

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

3. Edit the ant-oracle.properties file to reflect your installation environment.

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

5. Include the oracle namespace as a prefix to all WebServicesAssembler commands. For example:

   <oracle:deploy ..../>
   <oracle:genProxy ..../>
   

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

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 a previous installation of Ant 1.5.2.

1. Ensure that your installations of Ant and the Java JDK are already included in the classpath environment variable.

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

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

4. (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 
     

How to Set Up the "oracle:" Namespace Prefix for Ant Tasks

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

Database Requirements

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.