Programming Web Services for WebLogic Server

Introduction and Roadmap

This section describes the contents and organization of this guide—Programming Web Services for WebLogic Server.

Document Scope and Audience

This document is a resource for software developers who develop WebLogic Web Services. It also contains information that is useful for business analysts and system architects who are evaluating WebLogic Server or considering the use of WebLogic Web Services for a particular application.

The topics in this document are relevant during the design and development phases of a software project. The document also includes topics that are useful in solving application problems that are discovered during test and pre-production phases of a project.

This document does not address production phase administration, monitoring, or performance tuning Web Service topics. For links to WebLogic Server® documentation and resources for these topics, see Related Documentation.

It is assumed that the reader is familiar with J2EE and Web Services concepts, the Java programming language, Enterprise Java Beans (EJBs), and Web technologies. This document emphasizes the value-added features provided by WebLogic Web Services and key information about how to use WebLogic Server features and facilities to get a WebLogic Web Service application up and running.

Guide to This Document

This document is organized as follows:

This chapter, Introduction and Roadmap, introduces the organization of this guide and the features of WebLogic Web Services.
Understanding WebLogic Web Services, provides an overview of how WebLogic Web Services are implemented, why they are useful, and the standard specifications that they implement or to which they conform.
Common Web Services Use Cases and Examples, provides a set of common use case and examples of programming WebLogic Web Services, along with step by step instructions on reproducing the example in your own environment.
Iterative Development of WebLogic Web Services, provides procedures for setting up your development environment and iterative programming of a WebLogic Web Service.
Programming the JWS File, provides details about using JWS annotations in a Java file to implement a basic Web Service. The section discusses both standard (JSR-181) JWS annotations as well as WebLogic-specific ones.
Advanced JWS Programming: Implementing Asynchronous Features, discusses how to implement the following advanced features for your Web Service: Web Service reliable messaging, conversational Web Services, buffering, asynchronous request-response, and SOAP message handlers for intercepting the request and response SOAP message.
Data Types and Data Binding, discusses the built-in and user-defined XML Schema and Java data types that are supported by WebLogic Web Services.
Invoking Web Services,describes how to write a client application (stand-alone or inside a WebLogic Web Service) that invokes a Web Service using the JAX-RPC stubs generated by the WebLogic Web Service Ant task clientgen.
Configuring Security, provides information about configuring different types of security for a WebLogic Web Service: message-level (digital signatures and encryption), transport-level (SSL), and access control.
Administering Web Services, provides information about the types of administrative tasks you typically perform with WebLogic Web Services and the different ways you can go about administering them: Administration Console, WebLogic Scripting Tool, and so on.
Publishing and Finding Web Services Using UDDI, describes how to use UDDI to publish and find Web Services.
Upgrading an 8.1 Web Service to 9.0, describes how to upgrade a Web Service built on WebLogic Server 8.1 to run on the new 9.0 Web Services runtime environment.
Ant Task Reference, provides reference documentation about the WebLogic Web Services Ant tasks.
JWS Annotation Reference,provides reference information about the JWS annotations (both standard JSR-181 and WebLogic-specific) that you can use in the JWS file that implements your Web Service.
Web Service Reliable Messaging Policy Assertion Reference, provides reference information about the policy assertions you can add to a WS-Policy file to configure the Web Service reliable messaging feature of a WebLogic Web Service.
Security Policy Assertion Reference, provides reference information about the policy assertions you can add to a WS-Policy file to configure the message-level (digital signatures and encryption) security of a WebLogic Web Service.
WebLogic Web Service Deployment Descriptor Element Reference, provides reference information about the elements in the WebLogic-specific Web Services deployment descriptor weblogic-webservices.xml.

Samples for the Web Services Developer

In addition to this document, BEA Systems provides a variety of code samples for Web Services developers. The examples and tutorials illustrate WebLogic Web Services in action, and provide practical instructions on how to perform key Web Service development tasks.

BEA recommends that you run some or all of the Web Service examples before programming your own application that use Web Services.

Downloading Examples Described in this Guide

Many of the samples described in this guide are available for download from the dev2dev CodeShare site. Each example is self-contained and requires only that you install WebLogic Server, create a domain, and start a server instance. All needed files, such as the JWS file that implements the sample Web Service, the Java client to invoke the Web Service, and the Ant build.xml file to build, deploy, and run the example are included in the ZIP file.

Avitek Medical Records Application (MedRec) and Tutorials

MedRec is an end-to-end sample J2EE application shipped with WebLogic Server that simulates an independent, centralized medical record management system. The MedRec application provides a framework for patients, doctors, and administrators to manage patient data using a variety of different clients.

MedRec demonstrates WebLogic Server and J2EE features, and highlights BEA-recommended best practices. MedRec is included in the WebLogic Server distribution, and can be accessed from the Start menu on Windows machines. For Linux and other platforms, you can start MedRec from the WL_HOME\samples\domains\medrec directory, where WL_HOME is the top-level installation directory for WebLogic Server.

As companion documentation to the MedRec application, BEA provides development tutorials that provide step-by-step procedures for key development tasks, including Web Service-specific tasks. See Application Examples and Tutorials for the latest information.

Web Services Examples in the WebLogic Server Distribution

WebLogic Server optionally installs API code examples in WL_HOME\samples\server\examples\src\examples\webservices, where WL_HOME is the top-level directory of your WebLogic Server installation. You can start the examples server, and obtain information about the samples and how to run them from the WebLogic Server Start menu.

Additional Web Services Examples Available for Download

Additional API examples for download can be found at http://dev2dev.bea.com. These examples include BEA-certified ones, as well as examples submitted by fellow developers.

Release-Specific WebLogic Web Services Information

For release-specific information, see these sections in WebLogic Server Release Notes:

WebLogic Server Features and Changes lists new, changed, and deprecated features.
WebLogic Server Known and Resolved Issues lists known problems by general release, as well as service pack, for all WebLogic Server APIs, including Web Services.

Differences Between 8.1 and 9.0 WebLogic Web Services

Web Services is one of the most important themes of J2EE 1.4, and thus of WebLogic Server 9.0. J2EE 1.4 introduces a standard Java component model for authoring Web Services with the inclusion of new specifications such as Implementing Enterprise Web Services (JSR-921) and Java API for XML Registries (JAX-R), as well as the updated JAX-RPC and SAAJ specifications. Because the implementation of Web Services is now a J2EE standard, there have been many changes between 8.1 and 9.0 WebLogic Web Services.

In particular, the programming model used to create WebLogic Web Services has changed to take advantage of the powerful new metadata annotations feature introduced in Version 5.0 of the JDK. In 9.0 you use JWS metadata annotations to annotate a Java file with information that specifies the shape and behavior of the Web Service. These JWS annotations include both the standard ones defined by the Web Services Metadata for the Java Platform specification (JSR-181), as well as additional WebLogic-specific ones. This JWS-based programming model is similar to that of WebLogic Workshop 8.1, although in 8.1 the metadata was specified via Javadoc tags. The WebLogic Web Services programming model in 8.1, by contrast, used the many attributes of the Web Service Ant tasks, such as servicegen, to specify the shape and behavior of the Web Service. Occasionally programmers had to update the deployment descriptor file (webservices.xml) manually to specify characteristics of the Web Service. The new programming model makes implementing Web Services much easier and quicker.

See Programming the JWS File, for more information.

Additionally, the runtime environment upon which WebLogic Web Services 9.0 run has been completely rewritten to support the Implementing Enterprise Web Services, Version 1.1 (JSR-921), specification. This means that Web Services created in 9.0 are internally implemented differently from those created in 8.1 and both run in completely different runtime environments. The 8.1 runtime environment has been deprecated, although it will continue to be supported for a limited number of future WebLogic Server releases. This means that even though 8.1 WebLogic Web Services run correctly on WebLogic Server 9.0, this may not always be true and BEA recommends that you upgrade the 8.1 Web Services to run in the 9.0 runtime environment.

See Anatomy of a WebLogic Web Service for more information.

Summary of WebLogic Web Services Features

The following list summarizes the main features of WebLogic Web Services and provides links for additional detailed information:

Programming model based on the new JDK 5.0 metadata annotations feature. The Web Services programming model uses JWS annotations, defined by the Web Services Metadata for the Java Platform specification (JSR-181).

See Programming the JWS File.

Implementation of the Web Services for J2EE, Version 1.1 specification, which defines the standard J2EE runtime architecture for implementing Web Services in Java.

See Anatomy of a WebLogic Web Service.

Asynchronous, loosely-coupled Web Services that take advantage of the following features, either separately or all together: Web Service reliable messaging, conversations, buffering, asynchronous request-response, and JMS transport.

See:

Digital signatures and encryption of request and response SOAP messages, as specified by the WS-Security specification.

See Configuring Message-Level Security (Digital Signatures and Encryption).

Use of WS-Policy files for the Web Service reliable messaging and digital signatures/encryption features.

See Use of WS-Policy Files for Web Service Reliable Messaging Configuration and Using WS-Policy Files for Message-Level Security Configuration.

Data binding between built-in and user-defined XML and Java data types.

See Data Types and Data Binding.

SOAP message handlers that intercept the request and response SOAP message from an invoke of a Web Service.

See Creating and Using SOAP Message Handlers.

Ant tasks that handle JWS files, generate a Web Service from a WSDL file, and create the JAX-RPC client classes needed to invoke a Web Service.

See Ant Task Reference.

Implementation of and conformance with standard Web Services specifications.

See Standards Supported by WebLogic Web Services.

Differences Between Beta and GA WebLogic Web Services

This section describes, at a high-level, the major changes that have occurred between the Beta and GA versions of this release of WebLogic Web Services. The section does not describe new functionality; see Summary of WebLogic Web Services Features for the complete list of Web Service features in this release.

The programming model has changed so that the JWS files you create are almost always plain Java files. There are some cases when you must explicitly implement a stateless session EJB, although these cases are rare. The jwsc Ant task almost always creates a Java class-implemented Web Service, packaged in a WAR file. These details, however, are hidden from the programmer.

See Anatomy of a WebLogic Web Service.

The functionality of the jwsc Ant task has changed so that it now compiles all Java code into class files and packages everything into a WAR or JAR file and creates an exploded EAR directory structure. In Beta you had to compile and package everything yourself.

See Running the jwsc WebLogic Web Services Ant Task.

The jwsc Ant task definition has changed from weblogic.wsee.tools.anttasks.JWSWSEEGenTask to weblogic.wsee.tools.anttasks.JwscTask.

See jwsc.

The wsdl2service Ant task (task definition weblogic.wsee.tools.anttasks.Wsdl2ServiceAntTask) no longer exists. Programmers should now use the wsdlc Ant task (task definition weblogic.wsee.tools.anttasks.WsdlcTask) which generates a JWS interface and partial implementation which programmers update with their business code.

See Iterative Development of WebLogic Web Services Starting From a WSDL File: Main Steps.

The javax.jws.security.SecurityRoles|SecurityIdentity annotations are in a different package: weblogic.jws.security.SecurityRoles|SecurityIdentity.

See weblogic.jws.security.SecurityRoles and weblogic.jws.security.SecurityIdentity.

When using Web Service reliable messaging, you no longer need to deploy the internal message-driven bean and Web Service used by the Web Services runtime.

See Using Web Service Reliable Messaging.

The Web Services reliable messaging feature implements a later version of the WS-ReliableMessaging specification. As a result, the schema of the WS-Policy file used to configure reliable messaging has changed.

Web Service Reliable Messaging Policy Assertion Reference.