Ws

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------------------------------------------------------------------------------------------------------------------ SOAP body partial code: <soapenv:Body> <nsl:findpeople Soapenv:encodingStyle=“http://sschemas.xmlsoap.org/soap/encoding/” --------------------------------------------------------------------------------------------------------------------------------------------------------------

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 <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 continued Entities: data types – building blocks for SOAP messages; can be simple as one string, or a complicated XML structure with internal hierarchy Example: <wsdl:definitions . . . > <wsdl:types> <schema . . . > <sequence> <element name= “firstName” nillable = “true” Type = “soapenc:string”/> ----------------------------------------------------------------------------<sequence> 

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 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”/> -----------------------------------------------------------------------------

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 (JAXRPC), 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 pregenerated 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 JAXRPC 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 ejbjar.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 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?