Skip Headers

Oracle® Application Server Web Services Developer's Guide 10g Release 3 (10.1.3) B14434-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 2 Oracle Application Server Web Services Architecture and Life Cycle

This chapter provides an overview of the components that comprise Oracle Application Server Web Services and publishable service artifacts. These components are defined by the Java API for XML-Based RPC (JAX-RPC). This API enables Java technology developers to build Web applications and Web services incorporating XML-based RPC functionality according to the SOAP (Simple Object Access Protocol) 1.1 specification.

## Architecture

The OracleAS Web Services stack is designed with three primary goals in mind: performance, interoperability, and manageability. This section describes how the Web services runtime is structured to provide enterprise-quality infrastructure for SOAP-based communication endpoints.

### Processing Components

Each step in the processing of a Web services request is represented by a logical component in the runtime infrastructure. As an XML message is delivered to the system, it flows through the following layers before being delivered to an endpoint implementation: protocol handlers, XML processor, policy enforcement pipeline, JAX-RPC handlers, data binding, and the endpoint implementation. Response messages flow through the same infrastructure following a reverse path.

Figure 2-1 How XML Messages Flow From Client to Service

Description of "Figure 2-1 How XML Messages Flow From Client to Service"

This section describes the purpose of each of these processing layers. Where appropriate, pointers to other sections are provided for more detailed information on system functionality and configuration.

#### Protocol Handlers

A protocol handler provides the entry point to the Web services infrastructure. The protocol handler is used to send and receive SOAP messages over a transport protocol. The Web services infrastructure can be configured to send and receive messages over HTTP or JMS.

If the messages are sent over HTTP, the OracleAS Web Services stack uses the Oracle HTTP Client libraries for sending Web services messages to services and the OC4J Servlet engine for receiving Web services messages sent by clients. All of the capabilities and management infrastructure of the Oracle servlet environment are available to Web services. For example, a Web service can be accessed with an encrypted data stream using HTTP or HTTPS.

JMS transport may be configured to work with different JMS providers. It is integrated into the application server by using the JMS infrastructure provided with the Oracle Application Server. JMS is often used to gain the full quality of service features of a message bus during a SOAP message exchange.

#### XML Processing

Once the SOAP message is retrieved from the transport layer, it is converted into an XML message representation that is compatible with the SOAP with Attachments API for Java (SAAJ). The SAAJ message is constructed using Oracle's optimized XML parsing technologies for performance and efficient memory utilization. This message is the basis for the JAX-RPC compliant SOAP processing infrastructure provided with OC4J. Once instantiated, the SAAJ message is delivered to the next layer of the processing stack.

Some portions of the SOAP request may not be XML. For example, a SOAP message may be sent with attachments, which are used to package non-XML content along with a SOAP message. The SAAJ implementation also deals with these attachments.

Though the default processing of XML messages assumes the message payload is encoded in a SOAP 1.1 or SOAP 1.2 compliant envelope, the OracleAS Web Services stack can also be configured to accept and dispatch XML messages over HTTP directly without using SOAP. This allows developers to create applications that integrate directly with existing HTTP infrastructure that is not aware of the SOAP protocol. Applications can be built to conform to the REST architecture style, using HTTP and URLs to define the messages that describe the system.

When configured to use XML-over-HTTP messaging, the infrastructure determines if a message contains an application message directly or a SOAP envelope as the top level element of the payload. If the message is "raw" XML, the processing layer will wrap the message in a SOAP envelope with no headers. This SOAP envelope can then be processed through the rest of the Web services processing elements and delivered to the endpoint implementation for processing.

The XML message is next processed by the policy enforcement mechanisms of the Web services stack.

#### Policy Enforcement

The OracleAS Web Services stack can be configured with additional information to enable a management chain that is responsible for enforcing runtime management policies. These policies include Web services management features like WS-Reliability, WS-Security, auditing, and logging capabilities."Managing Web Services" in the Oracle Application Server Advanced Web Services Developer's Guide provides more information on the setup of these features. The Oracle Application Server Web Services Security Guide provides more information on setting up security. Enabled policies can be included in the WSDL document associated with a service to support automated configuration of client interceptor pipelines.

One of the protocols that the OracleAS Web Services stack supports is the WS-Reliability standard, which provides delivery guarantees for SOAP messages. The reliability infrastructure supports additional capabilities that allow the system infrastructure to send and receive asynchronous acknowledgment messages that conform to the WS-Reliability protocol. This is supported as an extension to the Oracle client infrastructure, which is available when using a JAX-RPC Stub or Call object.

The interceptor chain can also be configured to delegate to the OracleAS Web Services Management agent pipeline. This provides pre-integrated support for OracleAS Web Services Management product and capabilities that support management of policies for Web services across a data center.

The management interceptors provide a runtime infrastructure for systems services that are provided in OC4J. Application-specific interceptors are supported in conformance with the JAX-RPC 1.1 Handler API.

#### JAX-RPC Handlers

Handlers are configured to process application-specific SOAP headers according to specific roles or actor attributes. The handlers have access to a SAAJ representation of the SOAP message and can perform operations on any level of the SOAP message. Use of the Handler API is described in Chapter 15, "Understanding JAX-RPC Handlers" and Chapter 16, "Processing SOAP Headers".

Together, the interceptors and the handlers are used to enforce the SOAP processing model. This allows Web services endpoints to selectively process SOAP headers that are intended for a particular node. SOAP messages can then be passed along to other nodes in the system and SOAP headers are processed as required.

#### Data Binding

In many applications, portions of the XML payload are converted to Java objects that are used by the application framework. This capability is often called data binding, where portions of XML data are bound to members of a Java class hierarchy. The process of data binding is driven through the serialization framework, which manages the conversion from XML to Java. The serialization framework is extensible and allows developers to define custom type mapping from XML data to Java objects.

The OC4J runtime features a special "provider" implementation that is optimized for processing SAAJ messages. When the provider is used, no data binding is performed. Providers can be used to implement applications that work directly with XML payload in a SOAP message.

#### Endpoint Implementation

After passing through the preceding four layers of the Web services stack, the endpoint implementation containing the application business logic is invoked. The endpoint can be a regular Java class, an Enterprise Java Bean, or a provider. The endpoint can also be a JMS queue when a JMS endpoint configuration is enabled.

In the OracleAS Web Services container, there are very few requirements that a Java class must conform to in order to be exposed as a Web service. If the endpoint implementation requires more complex interaction with the container throughout its life cycle, it can implement a JAX-RPC `ServiceLifecycle` interface, which provides more information about the Web services requests to the endpoint during initialization of the service and while handling requests.

Java classes may also be augmented with Web services specific annotations. These annotations can be used to provide additional configuration information specifying what methods are exposed as Web services operations, what protocols can be used to access the service, and so on. Chapter 10, "Assembling Web Services with Annotations" provides more information about OracleAS Web Services support for J2SE 5.0 JDK Web Service Annotations.

### Java Management Extensions (JMX)

While the interceptor pipeline is used to enforce management policies, systems management capabilities are exposed in the OracleAS Web Services stack by using the Java Management Extensions (JMX) standard. JMX allows administrators to gather important metrics on the health of a running OC4J system and to change the configuration of a running system. JMX metrics and operations are available in the Web services console in the Application Server Control tool.

### Development Tools

Another key feature of the OracleAS Web Services implementation is the development tools that allow for the development and deployment of endpoint implementations. Web services can be developed using either command line tools or a Java Integrated Development Environment (IDE).

WebServicesAssembler (WSA), the command line tool, is used to generate artifacts required to deploy a Web service from WSDL or endpoint implementation classes. It is useful for automating the creation of Web services in a scripted environment since, in addition to command line, it exposes its functionality as Ant tasks.

JDeveloper, Oracle's full-featured Java IDE, can be used for end-to-end development of Web services. Developers can build Java classes or EJBs, expose them as Web services, automatically deploy them to an instance of the Oracle Application Server, and immediately test the running Web service. Alternatively, JDeveloper can be used to drive the creation of Web services from WSDL descriptions. Like WebServicesAssembler, JDeveloper also is Ant-aware. You can use this tool to build and run Ant scripts for assembling the client and for assembling and deploying the service.

## Web Services Development Life Cycle

This section describes the stages of Web service development.

1. Create the Implementation

2. Generate the Web Service

3. Generate the Client

4. Deploy the Web Service

5. Test the Web Service

6. Perform Post Deployment Tasks

### Create the Implementation

Create the implementation that you want to expose as a Web service. OracleAS Web Services allows a variety of artifacts to be exposed as a Web service, including:

- Java classes

- Enterprise Java Beans (EJBs)

- JMS queues or topics

- PL/SQL procedures

- SQL Statements

- Oracle Advanced Queues

- Java classes in the database

- CORBA servant objects

You can develop these artifacts using any tool or IDE. Oracle JDeveloper enables you to create Java classes, JMS queues and topics, PL/SQL procedures, CORBA servant objects, and EJBs.

### Generate the Web Service

OracleAS Web Services provides a variety of commands that let you generate a Web service by using either a top down (starting with a WSDL) or a bottom up (starting with Java classes, EJBs, database artifacts, or JMS queues) approach. These commands are described in "Web Service Assembly Commands". These commands can be issued on the command line or they can be written as tasks in an Ant script.

Since JDeveloper is fully Ant-aware, you can use this tool to build and run the Ant scripts. JDeveloper also has design-time wizards which symmetrically mirror several of the Web service generation commands. Using these wizards can speed your development process and save you the steps of creating the build scripts.

Most current Java IDEs (such as Eclipse) are also Ant-aware. You can use any of these IDEs to run the Ant scripts if you choose not to use JDeveloper.

If you need to invoke other OracleAS Web Services commands, for example, to generate a WSDL or to add quality of service features, you can invoke them on the command line or with Ant tasks. While there are no design-time wizards to support these commands, the Ant tasks can be run directly in JDeveloper.

### Generate the Client

OracleAS Web Services provides commands that can be used to generate J2SE and J2EE client code.

Oracle JDeveloper supports OC4J J2SE Web service clients by allowing developers to create Java stubs from Web service WSDL descriptions. These stubs can then be used to access existing Web services.

### Deploy the Web Service

Web services deployment can be performed either with Java-language commands or with Ant tasks. The Ant tasks can reside in a build file or they can be issued directly from JDeveloper. JDeveloper also has a deployment wizard which configures the deployable EAR file and deploys it.

Deployment can also be performed with Application Server Control. However, this tool cannot be used to configure the EAR file or change its contents.

### Test the Web Service

The OracleAS Web Services stack provides a Web Service Home Page for each deployed Web service. By entering a service endpoint address in a Web browser, you can access the operations that the Web service exposes. Interactive pages let you invoke the operations for values that you enter.

The WebServicesAssembler command line tool can generate tests suitable for the JUnit framework for every method in the Web service. If you use the WebServicesAssembler tool to generate JUnit tests for the `assemble`, `plsqlAssemble`, and `genProxy` commands, then JDeveloper can import them by default.

### Perform Post Deployment Tasks

There are a number of tasks you can perform post-deployment. Some of these involve fine-tuning the performance of the Web service, such as changing security and logging policies. Others involve larger changes to the Web service, such as changing a key store configuration. You can make some of these changes dynamically; for others, you must redeploy the Web service. To perform these tasks, use Oracle Application Server Control. For more information on these tasks, see the Application Server Control on-line help.