Skip Headers
Oracle® Application Server Web Services Developer's Guide
10
g
(10.1.3.1.0)
Part Number B28974-01
Home
Book List
Index
Contact Us
Next
View PDF
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 Service 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