COSC617, FALL 2006, Jeff Schmitt

Web Services
with

JAX-RPC and SAAJ

Presenters
Steven R. Bussow
Givry Mbouna
 Web Services (introduction)
a very resilient and powerful tool in enterprise architecture

born from joining of XML formatting language and HTTP communication

protocol

XML-RPC – one of the earlier web services formats that was widely used;
still around today

SOAP (Simple Object Access Protocol) – more recently developed standard

protocol for XML-based web services

Java standard APIs for web services include JAX-RPC (Java XML-Remote
Procedure Call) and SAAJ (SOAP with Attachments for Java)

web services, formally defined, as software component that communicates

using XML-formatted messages, transmitted over standard network
protocols such as HTTP or SMTP; it can export a description of its service,
its operations, and expected communication formats; service descriptors
typically in WSDL.
Web Service Descriptor Language (WSDL)
(introduction)
XML format for writing web service descriptors

WSDL service descriptor - describes types of data,

messages, and operations that web service supports,
and where the web service is located on the network.

client can use WSDL service description to generate

client side interfaces to the web service.

web service registry – register a web service; allows

client to acquire WSDL for a service, and if supported,
search web services by type.
 Simple Object Access Protocol
(SOAP)
Industry standard managed/published by W3C (World Wide Web
Consortium) http://www.w3.org/TR/SOAP

Defines how to package a message into a standard format that can

be delivered using standard protocols like HTTP and SMTP

APIs are used to generate and consume SOAP formatted

messages within a programming environment

SOAP messages include an envelope and a body

SOAP message envelope - contains information about how
message is encoded and XML schema definitions for the message
contents; including descriptions of XML elements used in a SOAP
message, how to construct and validated SOAP messages, and
XML documents in general.
SOAP message body – contains XML-encoded information; could
be client request to web service, response information, or details
about web service request failure.
SOAP RPC to a web service via HTTP
example
HHTP headers partial code:
POST /myapp/services/peopleFinder HTTP/1.0
Context-Type: text/xml;
-----------------------------
Host: myservices.com
------------------------------
SOAPAction: “ ”
-------------------------------
SOAP envelope partial code:
<soapenv: Envelope
xmlns:soapenv = “http://schemas.xmlsoap.org/soap/envelope/”
xmlns:xsd = “http://www.w3.org/2001/XMLSchema”
xmlns:xsi- = “http:// www.w3.org/2001/XMLSchema-instance”
---------------------------------------------------------------------------
-----------------SOAP
-----------------SOAP BODY-----------------------------------------
BODY-----------------------------------------
---------------------------------------------------------------------------
</soapenv:Envelope>
SOAP body partial code:
<soapenv:Body>
<nsl:findpeople
Soapenv:encodingStyle=“http://sschemas.xmlsoap.org/soap/encoding/”
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
</soapenv:Body>
 SOAP RPC example details:
example sent over HTTP

HTTP headers specify HTTP request type (POST),

contents of HTTP request, and HTTP location to which
request is being sent

SOAPAction – SOAP-specific custom header; specifies

entry point of web service to receive this message if the
HTTP URL is not sufficient (not necessary in this
example, so left blank)

body of HTTP request contains the entire SOAP

message (SOAP envelope and SOAP body)
 SOAP continued
SOAP Web Service – is a runtime entity that can accept
SOAP messages, do actions requested in the message,
and generate a response in the same general SOAP
format.

Serialization – is the process of converting programming

entities to SOAPXML

Deserialization – is the process of converting SOAPXML

back into programming entities

Serialization and deserialization are handled by Java web

service engines, such as Axis or JBossWS.
Web Service Description Language (WSDL)

WSDL – is an XML format that describes

web services in terms of operations they
support, and the messages and data
types that these operations expect as
arguments, and return as responses.


uses set of XML entities to describe web
services
 Example of a skeleton WSDL descriptor
<?xml version= “1.0” encoding = “UTF -8”?>
<wsdl:definitions
targetNamespace= “myserver.com/services/peopleFinder”
xmlns:wsdl= “schemas.xmlsoap.org/wsdl/”>
<wsdl:types>
------------------------------------------------------------------------------
<wsdl:message name= “message1”>
-----------------------------------------------------------------------------
<wsdl:portType name = “PeopleFinder”>
<wsdl:operation name = “findPeople” parameterOrder= “args”>
------------------------------------------------------------------------------
<wsdl:binding name = “peopleFinderSoapBinding”
------------------------------------------------------------------------------
<wsdl:service name = “PeopleFinderImplService”>
<wsdl:port binding = “impl: peopleFinderSoapBinding”
Name = “peopleFinder”>
------------------------------------------------------------------------------
</wsdl:definitions>
 WSDL continued
Entities:
 data types – building blocks for SOAP messages; can be simple as one string, or
a complicated XML structure with internal hierarchy
Example:
<?xml version= “1.0” encoding = “UTF -8”?>
<wsdl:definitions . . . >
<wsdl:types>
<schema . . . >
<complexType name = “Person”>
<sequence>
<element name= “firstName” nillable = “true”
Type = “soapenc:string”/>
-----------------------------------------------------------------------------
<sequence>
</complexType>
</schema>
</wsdl:definitions . . . >
 WSDL continued
Entities:
 messages – one or more data types grouped together; support
inputs, outputs, and faults used by operations

Example:
<wsdl:definitions . . . >
-------------------------------------------------
<wsdl:message name= “findPersonResponse”>
<wsdl:part name= “findPersonReturn” type = “impl:Person”/>
<wsdl:message>
----------------------------------------------------
</wsdl:definitions>
 WSDL continued
Entities:
 operation – an atomic unit of work for a web service; invoked by clients

Example:
----------------------------------------------------------
<wsdl:portType name = “PeopleFinderImpl”>
<wsdl:operation name = “findPerson” parameterOrder= “args”>
<wsdl:input message = “impl:findPersonRequest”
name = “findPersonRequest”/>
<wsdl:output message = “impl:findPersonResponse”
name = “findPersonResponse”/>
<wsdl:fault message = “impl:BadArgumentFault”
name = “BadArgumentFault”/>
----------------------------------------------------------------
<wsdl:operation>
<wsdl:portType>
 WSDL continued
Entities:
 port types – grouping of operations into sensible interfaces; represents a
conceptual description of a web service entry point
binding – describes how a particular port type has been bound to a
communication and encoding protocol, such as HTTP and SOAP

Example:
---------------------------------------------------------------------------
<wsdl:service name = “peopleFinderImplService”>
<wsdl:port binding= “impl:PeopleFinderSoapBinding” name = “peopleFinder”>
<wsdlsoap:address
location = http://myserver.com:8080//services/peopleFinder”/>
</wsdl:port>
</wsdl:service>
-----------------------------------------------------------------------------
Web Service Styles and Encoding

web service made up of ports

each port has one or more operations

each operation has input, output, and fault messages

each message is composed of XML data types

SOAP messages consumed and produced by web service
need a way to identify which operation in which port is in effect,
and how message types care expressed in XML of the
message
Styles: The style of a message refers to how the XML structure of the
SOAP body is structured; the two options for the style are RPC and
Document
RPC – The XML of the SOAP body is sturctured to match the
operation and message definitions.
Document – The root element of the SOAP body is matched to the
operation name, but the contents of the root element are not
reflective of the signature of the operation.
 Web Service Styles and Encoding
Encoding: The encoding determines how data is encoded
into XML within the message. The two options for the
encoding of service messages are:
Literal – This option specifies that the XML structure of
the data within the message will be totally specified by
XML Schema elements referenced in the WASDL
description of the service.
SOAP-encoded –This option requests that the message
data follow the default encoding rules( and XML
structures) specified in the SOAP specification.
 Java Web Services
There are several standards APIs for
implementing and using web services in
Java. The principal ones are the Java API
for XML Remote Procedure Calls (JAX-
RPC), the SOAP with Attachments API for
Java (SAAJ), and the Web services for
J2EE specification. JAX-RPC and SAAJ
are APIs aimed at helping you develop
both web services and web service clients.
 JAX-RPC and SAAJ
JAX-RPC and SAAJ together provide a
standard Java framework for consuming
SOAP messages from web services and
for generating SOAP messages and
delivering them to web services. The web
service APIs in Java use a different set of
protocols to accomplish their remote
object ans messaging services.
Mapping SOAP and WSDL to Java
JAX-RPC defines standard mappings from SOAP and WSDL
entities to Java entities and back again.
example of a mapping:
XML type:
xsd:anyURI
Java type:
java.lang.String
In all mappings, the xsd: prefix on an XML type
refers to an entity defined in the XML Schema
basic data types. Each XML data type has two Java
mappings. The first one is used by default for that XML type and the
second one is used if the XML entity is used in a context in which its
presence is optional.
Mapping SOAP and WSDL to Java
continued
When mapping Java entities into XML/SOAP entities, the process is
done in reverse. Java types are mapped to the same XML data
type, but the wrapper class is mapped with the nillable attribute
enabled.For example, a Java int, will be mapped to an XML Schema
like this:
<xsd:element name=“myintvar” type=“xsd:int”/>
while a java.lang.Integer will be mapped like this:
<xsd:element name=“myIntVar” type=“xsd:int” nillable=“true”/>
Finally, in addition to these mappings, JAX-RPC defines a set of
standard mappings from WSDL entities to Java entities. This
mapping is used in both directions by Java web service engine.
WSDL entities describing an external web service are mapped into
Java entities for use by a Java client of the web service.
 Web Service Deployment
The web services for J2EE specification sits next
to JAX-RPC and SAAJ as a complementary
standard, aimed at defining standard
approaches for describing web services to Java
application servers and for packaging web
services for deployment to these application
servers. It plays a role for Java-based web
services analogous to the deployment
descriptors and archive formats defined for web
components and EJB components.
Writing Web Service Clients
Client of a service wants to use that service to get
something done

Service using SOAP implementation:

 Client sends SOAP message, targeting specific operations
and ports of service
 If operations and ports generate response, client must receive
and interpret them
 Done by client mapping Java objects and data to operations
and ports and messages exposed by SOAP service using
JAX-RPC and SAAJ. Three common ways:
1) Static proxy
2) Dynamic proxy
3) Dynamic invocation interface (DII)
 Static Proxy Approach
(Writing Web Service Clients)

Mapping service’s WSDL descriptor to a

set of client-side Java code
All classes needed by client are pre-
generated by the mapping and used by
client to interact with service
Mapping once and encoding “statically” as
a set of concrete Java classes for client to
use
 Dynamic Proxy Approach
(Writing Web Service Clients)

Similar to Static Proxy Approach in

mapping functionality
However, mapping done dynamically at
runtime, with generated classes only
existing at runtime
Client only needs Java interface
compatible with the WSDL description of
the service
Dynamic Invocation Interface (DII) Approach
(Writing Web Service Clients)

Client does the mapping programmatically

in its code, with no service interface
classes being generated
Client dynamically constructs a call to the
target service, specifying all the particulars
of the service explicitly when configuring
the service call
 EchoService Example
(Writing Web Service Clients)

Example of clients that interact with very simple

web service
Web service simply echoes a string back to the
client
Service’s name in its WSDL description is
EchoService
Having a single port named echo
Port has a single operation, also called echo,
that accepts a message containing single string
and returns a message containing single string
 Static Proxy Approach
(Writing Web Service Clients – EchoService example)

Simplest approach, prior to runtime, generate

set of Java artifacts mapped from the WSDL
descriptor of the web service
Artifacts can be bundled to client code, with all
SOAP communication details hidden in
generated Service interfaces and Stub
implementations
Since we how have the mapped Java interfaces
and classes on the client side, we can import
them into our IDE to view/search/exercise them
just like other Java code
Static Proxy Approach - continued
(Writing Web Service Clients – EchoService example)

Axis – popular engine for building and using web services in

Java/J2EE environments
 WSDL2Java is Axis tool generates static proxy classes (Ant task format
also available)

If the WSDL for our Echo service were published at the URL
http://mywebservices.com/services/echo?wdl, we would then use
WSDL2Java to generate client stubs from the command line: >java
org.apache.axis.wsdl.WSDL2Java –o /home/dev/generated-src
http://mywebservices.com/services/echo?wsdl

Above command generates set of client-side Java classes mapped

from the WSDL file and writes the Java source files into
/home/dev/generated-scr directory, as specified with –o switch

In the case of our Echo service, and according to JAX-RPC

mapping specifications, two interfaces will be generated: Echo,
EchoService
Static Proxy Approach - continued
(Writing Web Service Clients – EchoService example)
Echo interface
 The echo port in the WSDL is mapped to this interface, which
extends java.rmi.Remote

Our interface name Echo is in mixed case, as all mapped
classes should be according to JAX-RPC specifications

Each operation in the WSDL for this port type is mapped to
corresponding method on this interface, and I/O messages for
operation are mapped to corresponding Java method arguments
and returns

Our example has single operation defined for the port, also
named echo; it has both an input message and an output
message, each consisting of one string; it is mapped to an
echo() method which has a single String argument and String
return value

No SOAP faults associated with operation in WSDL, so no
service-specific exceptions in echo(), only the RemoteException
required for all RMI remote methods
Static Proxy Approach - continued
(Writing Web Service Clients – EchoService example)

EchoService interface
 Same name of our service in WSDL which this Java
interface is mapped from
 For each port defined in the service, there is a
get<portname>() method that returns an instance of
Java class mapped from that port
 Ours is named getechoPort() because the bound port
is named echoPort in the service binding and in our
WSDL, (note that accessor methods are named after
the port binding, not the port definitions, because a
single port can be bound to multiple protocols or
physical endpoint URLs in the WSDL file)
Static Proxy Approach - continued
(Writing Web Service Clients – EchoService example)
Web service engine also needs to provide concrete implementations
of these mapped interfaces for the client to use

Names and implementation details of these implementations are not

specified by JAX-RPC standard

Axis generates two concrete implementation classes from the

WSDL: EchoBindingStub and EchoServiceLocator

EchoBindingStub – an Axis implementation of Echo interface

mapped from the port type. All methods mapped from WSDL
operation are implemented here as calls to the service endpoint.

EchoServiceLocator – an Axis implementation of EchoService

interface mapped from the WSDL service. The get<portname>()
methods declared in the interface are implemented here to construct
an implementation of the interface mapped from the WSDL port
type. In our example, getecho() method from EchoService is
implemented to return an instance of EchoBindingStub
Static Proxy Approach - continued
(Writing Web Service Clients – EchoService example)
Web service also needs to map these interfaces and
classes into namespaces used in the WSDL for their
corresponding XML entities
Namespace mapping not specified by JAX-RPC
standard
Unless otherwise specified, Axis converts the
namespace of each WSDL entity into a valid package
name, which may be undesirable
Use WSDL2Java utility with –N switch to specify a
namespace-to-package mapping file, (Java properties
file with namespaces as property and package as value)
Mapping file example:
 http\://myservices/services/echo=com.myapp.soap.echoclient
Use example:

>java org.apache.axis.wsdl.WSDL2Java –o
/home/dev/generated-src –N nsmap.properties
http://mywebservices.com/services/echo?wsdl
Static Proxy Approach - concluded
(Writing Web Service Clients – EchoService example)

The only parts of this mapping process specified by JAX-

RPC standard are the mapped port type interface (echo)
and the name of the mapped service interface
(EchoService), both taken from names and attributes of
their corresponding WSDL entities.

Concrete implementation classes of these interfaces is

free form

Mapping of namespaces to packages is free form

Static Proxy Approach for building a client to a web

service simply involves using the concrete stub class
generated by the web service engine’s tools.
 Static Proxy Approach - concluded
In Axis example, client uses the EchoSoapBindingStub class to
interact with the echo web service
//Get a stub to the remote service
Echo echo = new EchoServiceLocator().getechoPort();
//Invoke the operation and collect the result
String resp = echo.echo(msg);
Instances of stub class are obtained using the concrete Service
implementation, which calls the getecho() method to generate a
stub instance
The call to getechoPort() on the Service implementation returns an
instance of EchoBindingStub, the proxy for the echo service
When we call echo() method on the proxy, it internally constructs
the appropriate SOAP message to the web service, sends the
message to the service endpoint, receives the SOAP response,
extracts the string data, and returns it as the result of the method
call.
Nowhere in the client do we specify the URL location of the web
service (the service endpoint). The getechoPort() method on the
Service uses, by default, the endpoint URL found in the WSDL that
was used to generate the client-side Java classes. The endpoint
will be found in the service element of the WSDL description.
If client needs to contact an alternate instance of the web service
running at a different location , Axis generates an alternate
getecho() method on the mapped Service class.
 Dynamic Proxy Approach
(Writing Web Service Clients – EchoService example)

Does all WSDL-to-Java mapping dynamically

Client asks web service engine to generate a client stub class at
runtime
Client asks by creating a javax.xml.rps.Service instance that
references the WSDL descriptor for the target service
Client then uses generic getPort() methods on Service to
dynamically generate a stub class to use for communicating with the
web service
No mapped Java interfaces are generated from the WSDL
Client provides its own interface for the stub class, which must be
compatible with the service
Benefit: avoid using engine-specific concrete class implementations
of the mapped WSDL interfaces, (Axis’s EchoServicLocator and
EchoBindingStub described earlier)
Benefit: client code more easily run using different web service
engines, or, different versions of same web service engine
 Dynamic Proxy Approach
(Writing Web Service Clients – EchoService example)
Client creates a ServiceFactory instance by invoking the static
ServiceFactory.newInstance() method
We use ServiceFactory’s createService() method to create a
Service that represents the particular web service we desire,
passing through it:
 the URL for the WSDL file containing the service description,
 the qualified name of the target service in the WSDL file
// WSDL file we want
String wsdlLoc = http://myservices.com/services/echo?wsdl;
// Qualified name of service within WSDL file
QName serviceName = new QName(“http://myservices.com/services/echo”,”EchoService”);
ServiceFactory sFactory = ServiceFactory.newInstance();
Service service = sFactory.createService(new URL(wsdLoc), serviceName);
MyEcho echo = (MyEcho)service.getPort(myEcho.class);
// Invoke operation and get result
String resp = echo.echo(msg);
System.out.println(“Sent: \”” + msg + “\”, got response \ “” + resp + “\”);
In our example:
 WSDL defines the service within namespace
http://myservices.com/services/echo
 Service is named EchoService in WSDL
Stub interface of client must extend java.rmi.Remote, and its
methods must correspond with operations defined for the port in the
WSDL, per JAX-RPC rules
Dynamic Invocation Interface (DII) Approach
(Writing Web Service Clients – EchoService example)

Most burden on client, all service mapping

details are provided by client
Offers most flexibility, client can construct a call
to any web service w/out a predefined stub
interface
Client programmatically constructs the call to the
service, including all arguments required by web
service, and, ready to receive response type
Benefit: best suited for cases of little information
about the web service, such as no published
WSDL descriptor
Dynamic Invocation Interface (DII) Approach
(Writing Web Service Clients – EchoService example)

As before, client creates a Service instance, but

do not ask Service to do mapping
Instead, ask Service for raw javax.xml.rpc.Call
object so client can customize configuration of
the service call, including:
 Declare string parameters for namespaces
 Declare qualified names of service, port, and
operations
 All other details previously extracted from the WSDL
 Writing Web Services

Implementing SOAP web service, most

difficulties handled by Java web service
engines using JAX-RPC standards

Added complexity remains in deployment

process, discussed later
 Simple Java Web Services
Similar to static approach for implementing SOAP clients, JAX-RPC
uses RMI programming model to write web services in Java
The published interface for the web service is defined as a Remote
interface
Simple IEcho web service Remote interface example:
public interface IEcho extends java.rmi.Remote {
public String echo(String message) throws java.rmi.RemoteException;
}
Concrete implementation of simple Remote interface as Echo:
public class Echo implements IEcho {
public Echo() {
super();
}
public String echo(String message) throws RemoteException {
return message;
}
}

The web service engine manages the web service, converting

SOAP messages targeted for the specific service into the equivalent
method calls on the implementation class, and converting the
method return values or exceptions into SOAP messages or faults
that are delivered back to the client making the request.
 EJB Web Services
JAX-RPC and the EJB specifications support use of
EJB programming model to implement a web
service in Java, exposing a session EJB
component as a SOAP web service
Only stateless session beans can support web
service clients
Otherwise, interface is very similar to RMI
programming model described previously
public interface Peoplefinder extends javax.ejb.EJBObject {
public Person[] findPeople(SearchArg[] args)
throws Invalid SearchException, PersistenceException, RemoteException;
}
Notice the EJBObject extended here, rather than
Remote of previous example
EJB implementation class is virtually identical to
RMI example
Nonstandard Implementation Schemes
Several proprietary models for implementing
Java-based web services are available
Only work with specific Java web service engine
Intended to be faster way of launching web
service
Example: Apache Axis provides simple scheme
called JWS -
 Take source file for a concrete Java class, rename it
with .jws extension, and place it in your application’s
web context

If your web service has the Axis engine servlet
installed to handle .jws files, that engine will respond
to client requests, mapping code in JWS file to a web
service, complete with a WSDL descriptor
 Deploying Web Services
Like other J2EE components, web service implementations
need to be deployed to an application server

Deployment must tell web service engine how to manage

each web service at runtime, including for each service:
 Java implementation code information

Java-to-XML mapping information

Information for each service is typically provided by:


Web service deployment file (deployment descriptor)
 Mapping file (configuration file to expand default mappings)

Deployment and configuration file formats depend on the

particualrJava web service engine and application server
used
 J2EE Standard Model
JAX-RPC defines two approaches for
implementing web services:

simple Java object using RMI programming model,
running within a web container

EJB, running within an EJB container
Web Services for J2EE specification spells out
how web services are deployed in each of the
above cases
 Adding to information requirements for existing
deployment descriptors (web.xml and ejb-jar.xml)

Defining new deployment descriptors that axociate
specific components with corresponding web
services, as well as Java-to-XML conversions
 J2EE Standard Model
Steps for J2EE deployment model for web services:
2) Deploy the implementation component
 Web service implementation requires standard
component entry in its component archive
 For Java object, <servlet> entry in a web.xml
deployment descriptor

For EJB component, <session-bean> entry in an ejb-
jar.xml deployment descriptor
3) Create a web service deployment descriptor
 Takes the form of webservices.xml file included in
component archive (web or EJB)
 Lists each web service being deployed within that
component archive, linking the web service to
particular component and specifying the WSDL file for
the service and the Java-to XML mapping file for the
service
 J2EE Standard Model
1) Generate a WSDL descriptor for the web service
 Each web service must come bundled with a WSDL
descriptor within the component archive
 WSDL files are referenced in webservices.xml
2) Generate a JAX-RPC mapping file for each web
service
 Specifies how various Java entities in the
implementation are mapped into XML entities in the
WSDL descriptor
 Includes mapping Java packages to XML namespaces,
java methods to WSDL operations, Java objects to
WSDL data types and messages.
 Mapping file itself is in XML format, using schema
specified by Web Services for J2EE specification
 Simple Java Web Services
Web services implemented using simple Java objects
are deployed and managed within a web container
Service implementations themselves are not web
components, they’re just simple Java objects that follow
RMI programming model
<servlet> entries required in web.xml file for deployment,
create a virtual component for each web service
Require entry in webservices.xml deployment descriptor
located in the WEB-INF directory, following standard
XML Schema:
 <webservice-description>
<webservice-description-name>
Elements that specify WSDL descriptor for the service
Java/XML mapping file for the service
Information about each WSDL port in the web service
<port-component>
Name of port in WSDL file
Java interface used by the port implementation
reference to web component in the web.xml descriptor
 EJB Web Services
Web services implemented as EJB components are deployed much like
simple Java objects implementation
Web services tied to their EJB components in webservices.xml file
Each service also has JAX-RPC mapping file and WSDL file
All deployed within the EJB archive
Mapping files and webservices.xml file stored in META-INF directory,
while WSDL typically stored in META-INF/wsdl directory

Before a stateless session EJB can serve as a web service, its EJB
deployment descriptor entry needs to have a <service-endpoint> entry
added t it, to indicate the Java interface that its web service will expose:
<service-endpoint>
com.oreilly.jent.people.ejb.PeopleFinder</service-endpoint>

Key difference of EJB deployment is in the webservices.xml file:


The <webservice-description> entry will point to the appropriate EJB
component in the EJB archive, rather than to the virtual web
component used for simple Java class implementations.
 Axis Deployment Model

Came before Web Services for J2EE specification

Very popular engine for building and using web services
in Java/J2EE environments
Good example of nonstandard approach
Uses its own Web Services Deployment Descriptor
(WSDD) and separate namespace/package mapping file
WSDD fulfills very similar roles to webservices.xml file
WSDD contains <service> element, similar role of
<webservice-description> entry in webservices.xml file
Questions?