Building a Web Service with J2EE

Creating a web service as a distributed component that is
portable and interoperable is not a trivial task. As discussed
earlier, you can deploy either regular Java classes or stateless
EJBs as web services. Regular Java classes are packaged in a web
module and EJB web services are packaged in normal ejb-jar
modules.

Given these two deployment options, which one do you use?

Java Class versus Stateless EJB: The Endless Debate

It is a matter of prolonged debate whether you should choose a
regular Java class or EJBs as your technology for building a web
service. Java classes are easier to develop than EJBs, are pure
Java objects, and do not have the "extra baggage" that EJBs do.
However, EJBs provide several nice features, such as declarative
transaction and security, and let the developer concentrate on
building business logic without having to worry about the
infrastructure services.
EJB 3.0 is
greatly simplifying the programming model and in that spec EJBs
will look like regular Java classes.

Packaging Requirement

Whether you decide to use a regular Java class or EJBs, you need
to package several artifacts into your WAR or ejb-jar to expose your
component as a Java web service. Following are the packaging
structures for web services based either on EJB or regular Java
classes.

Endpoint interface: The web service endpoint
should implement the java.rmi.Remote interface, and
every method exposed in the endpoint interface must throw
java.rmi.RemoteException. This end point needs to
registered into the standard deployment descriptor for the module
(ejb-jar.xml or web.xml). Your deployment
descriptor (e.g., ejb-jar.xml) needs to have the following entry:

Web service deployment descriptors: The J2EE
platform requires a standard deployment descriptor named
webservices.xml. This descriptor specifies the set of
web service descriptions for deployment into the J2EE application
server and their dependencies on container resources and services.
It also specifies the location of the WSDL; mapping.xml, which
contains Java-to-WSDL mapping; and the service endpoint interface
for the HelloWorld web service. An example
webservices.xml is packaged with the code sample
provided in the Resources section.

Vendor-specific deployment descriptors:
Several implementation-specific references, such as the context root
and endpoint addresses, cannot be specified in the web services
deployment descriptor. Instead, you should specify them in the
vendor-specific deployment descriptor. For example, if you are
using OC4J, you will need to package an oracle-webservices.xml file
in WAR or ejb-jar or to define these properties.

Java-WSDL mapping: This file defines the
mappings between WSDL and Java types. There is no standard name for
the mapping file; the web services deployment descriptor determines
its name.

You must package all these artifacts in the WAR or ejb-jar
module before you can deploy your component as a web service. Many
development tools, such as
Oracle JDeveloper, simplify development of web services by
doing mundane tasks such as generating deployment descriptors,
mapping files, etc. Furthermore, most application servers provide
web services assembly tools that take care of the J2EE web service
packaging requirements.

Beyond an understanding of the components that make up a web
service and the associated packaging requirements, there are
architectural issues you must deal with when developing a web
service.

Approaches to Constructing Services

The main challenge in building a web service is to identify the
service with the right granularity. You can either build a new
service, or expose an existing component that is built as a Java
class or EJB and expose that as a service. When building a service,
you can take either the top-down or bottom-up approach:

Bottom-up approach: This approach allows an
existing Java class or EJB to be exposed as a web service. This is
a very popular method of building services, because it allows you to
reuse your existing business logic without having to rewrite your
applications. If you take this approach, you have to add a web
service end-point interface for the implementation that you want to
expose as a web service, and create a WSDL that describes the web
service as well as other deployment descriptors. Tools provided by
application servers such as Oracle Application Server's web
services assembler tool makes life simpler by generating WSDL,
descriptors such as webservices.xml, and mapping files
for Web services components--freeing developers from manually
creating these files.

Top-down approach: This is the "pure" approach
for building services, and is more relevant when you are building
your services from scratch. You start by describing the service
with WSDL rather than jumping right into implementation. This
approach is certainly preferred to the bottom-up approach, because
services become more usable, maintainable, and interoperable due to
careful consideration of the operations and messages exposed, as
well as the control you have over the WSDL while developing your
web service. Several J2EE vendors offer tools that make this
approach easier; for example, Oracle Application Server's web
services assembler generates interfaces, deployment descriptors,
and skeleton implementation classes with which you can build your
application.

Best Practices

Modularity of services is very important. Use a coarse-grained
web service; e.g., a session facade that encapsulates your business
logic to be used as a web service.

Make sure you design your web service so that it creates
minimal network traffic.

Adhere to the WS-I Basic Profile. Use JAX-RPC data types as the
method parameters for your web service to give it interoperability
with heterogeneous web services. Avoid types such as Collections,
HashMaps, and Lists as parameters for your web service if interoperability is important for your application.

Many of the conventional best practices for J2EE applications
are also relevant to web services. For example, avoid exposing a
component that involves long-running transactions as a web
service.

Weigh your security requirements for web services against
performance, because security comes with a higher cost. The
performance costs of end-to-end security for web services are quite
high.

Once a web service has been designed, developed, and deployed,
associated client components are generally created to interact with
the given service.

Invoking Web Services

The client for a web service can be any of the following types:
static stub, dynamic proxy, or Dynamic Invocation Interface
(DII).

Building a web service client may be as complex as building a
simple web service. Fortunately, J2EE 1.4 makes it simpler for J2EE
developers to use web services from any type of J2EE component--namely web clients or EJB components.

You can invoke a web service as you would any other resources using JNDI
via the following:

Define a service-ref element in the deployment
descriptor for your component. For example, if you access the
HelloWorldService web service from a web module, the module's
web.xml file may contain the following:

To enable your application to find the web service, you must
specify the web service's location in your vendor-specific
deployment descriptor. For example, if you use OC4J to look up the
web service from your web module, the vendor-specific web
descriptor orion-web.xml should have the following contents
to look up the component:

The Future of Java Web Services

Uptake of Emerging Web Services Standards

The web services platform has grown to include reliability,
security, transactions, manageability, policy and so
on. There are several standards that has emerged or emerging
in the web services space. There are several JSRs being worked on in
the Java Community Process to design a new Java API to uptake these
emerging standards and the following table lists some of these
JSRs.

In addition to these evolving standards, we are now getting a
glimpse into the web services support afforded by the next major
release of the J2EE platform.

Simplifying SOA Development with J2EE 5.0

Service-oriented applications are fairly difficult to build
with J2EE, so J2EE 5.0 is designed to make development simpler by
making use of Web Services Metadata annotations defined by
JSR 181.
EJB 3.0 and Web
Services Metadata have the similar goals of providing developer
friendliness.

For developing a simple Java web service in J2EE 1.4, you need
several web service artifacts: WSDL, mapping files, and several
verbose standard and proprietary web services deployment
descriptors. The Web Services Metadata specification is taking a
configuration-by-default approach similar to EJB 3.0 to make
development easier. The Web Services Metadata annotation processor
(or web services assembly tool) will generate these files for you
so you only have to worry about the implementation class.

Here is how a simple Java web service looks when it's developed
using Web Services Metadata:

As I mentioned previously, EJB 3.0 is simplifying the development of
EJBs by using regular Java classes. By making use of EJB 3.0
and Web Services Metadata, developing EJB-based web services is
going to be much simpler. Here is how a simple HelloWorld EJB web
service looks when using EJB 3.0 and web services metadata. You do
not have to worry about creating WSDL, deployment descriptors, etc.,
and the application server will take care of generating these
artifacts during deployment.

The above example clearly demonstrates that service development
is going to be much simpler with web services metadata and EJB
3.0.

Conclusion

In this article, you learned the basics of building web services
using the J2EE platform. You can start building and deploying your
web services in your favorite J2EE-compliant application servers
such as Oracle Application Server 10g, Sun Java System Application
Sever, etc. today.