Copyright 2005 SYSNET International, Inc. 1
Web Services Development with the
Apache Web Services Toolkit
Odysseas Pentakalos, Ph.D.
Chief Technical Officer SYSNET International, Inc.
odysseas@sysnetint.com
Developing Web Services with Axis
Introduction to Axis Styles Supported Client Development Architecture
Advanced Features
UDDI and jUDDI WS-Addressing
Copyright 2005 SYSNET International, Inc. 3
Apache Axis
Brief History of Axis (TD)
Apache Extensible Interaction System IBM contributes SOAP4J to Apache in 1999 Apache SOAP is released
Toolkit for developing SOAP 1.1 clients/servers Monolithic architecture
No support for other transports (some SMTP)
Axis 1.0 is released in October 2002 Axis 1.2.x is the current release
Copyright 2005 SYSNET International, Inc. 5
Axis: What do you get?
Toolkit for building clients/servers Support for SOAP 1.1/1.2
Simple stand-alone server
Server that plugs into servlet container Support for WSDL 1.1
Tool for monitoring SOAP messages
Features
Chains of message processing components Flexible extensibility:
Custom header processing Logging
Extensible transport framework
Clean separation between transport and engine Transport support for various protocols
Copyright 2005 SYSNET International, Inc. 7
Axis Client APIs
Generated Stubs:
Generate stubs from WSDL using provided tools. Use of web services is totally transparent to the application
Dynamic Stubs:
Stubs are generated at runtime as opposed to development time
Dynamic Invocation:
Build the request dynamically using the Call object
Generated Stub Client
WSDL2Java tool generates stubs and skeletons
based on WSDL
java org.apache.axis.wsdl.WSDL2Java
http://localhost:8080/axis/Calculator.jws?wsdl
CalculatorLocator locator = new CalculatorLocator(); Calculator stub = locator.getCalculator();
Copyright 2005 SYSNET International, Inc. 9
Dynamic Invocation
The SOAP call is constructed dynamically at runtime public class TestClient {
public static void main(String [] args) {
String endpoint = "http://ws.apache.org/axis/services/echo"; Service service = new Service();
Call call = (Call) service.createCall();
call.setTargetEndpointAddress( new java.net.URL(endpoint) ); call.setOperationName(new QName("http://soapinterop.org/", echoString"));
String ret = (String) call.invoke( new Object[] { "Hello!" } ); System.out.println("Sent 'Hello!', got '" + ret + "'");
Dynamic Stub Client
Stub is generated on the fly from the service
interface
Calculator calcPort = (Calculator) service.getPort(Calculator.class);
Copyright 2005 SYSNET International, Inc. 11
Supported WS Styles
RPC Style: SOAP RPC conventions with the SOAP
data model
Document Style: most interoperable style where
body is an XML fragment
Wrapped Style: like document style but root
element corresponds to method name
Message Style: Axis-specific where pure XML is
passed to method
RPC Web Service Style
RPC/encoded style was very popular but due to
interoperability issues, WS-I disallows it
Root element corresponds to method name Parameters are encoded using SOAP encoding <soap:envelope> <soap:body> <addNumbers> <x xsi:type=“xsd:int”>5</x> <y xsi:type=“xsd:float”>5.0</y> </addNumbers> </soap:body>
Copyright 2005 SYSNET International, Inc. 13
Document Web Service Style
Now becoming the most popular style based on WS-I
recommendation
public void method(PurchaseOrder po)
<soap:Envelope xmlns="http://xml.apache.org/axis/wsdd/" xmlns:java="http://xml.apache.org/axis/wsdd/providers/java"> <soap:Body> <myNS:PurchaseOrderxmlns:myNS="http://commerce.com/PO" > <item>SK001</item> <quantity>1</quantity> <description>Sushi Knife</description> </myNS:PurchaseOrder> </soap:Body> </soap:Envelope>
Wrapped Web Service Style
Like document literal since SOAP body is defined in the
WSDL schema
public void purchaseOrder(String item, int quantity, String description)
<soap:Envelope xmlns="http://xml.apache.org/axis/wsdd/" xmlns:java="http://xml.apache.org/axis/wsdd/providers/java"> <soap:Body> <myNS:PurchaseOrder xmlns:myNS="http://commerce.com/PO"> <item>SK001</item> <quantity>1</quantity>
Copyright 2005 SYSNET International, Inc. 15
Message Web Service Style
XML passed to service
Four supported method signatures:
public Element[] method(Element[] bodies);
public SOAPBodyElement[] method(SOAPBodyElement[] bodies); public Document method(Document body);
public void method(SOAPEnvelope req, SOAPEnvelope resp);
Axis Architecture: MessageContext
MessageContext provides a uniform context in
the processing of chains of handlers
Request Message
Response Message
Properties
Hard-wired properties
Copyright 2005 SYSNET International, Inc. 17
Axis Architecture: Handlers
Concept of Handler is central to the extensible
architecture of Axis
public interface Handler extends Serializable { public void init();
public void cleanup();
public void invoke(MessageContext msgContext) throws AxisFault;
… }
Axis Architecture: Handler Example
init() method from LogHandler:public void init() { super.init();
Object opt = this.getOption("LogHandler.writeToConsole"); if (opt != null && opt instanceof String &&
"true".equalsIgnoreCase((String)opt)) writeToConsole = true;
Copyright 2005 SYSNET International, Inc. 19
Axis Architecture: Handler Example
invoke() method from LogHandler:public void invoke(MessageContext msgContext) throws AxisFault { log.debug("Enter: LogHandler::invoke"); if (msgContext.getPastPivot() == false) { start = System.currentTimeMillis(); } else { logMessages(msgContext); } log.debug("Exit: LogHandler::invoke"); }
Axis Architecture: Simple Chains
Simple Chains: a sequence of one or more
handlers that should be processed in sequence
Copyright 2005 SYSNET International, Inc. 21
Axis Architecture: Targeted Chain
Targeted Chain: special purpose chain that
consists of a request handler, a pivot handler and a response handler
Pivot Handler Request Handler
Response Handler
Copyright 2005 SYSNET International, Inc. 23
Example Axis Server Configuration
Global Configuration section
<globalConfiguration>
<parameter name="disablePrettyXML" value="true"/> <requestFlow>
<handler type="java:org.apache.axis.handlers.JWSHandler"> <parameter name="scope" value="session"/>
</handler>
<handler type="java:org.apache.axis.handlers.JWSHandler"> <parameter name="scope" value="request"/>
<parameter name="extension" value=".jwr"/> </handler>
</requestFlow> <responseFlow/> </globalConfiguration>
Example Axis Server Configuration
Service section<service name="AdminService" provider="java:MSG">
<namespace>http://xml.apache.org/axis/wsdd/</namespace> <parameter name="allowedMethods" value="AdminService"/> <parameter name="enableRemoteAdmin" value="false"/>
<parameter name="className" value="org.apache.axis.utils.Admin"/> </service>
Copyright 2005 SYSNET International, Inc. 25
Axis Architecture: Client-Side Processing
JWS: Instant Deployment
Drop-and-play style deployment
Axis locates, compiles and invokes the service as
needed
URL for following service is:
http://localhost:8080/axis/Calculator.jws
Copyright 2005 SYSNET International, Inc. 27
Deployment via Descriptors
For more deployment control use the deployment
descriptors in wsdd file.
Can specify scoping, handlers and chains and custom
encoders/decoders
<deployment xmlns="http://xml.apache.org/axis/wsdd/"
xmlns:java="http://xml.apache.org/axis/wsdd/providers/java"> <service name="MyService" provider="java:RPC">
<parameter name="className"
value="samples.userguide.example3.MyService"/> <parameter name="allowedMethods" value="*"/> </service>
</deployment>
XML/Java Type Mapping
Support for basic data types
All XML schema data-types map to their reasonable Java equivalent types
Support for Java Collections
Some Java collections are supported but interop is limited
Support for Java Beans
Support is built-into Axis through BeanSerializer
Copyright 2005 SYSNET International, Inc. 29
Custom Serialization
1. Develop the custom serializer/deserializer (implement Serializer/Deserializer interfaces) 2. Register type mapping through deployment
descriptor <typeMapping qname="ns:local" xmlns:ns="someNamespace" languageSpecificType="java:my.java.thingy" serializer="my.java.SerializerFactory" deserializer="my.java.DeserializerFactory" encodingStyle="http://schemas.xmlsoap.org/soap/enco ding/"/>
Supported Transports
HTTP JMS Mail (SMTP/POP3) JavaCopyright 2005 SYSNET International, Inc. 31
Monitoring SOAP messages
tcpmon
% java org.apache.axis.utils.tcpmon [listenPort targetHost targetPort]
Copyright 2005 SYSNET International, Inc. 33
UDDI and SOA
SOA Registry Service Provider Service Consumer Publish Find Bind
The registry is central to the SOA architecture
UDDI History
Originally defined for the purpose of providing a
public business and service registry
First few versions came out through UDDI.org UDDI v3.0 is an OASIS standard
Currently private registries are more popular in
Copyright 2005 SYSNET International, Inc. 35
UDDI Scenarios
Design time use
Developer searches through the private registry for existing services that can take part in an orchestrated application
Interest is in the functionality but not the specific instances
Run time use
Application searches through the private registry for the service but focus is now on implementations of it
UDDI Categorization
To support searching across a number of
dimensions, UDDI allows for categorization
Includes a number of built-in schemes:
North American Industry Classification System (NAICS) Universal Standard Products and Services Classification
(UNSPSC)
ISO 3166 for geographic location classification <categoryBag>
<keyedReference keyName=“Custom Software Services” keyValue=“54133”
Copyright 2005 SYSNET International, Inc. 37
UDDI Datatypes
businessEntity: represents any provider of a
service. Includes name, description, contact information. It can be categorized with multiple keyReferences
businessService: represents a single service that
is owned by a single businessEntity. It can be categorized with multiple keyReferences
bindingTemplate: describes the technical
information about a deployed implementation of a web services. Includes an access point and a reference to a tModel.
UDDI Datatypes (cont.)
tModel: Used in many different different ways in
UDDI.
Used for representing value sets such as identification
and categorization systems
Used to define the technical interface of a web service
publisherAssertion: represents an association
Copyright 2005 SYSNET International, Inc. 39
Using UDDI
A UDDI registry is exposed as a web service
UDDI Inquiry API: defines find and get operations
against the registry
UDDI Publication API: defines operations for adding,
updating and removing content from the registry
Clients can be developed:
UDDI4J: open source Java API
JAX-RPC: a client application can be generated via the
WSDL
JAXR: standard API for access to registries such as
ebXML and UDDI.
jUDDI Architecture
Is implemented as a J2EE web application so can
be deployed on any J2EE web container
Requires an external database for persisting the
entries of the registry
Scripts are included for various standard RDBMS Provides default authenticator but includes a
pluggable-interface that will allow integration into existing authentication scheme
Copyright 2005 SYSNET International, Inc. 41
jUDDI Architecture
Sequence diagram of request processing
Installation
Configure jUDDI (juddi.properties)
Specify and configure DataSource juddi.dataSource=java:comp/env/jdbc/juddiDB Configure API URLs
juddi.proxy.inquiryURL=http://localhost:8080/juddi/inquiry Configure Authenticator Module
Configure UUIDGen Module
Copyright 2005 SYSNET International, Inc. 43
Using jUDDI
Copyright 2005 SYSNET International, Inc. 45
Using jUDDI through UDDI4j
Configure the proxy
UDDIProxy proxy = new UDDIProxy();
proxy.setInquiryURL("http://localhost:8080/juddi/inquiry"); proxy.setPublishURL("https://localhost:8080/juddi/publish”);
Find a business
BusinessList bl = proxy.find_business(“sysnet", null, 0);
Copyright 2005 SYSNET International, Inc. 47
Why do we need Addressing?
To find a Web Service you need a URL. Simple
right?
Address the web service with the URL, set the
action in the HTTP headers and you are set.
How about intermediaries?
How about SOAP over non-HTTP protocol?
How about dynamically generated web services?
Basic Concepts: Endpoint References
Endpoint references:
Dynamic generation and customization of service
endpoint descriptions.
Referencing and description of specific service
instances that are created as the result of stateful interactions.
Flexible and dynamic exchange of endpoint
information in tightly coupled environments where communicating parties share a set of common assumptions about specific policies or protocols that
Copyright 2005 SYSNET International, Inc. 49
Endpoint Reference Definition
An Endpoint Reference consists of:
Address: is a URI and identifies the address of the
endpoint
ReferenceParameters: XML elements that are
necessary in order to successfully interact with the web service
Metadata: provides an extensible container for
metadata that describes the endpoint
<wsa:EndpointReference
xmlns:wsa="http://www.w3.org/2005/03/addressing">
<wsa:Address>http://example.com/fabrikam/acct</wsa:Address> </wsa:EndpointReference>
Message Information Headers
Message Information Headers: headers to allow
messages to be addressed to an endpoint all within the SOAP message.
To: The URL of the target service
<wsa:To>http://localhost/MyServiceTest</wsa:To>
Copyright 2005 SYSNET International, Inc. 51
Message Information Headers
ReplyTo: The ERP to which the response should be
sent to.
FaultTo: The ERP to which the SOAP fault should be
sent to.
MessageID: Is a URI that uniquely identifies the
message
Action: Takes the place of the SOAPAction
RelatesTo: Element that indicates the MessageID of
the caller.
Axis WS-Addressing Implementation
Originally implemented as a pair of Axis handlers
(client-side and server-side)
Now also includes a pair of JAX-RPC handlers
thereby reducing dependency on Axis
Current implementation is a little behind the
Copyright 2005 SYSNET International, Inc. 53
Using Axis WS-Addressing
Client-side example from docs.
private static AddressingHeaders setUpAddressing() throws Exception {
AddressingHeaders headers = new AddressingHeaders(); Action a = new Action(new URI("urn:action"));
headers.setAction(a);
EndpointReference epr = new
EndpointReference("http://www.apache.org"); headers.setFaultTo(epr);
return headers; }
Using Axis WS-Addressing (cont.)
Client-side example from docs.
public static void main(String[] args) throws Exception {
Service service = new Service(); Call call = (Call) service.createCall();
AddressingHeaders headers = setUpAddressing();
call.setProperty(Constants.ENV_ADDRESSING_REQUEST_HEADERS, headers);
call.setTargetEndpointAddress(new java.net.URL(url)); call.setOperationName(new QName(
Copyright 2005 SYSNET International, Inc. 55
WS-Addressing Deployment
Axis addressing deployment descript
<?xml version="1.0" encoding="UTF-8"?>
<deployment xmlns="http://xml.apache.org/axis/wsdd/" xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">
<handler name="addr"
type="java:org.apache.axis.message.addressing.handler.AddressingHandler" /> <service name="AddressedVersion" provider="java:RPC">
<requestFlow> <handler type="addr"/> </requestFlow> <responseFlow> <handler type="addr"/> </responseFlow>
<parameter name="allowedMethods" value="getVersion"/> <parameter name="className" value="org.apache.axis.Version"/> </service>
</deployment>
Copyright 2005 SYSNET International, Inc. 57
Why do we need Reliable Messaging?
Network failures may prevent messages from
being delivered
Middleware failures may cause messages from
being delivered
Intermittent failures may cause duplicates Routing delays may cause out of order delivery
WS-Reliable Messaging Concepts
Sequence: reliable messaging is enforced within
the context of a sequence between two endpoints
Acknowledgments: an ack from the server
indicates the sequence range of messages received
Delivery Assurance Policy: endpoints can
Copyright 2005 SYSNET International, Inc. 59
Reliable Messaging Model
Application Source Initial Sender Application Source Ultimate Receiver Send Delivery RM Source Transmit RM Destination Receive Acknowledge
Reliable Messaging Protocol
Endpoint A
Endpoint B
Create Sequence
Create Sequence Response (Identifier) Sequence (Identifier, MessageNumber=1) Sequence (Identifier, MessageNumber=2) Sequence (Identifier, MessageNumber=3, LastMessage)
Sequence Ack. (Identifier, Range=1,3) Sequence (Identifier, MessageNumber=2)
Copyright 2005 SYSNET International, Inc. 61
Sequence Message
<wsrm:Sequence ...><wsu:Identifier> [URI] </wsu:Identifier> <wsrm:MessageNumber> [unsignedLong] </wsrm:MessageNumber>
<wsrm:LastMessage/>?
<wsu:Expires> [dateTime] </wsu:Expires>? ... </wsrm:Sequence>
Sequence Example
<wsrm:Sequence> <wsu:Identifier> http://fabrikam123.com/abc </wsu:Identifier> <wsrm:MessageNumber>10</wsrm:MessageNumber> <wsrm:LastMessage/> </wsrm:Sequence>Copyright 2005 SYSNET International, Inc. 63
Sequence Acknowledgement
<wsrm:SequenceAcknowledgement ...><wsu:Identifier> [URI] </wsu:Identifier> [ <wsrm:AcknowledgementRange ... Upper="[unsignedLong]" Lower="[unsignedLong]"/> + | <wsrm:Nack>[unsignedLong]</wsrm:Nack> + ] ... <wsrm:SequenceAcknowledgement>
Sequence Ack Example
<wsrm:SequenceAcknowledgement> <wsu:Identifier>
http://fabrikam123.com/abc </wsu:Identifier>
<wsrm:AcknowledgementRange Upper="2" Lower="1"/> <wsrm:AcknowledgementRange Upper="6" Lower="4"/> <wsrm:AcknowledgementRange Upper="10" Lower="8"/> </wsrm:SequenceAcknowledgement>
Copyright 2005 SYSNET International, Inc. 65
Create Sequence Message
Request <wsrm:CreateSequence ...> ... </wsrm:CreateSequence> Response <wsrm:CreateSequenceResponse ...>
<wsu:Identifier> [URI] </wsu:Identifier> ...
</wsrm:CreateSequenceResponse>
Sequence Termination
<wsrm:TerminateSequence ...>
<wsu:Identifier> [URI] </wsu:Identifier> ...
Copyright 2005 SYSNET International, Inc. 67
Sandesha Architecture
High-level architecture of Sandesha
Sandesha Architecture on Axis
Interaction between the Sandesha Architecture
Copyright 2005 SYSNET International, Inc. 69
Using Sandesha on the Client
public static void main(String[] args) { try {
Service service = new Service(); Call call = (Call) service.createCall();
SandeshaContext ctx = new SandeshaContext(); ctx.addNewSequeceContext(call, targetUrl,
"urn:wsrm:echoString",Constants.ClientProperties.IN_OUT); call.setOperationName(new QName("http://tempuri.org/", "echoString"));
call.addParameter("Text", XMLType.XSD_STRING, ParameterMode.IN); call.addParameter("Seq", XMLType.XSD_STRING, ParameterMode.IN); call.setReturnType(org.apache.axis.encoding.XMLType.XSD_STRING); ctx.setLastMessage(call);
String ret = (String) call.invoke(new Object[] {"Sandesha Echo 1", "abcdef"}); System.out.println("The Response for First Messsage is :" + ret);
ctx.endSequence(call); } catch (Exception e) {
Copyright 2005 SYSNET International, Inc. 71
Transactions
Why do we need Transactions?
In an application based on an orchestration of
Web Services all services involved in an operation must come to an undisputed resolution.
Typical ACID semantics are useful for some but
long-running transactions need different transactional support.
Copyright 2005 SYSNET International, Inc. 73
Atomic Transactions
Atomicity: on completion either all actions or
none are completed.
Consistency: consistency in the system is
preserved after processing multiple concurrent transactions
Isolation: intermediate states of the system are
not observable outside the transaction
Durability: if a transaction commits, the changes
are preserved even after a system failure
Business Transactions
Long-running transactions: transactions may take
hours, days or weeks to complete
Need to be able to select a subset of the original
participants before a commit
Compensating transactions: operations that are
Copyright 2005 SYSNET International, Inc. 75
Standards and scope
WS-Coordination:
allows a distributed system to establish a group of participants
around an activity
participants can register interest in participating in the outcome Coordination protocol can vary but operates upon completion of
the activity WS-Atomic:
Handles ACID transactions and defines variations of 2PC
WS-Business Activity:
Allows for the definition of nested scopes of operations Allows for the definition of compensating transactions
Copyright 2005 SYSNET International, Inc. 77
Coordination Context
Before services can participate in a transaction they need to establish a CoordinationContext. The response includes an identifier, an
expiration time and an endpoint reference to the registration service.
<soapenv:Envelope xmlns:soapenv=“http://schemas.xmlsoap.org/soap/envelope” xmlns:wscoor=“http://schemas.xmlsoap.org/ws/2002/09/wscoor”> <soapenv:Body> <wscoor:CreateCoordinationContext> <wscoor:CoordinationType> http://schemas.xmlsoap.org/ws/2002/09/wsat </wscoor:CoordinationType> </wscoor:CreateCoordinationContext> </soapenv:Body> </soapenv:Envelope>
Copyright 2005 SYSNET International, Inc. 79
Kandula
Goal is to provide complete support for:
WS-Coordination
WS-Atomic Transaction WS-Business Activity
Currently provides support for WS-Coordination
and part of WS-Atomic Transaction
Provides interfaces between the web services tx
context and the underlying service-specific context
Copyright 2005 SYSNET International, Inc. 81
Sequence of interactions
References
1. The specifications of course 2. ws.apache.org
3. “Web Services Platform Architecture”, by Weerawarana, Curbera, Leymann, Storey and Ferguson, Prentice Hall, 2005
4. “Building Web Services with Java”, Graham, Davis, et al., Sams Publishing, 2005
Copyright 2005 SYSNET International, Inc. 83