3 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

• Installing OC4J

• Setting Up Your Environment for OracleAS Web Services

• Setting Up Ant for WebServicesAssembler

• Database Requirements

• Development and Documentation Roadmap

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

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

Setting 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.x (recommended) is required if you will be using Ant tasks to assemble Web services. Jakarta Ant 1.6.x 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 "Setting 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 "Setting Up Ant 1.6.2 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.

• Add the following files or paths to the classpath:

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

  • 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. "Sample Classpath Commands" provides 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/1013/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.

    "Simplifying the Classpath with wsclient_extended.jar" provides 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 provides 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. For more information, see "Database Requirements".

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

• Setting Up Ant 1.6.2 Distributed with Oracle Application Server

• Setting Up Ant 1.6.2 Using a Previous Installation of Ant

• Setting Up Ant 1.5.2 Using a Previous Installation of Ant

• Using the "oracle:" namespace Prefix for Ant Tasks

Setting Up Ant 1.6.2 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.2 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.int/ernal.xsltc.trax.TransformerFactoryImpl. For example:

     set ANT_OPTS=-Djavax.xml.transform.TransformerFactory=com.sun.org.apache.xalan.int/ernal.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 
     

Setting Up Ant 1.6.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.6.2 (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. Import this file into your build script by using the Ant <import> task.

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.int/ernal.xsltc.trax.TransformerFactoryImpl. For example:

     set ANT_OPTS=-Djavax.xml.transform.TransformerFactory=com.sun.org.apache.xalan.int/ernal.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 
     

Setting 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 the 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.int/ernal.xsltc.trax.TransformerFactoryImpl. For example:

     set ANT_OPTS=-Djavax.xml.transform.TransformerFactory=com.sun.org.apache.xalan.int/ernal.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 
     

Using the "oracle:" namespace Prefix for Ant Tasks

Ant version 1.6.2 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 9, "Developing 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.

Development and Documentation Roadmap

The following sections provide a suggested roadmap through the documentation that takes you through the steps of developing a Web service.

• Setting Up Your Environment

• Best Coding Practices

• Assembling Web Service Artifacts

• Deploying the Web Service

• Testing the Deployed Web Service

• Assembling a Web Service Client

• Adding Quality of Service Features to a Web Service

• Adding Advanced Functionality to a Web Service

• Alternative Web Service Strategies

• Reference Chapters and Appendixes

Setting Up Your Environment

The following chapter describes how to set up your environment to use the functionality provided by OracleAS Web Services.

• Chapter 3, "Getting Started"

Best Coding Practices

The chapters in this section describe issues that you should consider as you design your Web service.

The following chapter describes the varieties of message formats that you can employ in OracleAS Web Services. It describes the advantages and disadvantages of each message format and suggests which format to use based on the client functionality.

• Chapter 4, "Oracle Application Server Web Services Messages"

The following chapter in the Oracle Application Server Advanced Web Services Developer's Guide identifies some of the common areas where interoperability problems can occur. It provides design suggestions and programming guidelines that increase the interoperability of your Web service with applications on different platforms.

• "Ensuring Interoperable Web Services"

Assembling Web Service Artifacts

OracleAS Web Services enables you to assemble Web service artifacts bottom up starting from Java classes, EJBs, JMS destinations, database resources, or source files which employ J2SE 5.0 JDK Web Service Annotations. You can also assemble the artifacts top down starting from a WSDL. In OracleAS Web Services, you use the WebServicesAssembler tool to perform the assembly. Chapter 17, "Using WebServicesAssembler" provides a reference guide to the tool.

The following chapters describe how to use the WebServicesAssembler tool to perform the different types of Web Service assembly supported by OracleAS Web Services.

• Chapter 5, "Assembling a Web Service from a WSDL"

• Chapter 6, "Assembling a Web Service with Java Classes"

• Chapter 7, "Assembling a Web Service with EJBs"

• Chapter 8, "Assembling Web Services with JMS Destinations"

• Chapter 9, "Developing Database Web Services"

• Chapter 10, "Assembling Web Services with Annotations"

Deploying the Web Service

While the WebServicesAssembler tool does not perform deployment, it does package the Web service into a deployable EAR or WAR file. Deploying this file is very similar to deploying any other EAR or WAR file into a running instance of OC4J. OC4J provides a separate book that describes how to perform deployment.

• Oracle Containers for J2EE Deployment Guide

The following chapter provides additional information about the packaging format and the files required for deployment. The chapter also briefly describes the deployment support offered by the JDeveloper and Application Server Control tools.

• Chapter 18, "Packaging and Deploying Web Services"

Testing the Deployed Web Service

The following chapter describes the Web Service Home Page. This page lets you test whether deployment was successful without the need to write any code.

• Chapter 12, "Testing Web Service Deployment"

Assembling a Web Service Client

The following chapters describe how to use WebServicesAssembler to assemble a Web service client for the J2SE and J2EE platforms.

• Chapter 13, "Assembling a J2EE Web Service Client"

• Chapter 14, "Assembling a J2SE Web Service Client"

Adding Quality of Service Features to a Web Service

OracleAS Web Services support quality of service features, such as security, reliability, message logging, and auditing. The following chapters describe how to implement these features; they can be managed by other tools such as JDeveloper and Application Server Control. The following chapters appear in the Oracle Application Server Advanced Web Services Developer's Guide.

• "Managing Web Services"

• "Ensuring Web Services Security"

  This chapter provides only an overview of the contents of the Oracle Application Server Web Services Security Guide. The Security Guide describes the Web Services implementation of message-level security.

• "Ensuring Web Service Reliability"

• "Auditing and Logging Messages"

Adding Advanced Functionality to a Web Service

The following chapters describe additional features that can enhance the performance and functionality of your Web service.

• Chapter 15, "Understanding JAX-RPC Handlers"

• Chapter 16, "Processing SOAP Headers"

See also the following chapters in the Oracle Application Server Advanced Web Services Developer's Guide.

• "Working with Message Attachments"

• "Custom Serialization of Java Value Types"

Alternative Web Service Strategies

The following chapters describe alternative modes of Web service implementation.

For example, you can write your own infrastructure to make Web service calls, create a client for non-SOAP protocols, or use a non-HTTP transport mechanism.

• Chapter 11, "Assembling REST Web Services"

See also the following chapters in the Oracle Application Server Advanced Web Services Developer's Guide.

• "Using JMS as a Web Service Transport"

• "Using Web Service Invocation Framework"

• "Using Web Service Providers"

Reference Chapters and Appendixes

The following chapters and appendixes provide information to supplement the implementation and development tasks described in this book.

• Chapter 1, "Web Services Overview"

• Chapter 2, "Oracle Application Server Web Services Architecture and Life Cycle"

• Chapter 17, "Using WebServicesAssembler"

• Appendix A, "Web Service Client APIs and JARs"

• Appendix B, "Oracle Implementation of the WSDL 1.1 API"

See also the following reference chapters and appendixes in the Oracle Application Server Advanced Web Services Developer's Guide.

• "Understanding the WSMGMT Schema"

• "JAX-RPC Mapping File Descriptor"

• "Web Service MBeans"

• "Mapping Java Types to XML and WSDL Types"