Web Services Documentation

Overview:

Web Services describes a standardized way of integrating Web-based

applications using the XML, SOAP, WSDL and UDDI open standards over an
Internet protocol. XML is used to tag the data, SOAP is used to transfer the data,
WSDL is used for describing the services available and UDDI is used for listing what
services are available.

XML (Extensible Markup Language):

Extensible Markup Language is a specification developed by the W3C.

XML is a pared-down version of SGML, designed especially for Web documents. It
allows designers to create their own customized tags, enabling the definition,
transmission, validation, and interpretation of data between applications and between
organizations.

SOAP (Simple Object Access Protocol):

Simple Object Access Protocol is a lightweight XML-based messaging

Protocol used to encode the information in Web service request and response
messages before sending them over a network. SOAP messages are independent of
any operating system or protocol and may be transported using a variety of Internet
protocols, including SMTP, MIME, and HTTP. The SOAP specification defines the
envelope structure (SOAP envelope, SOAP header (optional), SOAP body), encoding
rules, and conventions for representing remote procedure calls and responses. These
calls and responses are transmitted as SOAP messages (XML files) over HTTP.

WSDL (Web Services Description Language):

Web Services Description Language is an XML-formatted language used to

describe a Web service's capabilities as collections of communication endpoints
capable of exchanging messages. WSDL is an integral part of UDDI, an XML-based
worldwide business registry. WSDL is the language that UDDI uses. WSDL was
developed jointly by Microsoft and IBM.

UDDI (Universal Description, Discovery and Integration):

Universal Description, Discovery is to provide a standard data model for

Storing information about organizations and their Web services. An implementation
of the UDDI specification is called a UDDI registry.UDDI defines a SOAP-based API
that allows remote clients to access, update, and search the information in a UDDI
registry.
UDDI Inquiry API and Publishing API:

UDDI's standard Web services are divided into two WSDL/SOAP-based APIs:

1) Inquiry API: The Inquiry API is used to search and read data in a UDDI registry,
2) Publishing API: The Publishing API is used to add, modify, and delete data in a
UDDI registry.

WebService:

A WebService is a remote application described using the Web Service

Description Language (WSDL) and accessed using the Simple Object Access
Protocol (SOAP) according to the rules defined by the WS-I (Web Services
Integration Organization) Basic Profile 1.1.

Advantages of Webservices:

The idea of a Web service developed from the evolution of the Internet.
The Main purpose of Web service technologies is to allow applications on different
platforms to exchange business data.

Web service technologies are used for Application-to-Application (A2A) integration

or Business-to-Business (B2B) Communication.

A2A refers to disparate applications within a single Organization communicating and

exchanging data—A2A is also known as Enterprise Application Integration (EAI).

B2B refers to multiple organizations, typically business partners, exchanging data.

Web services allow organizations to communicate data without intimate knowledge of

each other's IT systems behind the firewall.

Web Services Technologies:

Technologies for web services in the J2EE are:

1) Java API for XML Processing (JAXP) 1.2

2) Java API for XML-based RPC (JAX-RPC) 1.1
3) SOAP with Attachments API for Java (SAAJ) 1.2
4) Java API for XML Registries (JAXR) 1.0

JAX-WS (Java API for XML WebServices):

JAX-WS is a technology for building web services and clients that

communicate using XML. In JAX-WS, a remote procedure call is represented by an
XML-based protocol such as SOAP.
Advantages of JAX-WS Client:

With JAX-WS, clients and web services have a big advantage: the Platform
independence of the Java programming language. A JAX-WS client can access a web
service that is not running on the Java platform, and vice versa. This flexibility is
possible because JAX-WS uses technologies defined by the Worldwide Web
Consortium (W3C): HTTP, SOAP, and the Web Service Description Language
(WSDL).

Requirements for Creating a Simple WebService:

The starting point for developing a JAX-WS web service is a Java class
annotated with the javax.jws.WebService annotation. The WebService annotation
defines the class as a web service endpoint. A service endpoint interface (SEI) is a
Java interface that declares the methods that a client can invoke on the service. An
SEI is not required when building a JAX-WS endpoint. The web service
implementation class implicitly defines a SEI.
You use the endpoint implementation class and the wsgen tool to generate the web
service artifacts and the stubs that connect a web service client to the JAX-WS
runtime.

Requirements of a JAX-WS Endpoint:

JAX-WS endpoints must follow these requirements:

1) The implementing class must be annotated with either the

javax.jws.WebService or javax.jws.WebServiceProvider annotation.

2) The implementing class may explicitly reference an SEI through the

endpoint Interface element of the @WebService annotation, but is not
required to do so. If no endpoint Interface is not specified in

@WebService, an SEI is implicityly defined for the implementing class.

3) The business methods of the implementing class must be public, and must not
be declared static or final.

4) Business methods that are exposed to web service clients must be

annotated with javax.jws.WebMethod.

5) The implementing class must not be declared final and must not be
abstract.
 6) The implementing class must have a default public constructor.

7) The implementing class must not define the finalize method.

8) The implementing class must not be declared final and must not be
abstract.

9) The implementing class must have a default public constructor.

10) The implementing class must not define the finalize method.

Example for Retreving the data using Webservices:

IDE:Netbean Beta version5.5

Server:Sun Application Server

Project Name: DataViaWS

Creating a New Project:

Step1:
Choose File Tab  Choose Web  Choose WebApplications Click on
Next.
Step 2:
Choose Project Name and Choose Server Name (Sun Java System Application
Server) Choose J2EE Version (Java EE5) and Click on Next and Click on Finish.

Creating Entity Classes from DataBase:

Step 3:

Right Click on WebApplication and Choose New-Choose File FolderChoose

Persistence Choose EntityClassesFromDatabase and Click on Next. Choose
DataSource and choose New DataSource Then It will Shows a Window like Create
Data Source Window and give the JNDI Name and Choose Database Connection (It
is already created the table in schema) and Give the Password then Click on OK.
From Available Tables Choose Customer and Click on Add Button and Click on Next
and give the package name. Click on Create Persistence Unit. Choose the Persistence
Provider (Hibernate) And Click on Create Button .and Click on Finish Button.

Then it will creates Customer Entity Class Like

Code for Customer.java

package com.iton;

import java.io.Serializable;
import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.Id;
import javax.persistence.NamedQueries;
import javax.persistence.NamedQuery;
import javax.persistence.Table;

@Entity

@Table(name = "customer")

@NamedQueries( {@NamedQuery(name = "Customer.findById",

query = "SELECT c FROM Customer c WHERE c.id = :id"),
@NamedQuery(name = "Customer.findByFirstName",
query = "SELECT c FROM Customer c WHERE c.firstName= :firstName"),
@NamedQuery(name = "Customer.findByLastName",
query = "SELECT c FROM Customer c WHERE c.lastName = :lastName"),
@NamedQuery(name = "Customer.findByAddressId",
query = "SELECT c FROM Customer c WHERE c.addressId = :addressId")})

public class Customer implements Serializable {

@Column(name = "id", nullable = false)

private int id;

@Column(name = "firstName")
private String firstName;

@Column(name = "lastName")
private String lastName;

@Id
@Column(name = "ADDRESS_ID")
private Integer addressId;
/** Creates a new instance of Customer */
public Customer() {
}

public Customer(Integer addressId) {

this.addressId = addressId;
}

public Customer(Integer addressId, int id) {

this.addressId = addressId;
this.id = id;
}

public int getId() {

return this.id;
}

public void setId(int id) {

this.id = id;
}

public String getFirstName() {

return this.firstName;
}

public void setFirstName(String firstName) {

this.firstName = firstName;
}

public String getLastName() {

return this.lastName;
}

public void setLastName(String lastName) {

this.lastName = lastName;
}

public Integer getAddressId() {

return this.addressId;
}

public void setAddressId(Integer addressId) {

this.addressId = addressId;
}

public int hashCode() {

int hash = 0;
hash += (this.addressId != null ? this.addressId.hashCode() : 0);
return hash;
}

public boolean equals(Object object) {

// TODO: Warning - this method won't work in the case the id fields are not set
if (!(object instanceof Customer)) {
return false;
}
Customer other = (Customer)object;
if (this.addressId != other.addressId && (this.addressId == null || !
this.addressId.equals(other.addressId))) return false;
return true;
}

public String toString() {

return "com.iton.Customer[addressId=" + addressId + "]";
}

Creating WebService:

Step 4:

RightClick on Project Choose New Choose File Folder Choose

WebServices -Choose WebService and Click on Next .

Give the WebServiceName(DataWS) and Give the Package Name

And Choose Create an Empty WebService and Click on Finish.

Coding the Service EndPoint Interface Implementation Class:

In this example, the implementation class, DataWS, is annotated as a web

Service endpoint using the @WebService annotation. DataWS declares two

methods named getCustomerId and getCustomer(int id) annotated with the

@WebMethod annotation.

@WebMethod exposes the annotated method to web service clients.

getCustomerId method returns Numbers of Ids Stored in the Customer

table and getCustomer method returns the details of the particular record of

the client.

Code for DataWS.java:

package com.iton;

import java.util.ArrayList;
import java.util.List;
import java.util.logging.Level;
import java.util.logging.Logger;
import javax.annotation.Resource;
import javax.jws.WebService;
import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.NamingException;
import javax.persistence.EntityManager;
import javax.persistence.PersistenceContext;
import javax.transaction.UserTransaction;

//This application is developed using ContainerManaged

@WebService()

//@ javax.jws.WebService annotation defines the class as a web service endpoint.

@PersistenceContext(name = "persistence/LogicalName", unitName =

"DataViaWSPU")
public class DataWS {

EntityManager em;

public DataWS(){

try {
Context ctx = (Context) new InitialContext().lookup("java:comp/env");
em = (EntityManager) ctx.lookup("persistence/LogicalName");
}
catch (NamingException ex) {
ex.printStackTrace();
}

@WebMethod

//Business Methods that are exposed to web service clients must be annotated
with @javax.jws.WebMethod.

public List<Object> getCustomerId() {

return em.createQuery("SELECT c.id from Customer c").getResultList();

@WebMethod

public List<Object> getCustomer(int id) {

ArrayList al=new ArrayList();

Customer customer=(Customer)em.createNamedQuery("Customer.findById").
setParameter("id",id).getSingleResult();

al.add(customer.getId());
al.add(customer.getFirstName());
al.add(customer.getLastName());

return al;

}
To display the result Choose the DataWS File under the WebServices Folder .

and RightClick on DataWS choose Test WebService.

Click on getCustomerId then the result will be look like this
Provide the id in the getCustomer method ,If you give 1 like

and Click on getCustomer Then the result will be look like this
 A Simple JAX-WS Client :

Client is a servlet program that accesses the getCustomer method of

DataWSService. It makes this call through a stub, a local object that acts as a

Proxy for the remote service. The stub is created at development time by the

Wsimport tool, which generates JAX-WS portable artifacts based on a WSDL

file.

Coding the Client :

When invoking the remote methods on the stub, the client performs these steps:

1) Uses the javax.xml.ws.WebServiceRef annotation to declare a reference

to a webservice. WebServiceRef uses the wsdlLocation element to specify

the URI of the deployed service's WSDL file.

 @WebServiceRef(wsdlLocation=
"http://192.168.0.30:8080/DataViaWS/DataWSService?wsdl")

2) Retrieves a proxy to the service, also known as a port, by invoking

getHelloPort on the service.

com.iton.DataWS port = service.getDataWSPort();

The port implements the SEI defined by the service.

3) Invokes the port's getCustomer method, passing to the service a name.

java.util.List<java.lang.Object> result1 = port.getCustomer(arg0);

Code for Creating the JAX-WS Client Program:

package com.iton;

import java.io.*;
import java.net.*;
import javax.servlet.*;
import javax.servlet.http.*;
import javax.xml.ws.WebServiceRef;

public class Client extends HttpServlet {

@WebServiceRef(wsdlLocation =
"http://192.168.0.30:8080/DataViaWS/DataWSService?wsdl")

private com.iton.DataWSService service;

protected void processRequest(HttpServletRequest request,

HttpServletResponse response) throws ServletException, IOException {

response.setContentType("text/html;charset=UTF-8");

PrintWriter out = response.getWriter();

try {
// Call Web Service Operation
com.iton.DataWS port = service.getDataWSPort();

// TODO initialize WS operation arguments here

int arg0 = 1;

int arg1 = 2;

int arg2 = 3;

// TODO process result here

java.util.List<java.lang.Object> result1 = port.getCustomer(arg0);

java.util.List<java.lang.Object> result2 = port.getCustomer(arg1);

java.util.List<java.lang.Object> result3 = port.getCustomer(arg2);

out.println("Result1 = "+result1);

out.println("<br>");

out.println("Result2 = "+result2);

out.println("<br>");

out.println("Result3 = "+result3);

} catch (Exception ex) {

ex.printStackTrace();
}

out.close();
}

protected void doGet(HttpServletRequest request, HttpServletResponse

response)
throws ServletException, IOException {

processRequest(request, response);

protected void doPost(HttpServletRequest request, HttpServletResponse

response) throws ServletException, IOException {
processRequest(request, response);

public String getServletInfo() {

return "Short description";

JAXR(Java API for XML Registries):

JAXR is a client-side API for accessing different kinds of XML-based

business registries (like UDDI and ebXML registries). The JAXR API has two
conformance levels: Level 0 and Level 1. Level 1 is a richer API that is designed for
accessing ebXML registries. Level 0 provides fewer features and is intended for
UDDI registries, which are less flexible than ebXML but more popular.
JAXR comes in two interdependent packages: The Query and Life Cycle API
(javax.xml.registry) and the Information Model (javax.xml.registry.infomodel). The
Query and Life Cycle API supports the UDDI Inquiry and Publishing APIs
respectively. The Information Model (info model for short) provides business- and
technical-object views that correspond to UDDI data structures (businessEntity,
bindingTemplate, tModel, and so on).

Advantages of JAXR:

JAXR is very useful under certain circumstances. If you need to build a

UDDI browsing tool, JAXR is a great choice for supporting the actual SOAP

communications between the browser and the UDDI registry.

The JAXR API can be used to look up the Web service in UDDI and

Determine whether an alternative access point is offered.

Registry:

An XML registry is an infrastructure that enables the building,

 deployment, and discovery of web services. A registry is available to

organizations as a shared resource, often in the form of a web-based service.

1) The Universal Description, Discovery, and Integration (UDDI) project,

which is being developed by a vendor consortium.

3) The ebXML Registry and Repository standard, which is sponsored by

The Organization for the Advancement of Structured Information

Standards (OASIS) and the United Nations Centre for the Facilitation of

Procedures and Practices in Administration, Commerce and Transport

(U.N./CEFACT)

JAXR Provider:

JAXR provider is a vendor's implementation of the JAXR API

JAXR Architecture :

The high-level architecture of JAXR consists of the following parts:

1) A JAXR client: This is a client program that uses the JAXR API to access a

business registry via a JAXR provider.

2) A JAXR provider: This is an implementation of the JAXR API that provides

access to a specific registry provider or to a class of registry providers that are

based on a common specification.

A JAXR provider implements two main packages:

a) javax.xml.registry, which consists of the API interfaces and classes that

define the registry access interface.

b) javax.xml.registry.infomodel, which consists of interfaces that define the

information model for JAXR. These interfaces define the types of objects
 that reside in a registry and how they relate to each other. The basic inte

rface in this package is the RegistryObject interface. Its subinterfaces

include Organization, Service, and ServiceBinding.

The most basic interfaces in the javax.xml.registry package are:

1) Connection: The Connection interface represents a client session with a

Registry provider. The client must create a connection with the JAXR

provider in order to use a registry.

2) RegistryService: The client obtains a RegistryService object from its

connection. The RegistryService object in turn enables the client to obtain the

interfaces it uses to access the registry.

The primary interfaces, also part of the javax.xml.registry package, are

1)BusinessQueryManager, which allows the client to search a registry for

information in accordance with the javax.xml.registry.infomodel interfaces.

An optional interface, DeclarativeQueryManager, allows the client to use

SQL syntax for queries. (The implementation of JAXR in the Application

Server does not implement DeclarativeQueryManager.)

2) BusinessLifeCycleManager, which allows the client to modify the information

in a registry by either saving it (updating it) or deleting it.

When an error occurs, JAXR API methods throw a JAXRException or

one of its subclasses.