Contents

List of Examples

List of Figures

List of Tables

Title and Copyright Information

Preface

• Intended Audience
• Documentation Accessibility
• Related Documents
• Conventions

1 Web Services Overview

• Understanding Web Services
• Web Services Standards
  • Java 2 Enterprise Edition
  • Simple Object Access Protocol 1.1 and 1.2
  • Web Service Description Language 1.1
  • Web Service-Interoperability Basic Profile 1.1
  • Web Service Inspection Language 1.0
• New and Enhanced Features
  • Web Service Security for Authentication, Integrity, and Confidentiality
  • Web Services Management Framework and Application Server Control
  • Web Services Metadata for the Java Platform (J2SE 5.0 Web Service Annotations)
  • REST Web Services
  • Enhanced Web Service Test Page
  • Ant Tasks for Configuration and Scripting
  • Custom Type Mapping Framework for Serialization
  • Database Web Services
  • SOAP Header Support
  • MIME and DIME Document Support
  • MTOM Binary Content as Attachments
  • Message Delivery Quality of Service
  • JMS Transport as an Alternative to HTTP
  • Web Services Provider Support
  • Web Services Invocation Framework for Describing WSDL Programming Artifacts
  • SOAP Message Auditing and Logging
  • Oracle BPEL
  • Oracle Web Services Manager
• Compatibility with Previous Versions of OracleAS Web Services
  • Redeploying Applications on OracleAS Web Services 10.1.3.1
  • Deprecated Features
• Clustered Environments and High Availability
• OC4J in a Standalone Versus Oracle Application Server Environment

2 Development and Documentation Roadmap

3 OracleAS Web Services Architecture and Life Cycle

• Architecture
  • Processing Components
    • Protocol Handlers
    • XML Processing
    • Policy Enforcement
    • JAX-RPC Handlers
    • Data Binding
    • Endpoint Implementation
  • Java Management Extensions (JMX)
  • Development Tools
• Web Services Development Life Cycle
  • Create the Implementation
  • Assemble the Web Service
  • Assemble the Client
  • Deploy the Web Service
  • Test the Web Service
  • Perform Post Deployment Tasks

4 Getting Started

• Supported Platforms
• How to Install OC4J
• How to Set Up Your Environment for OracleAS Web Services
• How to Set Up Ant for WebServicesAssembler
  • 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
• Database Requirements

5 OracleAS Web Services Messages

• OracleAS Web Services Message Formats
  • Understanding Message Formats
    • RPC and Document Styles
    • Literal and Encoded Uses
  • Supported Message Formats
    • Document-Literal Message Format
    • RPC-Encoded Message Format
    • RPC-Literal Message Format
  • How to Select Message Formats for a Web Service
  • Changing Message Formats in a Service Implementation
  • Message Format Recommendations
• Working with SOAP Messages
  • Understanding the OraSAAJ APIs
  • How to Use the OraSAAJ APIs to Manipulate SOAP Messages
  • How to Work with Messages with Attachments Containing Binary Data
  • How to Convert XML Elements to SOAP Elements
  • How to Use SOAP 1.2 Formatted Messages in Bottom Up Web Service Assembly
  • How to Use SOAP 1.2 Formatted Messages in Top Down Web Service Assembly
• Limitations
• Additional Information

6 Assembling a Web Service from WSDL

• Understanding Top Down Assembly
• How to Assemble a Web Service Top Down
  • Prerequisites
  • Steps for Assembling the Web Service Top Down
• Limitations
• Additional Information

7 Assembling a Web Service with Java Classes

• Requirements for Writing Java Classes for Web Services
• Java Classes and Stateless Web Services
  • Exposing Java Classes as a Stateless Web Service
  • How to Assemble A Stateless Web Service with Java Classes
    • Prerequisites
    • Steps for Assembling a Stateless Web Service with Java Classes
  • How to Write Java Implementations for Stateless Web Services
    • How to Define a Java Interface
    • How to Define a Java Class
• Java Classes and Stateful Web Services
  • Exposing Java Classes as a Stateful Web Service
  • How to Assemble a Stateful Web Service
    • Prerequisites
    • Steps for Assembling a Stateful Web Service
  • How to Write Java Implementations for Stateful Web Services
    • How to Define a Java Interface
    • How to Define a Java Class
• Packaging and Deploying Web Services
• Tool Support for Exposing Java Classes as Web Services
• Limitations
• Additional Information

8 Assembling a Web Service with EJBs

• Exposing EJBs as Web Services
  • Working with Version 2.0 EJBs
  • Working with Version 3.0 EJBs
• How to Assemble a Web Service with EJBs
  • Prerequisites
  • Steps for Assembling a Web Service from an EJB
• How to Write EJBs for Web Services
  • How to Write an EJB Service Endpoint Interface
  • How to Implement an EJB Interface for Web Services
• Packaging and Deploying Web Services that Expose EJBs
• How to Secure EJB-Based Web Services at the Transport-Level
• Tool Support for Exposing EJBs as a Web Service
• Limitations
• Additional Information

9 Assembling Web Services with JMS Destinations

• Understanding JMS Endpoint Web Services
  • Steps for Assembling a JMS Endpoint Web Service
  • Message Processing and Reply Messages
• Limitations
• Additional Information

10 Assembling Database Web Services

• Understanding Database Web Services
• Type Mapping Between SQL and XML
  • SQL to XML Type Mappings for Web Service Call-Ins
    • Changing the SQL to XML Mapping for Numeric Types
  • XML to SQL Type Mapping for Web Service Call-Outs
• Developing Web Services that Expose Database Resources
  • How to Use Life Cycle for Web Service Call-in
  • WebServicesAssembler Support for Web Service Call-in
  • How to Assemble a Web Service from a PL/SQL Package
    • Prerequisites
    • Steps for Assembling a Web Service from a PL/SQL Package
    • Sample PL/SQL Package
    • How PL/SQL Function Names are Mapped to Web Service Operation Names
    • How to Access PL/SQL IN and IN OUT Parameters from Client Code
    • How to Access SQL XMLType Types from Client Code
  • How to Assemble a Web Service from a SQL Query or DML Statement
    • Prerequisites
    • Steps for Assembling a Web Service from a SQL Statement or Query
    • Sample SQL Statements
    • How SQL Queries are Mapped to Web Service Operations
    • How DML Operations are Mapped to Web Service Operations
  • How to Assemble a Web Service from an Oracle Streams AQ
    • Prerequisites
    • Steps for Assembling a Web Service from an Oracle AQ
    • Sample AQ Queue and Topic Declaration
    • Sample Web Service for a Queue Generated by WebServicesAssembler
    • Sample Web Service for a Topic Generated by WebServicesAssembler
    • How to Access an AQ Queue Exposed as a Web Service from Client Code
    • How to Access an Oracle AQ Queue with JMS
  • How to Assemble a Server-Side Java Class as a Web Service
    • Prerequisites
    • Steps for Assembling a Web Service from a Server-Side Java Class
    • Sample Server-Side Java Class
    • Sample Web Service Operations Generated from a Server-Side Java Class
• Developing a Web Service Client in the Database
  • Understanding Web Service Call-Out
  • How to Call Web Services from the Database
    • How to Perform Web Services Call-Out using Static Proxy and JPublisher
    • How to Perform Web Services Call-Out using DII and the SYS.UTL_DBWS Utility
• Tool Support for Web Services that Expose Database Resources
• Limitations
• Additional Information

11 Assembling Web Services with Annotations

• OracleAS Web Services and J2SE 5.0 Web Service Annotations
• Supported Annotations
  • Supported J2SE 5.0 JDK Annotations
    • Using WebServiceRef within OracleAS Web Services
  • Oracle Additions to J2SE 5.0 JDK Annotations
    • Deployment Annotation
    • Schema Annotation
    • WSIFEJBBinding Annotation
• How to Use Annotations
  • Steps to Use Annotations to Assemble a Web Service from Java Classes
  • Steps to Use Annotations to Assemble a Web Service from a Version 3.0 EJB
  • How to Override Annotations
    • How to Override Annotation Values with WebServicesAssembler
    • How to Override Deployment Annotation Values with Deployment Descriptors
  • Sample Java File with Annotations
• Limitations
• Additional Information

12 Assembling REST Web Services

• Understanding REST Web Services
• WebServicesAssembler Support for REST Web Services
  • Commands that Can Assemble REST Web Services
  • Annotations that Support REST Web Services
• How to Assemble REST Web Services
  • Steps to Assemble a REST Web Service Top Down
    • How to Access REST Web Service Operations
  • Steps to Assemble a REST Web Service Bottom Up
    • How to Access REST Web Service Operations
• How to Test REST Web Services
• REST Additions to Deployment Descriptors
• How REST Builds Requests and Responses
  • HTTP GET Requests
  • HTTP POST Requests
  • REST Responses
• Tool Support for REST Web Services
• Limitations
• Additional Information

13 Testing Web Services Deployment

• Steps to Access and Test Web Service Operations
• How to Access the Web Services Test Page
  • Accessing the Web Services Test Page through a Web Browser
  • Accessing the Web Services Test Page through Application Server Control
  • Accessing a Web Services Test Page Protected with SSL
    • Accessing the SSL-Protected Test Page when OracleAS Web Services Runs as Standalone
    • Accessing the SSL-Protected Test Page when OracleAS Web Services runs on Oracle HTTP Server
• How to Use the Web Services Test Page
  • Viewing the Web Service WSDL
  • Editing Values in the Test Page
    • How to Edit the Test Page as XML Source
  • Testing WS-Security and Reliable Messaging Features
    • Reliable Messaging Parameters
    • WS-Security Parameters
  • Enabling HTTP Authentication for the Web Service Test
  • Stress Testing the Web Service Operation
  • Invoking the Web Service Test
    • Invoking the Test for a JAX-RPC Web Service
    • Invoking the Test for a REST Web Service
• How to Disable the Web Services Test Page
• How to Obtain a Web Service WSDL Directly
• Limitations
• Additional Information

14 Assembling a J2EE Web Service Client

• Understanding J2EE Web Service Clients
• How to Assemble a J2EE Web Service Client
  • Prerequisites
  • Steps to Assemble a J2EE Web Service Client
  • How to Add J2EE Web Service Client Information to Deployment Descriptors
  • Steps to Deploy and Run an Application Client Module
  • How to Access a Web Service from a Client in the Same Module
    • How to Add a Port Component Link to a J2EE Client Deployment Descriptor
  • How to Add OC4J-Specific Platform Information for Deployment and Runtime
  • How to Add JAX-RPC Handlers for Message Processing to Deployment Descriptors
• Writing J2EE Web Service Client Code
  • Steps for Writing a J2EE Web Service Client
  • How to Configure a J2EE Web Service Client for a Stateful Web Service
    • How to Configure a J2EE Client with Deployment Descriptor Files
    • How to Configure a J2EE Client Programmatically
  • How to Configure a J2EE Web Service Client to Make JMS Transport Calls
  • How to Enable Chunked Data Transfer for HTTP 1.1
  • How to Set a Character Encoding for a SOAP Message
• Understanding the Packaging Structure for J2EE Clients
  • Understanding the Packaging Structure for a Servlet or Web Application Client
    • Packaging Structure for Servlet or Web Application Clients
    • Relationship Between Deployment Descriptors for Servlet or Web Application Clients
  • Understanding the Packaging Structure for an EJB Client
    • Package Structure for EJB Application Clients
    • Relationship Between Deployment Descriptors for EJB Application Clients
• Limitations
• Additional Information

15 Assembling a J2SE Web Service Client

• Understanding J2SE Web Service Clients
  • Understanding Static Stub Clients
  • Understanding JAX-RPC Dynamic Invocation Interface
• How to Assemble a J2SE Web Service Client
  • Prerequisites
  • Steps to Assemble a J2SE Web Service Client with a Static Stub
    • Sample WSDL File
• Writing Web Service Client Applications
  • Understanding the Client Utility Class File
  • Steps to Create a Service Factory
  • How to Enable Chunked Data Transfer for HTTP 1.1
  • How to Set a Character Encoding for a SOAP Message on a J2SE Client
  • How to Set Cookies in a Web Service Client Stub
• How to Use Dynamic Invocation Interface to Invoke Web Services
  • Basic Calls
  • Configured Calls
  • Examples of Web Service Clients that use DII
• Tool Support for Assembling J2SE Web Service Clients
• Additional Information

16 Using JAX-RPC Handlers

• Understanding Message Handlers
• How to Write a JAX-RPC Handler
• How to Configure and Register a Server-Side Handler with Ant Tasks
  • Ant Tasks that can Configure and Register Handlers
• How to Edit webservices.xml to Register a Server-Side Handler
• Client-Side JAX-RPC Handlers
  • How to Register a JAX-RPC Handler for J2EE Web Service Client
    • Using the handler Element in a J2EE Web Service Client
  • How to Register a JAX-RPC Handler for a J2SE Web Service Client
• Limitations
• Additional Information

17 Processing SOAP Headers

• How to Process SOAP Headers with Parameter Mapping
  • Ant Tasks and Commands that can Map Headers to Parameters
• How to Process SOAP Headers by Using Handlers
• How to Process SOAP Headers by Using the ServiceLifecycle Interface
  • How to Get HTTP Response and Request Headers
    • How Stub Clients Can Get Headers with the ServiceLifecycle Interface
    • How DII Clients Can Get Headers with the OracleCall Interface
    • How DII Clients of WSIF Services Can Get Message Headers
• Limitations
• Additional Information

18 Using WebServicesAssembler

• About the WebServicesAssembler Tool
  • Command Line Syntax
• Setting Up Ant for WebServicesAssembler
• WebServicesAssembler Commands
  • Web Service Assembly Commands
  • aqAssemble
  • assemble
  • corbaAssemble
  • dbJavaAssemble
  • ejbAssemble
  • jmsAssemble
  • plsqlAssemble
  • sqlAssemble
  • topDownAssemble
  • WSDL Management Commands
  • analyze
  • fetchWsdl
  • genConcreteWsdl
  • genQosWsdl
  • genWsdl
  • Java Generation Commands
  • genInterface
  • genProxy
  • genValueTypes
  • Deployment Descriptor Generation Commands
  • genApplicationDescriptor
  • genDDs
  • Maintenance Commands
  • help
  • version
• WebServicesAssembler Arguments
  • General Web Services Assembly Arguments
    • appName
    • bindingName
    • classFileName
    • className
    • classpath
    • debug
    • ear
    • ejbName
    • emptySoapAction
    • help
    • initialContextFactory
    • input
    • interfaceFileName
    • interfaceName
    • jndiName
    • jndiProviderURL
    • mappingFileName
    • output
    • packageName
    • portName
    • portTypeName
    • restSupport
    • schema
    • searchSchema
    • serviceName
    • strictJaxrpcValidation
    • useDimeEncoding
    • war
  • Session Arguments
    • callScope
    • recoverable
    • session
    • timeout
  • CORBA Assembly Arguments
    • corbanameURL
    • corbaObjectPath
    • idlFile
    • idlInterfaceName
    • idljPath
    • ORBInitialHost
    • ORBInitialPort
    • ORBInitRef
  • Database Assembly Arguments
    • aqConnectionFactoryLocation
    • aqConnectionLocation
    • dataSource
    • dbConnection
    • dbJavaClassName
    • dbUser
    • jpubProp
    • sql
    • sqlstatement
    • sqlTimeout
    • sysUser
    • useDataSource
    • wsifDbBinding
    • wsifDbPort
  • JMS Assembly Arguments
    • deliveryMode
    • genJmsPropertyHeader
    • jmsTypeHeader
    • linkReceiveWithReplyTo
    • payloadBindingClassName
    • priority
    • receiveConnectionFactoryLocation
    • receiveQueueLocation
    • receiveTimeout
    • receiveTopicLocation
    • replyToConnectionFactoryLocation
    • replyToQueueLocation
    • replyToTopicLocation
    • sendConnectionFactoryLocation
    • sendQueueLocation
    • sendTopicLocation
    • timeToLive
    • topicDurableSubscriptionName
  • Proxy Arguments
    • endpointAddress
    • genJUnitTest
  • Deployment Descriptor Arguments
    • appendToExistingDDs
    • context
    • ddFileName
    • uri
  • WSDL Access Arguments
    • fetchWsdlImports
    • httpNonProxyHosts
    • httpProxyHost
    • httpProxyPort
    • importAbstractWsdl
    • wsdl
  • WSDL Management Arguments
    • createOneWayOperations
    • genQos
    • qualifiedElementForm
    • singleService
    • soapVersion
    • targetNamespace
    • typeNamespace
    • wsdlTimeout
  • Message Format Arguments
    • mtomSupport
    • style
    • use
  • Java Generation Arguments
    • dataBinding
    • mapHeadersToParameters
    • overwriteBeans
    • unwrapParameters
    • valueTypeClassName
    • valueTypePackagePrefix
    • wsifEjbBinding
    • wsifJavaBinding
• Resolving Name Collisions
• Default Algorithms to Map Between Target WSDL Namespaces and Java Package Names
  • Java Package Name to WSDL Namespace Mapping Algorithm
    • Mapping Java Artifacts to WSDL Artifacts
    • Mapping Java Types to XML Schema Types
  • WSDL Namespace to Java Package Name Mapping Algorithm
    • Mapping the WSDL Service Endpoint Interface and Related Endpoint Artifacts to Java Package and Class Names
    • Mapping WSDL Value Types and Related Artifacts to Java Names and Types
  • How to Specify a Namespace
  • How to Specify a Root Package Name
• How to Establish a Database Connection
• Additional Ant Support for WebServicesAssembler
  • How to Use Multiple Instances of an Argument in Ant
  • How to Configure Proxy Generation in an Ant Task
    • How to Generate Handler and Port Information into a Proxy
  • How to Configure a Port in an Ant Task
  • How to Configure a Port Type in an Ant Task
  • How to Configure Handlers in an Ant Task
    • Attributes and Child Tags for handler Tags
    • Sample Handler Configuration
    • Ant Tasks that Can Configure Handlers
    • Configuring Multiple Handlers in an Ant Task
  • How to Add Files to an Archive
  • How to Control a WebServicesAssembler Build
  • How to Assemble Support for MTOM Encoded Attachemnts into a Web Service
• How to Assign Multiple Web Services to an EAR or WAR Archive
  • Limitations on Assigning Multiple Web Services to a WAR File
• How to Represent Java Method Parameter Names in the WSDL
• Limitations
• Additional Information

19 Packaging and Deploying Web Services

• Understanding Web Service Packaging
• Packaging Structure for Web Service Applications
  • Packaging for a Web Service Based on Java Classes
  • Packaging for a Web Service Based on EJBs
• Descriptions of Packaged Files
  • Relationships Between Deployment Descriptor Files
    • Relationships Between webservices.xml and ejb-jar.xml
    • Relationships Between webservices.xml and oracle-webservices.xml
    • Relationships Between webservices.xml and web.xml
• Tool Support for Packaging
  • Packaging Support with WebServicesAssembler
    • WebServicesAssembler Commands that Perform Packaging
    • Managing Deployment Descriptors
  • Packaging Support with Oracle JDeveloper
• Understanding Web Service Deployment
• Tool Support for Deployment
  • Command Line Support for Deployment
    • A Sample Deployment Using admin_client.jar
  • Ant Task Support for Deployment
  • Deployment Support with Oracle JDeveloper
  • Deployment Support with Application Server Control
• Limitations
• Additional Information

A Web Service Client APIs and JARs

• Web Services API Packages
• Setting the Classpath for a Web Service Proxy
  • Simplifying the Classpath with wsclient_extended.jar
  • Classpath Components for Clients using a Client-Side Proxy
  • OC4J Security-Related Client JAR Files
  • WS-Security-Related Client JAR Files
  • Reliability-Related Client JAR File
  • JMS Transport-Related Client JAR File
  • Database Web Services-Related Client JAR Files
  • Sample Classpath Commands

B Oracle Implementation of the WSDL 1.1 API

• Understanding the OraWSDL APIs

C oracle-webservices.xml Deployment Descriptor Schema

• Hierarchy of XML Elements in oracle-webservices.xml
• Elements and Attributes of oracle-webservices.xml
  • <auth-method>
  • <context-root>
  • <download-external-imports>
  • <ejb-transport-login-config>
  • <ejb-transport-security-constraint>
  • <endpoint-address-uri>
  • <expose-testpage>
  • <expose-wsdl>
  • <implementation-class>
  • <implementor>
  • <jms-address>
  • <max-request-size>
  • <operation>
  • <operations>
  • <oracle-webservices>
  • <param>
  • <policy>
  • <port-component>
  • <property>
  • <provider-description>
  • <provider-description-name>
  • <provider-name>
  • <provider-port>
  • <realm-name>
  • <resolve-relative-imports>
  • <rest-support>
  • <role-name>
  • <runtime>
  • <servlet-link>
  • <soap-port>
  • <transport-guarantee>
  • <use-dime-encoding>
  • <web-site>
  • <webservice-description>
  • <wsdl-file>
  • <wsdl-port>
  • <wsdl-publish-location>
  • <wsdl-service-name>
  • <wsdl-url>
• Securing EJB-Based Web Services at the Transport Level
• oracle-webservices.xml File Listing

D service-ref-mapping Schema

• Hierarchy of service-ref-mapping Schema
• Elements and Attributes of service-ref-mapping Schema
  • <call-property>
  • <name>
  • <operation>
  • <operations>
  • <port-info>
  • <runtime>
  • <service-endpoint-interface>
  • <service-impl-class>
  • <service-qname>
  • <service-ref-mapping>
  • <stub-property>
  • <value>
  • <wsdl-file>
  • <wsdl-location>
  • <wsdl-port>
• service-ref-mapping File Listing

E Error Message Prefixes

F Troubleshooting

• OracleAS Web Services Messages
• Assembling Web Services from a WSDL
  • Schema Features Limitations
    • Schema Features that are Mapped to a SOAPElement
    • RPC Encoded Does Not Support Complex Types With Attributes
• Assembling Web Services from Java Classes
• Assembling Web Services From EJBs
• Assembling Web Services with JMS Destinations
• Developing Web Services From Database Resources
• Assembling Web Services with Annotations
• Assembling REST Web Services
• Testing Web Service Deployment
• Assembling a J2EE Web Service Client
• Understanding JAX-RPC Handlers
• Processing SOAP Headers
• Using WebServicesAssembler
• Packaging and Deploying Web Services
• Ensuring Interoperable Web Services
• Working with Message Attachments
• Managing Web Services
• Ensuring Web Service Reliability
• Auditing and Logging Messages
• Custom Serialization of Java Value Types
• Using JMS as a Web Service Transport
• Using the Web Service Invocation Framework
• Using Web Service Providers

G Third Party Licenses

• Apache
  • The Apache Software License
• Apache SOAP
  • Apache SOAP License
• JSR 110
• Jaxen
  • The Jaxen License
• SAXPath
  • The SAXPath License
• W3C DOM
  • The W3C License

Index