Java Web Services

What are Web Services?• Definition of Web Services

• The World Wide Web Consortium (W3C) organization, which establishes the standards for Web services, defines them as follows: "A Web service is a software system identified by a URI whose public interfaces and bindings are defined and described using XML.

• A simpler definition, and perhaps more useful, might be: "a Web service is a software application, accessible on the Web through a URL, that is accessed by clients using XML-based protocols, such as Simple Object Access Protocol (SOAP) sent over accepted Internet protocols, such as HTTP. Clients access a Web service application through its interfaces and bindings, which are defined using XML artifacts, such as a Web Services Definition Language (WSDL) file."

Web services provide a standardized way for applications to expose their functionality over the Web or communicate with other applications over a network, regardless of the application's implementation, programming language, or computer platform.

Web Services Benefits of Web Services

• Interoperability in a heterogeneous environment

• Business services through the Web

• Integration with existing systems

• Freedom of choice

• Support more client types

• Programming productivity

Web services standards include: • Common markup language for communication: Web services use eXtensible

Markup Language (XML) for the common markup language.

• Common message format for exchanging information: Simple Object Access Protocol (SOAP) provides a common message format for Web services.

• Common service specification formats: Web Services Description Language (WSDL) provides Web services with common specification formats.

• Common means for service lookup: Universal Description, Discovery, and Integration (UDDI) specification defines a common means for looking up Web services.

Web Services The Web Services Description Language (WSDL) defines a

standard way for specifying the details of a Web service. • It is a general-purpose XML schema that can be used to specify details of

Web service interfaces, bindings, and other deployment details. • By having such a standard way to specify details of a service, clients can still

use that Web service without prior knowledge of the service . • WSDL specifies a grammar that describes Web services as a collection of

communication endpoints, called ports. • The data being exchanged are specified as part of messages. Every type of

action allowed at an endpoint is considered an operation. • Collections of operations possible on an endpoint are grouped together into

port types. • The protocol and data format specifications for a particular port type are

specified as a binding. • A port is defined by associating a network address with a reusable binding,

and a collection of ports define a service. In addition, WSDL specifies a common binding mechanism to bring together all protocol and data formats with an abstract message, operation, or endpoint

Web Services

WSDL Service Description

Web Services A complete WSDL document consists of a set of definitions

starting with a root definitions element followed by six individual element definitions – types, message, portType, binding, port, and service – that describe the services. • The types element defines the data types contained in messages exchanged as

part of the service. Data types can be simple, complex, derived, or array types. Types, either schema definitions or references, that are referred to in a WSDL document's message element are defined in the WSDL document's type -element.

• The message element defines the messages that the Web service exchanges. A WSDL document has a message element for each message that is exchanged, and the message element contains the data types associated with the message.

• The portType element specifies, in an abstract manner, operations and messages that are part of the Web service. A WSDL document has one or more portType definitions for each Web service it defines.

• The binding element binds the abstract port type, and its messages and operations, to a transport protocol and to message formats.

• The service and port elements together define the name of the Web service and, by providing a single address for binding, assign an individual endpoint for the service. A port can have only one address. The service element groups related ports together and, through its name attribute, provides a logical name for the service.

J2EE Web Services Java APIs for XML Processing: Java APIs for XML Processing (JAXP) is a

vendor-neutral set of lightweight APIs for parsing or processing XML documents.

Java API for XML-Based RPC: Java API for XML-based RPC (JAX-RPC) supports XML-based RPC for Java and J2EE platforms. It enables a traditional client-server remote procedure call (RPC) mechanism using an XML-based protocol.

Java API for XML Registries: Java API for XML Registries (JAXR), a Java API for accessing business registries, has a flexible architecture that supports UDDI, and other registry specifications (such as ebXML).

SOAP with Attachments API for Java: SOAP with Attachments API for Java (SAAJ), which enables developers to produce and consume messages conforming to the SOAP 1.1 specification and SOAP with Attachments note, provides an abstraction for handling SOAP messages with attachments.

The Integrated Platform for Web Services in J2EE Platform: Using a JAX-RPC service endpoint or an EJB service endpoint.

Support for WS-I (the Web Services Interoperability Organization) Basic Profile: Messaging standards (such as SOAP), Description and discovery standards (such as UDDI), and Security

Designing a Web service Steps for designing a Web service:

• Decide on the interface for clients. Decide whether and how to publish this interface. Java

• Determine how to receive and preprocess requests. • Determine how to delegate the request to business logic. • Decide how to process the request. • Determine how to formulate and send the response. • Determine how to report problems.

A Web service can be viewed in terms of layers: an interaction layer and a processing layer

Service's Interaction Layer Two approaches to developing the interface definition for a Web

service are: • Java-to-WSDL: Start with a set of Java interfaces for the Web service • WSDL-to-Java: Start with a WSDL document describing the details of the

Web service interface . The endpoint type choice depends on the nature of your business

logic:• Use a JAX-RPC service endpoint when the processing layer is within the Web

tier.• Use an EJB service endpoint when the processing layer is only on the EJB

tier. Examplepublic interface WeatherService extends Remote { public String getWeather(String city) throws RemoteException; public String getWeather(int zip) throws RemoteException; }

Service's Interaction Layer Parameter Types for Web Service Operations

• A Web service interface exposes a set of method calls to clients. • When invoking a service interface method, a client may pass the parameters

to the Web service.• A method call and its parameters are sent as a SOAP message between the

client and the service. When received at the client or service end, the parameters are mapped from XML to their proper types or objects.

Parameters for Web service method calls may be standard Java objects and types, XML documents, or even nonstandard types.

The J2EE platform supports the following Java data types:• Java primitive types: boolean, byte, short, int, long, float, and double, along

with their corresponding wrapper Java classes • Standard Java classes: String, Date, Calendar, BigInteger, BigDecimal,

QName, and URI • QName class represents a combined definition of a qualified name with

the following two specifications: XML Schema Part2: Datatypes specification, Namespaces in XML

• The value of a QName contains a namespaceURI and a localPart. • Java arrays with JAX-RPC-supported Java types as members • JAX-RPC value types: user-defined Java classes, including classes with

JavaBeans component-like properties

Service's Interaction Layer After you define the interface, you run the vendor-provided tool to

create the WSDL from the interface. For example, in the J2EE 1.4 SDK its wscompile tool creates the

WSDL from the WeatherService interface shown as follows:

<?xml version="1.0" encoding="UTF-8"?> <definitions name="WeatherWebService" .......> <types/> <message name="WeatherService_getWeather"> <part name="int_1" type="xsd:int"/> </message> <message name="WeatherService_getWeatherResponse"> <part name="result" type="xsd:string"/> </message> <message name="WeatherService_getWeather2"> <part name="String_1" type="xsd:string"/> </message> <message name="WeatherService_getWeather2Response"> <part name="result" type="xsd:string"/> </message> ... </definitions>

Service's Interaction Layer Notice that the WSDL represents the getWeather overloaded

methods as two different SOAP messages, naming one getWeather, which takes an integer for the zip code as its parameter, and the other getWeather2, which takes a string parameter for the city. As a result, a client interested in obtaining weather information using a city name invokes the service by calling getWeather2, as shown below:

...

Context ic = new InitialContext();

WeatherWebService weatherSvc = (WeatherWebService) ic.lookup("java:comp/env/service/WeatherService");

WeatherServiceIntf port = (WeatherServiceInterface) weatherSvc.getPort(WeatherServiceInterface.class);

String returnValue = port.getWeather2("San Francisco");

...

Service's Interaction Layer If instead you choose to use the WSDL-to-Java approach, your

WSDL description might look as follows.

<?xml version="1.0" encoding="UTF-8"?><definitions name="WeatherWebService" ...>

<types/><message name="WeatherService_getWeatherByZip">

<part name="int_1" type="xsd:int"/></message><message name="WeatherService_getWeatherByZipResponse">

<part name="result" type="xsd:string"/></message><message name="WeatherService_getWeatherByCity">

<part name="String_1" type="xsd:string"/></message><message name="WeatherService_getWeatherByCityResponse">

<part name="result" type="xsd:string"/></message>...

</definitions>

Service's Interaction Layer Since the messages in a WSDL file must have unique names, you

must use different message names to represent methods that you would otherwise overload.

These different message names actually convert to different method calls in your interface. Notice that the WSDL includes a method getWeatherByZip, which takes an integer parameter, and a method getWeatherByCity, which takes a string parameter. Thus, a client wishing to obtain weather information by city name from a WeatherService interface associated with the WSDL might invoke the service as shown below:

Context ic = new InitialContext();WeatherWebService weatherSvc = (WeatherWebService)

ic.lookup("java:comp/env/service/WeatherService");WeatherServiceIntf port = (WeatherServiceIntf)

weatherSvc.getPort(WeatherServiceIntf.class);String returnValue = port.getWeatherByCity("San Francisco");

Service's Processing Layer The service's processing layer processes the request and, when the

processing completes, the service endpoint returns the response to the client.

The following code shows the weather service interface performing some basic parameter validation checks in the interaction layer.

public class WeatherServiceImpl implements WeatherService, ServiceLifecycle {public void init(Object context) throws JAXRPCException {....}public String getWeather(String city) throws CityNotFoundException {

/** Validate parameters **/ if(!validCity(city)) throw new CityNotFoundException(....);

/** Get weather info form processing layer and **/ / **return results **/ return (getWeatherInfoFromDataSource(city));}public void destroy() {....}

}

Deploying and Packaging a Service Endpoint

Once you complete the Web services implementation, you must write its deployment descriptors, package the service with all its components, and deploy the service.

Developers should use tools or IDEs to develop a Web service. • These Web service development tools and IDEs automatically create the

proper deployment descriptors for the service and correctly handle the packaging of the service – steps necessary for a service to operate properly.

• Furthermore, tools and IDEs hide these details from the developer. To successfully deploy a service, the developer provides the

following information. • Deployment-related details of the service implementation, including the Web

service interface, the classes that implement the Web service interface, and so forth.

• Details about the Web services to be deployed, such as the ports and mappings

• Details on the WSDL port-to-port component relationship

Deploying and Packaging a Service Endpoint

More specifically, the deployment descriptor contains information about a service's port and associated WSDL. • A port component (also called a port) gives a view of the service to clients

such that the client need not worry about how the service has been implemented.

• Each port has an associated WSDL. • Each port has an associated service endpoint (and its implementation). The

endpoint services all requests that pass through the location defined in the WSDL port address.

To begin, the service implementation declares its deployment details in the appropriate module-specific deployment descriptors. For example, a service implementation that uses a JAX-RPC service endpoint declares its details in the WEB-INF/web.xml file using the servlet-class element.

The Web services deployment descriptor, webservices.xml, links the WSDL port information to a unique port component and from there to the actual implementation classes and Java-to-WSDL mappings.

Deploying and Packaging a Service Endpoint

web.xml File for a JAX-RPC Service Endpoint <web-app ...>

...<servlet>

<description>Endpoint for Some Web Service</description><display-name>SomeWebService</display-name><servlet-name>SomeService</servlet-name><servlet-class>com.a.b.c.SomeServiceImpl</servlet-class><load-on-startup>0</load-on-startup>

</servlet><servlet-mapping>

<servlet-name>SomeService</servlet-name><url-pattern>/webservice/SomeService</url-pattern>

</servlet-mapping>...

</web-app>

• The Web services deployment descriptor, webservices.xml, links the WSDL port information to a unique port component and from there to the actual implementation classes and Java-to-WSDL mappings.

Deploying and Packaging a Service Endpoint<webservices ...>

<description>Web Service Descriptor for weather service</description><webservice-description> <webservice-description-name>WeatherWebService</webservice-description-name> <wsdl-file>WEB-INF/wsdl/WeatherWebService.wsdl</wsdl-file> <jaxrpc-mapping-file>WEB-INF/WeatherWebServiceMapping.xml</jaxrpc-mapping-file> <port-component> <description>port component description</description> <port-component-name>WeatherServicePort</port-component-name>

<wsdl-port xmlns:weatherns="urn:WeatherWebService">weatherns:WeatherServicePort

</wsdl-port><service-endpoint-interface>endpoint.WeatherService</service-

endpoint-interface><service-impl-bean><servlet-link>WeatherService</servlet-link></

service-impl-bean> </port-component></webservice-description>

</webservices>

Deploying and Packaging a Service Endpoint

Once the service implementation and deployment descriptors are completed, the following files should be packaged into the appropriate J2EE module:• The WSDL file • The service endpoint interface, including its implementation and dependent classes • The JAX-RPC mapping file, which specifies the package name containing the

generated runtime classes and defines the namespace URI for the service. • The Web service deployment descriptor

The type of endpoint used for the service implementation determines the type of the J2EE module to use.• The appropriate J2EE module for a service with a JAX-RPC service endpoint is a

WAR file. A service using an EJB service endpoint must be packaged in an EJB-JAR file.

The package structure is as follows (Web Application Archive – WAR):• WSDL files are located relative to the root of the module. • The service interface, the service implementation classes, and the dependent classes

are packaged just like any other J2EE component. • The JAX-RPC mapping file is located relative to the root of the module (typically in

the same place as the module's deployment descriptor). • The Web service deployment descriptor location depends on the type of service

endpoint,

Client Design Web services are only one of several ways for a client to access an

application service. For example, Java applications may access application services using RMI/IIOP, JMS, or Web services.

Interoperability is the primary advantage for using Web services as a means of communication.

Web services use HTTP as the transport protocol, which enables clients to operate with systems through firewalls. The service's WSDL document enables clients and services that use very different technologies to map and convert their respective data objects. For services and clients that are based on JAX-RPC, the JAX-RPC runtime handles this mapping transparently.

Scenarios for Web Services-Based Client Applications• J2EE component – a J2EE component accesses a Web service.• J2SE client – A J2SE client may access the same Web service as the J2EE

component. • J2ME client – A J2ME client may access the same Web service,• Non-Java client – A non-Java client accesses the same Web service using

SOAP over HTTP.

Client Design Each client type relies on a runtime – either a JAX-RPC or SOAP

runtime to communicate the service.

Client Design J2EE Client: The J2EE platform provides many other technologies

in addition to supporting Web services. Developers can obtain a richer set of functionality by using these other services, such as Web and EJB components, in addition to Web services for their client applications.

J2SE Client: Developers of non-J2EE clients are responsible for much of the underlying work to look up a service and to create and maintain instances of classes that access the service. Since they cannot rely on a container, these developers must create and manage their own services and ensure the availability of all runtime environments needed to access the Web services.

J2ME Clients: J2ME clients may access Web services using a subset of the JAX-RPC API.

Client Design Keep the following considerations in mind when designing J2ME

clients.• Connectivity and bandwidth limitations – J2ME clients may have limited

bandwidth, intermittent disconnects, and fees for connection usage.

• Processing power – The processing capabilities of a Web service client should be considered in its design.

• State maintenance – J2ME clients may operate in a connected or disconnected mode, requiring the maintenance of state and synchronization between client and service.

Communication Modes for Accessing a Service• Using Stub Communication

• Using Dynamic Proxy Communication

• Using DII Call Interface

Client Design Using Stub Communication

• J2EE clients should use generated stubs to access services, especially for services with fairly static interfaces.

• Stub communication easily allows Java access to a Web service. • This is the recommended approach for accessing services and their WSDL files when

they are unlikely to change over time. Using Dynamic Proxy Communication

• The dynamic proxies are similar in many ways to the stubs previously described. However, unlike stubs, the client developer needs only the client-side interface that matches the service endpoint interface. That is, clients using dynamic proxies program to an interface that ensures the client application is portable across other JAX-RPC runtime implementations. Developers using dynamic proxies must create Java classes to serve as JAX-RPC value types – these classes have an empty constructor and set methods for each field, similar to JavaBeans classes.

• Using DII (Dynamic Invocation Interface) Call Interface• A client application may also dynamically access a Web service by locating the

service at runtime from a registry. • The client does not know about the service when it is compiled; instead, the client

discovers the service's name from a JAXR registry at runtime. • Along with the name, the client discovers the required parameters and return values

for making a call to the service. Using a dynamic invocation interface, the client locates the service and calls it at runtime.

Client Design Accessing a Service with a Stub in J2SE and J2ME Environments

• The client application accesses a stub for a service using the method getOrderTrackingIntfPort on the generated implementation class, OpcOrderTrackingService_Impl, which is specific to each JAX-RPC runtime. J2SE or J2ME clients use these generated Impl files because they do not have access to the naming services available to clients in a J2EE environment through JNDI (Java Naming and Directory Interface) APIs.

Stub stub = (Stub)(new OpcOrderTrackingService_Impl().getOrderTrackingIntfPort());OrderTrackingIntf port = (OrderTrackingIntf)stub;

In addition, a J2SE or J2ME client can access a service by using the javax.xml.rpc.ServiceFactory class to instantiate a stub object. The following code shows how a J2SE client might use a factory to locate the same order tracking service.

ServiceFactory factory = ServiceFactory.newInstance();Service service = factory.createService(new QName(

"urn:OpcOrderTrackingService", "OpcOrderTrackingService"));

Client Design J2SE Client Dynamic Proxy Service Lookup

ServiceFactory sf = ServiceFactory.newInstance();

String wsdlURI = "http://localhost:8001/webservice/OtEndpointEJB?WSDL";

URL wsdlURL = new URL(wsdlURI);

Service ots = sf.createService(wsdlURL,

new QName("urn:OpcOrderTrackingService",

"OpcOrderTrackingService"));

OrderTrackingIntf port = (

OrderTrackingIntf)ots.getPort(new QName(

"urn:OpcOrderTrackingService", "OrderTrackingIntfPort"),

OrderTrackingIntf.class);

...

Java-based Web Services Developing Tools To build and run a Web service, here is the list of tools:

• Sun's J2SE JDK: Sun's J2SE development toolkit provides build tools and utilities.

• Web container:• Sun Java System Application Server Platform Edition 8.1 Update 2:

The Java System Application Server Platform Edition 8 is the implementation of the Java 2 Platform, Enterprise Edition (J2EE) 1.4 specification.

• Sun Java System Web Server 6.1 Service Pack 3: The Java System Web Server delivers built-in Web security with unmatched reliability for all types of Web applications, including those based on JSP/Servlet technologies.

• Tomcat 5.0 for Java WSDP: This Web container is based on Apache's Jakarta Tomcat. It implements the JSP and servlet specifications. While it is not intended for production use, it provides an easy-to-learn and use platform for hosting a Web service.

• Java Web Services Developer Pack 1.6: A Web service toolkit that can be integrated with the Tomcat Web container (above) that will allow you to build and test Web services.

• Apache Ant: A Java-based tool for building and deploying your Web service.

Developing the Example Application The formula for developing this application can be divided into

two parts: • Sever: developing the Web service

• Client: developing the Java Client that accesses that Web service.

The basic steps to create a Web service and deploy it to the Tomcat server are as follows: • Write the Web service interface class.

• Write the Web service implementation class.

• Write the associated descriptor files (all XML files).

• Compile the service and generate Web services stubs/ties and WSDL file using tools provided with the Java Web Services Developer Pack.

• Deploy the web service to the Tomcat server.

Developing the Example Application Write the Web service interface class. import java.rmi.Remote;

import java.rmi.RemoteException;

public interface HelloService extends Remote {

public String sayHello(String msg) throws RemoteException;

}

Write the Web service implementation class. public class HelloImpl implements HelloService {

public String sayHello(String msg) {

String result = " Hi " + msg + " From Server for WSDL client";

System.out.println("In sayHello for WSDL : " + msg);

return result;

}

}

Developing the Example Application Web Service Clientimport javax.xml.rpc.Stub;

public class HelloClient {

public static void main(String[] args) {

try {

Stub stub = createProxy();

HelloService hello = (HelloService)stub;

System.out.println(hello.sayHello("Duke!"));

} catch (Exception ex) { ex.printStackTrace(); }

}

private static Stub createProxy() {

return (Stub)(new MyHello_Impl().getHelloServicePort());

}

}