Notes on Web Services and Tools
Created 02/16/03
Updated 03/02/03, Updated 04/25/04, Updated 06/16/05, Updated 08/12/06, Updated 11/26/06, Updated 12/04/06
Updated 07/31/07, Updated 08/02/07, Updated 08/07/07, Updated 12/27/07, Updated 01/14/08, Updated 07/12/08
Updated 12/06/08, Updated 02/10/09, Updated 03/27/09, Updated 10/12/09, Updated 02/15/10, Updated 09/10/10
Updated 11/19/11, Updated 04/09/12, Updated 12/30/12, Updated 05/04/13, Updated 07/06/13, Updated 07/09/13
Updated 07/12/13, Updated 07/26/13
Introduction
These notes first describe Web Services from a concepts, standards, terminology, and technology perspective. Of all
the technologies that were current in the mid-decade, this is probably the one with most importance, and yet the
most scattered implementations and approaches. During the 2005-2008 era, we have seen entire library sets and
tools come and go, not to mention software companies producing commercial versions of such tools.
Then these notes focus on tools for developing and deploying Web Services using Java. In particular we look at
four of them: Apache CXF, Spring web services, Apache Axis2, and Sun’s Metro.
There are several key standards that underlie web services:
 JAX-WS is a reference standard for Web Services implementation within the JEE world that has been
driven by Sun, JBoss, and others and is present in their application servers.
 JAX-RS is a reference standard for REST-based services
 WSDL is the description standard
 JAXB is the binding standard
 SOAP is the protocol/payload standard
 UDDI is the discovery standard
Resources
“Implementing SOA Using Java EE” by B.V. Kumar, Prakash Narayan, Tony Ng. Addison-Wesley Professional,
January 2010, 384 pages. List price $54.99 Amazon price $42.77, used from $24.00. Rated 4 stars on
Amazon.com. The authors are from Cognizant, Sun, and Yahoo!
“Open Source SOA” by Jeff Davis. Manning Press, June 2009, 448 pages. List price $49.99, Amazon price $31.77,
used from $26.55. Rated 5 stars.
“Java SOA Cookbook” by Eben Hewitt. O’Reilly Press, May 2009, 740 pages. List price $49.99, Amazon price
$31.40, used from $25.66. Rated 5 stars on Amazon.com (from 2 reviews). One of the best and most recent
solution-oriented books on Web Services and related technologies. Has chapters on JAX-WS, web service tools,
notes on developing web service API’s, and more. There is a copy available on the IEEE Computer Society Safari
bookshelf.
“Java Web Services: Up and Running” by Martin Kalin. O’Reilly Press, February 2009, 316 pages. List price
$35.33, Amazon price $23.09, used from $19.49. Rated 4.5 stars on Amazon.com (from 6 reviews). This exampledriven book offers a thorough introduction to Java's APIs for XML Web Services (JAX-WS) and RESTful Web
Services (JAX-RS). We found this book to be tightly-written and containing a large number of useful examples. It
is probably the most up-to-date book about JAX-WS.
“JBoss in Action” by Javid Jamae and Peter Johnson. Manning Press, January 2009, 496 pages. List price $49.99,
Amazon price $31.40, used from $27.10. Rated 5 stars (from 1 review). This JBoss book has a chapter on Web
Service implementation, and that chapter happens to be on the free download list. See
http://www.manning.com/jamae/chapter_9.pdf.
Page 1 of 17
Printed at 8:28 PM on 3/7/2016
“SOA Using Java Web Services”, by Mark D. Hanson. Prentice-Hall PTR, May 2007, 608 pages. List price
$49.99, Amazon price $49.99, used from $37.40. Rated 4 stars on Amazon. This is a relatively recent book on the
topic, and covers the concepts as well as the details, using current JEE 5 and related implementations of Java tools.
Instead of being based on Axis, the bulk of the text essentially works through very detailed examples using JWS and
associated (recent) standards like JAXB 2.
“Java EE 5 Development using GlassFish Application Server”, David Heffelfinger, Packt Publishing, October 2007.
List price $49.99, Amazon price $44.99, used from $44.99. Rated 3 stars on Amazon.com. Covers the JAX-WS
implementation in GlassFish, which tends to slightly lead the JBoss development.
“Developing Web Services with Apache Axis”, by Kent Tong. Lulu.com, April 2006, 178 pages. List price $32.95,
Amazon price $29.95, used from $19.63. This is the most recent book specifically on Axis. Rated 4 stars on
Amazon. Apparently it is a very step-by-step book, and relies on working in the Eclipse environment.
“Building Web Services with Java: Making Sense of XML, SOAP, WSDL, and UDDI (2nd Edition)” by Steve
Graham, Doug Davis, et. al. New Riders, June 2004, 800 pages. List price $49.99 Amazon price $31.49 used from
$20. Rated 3.5 stars. This revised edition covers the new SOAP 1.2 and WSDL 1.2 standards, as well as other
technologies developed since the first edition was published, including the Java Web Services Developer Pack from
Sun and the powerful Apache Axis Web services engine. Throughout the book the authors focus on practical
examples of each concept and provide a running example illustrating a full enterprise solution.
There are dozens of other books on Web Services, a portion of which deal with Java implementations.
Web Services Overview
At a simple level, web services are remotely invocable operations. While this has been done several times before
(RPC, DCE, CORBA, etc.), web services are more open version of the concept, and have gained a level of
acceptance that the earlier approaches did not.
Web Services enable a Service-Oriented-Architecture, in which system elements interact with each other, where
each one is exporting one or more services. The services can be fine-grain, like specific lookup and fetch
operations, or can be entire business processes such as “order validation”.
Also, Web Services have concepts of description and discovery that were not present (as completely) in the earlier
approaches. These facilities for description are called WSDL files and are specifications how to use a given web
service. XML is ubiquitous in the Web Services area, and in particular, the XML Schema facilities are used greatly
for describing complex data structures. The WSDL specification uses XML Schema in many areas.
The idea of metadata-driven specification of invocation information allows for interoperability between Web
Service providers and requestors, even on different platforms. The interoperability stacks are:



Wire – this covers how information is serialized for sending as buffers “on the wire”
Description – this covers how URLs and their request and response objects are described in representation
neutral fashion
Discovery – this covers how descriptions may be publically offered and found.
Relevant Concepts of XML
XML is mostly covered in our document “Notes on XML and its Usage”, which talked about DOM, SAX, element
structure, namespaces, etc. That document also had a brief introduction to SOAP. The document was focused on
the creation and navigation through the tree of elements that constitutes an XML document.
The additional layer that one must understand for Web Services is XML Schemas. These provide the equivalent of
a data structure description language, which has primitive types, complex types, inheritance, and more. Without
these, one cannot provide an interface definition facility that has the structural sophistication of CORBA, DCE, etc.
Page 2 of 17
Printed at 8:28 PM on 3/7/2016
Here is a simple example of an XML Schema (where the “xsd” namespace has been mapped to the XMLSchema
standard, located at: “http://www.w3.org/2001/XMLSchema”
<xsd:simpleType name=”skuType”>
<xsd:restriction base=”xsd:string”>
<xsd:pattern value=”\d{3}-[A-Z]{2}”/>
</xsd:restriction>
</xsd:simpleType>
For complex types, there are tags that indicate the combining rules for the complex classes:
 xsd:sequence – a specific sequence of the elements
 xsd:choice – allows one out of the list
 xsd:all – allow a certain set of elements one or not at all but in any order
 xsd:group – references a model group that is defined someplace else
Here is an example:
<xsd:complexType name=”addressType”>
<xsd:sequence>
<xsd:element name=”name”
type=”xsd:string”
<xsd:element name=”company”
type=”xsd:string”
<xsd:element name=”street”
type=”xsd:string”
<xsd:element name=”postalCode” type=”xsd:string”
<xsd:element name=”country”
type=”xsd:string”
</xsd:sequence>
<xsd:attribute name=”id”
type=”xsd:ID”/>
<xsd:attribute name=”href” type=”xsd:IDREF”/>
</xsd:complexType>
minOccurs=”0”/>
minOccurs=”0”/>
maxOccurs=”unbounded”/>
minOccurs=”0”/>
minOccurs=”0”/>
Some thoughts that we have on this facility, now that we are seeing it for the 3rd or 4th time, is first of all how much
is resembles the metadata facilities developed by integration vendors (i.e., TIBCO), and that by now there must be a
standard, stable, implementation of these metadata facilities and readers. It is here that a variety of open source
libraries for metadata processing come into play.
SOAP
SOAP is a specification for requesting invocation of a service. Technically, it stands for Simple Object Access
Protocol, but this name is not particularly meaningful. The term “object” in SOAP would seem to imply some
connection to object-oriented development, but instead SOAP is entirely procedural in nature. Finally, “protocol”
might convey some sense that it’s a replacement or upgrade to HTTP, but instead SOAP relies on other protocols to
actually handle data transfer.
SOAP is a specific organization of an XML document. These documents are called messages. SOAP messages
have an envelope framework that includes a versioning section, headers, and a body. SOAP is now on version 1.2.
SOAP provides an elegant mechanism for specify the encoding rules that apply to the message as whole or any
portion of it. This is the done via the encodingStyle attribute in the SOAP envelope namespace. It uses a type
system based on XML Schema.
REST
REST is an alternative to SOAP, and is a term coined by Roy Fielding in his Ph.D. dissertation to describe an
architectural style of networked systems. REST is an acronym standing for Representational State Transfer.
Why is it called Representational State Transfer? The Web is comprised of resources. A resource is any item of
interest. For example, the Boeing Aircraft Corp may define a 747 resource. Clients may access that resource with
this URL:
Page 3 of 17
Printed at 8:28 PM on 3/7/2016
http://www.boeing.com/aircraft/747
A representation of the resource is returned (e.g., Boeing747.html). The representation places the client
application in a state. The result of the client traversing a hyperlink in Boeing747.html is another resource is
accessed. The new representation places the client application into yet another state. Thus, the client application
changes (transfers) state with each resource representation, and hence this is Representational State Transfer.
In many ways, REST is a return to the simpler XML-RPC concept, because it lets you interchange XML documents
using standard HTTP concepts. That said, REST is an architectural style without a concrete specification, using
REST is a lot closer to opening up a stream of bytes. For instance, you can invoke a REST-based service simply by
using the query string of a URL. It has become quite popular in social networking sites, such as those that provide
data for mashups.
For more on REST see http://conveyer.com/RESTwiki/moin.cgi.
RPC or Document Style
Web Services can be built as ‘RPC’ or ‘document’ styles (Open Question: how is this related to the WS or REST
discussion above?). In the document style, whole documents are exchanged between caller and service. This is
controlled with a SOAP attribute. If the attribute is not specified, the protocol will use document style.
In a SOAP message for which document style is declared, the message is placed directly into the body portion of the
SOAP envelope, either as-is or encoded. If the style is declared as RPC, the message is enclosed within a wrapper
element, with the name of the element taken from the operation name attribute and namespace taken from the
operation namespace attribute.
The benefits of document style include:




You can use full XML processing and validation
Does not require a rigid contract, but instead uses the WSDL.
Better suited for asynchronous processing
Makes object exchange more flexible, because the WSDL-specified document is the basis for the exchange.
You should use document style anytime you are not interfacing with a pre-existing remote procedure call.
Examples of Web Services API’s in production use
One that we have been looking at lately is Kiva.org, which introduced an API in early 2009. This site manages lists
of loans for emerging-nation entrepreneurs.
For example, take the operation called ‘loans/search’. This call returns paginated results of loans matching certain
filtering criteria, which can be expressed in XML, JSON, or an HTML table (the XML and JSON formats are
particularly useful for mashups). Optionally the data can be sorted.
URL: http://api.kivaws.org/v1/loans/search.xml
Parameters


sort_by | (string) - The order in which to sort the results
o
one of [popularity, loan_amount, oldest, expiration, newest, amount_remaining, repayment_term]
o
default: newest
page | (number) - the page position of results to return
Filtering
Results are filtered by these criteria if specified. Some criteria use a default filter value; otherwise results are not
filtered by that criteria.
Page 4 of 17
Printed at 8:28 PM on 3/7/2016

status | (list) - The status of the loans to return
o

gender | (list) - Matches the gender of the borrower(s) requesting the loan
o

any of [male,female]
sector | (list) - Matches sector based on the name of a sector
o

any of [fundraising, funded, in_repayment, paid, defaulted]
string
region | (list) - Matches two character codes representing Kiva lending regions
o
any of [na,ca,sa,af,as,me,ee]

country_code | (list) - Matches valid two character ISO codes representing the origin of the loans

partner | (list): Matches partners based on numeric id
o

item type: number
q | (string) - general query string applied to activity, city or country, partner, or business name
Output
 loans
This API can be thought of REST-based, because you send URLs with their query strings holding the parameters. It
can be thought of as a web service because one of the results can be an XML file. It is somewhat of a weak Web
Service in its formal sense, because there is no WSDL file, description facility, or discovery facility.
Characteristics of the Data Model for a Web Service
1.
2.
3.
4.
5.
6.
7.
8.
DOM-tree structured, i.e., built into a set of nested groups. This doesn’t lend itself well to an HTML table,
but is a clear match for XML or JSON trees. However, the tree should not be too deep, or in many cases
you will be transmitting more detail that is needed.
Presentation-oriented, i.e., you don’t have to look up the meaning of status codes. For instance, the loan
status says “paid”, it doesn’t give the type code for “paid”, such as 3.
Standardized date formats – there is an Internet RFC for this.
Key relationships can be traversed in successive calls, i.e., the primary key of the major items (such as
lenders or loads) are given as an integer or other unique value. This value can then be used in successive
calls. In Kiva.org, the primary keys are integers, while in salesforce.com, the primary keys are code strings
that appear to be GUIDs of some cryptic design.
Status representing, i.e., there is to be a field that indicates a status result, no matter what the rest of the
result is. This status might also include the timestamp at which the request was processed, or the user token
which was provided for authentication.
Validating, i.e., the possible values of control fields in the input are checked and when there is an error, you
get a clear indication. An example in Kiva.org is that the only possible values for ‘gender’ are ‘male’, and
‘female’, and if you try to filter for any other value you get an error rather than a null result.
Consistently noun-oriented or verb-oriented. This facet is related to the REST vs RPC approach.
Authenticating, i.e., you first identify yourself and get a token that is used in all successive calls, to provide
the context and access rules for your requests. The Amazon, FedEx, and eBay API’s all have this.
See also http://kingsfleet.blogspot.com/2009/02/exposing-tables-mapped-to-entity-beans.html.
Page 5 of 17
Printed at 8:28 PM on 3/7/2016
Java Web Services Toolkits
This part of the document has been revised in 2007, 2009, and 2013 to reflect the most-current and commonly used
tools. We are particularly looking at toolkits that can be integrated into applications that are not full JEE stack
environments, avoiding those that require all of JBoss for their runtime.
As of 2013, the landscape looks like:
 CXF
 Spring Web Services
 Axis2
 Metro
Comparisons: http://stackoverflow.com/questions/297033/which-framework-is-better-cxf-or-spring-ws?rq=1
http://stackoverflow.com/questions/1608996/comparison-between-sun-metro-and-apache-cxf-for-webservicesdevelopment
The common element to most of these is the JAX-WS package, which defines the endpoints, methods, parameters,
etc. Another common element is the binding library, with JAXB as the most common.
Older toolkits include:
 Axis
 XFire (replaced by CXF)
Using Apache CXF
Apache CXF is an open source services framework. CXF helps you build and develop services using frontend
programming APIs, like JAX-WS and JAX-RS. These services can speak a variety of protocols such as SOAP,
XML/HTTP, RESTful HTTP, or CORBA and work over a variety of transports such as HTTP, JMS or JBI.
JSR Support




JAX-WS - Java API for XML-Based Web Services (JAX-WS) 2.0 - JSR-224
Web Services Metadata for the Java Platform - JSR-181
JAX-RS - The Java API for RESTful Web Services - JSR-311
SAAJ - SOAP with Attachments API for Java (SAAJ) - JSR-67
WS-* and related Specifications Support



Basic support: WS-I Basic Profile 1.1
Quality of Service: WS-Reliable Messaging
Metadata: WS-Policy, WSDL 1.1 - Web Service Definition Language
Page 6 of 17
Printed at 8:28 PM on 3/7/2016


Communication Security: WS-Security, WS-SecurityPolicy, WS-SecureConversation, WS-Trust (partial
support)
Messaging Support: WS-Addressing, SOAP 1.1, SOAP 1.2, Message Transmission Optimization
Mechanism (MTOM)
Multiple Transports, Protocol Bindings, Data Bindings, and Formats





Transports: HTTP, Servlet, JMS, In-VM and many others via the Camel transport for CXF such as
SMTP/POP3, TCP and Jabber
Protocol Bindings: SOAP, REST/HTTP, pure XML
Data bindings: JAXB 2.x, Aegis, Apache XMLBeans, Service Data Objects (SDO), JiBX
Formats: XML Textual, JSON, FastInfoset
Extensibility API allows additional bindings for CXF, enabling additional message format support such as
CORBA/IIOP
Flexible Deployment




Lightweight containers: deploy services in Jetty, Tomcat or Spring-based containers
JBI integration: deploy as a service engine in a JBI container such as ServiceMix, OpenESB or Petals
Java EE integration: deploy services in Java EE application servers such as Apache Geronimo, JOnAS,
Redhat JBoss, OC4J, Oracle WebLogic, and IBM WebSphere
Standalone Java client/server
Support for Multiple Programming Languages









Full support for JAX-WS 2.x client/server programming model
JAX-WS 2.x synchronous, asynchronous and one-way API's
JAX-WS 2.x Dynamic Invocation Interface (DII) API
JAX-RS for RESTful clients
Support for wrapped and non-wrapped styles
XML messaging API
Support for JavaScript and ECMAScript 4 XML (E4X) - both client and server
Support for CORBA
Support for JBI with ServiceMix
Tooling





Generating Code: WSDL to Java, WSDL to JavaScript, Java to JavaScript
Generating WSDL: Java to WSDL, XSD to WSDL, IDL to WSDL, WSDL to XML
Adding Endpoints: WSDL to SOAP, WSDL to CORBA, WSDL to service
Generating Support Files: WSDL to IDL
Validating Files: WSDL Validation
Tools
CXF provides tools for generating code (wsdl2java, wsdl2js and java2js), generating WSDLs (java2ws, xsd2wsdl
and idl2wsdl), adding endpoints and support files (wsdl2soap and wsdl2corba), validating WSDLs (wsdlvalidate)
and for using Maven.

CXF tools in Eclipse

IDL to WSDL

Java to Javascript

Java to WS

Java to WSDL

Maven cxf-codegen-plugin (WSDL to Java)

Maven Java2WSDL plugin (CXF 2.0.x only. Removed in 2.1 and replaced with Java2WS)
Page 7 of 17
Printed at 8:28 PM on 3/7/2016

Maven Java2WS plugin

Using CXF with maven

WSDL to CORBA

WSDL to Java

WSDL to Javascript

WSDL to Service

WSDL to SOAP

WSDL to XML

WSDLValidator

XSD to WSDL
Java-First: Using JAX-WS
To describe a data object we use a Java class with just attributes. The Namespace will come from the package
name. To make JAXB understand this syntax only one annotation is necessary (XmlAccessorType). Of course
some more annotations are necessary if you want to use special features.
Customer datatype
package com.example.customerservice;
@XmlAccessorType( XmlAccessType.FIELD )
public class Customer {
String name;
String[] address;
int numOrders;
double revenue;
BigDecimal test;
Date birthDate;
CustomerType type;
}
The sample class Customer gives a nice overview which primitive datatypes can be used. Additionally you can
create arrays of primitive or class datatypes in this way. The complete example also contains an enumeration
definition to show this is possible. I think this code is quite near the DSL I would imagine to describe my services.
Here is an example of an enumeration:
package com.example.customerservice;
public enum CustomerType {
PRIVATE, BUSINESS
Page 8 of 17
Printed at 8:28 PM on 3/7/2016
}
Defining Exceptions is a little tricky as the default behaviour is to create Exception_Exception classes in the later
generated Java code. So we have to use the @WebFault annotation to give the Bean for the data a name that is
separate from the Exception name.
package com.example.customerservice;
@WebFault(name="NoSuchCustomer")
@XmlAccessorType( XmlAccessType.FIELD )
public class NoSuchCustomerException extends RuntimeException {
/**
* We only define the fault details here. Additionally each fault has a message
* that should not be defined separately
*/
String customerName;
}
Service definition
package com.example.customerservice;
@WebService
public interface CustomerService {
public Customer[] getCustomersByName(@WebParam(name="name") String name) throws
NoSuchCustomerException;
}
As you can see only two annotations are necessary here. @WebService marks the interface as a service and
@Webparam is necessary as Java will else lose the name of the parameter and the wsdl will contain arg0 instead of
the desired name. Using the @WebService annotation you can also customize the port name and service name.
To generate the wsdl the maven plugin cxf-java2ws-plugin is used. See the pom.xml in the complete example for
details.
Let´s take a look at the resulting WSDL
You can download the wsdl this example creates here.
<xs:complexType name="customer">
<xs:sequence>
<xs:element minOccurs="0" name="name" type="xs:string"/>
<xs:element maxOccurs="unbounded" minOccurs="0" name="address" nillable="true"
type="xs:string"/>
<xs:element name="numOrders" type="xs:int"/>
<xs:element name="revenue" type="xs:double"/>
Page 9 of 17
Printed at 8:28 PM on 3/7/2016
<xs:element minOccurs="0" name="test" type="xs:decimal"/>
<xs:element minOccurs="0" name="birthDate" type="xs:dateTime"/>
<xs:element minOccurs="0" name="type" type="tns:customerType"/>
</xs:sequence>
</xs:complexType>
The customer Class is a complex type in xsd. As you can see the Java types have been described as their respective
XSD primitive types.
Each element has minOccurs="0" which marks it as optional. This is a good thing as you can add new optional
elements and keep compatible. If you do not want this optionality you can use @XmlElement(required=true).
The array of Strings for address is described as maxOccurs="unbounded" so the element may be repeated in the later
xml to form the array.
The enumeration customerType is described as a simple type with a restriction:
<xs:simpleType name="customerType">
<xs:restriction base="xs:string">
<xs:enumeration value="PRIVATE"/>
<xs:enumeration value="BUSINESS"/>
</xs:restriction>
</xs:simpleType>
The Exception we defined is generated as a complexType with the defined details and a message for the fault. It is
important here that the Element and the Message have different names. We ensure this by using the @Webfault
Annotation above. Else the later Java Code generation will produce an ugly Exception name
NoSuchCustomerException_Exception.
<xs:element name="NoSuchCustomer" type="tns:NoSuchCustomer"/>
<xs:complexType name="NoSuchCustomer">
<xs:sequence>
<xs:element name="customerName" nillable="true" type="xs:string"/>
</xs:sequence>
</xs:complexType>
<wsdl:message name="NoSuchCustomerException">
<wsdl:part name="NoSuchCustomerException" element="tns:NoSuchCustomer">
</wsdl:part>
</wsdl:message>
The wsdl defines a SOAP/HTTP binding by default but can also be used to build services based on JMS as I will
show in my next post.
Page 10 of 17
Printed at 8:28 PM on 3/7/2016
Requirements of a JAX-WS Endpoint
JAX-WS endpoints must follow these requirements:

The implementing class must be annotated with either the javax.jws.WebService or
javax.jws.WebServiceProvider annotation.

The implementing class may explicitly reference an SEI through the endpointInterface element of the
@WebService annotation, but is not required to do so. If no endpointInterface is not specified in
@WebService, an SEI is implicityly defined for the implementing class.

The business methods of the implementing class must be public, and must not be declared static or final.

Business methods that are exposed to web service clients must be annotated with javax.jws.WebMethod.

Business methods that are exposed to web service clients must have JAX-B-compatible parameters and
return types. See Default Data Type Bindings.

The implementing class must not be declared final and must not be abstract.

The implementing class must have a default public constructor.

The implementing class must not define the finalize method.

The implementing class may use the javax.annotation.PostConstruct or javax.annotation.PreDestroy
annotations on its methods for lifecycle event callbacks.
The @PostConstruct method is called by the container before the implementing class begins responding to web
service clients.
The @PreDestroy method is called by the container before the endpoint is removed from operation.
You cannot use fields such as Timestamp or Date, because they don’t have a default no-arg constructor. Instead,
you must use String.
For instance, using JSR 181 annotations you can customize your service and the resulting WSDL relatively easily.
Here is an example:
package com.incra;
import java.util.ArrayList;
import java.util.Collection;
import java.util.List;
import
import
import
import
javax.jws.WebMethod;
javax.jws.WebParam;
javax.jws.WebResult;
javax.jws.WebService;
@WebService(name=”CustomerService”)
@Stateless
public class CustomerService {
private List<Customer> customers = new ArrayList<Customer>();
public CustomerService() {
}
Page 11 of 17
Printed at 8:28 PM on 3/7/2016
@WebMethod
@WebResult(name="Customers")
public Collection<Customer> getCustomers
(@WebParam(name="UserToken", header=true) UserToken auth) {
authorize(auth);
return customers;
}
private void authorize(UserToken auth) {
System.out.println(auth.getUsername());
System.out.println(auth.getPassword());
}
@WebMethod
public String addCustomer(@WebParam(name="UserToken", header=true) UserToken auth,
@WebParam(name="customer") Customer customer) {
authorize(auth);
customers.add(customer);
return "";
}
}
The “WebService”, “WebMethod”, and “WebParam” tags provide the information needed to generate the service.
How to Deploy to the Server
The purpose of the WebService annotation is to mark a endpoint implementation as implementing a web service or
to mark that a service endpoint interface as defining a web service interface. All endpoint implementation classes
MUST have a WebService annotation and must meet the requirements of section 3.3 of the JAX-WS 2.0
specification.
Property
Description
Default
Name
The name of the wsdl:portType
The unqualified name of the Java
class or interface
targetNamespace The XML namespace of the WSDL and some of the XML
elements generated from this web service. Most of the XML
elements will be in the namespace according to the JAXB
mapping rules.
The namespace mapped from the
package name containing the web
service according to section 3.2 of
the JAX-WS 2.0 specification.
serviceName
The unqualified name of the Java
class or interface + “Service”
The Service name of the web service: wsdl:service
endpointInterface The qualified name of the service endpoint interface. This
annotation allows the separation of interface contract from
implementation. If this property is specified, all other
WebService properties are ignored as are all other 181
annotations. Only the annotations on the service endpoint
interface will be taken into consideration. The endpoint
implementation class is not required to implement the
endpointInterface.
None – If not specified, the
endpoint implementation class is
used to generate the web service
contract. In this case, a service
endpoint interface is not required.
portName
The wsdl:portName
The WebService.name + "Port"
wsdlLocation
Not currently used by JAX-WS 2.0
Page 12 of 17
Printed at 8:28 PM on 3/7/2016
That means that the most important parameters include serviceName: if we had ProfitService, this would be
“ProfitServiceService”.
Here is an example from the Iona manual:
package com.iona.demo;
import javax.jws.*;
@WebService(name="quoteUpdater",
targetNamespace="http:\\demos.iona.com",
serviceName="updateQuoteService",
wsdlLocation="http:\\demos.iona.com\quoteExampleService?wsdl",
portName="updateQuotePort")
public interface quoteReporter {
public Quote getQuote(String ticker);
}
If there is a separate implementation file, the endpoint classes must implement the interface file, and have all the
same decorations.
WSDL-First: using the JAX-WS service
Using the WSDL first model of service development, you start with a WSDL document that defines the service you
wish to implement. This WSDL document could be obtained from another developer, a system architect, a UDDI
registry, or you could write it yourself. The document must contain at least a fully specified logical interface before
you can begin generating code from it.
Once you have a WSDL document, the process for developing a JAX-WS service is three steps:
1.
Generate starting point code.
2.
Implement the service's operations.
3.
Publish the implemented service.
Generating the Starting Point Code
JAX-WS specifies a detailed mapping from a service defined in WSDL to the Java classes that will implement that
service. The logical interface, defined by the wsdl:portType element, is mapped to a service endpoint interface
(SEI). Any complex types defined in the WSDL are mapped into Java classes following the mapping defined by the
Java Architecture for XML Binding (JAXB) specification. The endpoint defined by the wsdl:service element is
also generated into a Java class that is used by consumers to access endpoints implementing the service.
The wsdl2java command automates the generation of this code. It also provides options for generating starting point
code for your implementation and an ant based makefile to build the application. wsdl2java provides a number of
arguments for controlling the generated code.
Running wsdl2java
You can generate the code needed to develop your service using the following command:
wsdl2java -ant -impl -server -d outputDir myService.wsdl
The command does the following:
 The -ant argument generates a Ant makefile, called build.xml, for your application.
 The -impl argument generates a shell implementation class for each portType element in the WSDL
document.
 The -server argument generates a simple main() to launch your service as a stand alone application.
 The -d outputDir argument tells wsdl2java to write the generated code to a directory called outputDir.
Page 13 of 17
Printed at 8:28 PM on 3/7/2016

myService.wsdl is the WSDL document from which code is generated.
Generated code
Table1 describes the files generated for creating a service.
Table 1: Generated Classes for a Service
File
portTypeName.java
serviceName.java
portTypeNameImpl.java
portTypeName_portTypeNameImplPort_Server.java
Description
The SEI. This file contains the interface your
service implements. You should not edit this
file.
The endpoint. This file contains the Java class
your clients will use to make requests on the
service.
The skeleton implementation class. You will
modify this file to implement your service.
A basic server main() that allows you to
deploy your service as a stand alone process.
Implementing the Service
Once the starting point code is generated, you must provide the business logic for each of the operations defined in
the service's interface.
Generating the implementation code
You generate the implementation class for your service with wsdl2java's -impl flag.
Tip
If your service's contract included any custom types defined in XML Schema, you will also need to ensure that
the classes for the types are also generated and available.
Generated code
The service implementation code consists of two files:

portTypeName.java is the service interface(SEI) for the service.

portTypeNameImpl.java is the class you will use to implement the operations defined for the
service.
Implement the operation's logic
You provide the business logic for your service's operations by completing the stub methods in
portTypeNameImpl.java. For the most part, you use standard Java to implement the business logic. If your
service uses custom XML Schema types, you will need to use the generated classes for each type to manipulate
them. There are also some CXF specific APIs that you can use to access some advanced features.
Example
For example, an implementation class for a service that defined the operations sayHi and greetMe may look like
the following:
Implementation of the Greeter Service
package demo.hw.server;
import org.apache.hello_world_soap_http.Greeter;
@javax.jws.WebService(portName = "SoapPort", serviceName = "SOAPService",
targetNamespace = "http://apache.org/hello_world_soap_http",
Page 14 of 17
Printed at 8:28 PM on 3/7/2016
endpointInterface = "org.apache.hello_world_soap_http.Greeter")
public class GreeterImpl implements Greeter {
public String greetMe(String me)
{
System.out.println("Executing operation greetMe");
System.out.println("Message received: " + me + "\n");
return "Hello " + me;
}
public String sayHi()
{
System.out.println("Executing operation sayHi\n");
return "Bonjour";
}
}
Spring Web Services
Spring Web Services is a product of the Spring community focused on creating document-driven Web services.
Spring Web Services aims to facilitate contract-first SOAP service development, allowing for the creation of
flexible web services using one of the many ways to manipulate XML payloads.
Key Features









Makes the Best Practice an Easy Practice: Spring Web Services makes enforcing best practices easier.
This includes practices such as the WS-I basic profile, Contract-First development, and having a loose
coupling between contract and implementation.
Powerful mappings: You can distribute incoming XML request to any object, depending on message
payload, SOAP Action header, or an XPath expression.
XML API support: Incoming XML messages can be handled in standard JAXP APIs such as DOM, SAX,
and StAX, but also JDOM, dom4j, XOM, or even marshalling technologies.
Flexible XML Marshalling: The Object/XML Mapping module in the Spring Web Services distribution
supports JAXB 1 and 2, Castor, XMLBeans, JiBX, and XStream. And because it is a separate module, you
can use it in non-Web services code as well.
Reuses your Spring expertise: Spring-WS uses Spring application contexts for all configuration, which
should help Spring developers get up-to-speed nice and quickly. Also, the architecture of Spring-WS
resembles that of Spring-MVC.
Supports WS-Security: WS-Security allows you to sign SOAP messages, encrypt and decrypt them, or
authenticate against them.
Integrates with Acegi Security: The WS-Security implementation of Spring Web Services provides
integration with Spring Security. This means you can use your existing configuration for your SOAP
service as well.
Built by Maven: This assists you in effectively reusing the Spring Web Services artifacts in your own
Maven-based projects.
Apache license. You can confidently use Spring-WS in your project.
Page 15 of 17
Printed at 8:28 PM on 3/7/2016
Introduction to Axis2
Apache Axis2 is a core engine for Web services. It is a complete re-design and re-write of the widely used Apache
Axis SOAP stack. Implementations of Axis2 are available in Java and C.
Axis2 not only provides the capability to add Web services interfaces to Web applications, but can also function as a
standalone server application.
Apache Axis2 not only supports SOAP 1.1 and SOAP 1.2, but it also has integrated support for the widely popular
REST style of Web services. The same business-logic implementation can offer both a WS-* style interface as well
as a REST/POX style interface simultaneously.
Axis2/Java has support for Spring Framework.
Axis2/C seems to be abandoned in 2009.
Axis2 Features
Apache Axis2 includes support for following standards:
 WS - ReliableMessaging - Via Apache Sandesha2
 WS - Coordination - Via Apache Kandula2
 WS - AtomicTransaction - Via Apache Kandula2
 WS - SecurityPolicy - Via Apache Rampart
 WS - Security - Via Apache Rampart
 WS - Trust - Via Apache Rampart
 WS - SecureConversation - Via Apache Rampart
 SAML 1.1 - Via Apache Rampart
 SAML 2.0 - Via Apache Rampart
 WS - Addressing - Module included as part of Axis2 core
Further, Axis2 offers following features and characteristics.
 Speed - Axis2 uses its own object model and StAX (Streaming API for XML) parsing to achieve
significantly greater speed than earlier versions of Apache Axis.
 Low memory foot print - Axis2 was designed ground-up keeping low memory foot print in mind.
 AXIOM - Axis2 comes with its own light-weight object model, AXIOM, for message processing which is
extensible, optimized for performance, and simplified for developers.
 Hot Deployment - Axis2 is equipped with the capability of deploying Web services and handlers while the
system is up and running. In other words, new services can be added to the system without having to shut
down the server. Simply drop the required Web service archive into the services directory in the repository,
and the deployment model will automatically deploy the service and make it available for use.
 Asynchronous Web services - Axis2 now supports asynchronous Web services and asynchronous Web
services invocation using non-blocking clients and transports.
 MEP Support - Axis2 now comes handy with the flexibility to support Message Exchange Patterns
(MEPs) with in-built support for basic MEPs defined in WSDL 2.0.
 Flexibility - The Axis2 architecture gives the developer complete freedom to insert extensions into the
engine for custom header processing, system management, and anything else you can imagine.
 Stability - Axis2 defines a set of published interfaces which change relatively slowly compared to the rest
of Axis.
 Component-oriented Deployment - You can easily define reusable networks of Handlers to implement
common patterns of processing for your applications, or to distribute to partners.
 Transport Framework - We have a clean and simple abstraction for integrating and using Transports (i.e.,
senders and listeners for SOAP over various protocols such as SMTP, FTP, message-oriented middleware,
etc.), and the core of the engine is completely transport-independent.
Page 16 of 17
Printed at 8:28 PM on 3/7/2016



WSDL support - Axis2 supports the Web Services Description Language, version 1.1 and 2.0, which
allows you to easily build stubs to access remote services, and also to automatically export machinereadable descriptions of your deployed services from Axis2.
Add-ons - Several Web services specifications have been incorporated including WSS4J for security
(Apache Rampart), Sandesha for reliable messaging, Kandula which is an encapsulation of WSCoordination, WS-AtomicTransaction and WS-BusinessActivity.
Composition and Extensibility - Modules and phases improve support for composability and extensibility.
Modules support composability and can also support new WS-* specifications in a simple and clean
manner. They are however not hot deployable as they change the overall behavior of the system.
Introduction to Metro
Metro is an opensource web service stack that is a part of the GlassFish project, though it can also be used in a
stand-alone configuration.[1] Components of metro include JAXB RI, JAX-WS RI, SAAJ RI, StAX (SJSXP
implementation) and WSIT. It is available under the CDDL and GPLv2 (with classpath exception.)[2]
Questions and Open Issues
To be filled in later
Page 17 of 17
Printed at 8:28 PM on 3/7/2016