Constructing Services with J2EE

Web services are now a popular technology for implementing service-oriented applications. J2EE has become a popular platform to deploy web services applications. And J2EE 1.4 standardized building and deploying web services applications for the Java platform.

In my last article, I provided an introduction to service-oriented architecture (SOA) from a Java developer's perspective. In this article, I will explain how you can use J2EE 1.4 to build services that are interoperable and portable across J2EE 1.4-compliant application servers such as Oracle Application Server 10g.

Web Services Architecture

Let's briefly examine the architecture of a web service before drilling down into the details of web services development and deployment on the J2EE platform.

There are many definitions for web services, but in simple terms, web services are self-contained and self-describing components that can be published, discovered, and invoked across the network. A web service, as shown in Figure 1, may perform a simple function, such as checking a credit history, or a complicated task that can span several business processes.

Figure 1. How a web service works

There are two methods of interaction with web services: RPC style and document style. RPC-style web services were initially popular in the industry, but in recent years have been eclipsed by document-style as the preferred means of message exchange with web services.

Related Reading Java Web Services in a Nutshell By Kim Topley

RPC-style web services represent exchanges that can be modeled as remote procedure calls (RPC). These are quite common in business applications, with the exchanged messages conforming to a well-defined signature for the remote call and its return. In contrast, document-style web services model XML document exchange, where the exchange patterns are defined by the sending and the receiving applications. Document-style services are more relevant for applications that need to exchange business or other types of documents and, unlike RPC-style web services, the sender may not expect or wait for an immediate response.

Most developers would agree that web services is an effective technology for implementing SOA because it provides interoperability between heterogeneous platforms and technologies relying upon portable technologies such as XML, SOAP, and HTTP.

This independence of platform and implementation technology is the primary reason for web services' popularity. The clients do not have to know the implementation technology involved and can simply invoke the service over the network. For example, even if you build a service using Java/J2EE technologies and deploy it on a J2EE server such as Oracle Application Server Containers for J2EE (OC4J), the clients can be built using Microsoft's .NET framework.

Now that we have a basic understanding of web services, let's take a look at the elements that make up a web service.

What Are Web Services Made of?

A Web Services Definition Language (WSDL; pronounced "wizdle") document is at the heart of a web service. The WSDL describes the service, and is the "contract" to which the web service guarantees it will conform. The WSDL provides a complete description of the web service, including the port, operations, and message types involved.

Here is a simple example of a WSDL document that describes a HelloWorld web service:

<definitions 
 name="HelloService" 
 targetNamespace="http://oracle.j2ee.ws/ejb/Hello"
 xmlns="http://schemas.xmlsoap.org/wsdl/" 
 xmlns:tns="http://oracle.j2ee.ws/ejb/Hello" 
 xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" 
 xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/" 
 xmlns:ns1="http://oracle.j2ee.ws/ejb/Hello/types" 
 xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
 xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"> 
 <types> 
  <schema elementFormDefault="qualified" 
  targetNamespace="http://oracle.j2ee.ws/ejb/Hello/types" 
   xmlns="http://www.w3.org/2001/XMLSchema" 
   xmlns:soap11-enc="http://schemas.xmlsoap.org/soap/encoding/"
   xmlns:tns="http://oracle.j2ee.ws/ejb/Hello/types" 
   xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> 
  <complexType name="sayHello"> 
    <message name="HelloServiceInf_sayHello"> 
      <part name="parameters"
        element="ns1:sayHelloElement"/> 
    </message> 
    <message name="HelloServiceInf_sayHelloResponse"> 
      <part name="parameters" 
        element="ns1:sayHelloResponseElement"/> 
    </message> 
    <portType name="HelloServiceInf">
      <operation name="sayHello"> 
        <input message="tns:HelloServiceInf_sayHello"/> 
        <output message="tns:HelloServiceInf_sayHelloResponse"/>
      </operation> 
    </portType> 
    <sequence> 
      <element name="String_1" nillable="true" type="string"/> 
    </sequence> 
  </complexType> 
  <complexType name="sayHelloResponse"> 
    <sequence> 
    <element name="result" nillable="true" type="string"/> 
    </sequence> 
  </complexType> 
  <element name="sayHelloElement" type="tns:sayHello"/> 
  <element name="sayHelloResponseElement" 
    type="tns:sayHelloResponse"/> 
  </schema>
 </types> 
 <binding name="HttpSoap11Binding" type="tns:HelloServiceInf"> 
 <soap:binding style="document" 
      transport="http://schemas.xmlsoap.org/soap/http"/> 
 <operation name="sayHello">
   <soap:operation 
      soapAction="http://oracle.j2ee.ws/ejb/Hello:sayHello"/> 
   <input> 
     <soap:body use="literal" parts="parameters"/> 
   </input>
   <output> 
     <soap:body use="literal" parts="parameters"/> 
   </output> 
 </operation> 
 </binding> 
 <service name="HelloService"> 
   <port name="HttpSoap11" binding="tns:HttpSoap11Binding"> 
     <soap:address location="REPLACE_WITH_ACTUAL_URL"/> 
   </port>
</service>
</definitions> 

If you look at the WSDL, you'll note that it has a complete description of the HelloService web service, including the port, operations, and message types. The WSDL is the contract between the web service and its clients and it help automate the generation of client proxies.

The other two key technologies of the web services platform are SOAP, the protocol used to invoke a web service, and UDDI, which provides the registry where web services can be located.

Support for these technologies is fully integrated into the J2EE platform. Let's take a look at J2EE's web services support.

Using J2EE as a Web Services Platform

J2EE 1.4 provides a comprehensive platform for building and deploying web services applications using regular Java classes or Enterprise Java Beans. The following table provides the details of the web service APIs included in J2EE 1.4.

JAX-RPC

JAX-RPC, defined under JSR 101 in the Java Community Process, provides the Java API for building and accessing web services and is thus the "heart and soul" of building and deploying web services with the J2EE platform. It provides a simple, robust platform for building web services applications by hiding from the application developer the complexity of mapping between XML types and Java types and the lower-level details of handling XML and SOAP messages. It introduces a method call paradigm by providing two programming models: a server-side model for developing web service endpoints using Java classes or stateless EJBs, and a client-side model for building Java clients that access web services as local objects. JAX-RPC 1.1 mandates the use of SOAP 1.1 and interoperability with web services built with other technologies such as Microsoft .NET. J2EE-1.4-compliant application servers, such as OC4J 10.1.3 and the Sun Java System Application Sever, provide support for JAX-RPC.

JAX-RPC is somewhat of a misnomer, since it supports both RPC-style and document-style web services.

Web Services Deployment Model

Prior to J2EE 1.4, all J2EE vendors supported web services using their proprietary deployment models. J2EE 1.4 defined the deployment model for Java web services. It standardized development, deployment, and service publication and consumption for web services for the J2EE platform.

I will discuss the deployment and consumption aspects of Java-based web services later in this article.

Given the J2EE 1.4 support for web services, let's examine the way in which a web service is constructed using the J2EE platform.

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.

/META-INF/
    ejb-jar.xml    
    webservices.xml    
          oracle-webservices.xml    
    mapping-file.xml   
          wsdl/ the wsdl file 
    ejb classes (includes endpoint and bean classes)

Web app (.war) for a regular Java web service:

/WEB-INF/
    web.xml 
    webservices.xml    
    oracle-webservices.xml    
    mapping-file.xml    
    wsdl/        the wsdl file     
    /classes/(includes endpoint and bean classes)
    /lib/

Let us discuss each of the deployment-time artifacts and descriptors:

• WSDL: As previously described.
• 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:

  <service-endpoint>
      oracle.ejb21.ws.HelloServiceInf
  </service-endpoint>
  

  The following shows the code for the Web service endpoint for a HelloWorld web service:

  
  public interface HelloServiceInf
                   extends java.rmi.Remote {
  java.lang.String sayHello(java.lang.String name)
                      throws java.rmi.RemoteException;
  }
  
  

• 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.

Interoperability Matters

Obviously, it is imperative that your web services be interoperable in nature. J2EE 1.4 mandates conformance to the Basic Profile 1.0 specified by the Web Services: Interoperability (WS-I) organization. When building web services, you must test for interoperability before you deploy them into production.

In addition to the design approaches and a need to field interoperable services, there are a few best practices that you can follow to maximize the utility of your web service.

Best Practices

Here are a few best practices for developing web services:

• Avoid overusing web services in your applications. Examine whether you really need to expose your applications as a web service.
• 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.

The J2EE Blueprint Application Java Adventure Builder provides a nice blueprint application for building Java-based web services application.

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:

  <service-ref>        
       <service-ref-name>service/HelloWorldService</service-ref-name>
       <service-interface>oracle.ws.HelloWorldService</service-interface>
        <wsdl-file>META-INF/HelloWorldService.wsdl</wsdl-file>
        <service-qname>urn:oracle-ws</service-qname>
  </service-ref>
  

• 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:

  <service-ref-mapping name="service/HelloWorldService">
      <port-info>
        <wsdl-port namespaceURI="urn: HelloWorldService" 
                           localpart="HelloWorldServicePort"/>
      <stub-property>
           <name>javax.xml.rpc.service.endpoint.address</name>
           <value>http://localhost:8888/hello/HelloWorldInf</value>
      </stub-property>
     </port-info>
  </service-ref-mapping>
  

• You must package end-point interface and type classes with your application prior to deployment in your server. You can make a JNDI lookup to use a web service:

  InitialContext ctx= new InitialContext();
  HelloServiceInf hs = (HelloServiceInf)
               ctx.lookup("java:comp/env/service/HelloWorldService");
  HelloWorld hello= hs.getHelloWorldServicePort();
  String myhello = hs.sayHello("Debu Panda") ;
  

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:

package oracle.jr181.demo; 
import javax.jws.WebMethod; 
import javax.jws.WebService; 
@WebService(name = "HelloWorldService", 
      targetNamespace = "http://hello/targetNamespace" ) 
public class HelloWorldService {        
@WebMethod public String sayhello(String name ) { 
     return "Hello” +name+ “ from jws";
    }   
}
  

package oracle.ejb30.ws;
import javax.ejb.Remote;
import javax.jws.WebService;
@WebService  
public interface HelloServiceInf extends java.rmi.Remote{
@WebMethod java.lang.String sayHello(java.lang.String name) 
                              throws java.rmi.RemoteException;
}

The following is the implementation class for the HelloWorld EJB in EJB 3.0:

package oracle.ejb30.ws;
import java.rmi.RemoteException;
import javax.ejb.Stateless;
@Stateless(name="HelloServiceEJB")
public class HelloServiceBean implements HelloServiceInf {
public String sayHello(String name) {
 return("Hello "+name +" from first EJB3.0 Web Service");
 }
}

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.

Resources

• Example web service used in this article
• " How To Develop a Web Service From an Existing Java Class" ( .zip)
• " How To Develop a Web Service From a WSDL Document" ( .zip)
• "Service-Oriented Architecture: Beyond Web Services" by Ted Farrell
• "Service-Oriented Architecture: Parts 1 & 2" by Samudra Gupta
• " What is Service Oriented Architecture?" by Hao He
• OTN Web Services Technology Center
  

Debu Panda is a Senior Principal Product Manager of the Oracle Application Server development team.

Return to ONJava.com.

Copyright © 2009 O'Reilly Media, Inc.