|
| Sun ONE Application Server 7, Update 1 Developer's Guide to Web Services |
About Web ServicesThis module introduces you to Web services, standards used in implementing Web services, and summarizes the process of building such services.
This module describes the following topics:
- What are Web Services?
- Messaging Models Used in Web Services
- Standards and Interoperability in Web Services
- Support for Web Services in Sun ONE Application Server
- A Simple Web Service Scenario
- Java APIs for XML and Web Services
- Implementing Web Services Using Java APIs
- Preparing for Developing Web Services and Clients
What are Web Services?
A Web service is a modular application that you can describe, publish, locate, and invoke across the web. A Web service perform functions, which can be anything from simple requests to complicated business processes. Once a Web service is deployed, other applications or other Web services can discover and invoke the deployed service.
Web services are invoked using Simple Object Access Protocol (SOAP) messages. SOAP is a lightweight messaging protocol that allows objects of any kind, on any platform, written in any language to cross-communicate. SOAP messages are encoded in eXtensible Markup Language (XML) and typically transported over HTTP. Unlike other distributed computing technologies, Web services are loosely coupled and can dynamically locate and interact with other components on the internet to provide services.
A Web service is invoked using an XML message such as a SOAP message through a well-defined message exchange pattern. The message exchange pattern is defined in a Web Services Description Language (WSDL) document by a description of the data required to invoke the service.
Messaging Models Used in Web Services
This section describes the two principal messaging models used in Web services. The two Web service messaging models are distinguished by their request-response operation handling.
This section describes the following Web services models:
Synchronous Model
Synchronous means that every time a client accesses a Web service application, the client receives a SOAP response. Synchronous is request-response operation. Synchronous services are designed when client applications require a more immediate response to a request. Web services that rely on synchronous communication are usually Remote Procedure Call (RPC)-oriented. JavaTM API for XML-based RPC (JAX-RPC) and SOAP with Attachments API for JavaTM (SAAJ) use the synchronous model for communication.
Asynchronous Model
Asynchronous means that the client which invokes a Web service, does not or can not wait for a response. Thus, asynchronous is one-way operation. The client sends a request in the form of an XML message. The Web service receives the message and processes it, sending the results when it completes its processing. An asynchronous send requires a messaging provider which is not supported in Sun ONE Application Server. Asynchronous receive is supported in the application server using the JavaTM API for XML Messaging (JAXM).
Standards and Interoperability in Web Services
Web services are based on a set of standard protocols and technologies, so that all the components of a Web service understand how to communicate. This section describes the following standards.
SOAP
Simple Object Access Protocol (SOAP) is a lightweight protocol that allows exchange of information in a distributed environment. It plays a very important role in the communication mechanism for Web services. It provides a standard packaging structure for transporting XML documents using a variety of standard internet technologies including SMTP, HTTP, and FTP.
For more information about SOAP 1.1 specification, visit the following URL:
http://www.w3.org/TR/soapWSDL
Web Services Description Language (WSDL) is an XML-based specification schema for describing a Web service. WSDL defines Web services as a set of endpoints or ports operating on messages. A port is defined by associating a network address with a reusable binding, and a collection of ports define a service. The message can be either message-style or RPC-style. WSDL is extensible to allow the description of endpoints and their associated messages regardless of what message formats or network protocols are used to communicate.
For more information about WSDL specification, visit the following URL: http://www.w3.org/TR/wsdl
UDDI
Universal Description, Discovery, and Integration (UDDI) standard provides a mechanism for businesses to describe themselves and the types of services they provide and allows these to register themselves in a UDDI registry. Using SOAP messages, other businesses can search, query, or discover registered businesses. Having discovered other suitable businesses to partner with, businesses can then integrate their services with their partners and provide service to their customers.
For more information about UDDI 2.0 specification, visit the following URL: http://www.uddi.org
ebXML
electronic business eXtensible Markup Language (ebXML) defines core components, business processes, registry and repository, messaging services, trading partner agreements, and security. ebXML defines standards by extending all three of the previous standards to achieve e-business partner interoperability for document exchange. ebXML message service extends SOAP 1.1 with attachment for use as the base messaging protocol to achieve reliability and other quality of service aspects.
ebXML Collaboration Partner Profile and Agreement (CPP and CPA) describe partner interactions for the e-business scenario in a complete manner.
An ebXML Registry and Repository enables the storing and sharing of information between parties to allow e-business collaboration. Sun ONE Application Server supports clients to access an ebXML registry through a third-party provider.
For more information on ebXML, visit the following URL:
http://www.ebxml.orgA Simple Web Service Scenario
The following figure illustrates the working of a simple Web service in Sun ONE Application Server environment.
Web services in Sun ONE Application Server Environment
The typical working of Web services is explained in the following steps:
- Once the Web service application is ready to accept requests, the Web service is registered with a registry, such as a UDDI registry or an ebXML registry and repository. Describe the Web service using a WSDL.
- Another service or a user locates this registered service and requests by querying the registry.
- The requesting service or a user writes an application to bind the registered service using SOAP.
- The client discovers the Web service that is registered with the registry.
- The request from a client to a Web service arrives in the form of an XML document.
- The Web service receives the request and processes the request.
- The Web service calls one or more Enterprise JavaBeans (EJBs) components to perform business data processing.
- The EJB components perform their processing calling external systems.
- The EJB components return data to the service.
- The Web service then marshals this return value into an XML document.
- The Web service returns the XML document to the client on a response.
Support for Web Services in Sun ONE Application Server
Support for Web services in Sun ONE Application Server, is primarily through the implementation of different JAX* APIs. Sun ONE Application Server delivers the runtime environment and tools to develop, deploy, and host RPC and document-oriented Web services. Sun ONE Application Server provides the facility to publish Web services into a UDDI registry and discover the registered services. In addition, Sun ONE Application Server enables integration of reliable messaging into Web services using Sun ONE MQ 3.0.1 (Message Queue).
For more information on the Java APIs, see "Java APIs for XML and Web Services".
Sun ONE Application Server includes the following features:
- Sun ONE Application Server includes command-line tools to perform the following tasks:
Generate client side stubs and server-side tie classes which interface with the application server at runtime. You can generate stubs and tie-classes using the wscompile and wsdeploy tools provided with Sun ONE Application Server. For more information on using these tools, see "JAX-RPC Tools".
Convert Java interfaces-to-WSDL and vice versa.
Ant tasks to develop and deploy Web services to Sun ONE Application Server.
- Provides Sun ONE Studio 4, a graphical user interface, that helps in the development and deployment of Web services and clients.
For instructions on how to use Sun ONE Studio to build Web services and clients, see the Sun ONE Studio Building Web Services documentation. The Sun ONE Studio documentation is available at the following URL:
http://docs.sun.com/source/816-7862/index.html
Unsupported Features in Sun ONE Application Server
Sun ONE Application Server does not support the following features:
- Does not include any registry servers but, is certified with the Sun ONE Registry Server as well as tested with external UDDI registry.
- Does not support any Web services security protocols, instead relies on web container's security.
- Does not include a messaging provider that enforces reliable messaging between the client and the server.
Java APIs for XML and Web Services
Support for developing Web services on Sun ONE Application Server is primarily based on the implementation of Java APIs for XML and Web services. These APIs provide specific XML and/or SOAP capabilities required to access or deliver Web services from the Java platforms. This section describes each API as delivered in Sun ONE Application Server.
For detailed information on the Java APIs and the programming concepts, visit the following URL:
http://java.sun.com/webservices/docs/1.0/tutorial/index.html
The following table lists the Java APIs supported by Sun ONE Application Server. The first column lists the Java APIs and the second column shows the version number of the Java API.
Java APIs for XML and Web Services supported in Sun ONE Application Server
Java API
Version Number
1.1, 1.2
1.0
1.0
1.1
1.1
JAXP
The JavaTM API for XML Processing (JAXP) supports the processing of XML documents using Simple API for XML (SAX) and Document Object Model (DOM), along with a pluggable interface to an XML Stylesheet Language Transformations (XSLT) engine. JAXP enables applications to parse and transform XML documents independent of a particular XML processing implementation. Depending on the needs of the application, developers have the flexibility to swap between XML processors, such as high performance vs. memory conservative parsers, without making application code changes. Thus, application and tools developers can rapidly and easily XML-enable their Java applications for e-commerce, application integration, and dynamic web publishing. JAXP 1.2 implementation in Sun ONE Application Server has support for XML schema and an XML compiler (XSLTC).
JAXP 1.2 is required for the other Java APIs for XML and Web services in Sun ONE Application Server. JDK 1.4 bundles an implementation of JAXP 1.1. Sun ONE Application Server bundles JAXP 1.2 implementation. To override the classes in JAXP implementation in JDK 1.4, see "Overriding the JAXP Implementation".
For more information about JAXP, visit the following URLs: http://java.sun.com/xml/tutorial_intro.html http://java.sun.com/xml/xml_jaxp.html
JAX-RPC
The Java API for XML-based RPC (JAX-RPC) enables developers to build SOAP based interoperable and portable Web services. JAX-RPC provides an easy to develop programming model for the development of SOAP based synchronous Web services. Developers use the RPC programming model to develop clients and endpoints. For typical scenarios, developers are not exposed to the complexity of the underlying runtime mechanisms, such as SOAP protocol level mechanisms, marshalling, and unmarshalling.
A JAX-RPC runtime system or a library abstracts these runtime mechanisms for programming Web services. A JAX-RPC client can use stubs-based, dynamic proxy, or dynamic invocation interface (DII) programming models to invoke a heterogeneous Web services application. JAX-RPC provides support for document based messaging. Using JAX-RPC, any MIME encoded content can be carried as part of a SOAP message with attachments. This enables exchange of XML document, images, and other MIME types across Web services. JAX-RPC supports HTTP level session management and SSL based security mechanisms. This enables in the development of secured Web services.
Sun ONE Application Server provides support for development and deployment of JAX-RPC Web services and clients. In addition to providing implementation for JAX-RPC API, application server provides tools support for WSDL to Java and Java to WSDL mapping as part of the development of clients and services.
For detailed information on JAX-RPC, visit the following URL: http://java.sun.com/xml/jaxrpc/index.html
JAXR
The JavaTM API for XML Registries (JAXR) provides standard Java API for accessing different kinds of XML registries in a uniform manner. An XML registry is an enabling infrastructure for building, deploying, and discovering Web services.
Currently, there are a variety of specifications for XML registries including pre-eminently, the ebXML Registry and Repository standard, which is being developed by OASIS and U.N./CEFACT and the UDDI specification, which is being developed by a vendor consortium.
JAXR enables Java software programmers to use a single, easy-to-use abstraction API to access a variety of XML registries. Simplicity and ease of use are facilitated within JAXR by a unified JAXR information model, which describes content and metadata within XML registries.
JAXR provides rich metadata capabilities for classification and association, as well as rich query capabilities. As an abstraction-based API, JAXR gives developers the ability to write registry client programs that are portable across different target registries.
Sun ONE Application Server provides implementation for JAXR 1.0 version. This version of the JAXR specification includes detailed bindings between the JAXR information model and both the ebXML Registry and the UDDI Registry v2.0 specifications.
For detailed information on JAXR visit the following URL: http://java.sun.com/xml/jaxr/index.html
SAAJ
The SOAP with Attachments API for JavaTM (SAAJ) enables developers to produce and consume messages conforming to the SOAP 1.1 specification and SOAP with Attachments note. This API is derived from the java.xml.soap package originally defined in the JAXM 1.0 specification.
Sun ONE Application Server provides support for SAAJ API 1.1. For more information on SAAJ 1.1 API, visit the following URL:
http://java.sun.com/xml/downloads/saaj.html
JAXM
JavaTM API for XML Messaging (JAXM) defines the API for xml messaging using a messaging provider. JAXM API enables applications to send and receive document-oriented XML messages. JAXM implements SOAP 1.1 with attachments messaging so that developers can focus on building, sending, receiving, and retrieving messages, avoiding programming low level communication routines.
Sun ONE Application Server implements the JAXM 1.1 API that enables applications to send and receive asynchronous messages using a messaging provider.
For detailed information on JAXM visit the following URL: http://java.sun.com/xml/jaxm/index.html
Implementing Web Services Using Java APIs
The following figure illustrates the role of standard Java APIs in implementing Web services.
Implementing Web Services Using Java APIs
SOAP messaging is the protocol for Web services. JAXP API allows you to access and parse XML data. The main goal of JAXP is to provide an interface that lets the you create, manipulate, and use standard XML parsers without reference to the underlying implementation, allowing you to create parser-neutral code, and deferring parser selection to runtime.
JAX-RPC aids you in building XML-based requests such as SOAP requests, used for sending and receiving method calls using XML-based protocols. JAX-RPC API provides the high level framework to expose Java functionality as Web services that can be consumed by SOAP clients or as the way to consuming SOAP services and clients. In the typical JAX-RPC use case, the developer does not have to deal with XML and SOAP programming, thus enabling rapid application development. This not only does XML to Java mapping and vice-versa, also avoids you to interact directly with the XML representation of the call.
JAXM provides the framework for such XML data to interact between two applications. That is, JAXM allows the transfer of complete XML documents between two separate Web services. SOAP provides the underlying format of messages transferred between the applications. JAXM being a lightweight API, abstracts away the underlying message infrastructure. Hence it is easy to develop JAXM messages packaged via SOAP, which allows you to access SOAP messages quickly and easily.
SAAJ API allows you to manipulate simple SOAP messages. It can be used in combination with JAX-RPC, which is the J2EE standard API for sending and receiving SOAP messages, to represent literal XML document fragments. SAAJ is an integral part of the JAX-RPC, but you can also use it with other APIs such as JAXM.
The difference between JAXM and JAX-RPC is, JAXM supports the development of message-oriented middle ware-type applications, that allows you to focus on sending and receiving messages. Whereas, JAX-RPC supports the application for RPC behavior. JAX-RPC provides the Java interface to XML RPC calls as defined in SOAP.
The Coffee Break Example
The Coffee Break example demonstrates how each of the Java APIs for XML and Web services can be used.
Coffee Break Web Service Using Java APIs
The following steps describes the working of the Coffee Break Web service.
- The Coffee Break server obtains the information about the various types of coffees it sells and the prices associated, by querying the distributors at startup and on demand.
- The Coffee Break server uses JAXM messaging to communicate with one of its distributors. It has been dealing with this distributor for some time and has previously made the necessary arrangements for performing request-response JAXM messaging. The two parties have agreed to exchange four kinds of XML messages and have set up the DTDs that these messages will follow.
- The Coffee Break server uses JAXR to send a query searching for coffee distributors that support JAX-RPC to the Registry Server.
- The Coffee Break server requests the price lists from each of the coffee distributors. The server makes the appropriate remote procedure calls and waits for the response, which is a JavaBean component representing a price list. The JAXM distributor returns the price lists as XML documents.
- Upon receiving the responses, the Coffee Break server processes the price lists from the JavaBean components returned by calls to the distributors.
- The Coffee Break Server creates a local database of distributors.
- When an order is placed, suborders are sent to one or more distributors using the distributor's preferred protocol.
The code examples for the coffee break server is installed at install_dir/samples/webservices/cb. For more information on using the sample, see the sample application document.
Preparing for Developing Web Services and Clients
This section describes the pre-requisites to develop Web services and clients. This section presents the following topics:
Using Ant Tasks
You can use the automated assembly features available through Ant, a Java-based build tool available through the Apache Software Foundation:
http://jakarta.apache.org/ant/
Ant is a java-based build tool that is extended using Java classes. Instead of using shell commands, the configuration files are XML-based, calling out a target tree where tasks get executed. Each task is run by an object that implements a particular task interface.
In order to use ant tasks in your client environment, perform the following tasks:
- Include install_dir/appserver7/bin in the PATH environment variable. The Ant script provided with Sun ONE Application Server, asant, is located in this directory. For details on how to use asant, see the sample applications documentation in the
install_dir/appserver7/samples/docs/ant.html
For more information on using Ant tasks in Sun ONE Application Server environment, see the Sun ONE Application Server Developer's Guide.
Creating the build.xml File
Ant commands operate under the control of a build file, normally called build.xml, that defines the processing steps required.
The build.xml file provides several targets that support optional development activities. This build file includes targets for compiling the application, deploying the application to the application server, redeploying the modified application to the application server, and removing old copies of the application to regenerate their content.
For more information on creating an ant build file, see the Apache Ant Manual at:
http://jakarta.apache.org/ant/manual/index.html
Setting Up the Client Environment
A client uses various jar files that are bundled with Sun ONE Application Server. This section describes how to setup your client environment:
If you are developing a client application in the system where you have installed Sun ONE Application Server, the required jar files are included to help the development of a client.
If your client development environment is different from that of the system where Sun ONE Application Server is installed, you must perform the following steps:
If you are using version 1.3 of Java 2 SDK, perform the following steps:
- Copy the following jar files to your client development environment.
mail.jar - JavaMail API. Installed at install_dir/share/lib
activation.jar - JavaBeans Activation Framework. Installed at install_dir/share/lib.
fscontext.jar - Contains the file system service provider. Installed at install_dir/share/lib.
jaxm-api.jar - Java API for XML Messaging. Installed at install_dir/share/lib.
jaxrpc-api.jar - Java API for XML-based RPC. Installed at install_dir/share/lib.
jaxrpc-impl.jar - Java API for XML-based RPC implementation. Installed at install_dir/share/lib.
jaxr-api.jar - Java API for XML Registry. Installed at install_dir/share/lib.
jaxr-impl.jar - Java API for XML Registry implementation. Installed at install_dir/share/lib.
saaj.-api.jar - SOAP runtime API. Installed at install_dir/share/lib.
saaj-impl.jar - SOAP implementation. Installed at install_dir/share/lib.
commons-logging.jar - Contains a logging library package. Installed at install_dir/share/lib.
jaxp-api.jar - The javax.xml.parsers and javax.xml.transform components of JAXP. These packages contain the APIs that give applications a consistent way to obtain instances of XML processing implementations.
sax.jar - The APIs and helper classes for the Simple API for XML (SAX), used for serial access to XML data.
dom.jar - The APIs and helper classes for the Document Object Model (DOM), used to create an in-memory tree structure from the XML data.
xercesImpl.jar - The implementation classes for the SAX and DOM parsers, as well as xerces-specific implementations of the JAXP APIs.
xalan.jar - The "classic" (interpreting) XSLT processor.
xsltc.jar - The compiling XSLT processor.
- Add the following jar files to the starting of your classpath. These jar files must appear first in the classpath to avoid using any other parser:
- Add the rest of the jar files also to your classpath.
If you are using version 1.4 of Java 2 SDK for developing clients, perform the following step:
Copy all the jar files listed in Step 1, except the following to your client development environment and add them to your classpath.
The J2SE 1.4 is the first version of the JDK that bundles an implementation of JAXP 1.1. This allows developers to write applications without having to provide a parser and XSLT processor with their application. However, to override this implementation of JDK with a newer version, you need to use the `Endorsed Standards Override Mechanism'.
Overriding the JAXP Implementation
To use the JAXP 1.2 implementation, copy the following jar files into Java_home/jre/lib/endorsed/ directory:
If the /endorsed directory does not exist, you must create it.
Note The jaxp-api.jar file should not be copied, because it contains high-level APIs that are not subject to change.
The jar files must exist in Java_home/jre/lib/endorsed/ directory to override earlier versions of the Xalan libraries that are a standard part of the 1.4 platform. Because of that special requirement, it is not possible to specify these libraries using the -classpath option on the java/javac command line.
Alternatively, you can use the java.endorsed.dirs system property to dynamically add those jar files to the JVM when you start your client development. Using that system property gives you flexibility of using different implementations for different applications.
For more information on how to use `Endorsed Standards Override Mechanism', visit the following URL:
http://java.sun.com/j2se/1.4/docs/guide/standards