Download An introduction to creating Web services applications in Rational

An introduction to creating
Web services applications in
Rational Application Developer Version 8.0
September 2010
© Copyright IBM Corporation 2010.
1
Overview
A Web service is a set of related application functions that can be
programmatically invoked over the Internet. Businesses can dynamically mix and
match Web services to perform complex transactions with minimal programming.
Web services allow buyers and sellers all over the world to discover each other,
connect dynamically, and execute transactions in real time with minimal human
interaction.
Web services are self-contained, self-describing modular applications that can
be published, located, and invoked across the Web.
•
•
•
•
Web services are self-contained. On the client side, no additional software
is required. A programming language with XML and HTTP client support is
enough to get you started. On the server side, a Web server and servlet
engine are required. The client and server can be implemented in different
environments. It is possible to Web service enable an existing application
without writing a single line of code.
Web services are self-describing. The client and server need to recognize
only the format and content of request and response messages. The
definition of the message format travels with the message; no external
metadata repositories or code generation tools are required.
Web services are modular. Simple Web services can be aggregated to form
more complex Web services either by using workflow techniques or by calling
lower layer Web services from a Web service implementation.
Web Services are platform independent. Web services are based on a
concise set of open, XML-based standards designed to promote
interoperability between a Web service and clients across a variety of
computing platforms and programming languages.
Web services might be anything, for example, theatre review articles, weather
reports, credit checks, stock quotations, travel advisories, or airline travel
reservation processes. Each of these self-contained business services is an
application that can easily integrate with other services, from the same or
different companies, to create a complete business process. This interoperability
allows businesses to dynamically publish, discover, and bind a range of Web
services through the Internet.
Categories of Web services
Web services can be grouped into three categories:
© Copyright IBM Corporation 2010.
2
•
•
•
Business information. A business shares information with consumers or
other businesses. In this case, the business is using Web services to expand
its scope. Examples of business informational Web services are news
streams, weather reports, or stock quotations.
Business integration. A business provides transactional, "for fee" services to
its customers. In this case, the business becomes part of a global network of
value-added suppliers that can be used to conduct commerce. Examples of
business integration Web services include bid and auction e-marketplaces,
reservation systems, and credit checking.
Business process externalization. A business differentiates itself from its
competition through the creation of a global value chain. In this case, the
business uses Web services to dynamically integrate its processes. An
example of business process externalization Web services is the associations
between different companies to combine manufacturing, assembly, wholesale
distribution, and retail sales of a particular product.
Service roles and interactions
A network component in a Web Services architecture can play one or more
fundamental roles: service provider, service broker, and service client.
•
•
•
Service providers create and deploy their Web services and can publish the
availability of their WSDL-described services through a service registry, such
as a UDDI Business Registry.
Service brokers register and categorize published services and provide search
services. For example, UDDI acts as a service broker for WSDL-described
Web services.
Service clients use broker services such as the UDDI Business Registry to
discover a needed WSDL-described service and then bind to and call the
service provider.
Binding involves establishing all environmental prerequisites that are necessary
to successfully complete the services. Examples of environmental prerequisites
include security, transaction monitoring, and HTTP availability. The relationships
between these roles are described in Figure 1.
© Copyright IBM Corporation 2010.
3
Web services standards
One of the key attributes of Internet standards is that they focus on protocols and
not on implementations. The Internet is composed of heterogeneous
technologies that successfully interoperate through shared protocols. This
prevents individual vendors from imposing a standard on the Internet. Open
Source software development plays a crucial role in preserving the
interoperability of vendor implementations of standards.
The following standards play key roles in Web services: Universal Description,
Discovery and Integration (UDDI), Web Services Description Language (WSDL),
Web Services Inspection Language (WSIL), SOAP, and Web Services
Interoperability (WS-I). The relationship between these standards is described in
Figure 2.
The UDDI specification defines open, platform-independent standards that
enable businesses to share information in a global business registry, discover
services on the registry, and define how they interact over the Internet. For more
information on UDDI, refer to www.uddi.org.
WSIL is an XML-based open specification that defines a distributed service
discovery method that supplies references to service descriptions at the service
provider's point-of-offering, by specifying how to inspect a Web site for available
Web services. A WSIL document defines the locations on a Web site where you
can look for Web service descriptions. Since WSIL focuses on distributed
service discovery, the WSIL specification complements UDDI by facilitating the
discovery of services that are available on Web sites that may not be listed yet in
a UDDI registry. For more information on WSIL, refer to www.ibm.com/
developerworks/webservices/library/ws-wsilspec.html
© Copyright IBM Corporation 2010.
4
WSDL is an XML-based open specification that describes the interfaces to and
instances of Web services on the network. It is extensible, so endpoints can be
described regardless of the message formats or network protocols that are used
to communicate. Businesses can make the WSDL documents for their Web
services available though UDDI, WSIL, or by broadcasting the URLs to their
WSDL via email or Web sites. WSDL is described as a separate topic in this
documentation. For more information on WSDL, refer to www.w3.org/TR/wsdl
SOAP is an XML-based standard for messaging over HTTP and other Internet
protocols. It is a lightweight protocol for the exchange of information in a
decentralized, distributed environment. It is based on XML and consists of three
parts:
•
An envelope that defines a framework for describing what is in a message and
how to process it.
•
A set of encoding rules for expressing instances of application-defined data
types.
•
A convention for representing remote procedure calls and responses.
SOAP enables the binding and usage of discovered Web services by defining a
message path for routing messages. SOAP may be used to query UDDI for Web
services. For more information on SOAP 1.1 (SOAP 1.2 is not supported by the
Web services tools), refer to www.w3.org/TR/SOAP
© Copyright IBM Corporation 2010.
5
A service provider hosts a Web service and makes it accessible using protocols
such as SOAP/HTTP or SOAP/JMS. The Web service is described by a WSDL
document that is stored on the provider's server or in a special repository. The
WSDL document may be referenced by the UDDI business registry and WSIL
documents. These contain pointers to the Web service's WSDL files.
The WS-I Simple SOAP Binding Profile and WS-I Attachments Profile are
outlines of requirements to which WSDL and Web service protocol (SOAP/
HTTP) traffic must comply in order to claim WS-I conformance. The Web
services WS-I validation tools currently support WS-I Simple SOAP Binding
Profile 1.0 and the Attachment Profile 1.0. To view the specifications, refer to the
WS-I Web site, and under Resources select Documentation: http://www.ws-i.org
Several new Web services standards are also supported by this development
environment. These include:
© Copyright IBM Corporation 2010.
6
JAX-RPC
JAX-RPC stands for Java™ API for XML-based RPC, also known as JSR 101. It
is a specification that describes Java Application Programming Interfaces (APIs)
and conventions for building Web services and Web service clients that use
remote procedure calls (RPC) and XML. It standardizes the Java to WSDL and
WSDL to Java mappings, and provides the core APIs for developing and
deploying Web services and Web service clients on the Java platform. For more
information refer to the official specifications.
JSR-109
JSR-109 (Implementing Enterprise Web Services) defines the programming
model and run-time architecture to deploy and look up Web services in the Java
EE environment; more specifically, in the Web, EJB, and Client Application
containers. One of its main goals is to ensure vendors' implementations
interoperate. For more information, refer to the official specifications:
• JSR-109
• JSR-921
WS-S
These tools support the OASIS Web Services Security 1.0 standard. For more
information on the various components of this standard, refer to:
• Web Services Security: SOAP Message Security V1.0
• Web Services Security: Username Token Profile V1.0
• Web Services Security: X.509 Token Profile V1.0
Web Services Description Language (WSDL)
Web Services Description Language (WSDL) is a standard specification for
describing networked, XML-based services. It provides a simple way for service
providers to describe the basic format of requests to their systems regardless of
the underlying run-time implementation.
WSDL defines an XML format for describing network services as a set of
endpoints that operate on messages that contain either document-oriented or
procedure-oriented information. The operations and messages are first
described abstractly and then bound to a concrete network protocol and
message format in order to define an endpoint. Related concrete endpoints are
combined into abstract endpoints (services). WSDL is extensible to allow
description of endpoints and their messages, regardless of which message
formats or network protocols are used to communicate. This means that
interfaces are defined abstractly using XML schema and then bound to concrete
representations that are appropriate for the protocol.
© Copyright IBM Corporation 2010.
7
WSDL allows a service provider to specify the following characteristics of a Web
service:
•
The name of the Web service and addressing information
•
The protocol and encoding style to be used when accessing the public
operations of the Web service
•
The type information such as operations, parameters, and data types
comprising the interface of the Web service
WSDL documents allow developers to expose their applications as networkaccessible services on the Internet. Through UDDI and WSIL, other applications
can discover WSDL documents and bind with them to execute transactions or
perform other business processes.
This development platform supports and encourages the development and use
of WS-I compliant WSDL. Business service providers can deploy Java™ beans
and enterprise beans as a Web service and generate a WSDL document that
describes the service. They can also generate Java and enterprise bean
skeletons from an existing WSDL file. A business service client can generate a
Java proxy from a WSDL document, thereby providing an easy-to-use Java
interface to the Web service. The Java interface hides the network
communications details from the client enabling the business service provider to
focus on business and process portions of the application.
In addition to providing tools to create Web services, the workbench provides a
WSDL editor that allows you to create WSDL files using a graphical interface, a
WSDL validator that ensures that your WSDL file is semantically correct and
optionally checks for WS-I compliance, and the Web Services Explorer which
allows you to dynamically test Web services without requiring you to generate a
proxy.
Rational Application Developer supports WSDL 1.1. For more information on the
WSDL specification, refer to www.w3.org/TR/wsdl.
JAX-WS
Java™ API for XML-Based Web Services (JAX-WS), which is also known as
JSR-224, is the next generation Web services programming model that extends
the foundation provided by the Java API for XML-based RPC (JAX-RPC)
programming model. Using JAX-WS, developing Web services and clients is
simplified with greater platform independence for Java applications by the use of
dynamic proxies and Java annotations. The Web services tools included in this
product support JAX-WS 2.0 and 2.1.
JAX-WS is a new programming model that simplifies application development
© Copyright IBM Corporation 2010.
8
through support of a standard, annotation-based model to develop Web Service
applications and clients. The JAX-WS programming standard strategically aligns
itself with the current industry trend toward a more document-centric messaging
model and replaces the remote procedure call programming model as defined by
JAX-RPC. Although this product still supports the JAX-RPC programming model
and applications, JAX-RPC has limitations and does not support many current
document-centric services. JAX-WS is the strategic programming model for
developing Web services and is a required part of the Java EE 5 platform.
Implementing the JAX-WS programming standard provides the following
enhancements for developing Web services and clients:
Better platform independence for Java applications
Using JAX-WS APIs, developing Web services and clients is simplified with
better platform independence for Java applications. JAX-WS takes advantage of
dynamic proxies whereas JAX-RPC uses generated stubs. The dynamic proxy
client invokes a Web service based on a Service Endpoint Interface (SEI) which
is generated or provided. The dynamic proxy client is similar to the stub client in
the JAX-RPC programming model. Although the JAX-WS dynamic proxy client
and the JAX-RPC stub client are both based on the Service Endpoint Interface
(SEI) that is generated from a WSDL file , there is a major difference. The
dynamic proxy client is dynamically generated at run time using the Java 5
dynamic proxy functionality, while the JAX-RPC-based stub client is a nonportable Java file that is generated by tooling. Unlike the JAX-RPC stub clients,
the dynamic proxy client does not require you to regenerate a stub prior to
running the client on an application server for a different vendor because the
generated interface does not require the specific vendor information. Refer to
Chapter 4 of the JAX-WS 2.0 specification for more information on using
dynamic proxy clients.
Annotations
JAX-WS introduces support for annotating Java classes with metadata to
indicate that the Java class is a Web service. JAX-WS supports the use of
annotations based on the Metadata Facility for the Java Programming Language
(JSR 175) specification, the Web Services Metadata for the Java Platform (JSR
181) specification and annotations that are defined by the JAX-WS 2.0
specification. Using annotations in the Java source and in the Java class
simplifies development of Web services by defining some of the additional
information that is typically obtained from deployment descriptor files, WSDL
files, or mapping metadata from XML and WSDL files into the source artifacts.
For example, you can embed a simple @WebService tag in the Java source to
expose the bean as a Web service.
© Copyright IBM Corporation 2010.
9
The annotation @WebService tells the server runtime environment to expose all
public methods on that bean as a Web service. Additional levels of granularity
can be controlled by adding additional annotations on individual methods or
parameters. Using annotations makes it much easier to expose Java artifacts as
Web services. In addition, as artifacts are created from using some of the topdown mapping tools starting from a WSDL file, annotations are included within
the source and Java classes as a way of capturing the metadata along with the
source files.
Invoking Web services asynchronously
With JAX-WS, Web services can be called both synchronously and
asynchronously. JAX-WS adds support for both a polling mechanism and
callback mechanism when calling Web services asynchronously. Using a polling
model, a client can issue a request, get a response object back, which is polled
to determine whether the server has responded. When the server responds, the
actual response is retrieved. Using the polling model, the client can continue to
process other work without waiting for a response to return. Using the callback
model, the client provides a callback handler to accept and process the inbound
response object. Both the polling and callback models enable the client to focus
on continuing to process work while providing for a more dynamic and efficient
model to invoke Web services.
For example, a Web service interface has methods for both synchronous and
asynchronous requests. Asynchronous requests are identified in bold in the
following example:
© Copyright IBM Corporation 2010.
10
The asynchronous invocation that uses the callback mechanism requires an
additional input by the client programmer. The callback handler is an object that
contains the application code that will be executed when an asynchronous
response is received. The following is a code example for an asynchronous
callback handler:
The following is a code example for an asynchronous polling client:
© Copyright IBM Corporation 2010.
11
Data binding with JAXB 2.0 and 2.1
JAX-WS leverages the JAXB API and tools as the binding technology for
mappings between Java objects and XML documents. JAX-WS tooling relies on
JAXB tooling for default data binding for two-way mappings between Java
objects and XML documents. JAXB data binding replaces the data binding
described by the JAX-RPC specification.
WebSphere® Application Server Version 7.0 supports the JAXB 2.1
specification. JAX-WS 2.1 requires JAXB 2.1 for data binding. JAXB 2.1 provides
enhancements such as improved compilation support and support for the
@XMLSeeAlso annotation, and full schema 1.0 support.
Dynamic and static clients
The dynamic client programming API for JAX-WS is called the dispatch client
(javax.xml.ws.Dispatch). The dispatch client is an XML messaging oriented
client. The data is sent in either PAYLOAD or MESSAGE mode. When using the
PAYLOAD mode, the dispatch client is only responsible for providing the
contents of the <soap:Body> element and JAX-WS adds the <soap:Envelope>
and <soap:Header> elements. When using the MESSAGE mode, the dispatch
client is responsible for providing the entire SOAP envelope including the
<soap:Envelope>, <soap:Header>, and <soap:Body> elements and JAX-WS
does not add anything additional to the message. The dispatch client supports
asynchronous invocations using a callback or polling mechanism. </
soap:Body></soap:Header></soap:Envelope></soap:Header></
soap:Envelope></soap:Body>
The static client programming model for JAX-WS is the called the proxy client.
The proxy client invokes a Web service based on a Service Endpoint interface
(SEI) which is generated or provided.
© Copyright IBM Corporation 2010.
12
MTOM support
Using JAX-WS, you can send binary attachments such as images or files along
with Web services requests. JAX-WS adds support for optimized transmission of
binary data as specified by Message Transmission Optimization Mechanism
(MTOM).
Multiple payload structures
JAX-WS exposes the following binding technologies to the user: XML Source,
SOAP Attachments API for Java (SAAJ) 1.3, and Java Architecture for XML
Binding (JAXB) 2.0. XML Source enables a user to pass a
javax.xml.transform.Source into the runtime which represents the data in a
Source object to be passed to the runtime. SAAJ 1.3 now has the ability to pass
an entire SOAP document across the interface rather than just the payload itself.
This is done by the client passing the SAAJ SOAPMessage object across the
interface. JAX-WS leverages the JAXB 2.0 support as the data binding
technology of choice between Java and XML.
SOAP 1.2 support
Support for SOAP 1.2 was added to JAX-WS 2.0. JAX-WS supports both SOAP
1.1 and SOAP 1.2. SOAP 1.2 provides a more specific definition of the SOAP
processing model, which removes many of the ambiguities that sometimes led to
interoperability problems in the absence of the Web Services-Interoperability
(WS-I) profiles. SOAP 1.2 should reduce the chances of interoperability issues
with SOAP 1.2 implementations between different vendors. It is not interoperable
with earlier versions.
JAX-WS 2.1.6
When a JAX-WS Web service is created from a Java class, the class's public
methods are exposed as operations and become part of the Web service's
WSDL contract. The mapping between these methods and operations is
governed mainly by JSR-181 and JSR-250. With these rules, a public method in
a Java class and its hierarchy up to but excluding java.lang.Object are exposed
when the following conditions are true:
•
The method is annotated with @WebMethod or @WebMethod(exclude=false)
and the containing class has an @WebService annotation
•
The method has no @WebMethod annotation but the containing class has an
@WebService annotation and no other methods are annotated with
@WebMethod or @WebMethod(exclude=false)
JAX-WS 2.1.6 alters the rules for how a Java class's methods are exposed on
the Web service interface. Now, a public method in a Java class and its
hierarchy up to but excluding java.lang.Object are exposed when the following
© Copyright IBM Corporation 2010.
13
conditions are true:
•
The method has an @WebMethod or @WebMethod(exclude=false)
annotation.
•
The method has no @WebMethod annotation but the containing class has a
@WebService annotation.
Example:
Before JAX-WS 2.1.6, the only exposed method would be public void exposed
(String s). In JAX-WS 2.1.6 and later the following methods will be exposed:
WebSphere Application Server will be picking up these changes in version
7.0.0.7 through IBM® JDK 6 SR6. To enable the workbench to provide guidance
on using JAX-WS 2.1.6, go to Window > Preferences > General > Service
policies > WebSphere Programming Models > JAX-WS and set the JAX-WS
2.1.6 method exposure guidance setting to true.
For more information on JAX-WS, refer to the official JSR-224 specification: JSR
224: Java API for XML-Based Web Services (JAX-WS) 2.0
Tools for Web services development
Rational Application Developer provides a set of tools to assist with the following
aspects of Web services development:
© Copyright IBM Corporation 2010.
14
•
Discover. Browse the UDDI Business Registries or WSIL documents to locate
existing Web services for integration.
•
Create or Transform. Create bottom-up Web services from existing artifacts,
such as Java™ beans and enterprise beans. Create top-down Web services
from WSDL discovered from others or created using the WSDL Editor.
•
Build. Wrap existing artifacts as SOAP accessible services and describe them
in WSDL. The Web services wizards assist you in generating a Java client
proxy to Web services described in WSDL and in generating Java bean
skeletons from WSDL.
•
Deploy. Deploy Web services into a variety of test environments.
•
Test. Test Web services running locally or remotely in order to get instant
feedback.
•
Develop. Generate sample applications to assist you in creating your own
Web service client application.
•
Publish. Publish Web services to a UDDI v2 or v3 Business Registry,
advertising your Web services so that other businesses and clients can
access them.
Services view
The Services view within the Java EE and Web perspectives of Rational
Application Developer allows Web services developers to quickly access a
variety of tools which simplify Web services development. Although these tasks
can also be performed in the Enterprise Explorer view, the Services view only
shows the Web services and clients making it easier to find what you are looking
for.
The JAX-WS tools you can launch from the Services view include the following:
WSDL interface editor
You can launch the WSDL file for your Web service or client in the WSDL editor
in order to view or edit it. This is available for both static WSDL files in your
workspace, and dynamic WSDL files generated by the runtime. Note that
dynamic WSDL files cannot be edited.
Deployment descriptor editors
If your Web service or client has deployment descriptors available, you can
launch the Deployment Descriptor Editor to edit the webservices.xml file.
Generate deployment descriptors
If you have not previously generated a deployment descriptor, you can do so
© Copyright IBM Corporation 2010.
15
from this view. Although deployment descriptors are not required for JAX-WS
Web services because the runtime can generate this information on the fly, by
generating deployment descriptors into your workspace you can customize the
deployment settings.
Generate a Web service or client
Depending on the object selected, you may be able to generate a top-down or
bottom-up Web service, or a Web service client.
Test with the Web Services Explorer
You can test the function of your Web service based on either a static or
dynamic WSDL file using the Web Services Explorer.
Manage the policy sets for the Web service or client
You can apply and edit WebSphere® policy sets which regulate the qualities of
service for your Web services and clients.
Configure JAX-WS Web service handlers
This launches the JAX-WS Service Handlers Configuration wizard, which
enabled you to add or edit handlers for your JAX-WS Web service.
Create router modules
This option is available for EJB Web services. The Create Router Modules
wizard enables a set of Web services within an Enterprise Application Archive
(EAR) file. For each Web service-enabled EJB JAR in the EAR file, it adds an
HTTP router, a JMS router, or both to the EAR. Each router module provides a
Web service endpoint for a particular transport.
Web services runtime environments
Rational Application Developer supports the following runtime environments
Web service generation:
•
IBM® WebSphere® JAX-WS runtime environment
•
IBM WebSphere JAX-RPC runtime environment
•
Apache Axis 1.4 runtime environment
The IBM WebSphere JAX-WS runtime environment is the strategic Web
services runtime supported by IBM. The IBM WebSphere JAX-RPC runtime is a
legacy environment which is still supported, however new applications should
use JAX-WS whenever possible. The Apache Axis 1.4 runtime is an open source
runtime supported by the tools, however it is not recommended for use in a
production environment.
© Copyright IBM Corporation 2010.
16
For more information
To learn more about Web Services and Rational Application Developer, see
these resources:
•
Rational Application Developer Web site:
http://www-01.ibm.com/software/awdtools/developer/application/index.html
•
Rational Application Developer Information Center:
http://publib.boulder.ibm.com/infocenter/radhelp/v8/index.jsp
•
Rational Application Developer wiki:
https://www.ibm.com/developerworks/wikis/display/rad/Home
© Copyright IBM Corporation 2010.
17