1 Introduction to JAX-WS Web Services
This chapter includes the following sections:
For definitions of unfamiliar terms found in this and other books, see the Glossary.
Overview of JAX-WS Web Service Development
WebLogic web services are implemented according to the JSR 109: Implementing Enterprise Web Services specification (http://www.jcp.org/en/jsr/detail?id=109), which defines the standard Java EE runtime architecture for implementing web services in Java. The specification also describes a standard Java EE web service packaging format, deployment model, and runtime services, all of which are implemented by WebLogic web services.
The following sections describe:
The Programming Model—Metadata Annotations
The JSR 109: Implementing Enterprise Web Services specification (http://www.jcp.org/en/jsr/detail?id=109) describes that a Java EE web service is implemented by one of the following components:
-
A Java class running in the Web container.
-
A stateless or singleton session EJB running in the EJB container.
The code in the Java class or EJB implements the business logic of your web service. Oracle recommends that, instead of coding the raw Java class or EJB directly, you use the JWS annotations programming model, which makes programming a WebLogic web service much easier.
This programing model takes advantage of the JDK metadata annotations feature in which you create an annotated Java file and then use Ant tasks to compile the file into a Java class and generate all the associated artifacts. The Java Web Service (JWS) annotated file is the core of your web service. It contains the Java code that determines how your web service behaves. A JWS file is an ordinary Java class file that uses annotations to specify the shape and characteristics of the web service. The JWS annotations you can use in a JWS file include the standard ones defined by the Web Services Metadata for the Java Platform specification (http://www.jcp.org/en/jsr/detail?id=181) as well as a set of other standard or WebLogic-specific annotations, depending on the type of web service you are creating.
Once you have coded the basic WebLogic web service, you can program and configure additional advanced features. For example, you can specify that the SOAP messages be digitally signed and encrypted (as specified by the WS-Security specification at http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss). You configure these more advanced features of WebLogic web services using WS-Policy files, which is an XML file that adheres to the WS-Policy specification and contains security-specific or web service reliable messaging-specific XML elements that describe the security and reliable-messaging configuration, respectively.
The Development Model—Bottom-up and Top-down
There are two approaches to web service development: bottom-up and top-down. Each approach is described in the following sections.
Bottom-up Approach: Starting from Java
In the bottom-up approach, you develop your the JWS file from scratch. After you create the JWS file, you use the jwsc WebLogic web service Ant task to compile the JWS file, as described by the JSR 109: Implementing Enterprise Web Services specification at http://www.jcp.org/en/jsr/detail?id=109.
The jwsc Ant task always compiles the JWS file into a plain Java class; the only time it implements a stateless or singleton session EJB is if you implement a stateless or singleton session EJB in your JWS file. The jwsc Ant task also generates all the supporting artifacts for the web service, packages everything into an archive file, and creates an Enterprise Application that you can then deploy to WebLogic Server.
By default, the jwsc Ant task packages the web service in a standard Web application WAR file with all the standard WAR artifacts. The WAR file, however, contains additional artifacts to indicate that it is also a web service; these additional artifacts include deployment descriptor files, the WSDL file that describes the public contract of the web service, and so on. If you execute jwsc against more than one JWS file, you can choose whether jwsc packages the web services in a single WAR file or each web service in a separate WAR file. In either case, jwsc generates a single Enterprise Application.
If you implement a stateless or singleton session EJB in your JWS file, then the jwsc Ant task packages the web service in a standard EJB JAR with all the usual artifacts, such as the ejb-jar.xml and weblogic-ejb.jar.xml deployment descriptor files. The EJB JAR file also contains additional web service-specific artifacts, as described in the preceding paragraph, to indicate that it is a web service. Similarly, you can choose whether multiple JWS files are packaged in a single or multiple EJB JAR files.
Alternatively, you can specify that your session EJB be packaged as a Web application WAR file by updating the jwsc Ant task in your build.xml file to enable the ejbWsInWar attribute in the module child element. For more information, see jwsc in WebLogic Web Services Reference for Oracle WebLogic Server.
For more information about the bottom-up approach, see Developing WebLogic Web Services Starting From Java: Main Steps.
Top-down Approach: Starting from WSDL
In the top-down approach, you create the web service from a WSDL file. You can use the wsdlc Ant task to generate a partial implementation of the web service described by the WSDL file. The wsdlc Ant task generates the JWS service endpoint interface (SEI), the stubbed-out JWS class file, JavaBeans that represent the XML Schema data types, and so on, into output directories.
After running the wsdlc Ant task, (which typically you only do once) you update the generated JWS implementation file, for example, to add Java code to the methods so that they function as defined by your business requirements. The generated JWS implementation file does not initially contain any business logic because the wsdlc Ant task does not know how you want your web service to function, although it does know the shape of the web service, based on the WSDL file.
The wsdlc Ant task packages the JWS SEI and data binding artifacts together into a JAR file that you later specify to the jwsc Ant task. You never need to update this JAR file; the only file you update is the JWS implementation class.
For more information about the top-down approach, see Developing WebLogic Web Services Starting From a WSDL File: Main Steps.
Roadmap for Implementing JAX-WS Web Services
The following table provides a roadmap of common tasks for developing, packaging and deploying, invoking, and administering JAX-WS web services and clients using WebLogic Server.
Table 1-1 Roadmap for Implementing JAX-WS Web Services
| This chapter . . . | Describes how to . . . |
|---|---|
|
Develop basic JAX-WS web services using the WebLogic development environment. Program the JWS file that implements your web service and use the Java Architecture for XML Binding (JAXB) data binding. |
|
|
Develop WebLogic web service clients using JAX-WS and apply best practices. |
|
|
Develop advanced features of WebLogic web services using JAX-WS. Advanced features include asynchronous clients, reliable messaging, atomic transactions, and so on. Test and monitor web services. |
|
|
Use pre-packaged WS-Policy files for web services reliable messaging and Make Connection, use batch reliable messaging, and migrate JAX-RPC web services and clients to JAX-WS. |
Note:
The JAX-WS implementation in Oracle WebLogic Server is extended from the JAX-WS Reference Implementation (RI) developed by the Glassfish Community (see https://github.com/eclipse-ee4j/metro-jax-ws). All features defined in the JAX-WS specification (JSR-224) are fully supported by Oracle WebLogic Server.
The JAX-WS RI also contains a variety of extensions, provided by Glassfish contributors. Unless specifically documented, JAX-WS RI extensions are not supported for use in Oracle WebLogic Server.
For an overview of WebLogic web services, standards, samples, and related documentation, see Understanding WebLogic Web Services for Oracle WebLogic Server.