370
CHAPTER 14
■ BUILDING XML-BASED WEB SERVICES
name="web.xml"
lastUpdated="2006-06-28T20:51:23.984-04:00"
createdOn="2006-06-28T20:51:23.984-04:00">
</document>
</folder>
</ns1:manifest>
</soapenv:Body>
</soapenv:Envelope>
=_Part_2_16020374.1151542284234
Content-Type: application/octet-stream
Content-ID: <zip=>
Content-transfer-encoding: binary
=_Part_2_16020374.1151542284234—
If you examine the response message in Listing 14-5, you’ll notice it is a MIME multipart-related
message. The first part contains a SOAP 1.1 message document, and the second part contains binary
content (we have deleted the binary content from Listing 14-5) associated with downloaded ZIP file.
The SOAP 1.1 message part and the related parts form a SOAP 1.1 message package. Within a SOAP
1.1 message package, a core part contains the SOAP 1.1 message, and one or more related parts
contain attachments. In the “Understanding WSDL 1.1” section, you will see how an abstract WSDL
1.1 message definition is bound to a concrete MIME multipart-related message.
Understanding WSDL 1.1
Whenever you have to build a web service, the first step you need to take is to formally describe the
web service in a WSDL 1.1 document. Although it is possible to reverse engineer a WSDL 1.1 document
from Java classes, in our opinion, such reverse engineering is adequate only for building trivial web
services, perhaps for quick prototyping. The reverse-engineering option seriously limits the flexi-
bility you need to describe nontrivial, real-world web services. So, we will not discuss it any further
in this chapter.
We describe the overall structure of a WSDL 1.1 document next.

WSDL 1.1 Document Structure
A WSDL 1.1 document is an XML document that conforms to the WSDL 1.1 schema, which is available
at The WSDL 1.1 schema location also defines the WSDL 1.1
namespace. Assuming the wsdl prefix for the WSDL 1.1 namespace, the root element of a WSDL 1.1
document is wsdl:definitions.
The wsdl:definitions element contains the following child elements:
•The wsdl:types element defines data type definitions using the XML Schema language. In
other words, the XML content of wsdl:types element is a schema definition.
•The wsdl:message element defines an abstract message type used in web service interaction.
Each wsdl:message consists of one or more wsdl:part elements, whereby each wsdl:part is
based on either a schema element or a schema type, defined within wsdl:types. The
wsdl:definitions element can contain one or more wsdl:message elements.
•The wsdl:portType element defines an abstract service interface. Each wsdl:portType element
can contain one or more wsdl:operation elements. However, each wsdl:operation element
within a wsdl:portType must have a unique value for its name attribute.
Vohra_706-0C14.fm Page 370 Saturday, August 12, 2006 5:18 AM
CHAPTER 14 ■ BUILDING XML-BASED WEB SERVICES
371
•A wsdl:operation element is an abstract definition of a service operation. Each wsdl:operation
contains a combination of wsdl:input, wsdl:output, and wsdl:fault elements; each of these
elements is a message component that is part of the message exchange pattern used by
wsdl:operation.
•Each wsdl:input, wsdl:output, and wsdl:fault element is based on a wsdl:message element.
If a wsdl:operation uses a request-response message exchange pattern, it must specify a
wsdl:input element and a wsdl:output element, and possibly one or more wsdl:fault
elements. If a wsdl:operation uses a one-way message exchange pattern, it must specify a
single wsdl:input element.
•Since a wsdl:portType element defines an abstract service interface, it needs to be mapped to
a messaging protocol and a transport protocol. Each wsdl:portType is recursively mapped
to a messaging protocol and a transport protocol in a wsdl:binding element, which is a child

of wsdl:definitions.
•Each wsdl:portType abstract interface is mapped to a concrete network endpoint address
through a wsdl:port element. A wsdl:port element is defined within a wsdl:service element,
which is a child of wsdl:definitions.
Listing 14-6 shows the basic outline of a WSDL 1.1 document.
Listing 14-6. Basic Outline of a WSDL 1.1 Document
<wsdl:definitions
xmlns:wsdl=" /> <wsdl:types>
<! schema elements or schema types >
</wsdl:types>
<! One or more abstract message types >
<wsdl:message name=" ">
<! One or more message parts >
<wsdl:part element=" " name=" " type=" ">
<! Based on either a schema element or a schema type >
</wsdl:part>
</wsdl:message>
<! one or more abstract port type interfaces >
<wsdl:portType name=" ">
<! One or more abstract operations, but name should be unique >
<wsdl:operations name=" ">
<! Request must have an input >
<wsdl:input message=" " name=" ">
</wsdl:input>
<! Optional response contains one output element
and zero or more fault elements >
<wsdl:output message=" " name=" ">
</wsdl:output>
<wsdl:fault message=" " name=" ">
Vohra_706-0C14.fm Page 371 Saturday, August 12, 2006 5:18 AM

372
CHAPTER 14
■ BUILDING XML-BASED WEB SERVICES
</wsdl:fault>
</wsdl:operations>
</wsdl:portType>
<wsdl:binding name=" " type=" ">
<! Maps the port type to a messaging
and a transport protocol >
</wsdl:binding>
<wsdl:service name=" " >
<! One or more ports >
<wsdl:port binding=" " name=" ">
<! Binds a port type binding to a network endpoint address >
</wsdl:port>
</wsdl:service>
</wsdl:definitions>
In the next section, you will examine an example WSDL 1.1 document.
Example WSDL 1.1 Document
In our opinion, if you are building a web service, the only way to start is to first construct a WSDL 1.1
document. To build the example web service that implements all the use case scenarios, you need to
construct a WSDL 1.1 document that formally describes the example web service. We will show you
how to do that step by step; we describe these steps in detail in the following sections:
1. Declare the relevant namespaces.
2. Define a schema in a separate document.
3. Import the schema into a WSDL 1.1 document.
4. Define message types used by the web service.
5. Define the web service interface (port type), including all the operations.
6. Define the binding of port type to the SOAP 1.1/HTTP messaging and transport protocols.
7. Define the port that binds the web service binding to the endpoint address.

Namespace Declarations
The first step you want to take is to declare all the namespace declarations you will need in this
document:
• The WSDL 1.1 language constructs are defined in the
namespace, and you will use the wsdl prefix with this namespace.
• The target namespace for the document will be />definitions, which is entirely arbitrary. You will use the defs prefix with this namespace.
• The namespace for the XML Schema language is and
you will use the xsd prefix with this namespace.
Vohra_706-0C14.fm Page 372 Saturday, August 12, 2006 5:18 AM
CHAPTER 14 ■ BUILDING XML-BASED WEB SERVICES
373
• The namespace for MIME constructs is and you
will use the mime prefix with this namespace.
• The WSDL 1.1 to SOAP binding is specified in the
namespace in the soap prefix.
• You will be defining your own schema types, and you will use the />xmljava/webservices/schemas namespace for the schema types. You will use the types prefix
with this namespace.
The root wsdl:definitions element of the WSDL 1.1 document with the relevant namespace
declarations is as follows:
<?xml version='1.0' encoding='UTF-8' ?>
<wsdl:definitions
targetNamespace=" /> xmlns:defs=" /> xmlns:mime=" /> xmlns:soap=" /> xmlns:types=" /> xmlns:wsdl=" /> xmlns:xsd=" >
</wsdl:definitions>
Schema Definition
In writing any but the most trivial of WSDL 1.1 documents, you will need schema data types. Although it
is not a must, it is best to define these data types within a separate schema file and the schema file
imported within the WSDL 1.1 document. Separating the schema definition from the WSDL 1.1
document is highly recommended, both for maintenance and for reuse. For the example web
service, define the schema definition shown in Listing 14-7 in a separate file named types.xsd.
Listing 14-7. Schema Types for Example Web Service in types.xsd

<?xml version='1.0' encoding='UTF-8' ?>
<xsd:schema
targetNamespace=" /> xmlns=" /> xmlns:xsd=" /> xmlns:xsi=" /> xsi:schemaLocation=" /> >
<xsd:complexType name="documentInfo" >
<xsd:attribute name="name" type="xsd:string" use="required" ></xsd:attribute>
<xsd:attribute name="createdOn"
type="xsd:dateTime" use="optional" >
</xsd:attribute>
<xsd:attribute name="lastUpdated"
type="xsd:dateTime" use="optional" >
</xsd:attribute>
</xsd:complexType>
Vohra_706-0C14.fm Page 373 Saturday, August 12, 2006 5:18 AM
374
CHAPTER 14
■ BUILDING XML-BASED WEB SERVICES
<xsd:complexType name="folderInfo" >
<xsd:sequence>
<xsd:element maxOccurs="unbounded" minOccurs="0" name="document"
type="documentInfo" >
</xsd:element>
</xsd:sequence>
<xsd:attribute name="location"
type="xsd:string" use="required" >
</xsd:attribute>
<xsd:attribute name="createdOn"
type="xsd:dateTime" use="optional" >
</xsd:attribute>
<xsd:attribute name="lastUpdated"
type="xsd:dateTime" use="optional" >

</xsd:attribute>
</xsd:complexType>
<xsd:complexType name="projectInfo" >
<xsd:sequence>
<xsd:element maxOccurs="unbounded"
minOccurs="0" name="folder" type="folderInfo" >
</xsd:element>
</xsd:sequence>
<xsd:attribute name="name" type="xsd:string" use="required" ></xsd:attribute>
<xsd:attribute name="createdOn"
type="xsd:dateTime" use="optional" >
</xsd:attribute>
<xsd:attribute name="lastUpdated"
type="xsd:dateTime" use="optional" >
</xsd:attribute>
<xsd:attribute name="email"
type="xsd:string" use="required" >
</xsd:attribute>
</xsd:complexType>
<xsd:element name="manifest" type="projectInfo" ></xsd:element>
<xsd:element name="project" type="projectInfo" ></xsd:element>
<xsd:element name="remove" type="projectInfo" ></xsd:element>
<xsd:element name="projects" >
<xsd:complexType>
<xsd:sequence>
<xsd:element maxOccurs="unbounded" minOccurs="0"
name="project" type="projectInfo" >
</xsd:element>
</xsd:sequence>
</xsd:complexType>

</xsd:element>
Vohra_706-0C14.fm Page 374 Saturday, August 12, 2006 5:18 AM
CHAPTER 14 ■ BUILDING XML-BASED WEB SERVICES
375
<xsd:element name="projectsDetail" >
<xsd:complexType>
<xsd:sequence>
<xsd:element name="folders" type="xsd:boolean" ></xsd:element>
<xsd:element name="documents" type="xsd:boolean" ></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="userInfo" >
<xsd:complexType>
<xsd:sequence>
<xsd:element name="email" type="xsd:string" ></xsd:element>
<xsd:element name="pwd" type="xsd:string" ></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="authDetail" >
<xsd:complexType>
<xsd:sequence>
<xsd:any></xsd:any>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="authScope" >
<xsd:complexType>
<xsd:sequence>

<xsd:element name="scope" type="xsd:string" ></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="faultDetail" >
<xsd:complexType>
<xsd:sequence>
<xsd:element minOccurs="1" name="major" type="xsd:string" ></xsd:element>
<xsd:element minOccurs="0" name="minor" type="xsd:string" ></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
We will not describe this schema definition in great detail. By now, you should be familiar with
schema constructs; if you need to review this material, please refer to Chapter 1. Briefly, the schema
in Listing 14-7 defines data types for use in the example WSDL 1.1 document; these data types include
the following:
•The userInfo schema type contains email and password information.
•The projectInfo schema type contains information about a project.
Vohra_706-0C14.fm Page 375 Saturday, August 12, 2006 5:18 AM
376
CHAPTER 14
■ BUILDING XML-BASED WEB SERVICES
•The project, remove, and manifest elements are all of type projectInfo.
•The projects schema element contains information about a list of projects.
•The projectsDetail schema element contains information about what type of elements
should be included in returned content when getting information about all the projects.
•The folderInfo schema type contains information about folders, and they are nested
within projectInfo.
•The documentInfo schema type contains information about documents, and they are nested

within folderInfo.
•The authScope schema element defines the authentication scope.
•The authDetail schema element defines the arbitrary authentication data that may be sent
with userInfo. This is an example of extensibility using xsd:any.
You should have no problem deciphering the structure of each of these schema elements or
types by examining the schema shown in Listing 14-7.
Schema Import
You will refer to the xsd:complexType definitions and the xsd:element declarations shown in
Listing 14-7 within the WSDL 1.1 document, so the first step you need to take within your WSDL 1.1
document is to import the schema definition, which is assumed to be defined in a file named
types.xsd. The schema import within the WSDL document is as follows:
<wsdl:types>
<xsd:schema>
<xsd:import
namespace=" />schemaLocation="types.xsd" >
</xsd:import>
</xsd:schema>
</wsdl:types>
Abstract Message Definitions
As you have already seen, all web service interactions involve the exchange of messages. So, of
course, in the WSDL 1.1 document, you have to define the abstract messages used by the example
web service. Through the appropriate wsdl:binding definition, you will later map these abstract
messages to the soapenv:Body content.
Not surprisingly, these messages are based on the schema elements defined within the schema
shown in Listing 14-7; the element attribute of a wsdl:part denotes a schema element in the types
namespace. For example, the abstract request message for getting all the projects for a user, GetProjects,
is as follows:
<wsdl:message name="GetProjects" >
<wsdl:part element="types:userInfo" name="user" ></wsdl:part>
<wsdl:part element="types:projectsDetail" name="detail" ></wsdl:part>

</wsdl:message>
The GetProjects abstract message has two parts:
• The first part is based on the types:userInfo schema element.
• The second part is based on the types:projectsDetail schema element.
Vohra_706-0C14.fm Page 376 Saturday, August 12, 2006 5:18 AM
CHAPTER 14 ■ BUILDING XML-BASED WEB SERVICES
377
Each wsdl:message element contains one or more wsdl:part elements. The wsdl:message
names and the wsdl:part names are completely arbitrary but should attempt to impart some infor-
mation about web service semantics.
Some wsdl:part elements are based on schema elements defined within the schema shown in
Listing 14-7, such as types:manifest; other wsdl:part elements are based on built-in schema types,
such as xsd:base64Binary, as shown in the following DownloadZip message:
<wsdl:message name="DownloadZip" >
<wsdl:part element="types:manifest" name="manifest" ></wsdl:part>
<wsdl:part name="zip" type="xsd:base64Binary" ></wsdl:part>
</wsdl:message>
The xsd:base64Binary data type refers to binary data in Base 64 encoding.
Listing 14-8 shows the complete set of abstract message definitions that describe the messages
for all the use case scenarios within the WSDL 1.1 document.
Listing 14-8. WSDL 1.1 Message Definitions for Example Web Service
<wsdl:message name="ProjectFault" >
<wsdl:part element="types:faultDetail" name="faultDetail" ></wsdl:part>
</wsdl:message>
<wsdl:message name="DownloadProject" >
<wsdl:part element="types:userInfo" name="user" ></wsdl:part>
<wsdl:part element="types:project" name="project" ></wsdl:part>
</wsdl:message>
<wsdl:message name="GetProjects" >
<wsdl:part element="types:userInfo" name="user" ></wsdl:part>

<wsdl:part element="types:projectsDetail" name="detail" ></wsdl:part>
</wsdl:message>
<wsdl:message name="AuthUser" >
<wsdl:part element="types:userInfo" name="user" ></wsdl:part>
<wsdl:part element="types:authDetail" name="detail" ></wsdl:part>
</wsdl:message>
<wsdl:message name="Project" >
<wsdl:part element="types:project" name="project" ></wsdl:part>
</wsdl:message>
<wsdl:message name="Projects" >
<wsdl:part element="types:projects" name="projects" ></wsdl:part>
</wsdl:message>
<wsdl:message name="RemoveProject" >
<wsdl:part element="types:userInfo" name="user" ></wsdl:part>
<wsdl:part element="types:remove" name="remove" ></wsdl:part>
</wsdl:message>
<wsdl:message name="UploadZip" >
<wsdl:part element="types:userInfo" name="user" ></wsdl:part>
<wsdl:part element="types:manifest" name="manifest" ></wsdl:part>
<wsdl:part name="zip" type="xsd:base64Binary" ></wsdl:part>
</wsdl:message>
Vohra_706-0C14.fm Page 377 Saturday, August 12, 2006 5:18 AM
378
CHAPTER 14
■ BUILDING XML-BASED WEB SERVICES
<wsdl:message name="DownloadZip" >
<wsdl:part element="types:manifest" name="manifest" ></wsdl:part>
<wsdl:part name="zip" type="xsd:base64Binary" ></wsdl:part>
</wsdl:message>
The abstract messages are used by wsdl:operations within wsdl:portType, as discussed in the

next section.
Port Type
Just like a Java interface, the wsdl:portType element describes an abstract web service interface. Each
wsdl:portType element contains one or more wsdl:operation elements, whereby each wsdl:operation
element defines the message exchange pattern for that wsdl:operation.
A wsdl:operation element in the most general request-response message exchange pattern
case contains a wsdl:input element, a wsdl:output element, and zero or more wsdl:fault elements,
where each of these elements is associated with a wsdl:message definition through the message
attribute. wsdl:input, as the name implies, defines the request message, wsdl:output defines the
response message, and wsdl:fault defines the details of the SOAP fault message. An example of a
request-response wsdl:operation is download, as shown here:
<wsdl:operation name="download" >
<wsdl:input message="defs:DownloadProject" name="project" >
</wsdl:input>
<wsdl:output message="defs:DownloadZip" name="downloadZip" >
</wsdl:output>
<wsdl:fault message="defs:ProjectFault" name="fault" >
</wsdl:fault>
</wsdl:operation>
In download wsdl:operation shown previously, defs:DownloadProject, defs:DownloadZip, and
defs:ProjectFault are abstract messages that are used in the request-response message exchange
pattern.
For a one-way exchange pattern, only a single wsdl:input element is required, as in the case of
remove wsdl:operation shown here:
<wsdl:operation name="remove" >
<wsdl:input message="defs:RemoveProject" name="project" >
</wsdl:input>
</wsdl:operation>
You cannot specify a wsdl:fault message without a wsdl:output message, because a SOAP fault
message is generated only if a response was expected. So, for example, you cannot add a wsdl:fault

to a wsdl:operation named remove.
The wsdl:portType for the example web service is named ProjectPortType, and it defines the
following wsdl:operation for the use case scenarios:
• Uploading documents to a project is defined by upload.
• Downloading documents from a project is defined by download.
• Getting information about all the projects owned by a user is defined by
getProjects.
• Removing documents from a project is defined by remove.
•An authenticate operation, which is not required for these use cases, can be used to authen-
ticate a user and keep user information in an HTTP session.
Listing 14-9 shows the complete wsdl:portType for the example web service.
Vohra_706-0C14.fm Page 378 Saturday, August 12, 2006 5:18 AM
CHAPTER 14 ■ BUILDING XML-BASED WEB SERVICES
379
Listing 14-9. Port Types for the Example Web Service
<wsdl:portType name="ProjectPortType" >
<wsdl:operation name="download" >
<wsdl:input message="defs:DownloadProject" name="project" ></wsdl:input>
<wsdl:output message="defs:DownloadZip" name="downloadZip" ></wsdl:output>
<wsdl:fault message="defs:ProjectFault" name="fault" ></wsdl:fault>
</wsdl:operation>
<wsdl:operation name="upload" >
<wsdl:input message="defs:UploadZip" name="uploadZip" ></wsdl:input>
<wsdl:output message="defs:Project" name="project" ></wsdl:output>
<wsdl:fault message="defs:ProjectFault" name="fault" ></wsdl:fault>
</wsdl:operation>
<wsdl:operation name="remove" >
<wsdl:input message="defs:RemoveProject" name="project" ></wsdl:input>
</wsdl:operation>
<wsdl:operation name="getProjects" >

<wsdl:input message="defs:GetProjects" name="getprojects" ></wsdl:input>
<wsdl:output message="defs:Projects" name="projects" ></wsdl:output>
<wsdl:fault message="defs:ProjectFault" name="fault" ></wsdl:fault>
</wsdl:operation>
<wsdl:operation name="authenticate" >
<wsdl:input message="defs:AuthUser" name="authuser" ></wsdl:input>
<wsdl:output message="defs:AuthUser" name="authuser" ></wsdl:output>
<wsdl:fault message="defs:ProjectFault" name="fault" ></wsdl:fault>
</wsdl:operation>
</wsdl:portType>
As noted, wsdl:portType is an abstract interface. This abstract interface has to be bound to a
messaging protocol and a transport protocol, which is discussed in the next section.
Port Type Bindings to SOAP 1.1/HTTP
The abstract wsdl:portType needs to be bound to the SOAP 1.1/HTTP messaging protocol. There-
fore, you need to recursively bind the wsdl:portType element to SOAP 1.1/HTTP. In the following
discussion, the soap prefix, which is associated with a WSDL 1.1 to SOAP 1.1 binding, is associated
with the namespace.
The SOAP 1.1/HTTP binding for defs:ProjectPortType wsdl:portType is named
ProjectSoapBinding.
SOAP 1.1 to HTTP Binding
The following snippet specifies that the SOAP 1.1 messaging be bound to the HTTP (http://schemas.
xmlsoap.org/soap/http) message transport:
<soap:binding style="document"
transport=" >
</soap:binding>
Vohra_706-0C14.fm Page 379 Saturday, August 12, 2006 5:18 AM
380
CHAPTER 14
■ BUILDING XML-BASED WEB SERVICES
In addition, it specifies that the SOAP 1.1 messaging mode should be of type document, which is

described in the next section.
SOAP 1.1 Messaging Style
SOAP 1.1 messaging style, which is a completely distinct concept from the concept of message exchange
patterns (which can be request-response or one-way) and the concept of message encoding (which for
us is always literal), specifies rules for the structure of the XML content in the payload of the
soapenv:Body element. Two possible SOAP 1.1 messaging styles exist:
• Remote procedure call (rpc) style
•Document (document) style
You will look at each of the messaging styles next.
Remote Procedure Call Style
As the name implies, this style embodies the semantics associated with remote procedure invocations.
Under this style, the following is true:
•The content of the soapenv:Body element always has a single child element whose tag name
corresponds to the operation name being remotely invoked.
• The grandchild elements of the soapenv:Body element denote the parameters associated with
the remote operation.
• The names and order of the grandchild elements correspond to the remote operation param-
eter names and their order.
• The child and grandchild elements of soapenv:Body element must be namespace qualified;
the namespace is application specific.
This style is completely redundant, because the document style, which we will describe in the
next section, is much more general and, more important, adheres to the fundamental tenets of
keeping interacting applications as loosely coupled as possible. By contrast, the rpc style is akin
to making a method call, with all the attendant implications of tight coupling between the calling
application and the called application. In our opinion, the rpc style is the antithesis of loosely
coupled applications and should be, as much as possible, avoided.
Document Style
The rules for the structure of soapenv:Body in the document style are simple:
•The content of soapenv:Body element should be well-formed XML, and all soapenv:Body child
elements should be namespace qualified in an application-specific namespace.

•If a wsdl:part, mapped to the soapenv:Body element, corresponds to a schema element (that
is, it has an element attribute), in the document-style message the schema element occurs as a
child of the soapenv:Body element.
•If a wsdl:part, mapped to the soapenv:Body element, corresponds to a schema type (that is, it
has a type attribute) in the document-style message, then the soapenv:Body element assumes
this schema type, and the child elements of soapenv:Body conform to this schema type. This
implies that in the case of a wsdl:part with a type attribute, there can be only one wsdl:part
in its wsdl:message, since the soapenv:Body element can assume only a single schema type.
Vohra_706-0C14.fm Page 380 Saturday, August 12, 2006 5:18 AM
CHAPTER 14 ■ BUILDING XML-BASED WEB SERVICES
381
Listing 14-1 is an example of document-style message. You will see examples of specifying
document style in the wsdl:operation to soap:operation binding in the next section.
Binding wsdl:operation to SOAP 1.1
This is where you make a wsdl:operation concrete by binding each wsdl:operation to SOAP 1.1
messaging. For example, the binding of download wsdl:operation to SOAP 1.1 consists of the
following parts:
• Defining a soap:operation with a soapAction and SOAP 1.1 messaging style. A soapAction is
a hint to message processing nodes, which, according to WS-I BP 1.1, helps improve interop-
erability between applications. It is transported as an HTTP header attribute. It is essentially
a mechanism to infer something about a SOAP message by just looking at the HTTP header,
without having to inspect the SOAP message.
•Binding a wsdl:input abstract message to soap:header and soap:body.
•Binding wsdl:output to a mime:multipartRelated message.
•Binding wsdl:fault to soap:fault.
We explain each of the previous steps in the following sections.
Defining soap:operation
The soap:operation binding for download wsdl:operation is defined as follows:
<soap:operation
soapAction=" /> style="document" >

</soap:operation>
Remember, each SOAP 1.1 message is transported within an HTTP message. The URI in the
soapAction attribute of soap:operation is included as the value of the SOAPAction HTTP header.
Binding wsdl:input
The wsdl:input in a download operation is based on the defs:DownloadProject abstract message,
which defines two wsdl:part elements, as shown here:
<wsdl:message name="DownloadProject" >
<wsdl:part element="types:userInfo" name="user" ></wsdl:part>
<wsdl:part element="types:project" name="project" ></wsdl:part>
</wsdl:message>
When defs:DownloadProject is bound to a SOAP 1.1 message, you can choose to bind the user
part to the soap:header element and the project part to the soap:body element, as shown here:
<wsdl:input>
<soap:header message="defs:DownloadProject"
part="user" use="literal" >
</soap:header>
<soap:body parts="project" use="literal" ></soap:body>
</wsdl:input>
Vohra_706-0C14.fm Page 381 Saturday, August 12, 2006 5:18 AM
382
CHAPTER 14
■ BUILDING XML-BASED WEB SERVICES
Binding wsdl:output
The wsdl:output in a download operation is based on the defs:DownloadZip abstract message, as
shown here:
<wsdl:message name="DownloadZip" >
<wsdl:part element="types:manifest" name="manifest" ></wsdl:part>
<wsdl:part name="zip" type="xsd:base64Binary" ></wsdl:part>
</wsdl:message>
The defs:DownloadZip abstract message contains two parts. The first part is manifest, and the

second part, zip, is a Base 64 binary type containing the downloaded ZIP file. The wsdl:output is
bound to the SOAP 1.1 message as a MIME multipart-related message. The manifest part is bound to
the soap:body contained within a mime:part, and the zip part is bound to a mime:content contained
within mime:part, as shown here:
<wsdl:output>
<mime:multipartRelated>
<mime:part>
<soap:body parts="manifest" use="literal" ></soap:body>
</mime:part>
<mime:part>
<mime:content part="zip" type="application/zip" >
</mime:content>
</mime:part>
</mime:multipartRelated>
</wsdl:output>
Binding wsdl:fault
The wsdl:fault is mapped to soap:fault, as shown here:
<wsdl:fault name="fault" >
<soap:fault name="fault" use="literal" ></soap:fault>
</wsdl:fault>
Complete Port Type Binding
Listing 14-10 shows the complete SOAP 1.1/HTTP binding for ProjectPortType.
Listing 14-10. SOAP 1.1/HTTP Binding for ProjectPortType
<wsdl:binding name="ProjectSoapBinding" type="defs:ProjectPortType" >
<soap:binding style="document"
transport=" >
</soap:binding>
<wsdl:operation name="download" >
<soap:operation
soapAction=" /> style="document" >

</soap:operation>
<wsdl:input>
<soap:header message="defs:DownloadProject"
part="user" use="literal" >
</soap:header>
Vohra_706-0C14.fm Page 382 Saturday, August 12, 2006 5:18 AM
CHAPTER 14 ■ BUILDING XML-BASED WEB SERVICES
383
<soap:body parts="project" use="literal" ></soap:body>
</wsdl:input>
<wsdl:output>
<mime:multipartRelated>
<mime:part>
<soap:body parts="manifest" use="literal" ></soap:body> </mime:part>
<mime:part>
<mime:content part="zip" type="application/zip" ></mime:content>
</mime:part>
</mime:multipartRelated>
</wsdl:output>
<wsdl:fault name="fault" >
<soap:fault name="fault" use="literal" ></soap:fault> </wsdl:fault>
</wsdl:operation>
<wsdl:operation name="upload" >
<soap:operation
soapAction=" /> style="document" >
</soap:operation>
<wsdl:input>
<soap:header message="defs:UploadZip" part="user" use="literal" >
</soap:header>
<mime:multipartRelated>

<mime:part>
<soap:body parts="manifest" use="literal" ></soap:body>
</mime:part>
<mime:part>
<mime:content part="zip" type="application/zip" ></mime:content>
</mime:part>
</mime:multipartRelated>
</wsdl:input>
<wsdl:output>
<soap:body parts="project" use="literal" ></soap:body> </wsdl:output>
<wsdl:fault name="fault" >
<soap:fault name="fault" use="literal" ></soap:fault></wsdl:fault>
</wsdl:operation>
<wsdl:operation name="remove" >
<soap:operation
soapAction=" /> style="document" >
</soap:operation>
<wsdl:input>
<soap:header message="defs:RemoveProject"
part="user" use="literal" >
</soap:header>
<soap:body parts="remove" use="literal" >
Vohra_706-0C14.fm Page 383 Saturday, August 12, 2006 5:18 AM
384
CHAPTER 14
■ BUILDING XML-BASED WEB SERVICES
</soap:body>
</wsdl:input>
</wsdl:operation>
<wsdl:operation name="getProjects" >

<soap:operation
soapAction=" /> style="document" >
</soap:operation>
<wsdl:input>
<soap:header message="defs:GetProjects"
part="user" use="literal" >
</soap:header>
<soap:body message="defs:GetProjects"
parts="detail" use="literal" >
</soap:body>
</wsdl:input>
<wsdl:output>
<soap:body parts="projects" use="literal" ></soap:body>
</wsdl:output>
<wsdl:fault name="fault" >
<soap:fault name="fault" use="literal" ></soap:fault> </wsdl:fault>
</wsdl:operation>
<wsdl:operation name="authenticate" >
<soap:operation
soapAction=" /> style="document" >
</soap:operation>
<wsdl:input>
<soap:header message="defs:AuthUser"
part="user" use="literal" ></soap:header>
<soap:body message="defs:AuthUser"
parts="detail" use="literal" >
</soap:body>
</wsdl:input>
<wsdl:output>
<soap:header message="defs:AuthUser"

part="user" use="literal" >
</soap:header>
<soap:body message="defs:AuthUser"
parts="detail" use="literal" >
</soap:body>
</wsdl:output>
<wsdl:fault name="fault" >
<soap:fault name="fault" use="literal" ></soap:fault>
</wsdl:fault>
</wsdl:operation>
</wsdl:binding>
Vohra_706-0C14.fm Page 384 Saturday, August 12, 2006 5:18 AM
CHAPTER 14 ■ BUILDING XML-BASED WEB SERVICES
385
Service Port
Each wsdl:portType binding must be attached to a wsdl:port within a wsdl:service. For example,
the defs:ProjectSoapBinding port type binding shown in Listing 14-10 is mapped to the
ProjectPortTypeImplPort port within the ProjectPortTypeImplService service, as shown here:
<wsdl:service name="ProjectPortTypeImplService" >
<wsdl:port binding="defs:ProjectSoapBinding" name="ProjectPortTypeImplPort" >
<soap:address location="REPLACE_WITH_ACTUAL_URL" ></soap:address>
</wsdl:port>
</wsdl:service>
The mapping of a concrete port type binding to a port location creates a network service
endpoint that can be accessed by other applications using an HTTP URL. In general, although you
can, you should not specify a location HTTP URL and leave it as it is shown in the previous example.
Typically, this URL should be automatically assigned during the deployment of the web service,
which is discussed in detail in the “Using JAX-WS 2.0” section.
The complete WSDL 1.1 document for the example web service is included in the project. To
recap, building a WSDL document involves defining a schema definition, defining message types,

defining a port type (web service interface), defining a port type binding that binds a port type to
SOAP/HTTP, and, finally, defining a port that binds a port type binding to a network address.
Now that you have a WSDL 1.1 document, you are ready to build the example web service using
JAX-WS 2.0, which is what you will do in the next section.
Using JAX-WS 2.0
JAX-WS 2.0 is based on JSR-224.
11
A reference implementation of the JAX-WS 2.0 specification is
included in the Java EE 5 SDK.
12
In this section, we will use Java EE 5 SDK to show how to build and
deploy the example web service. The steps for building the web service using the Java EE 5 SDK are
as follows:
1. Use the wsimport tool included in the Java EE 5 SDK to automatically generate the Java code
that defines the Java types corresponding to the schema types, message types, and port types
defined in the services.wsdl document shown in Listing 14-10.
2. Implement the web service provider agent, writing whatever Java code is needed to implement
the application logic. The application logic implemented by this web service corresponds to
the use cases described earlier in the “Example Use Case Scenarios” section.
3. Compile generated and manually coded Java class files and package them into a Java EE
enterprise application archive file.
4. Deploy the enterprise application archive file in Sun One Application Server 9.0, which is
included in the Java EE 5 SDK. This makes the web service available for use at a specific
HTTP URL.
5. Write web service clients (requestor agents) to interact with the web service and run the
clients, and then observe the interaction.
In the following sections, you will follow the steps outlined previously.
11. JSR-224 is available at />12. The Java EE 5 SDK is available at />Vohra_706-0C14.fm Page 385 Saturday, August 12, 2006 5:18 AM
386
CHAPTER 14

■ BUILDING XML-BASED WEB SERVICES
Installing the Software
Before you can proceed, you need to download and install the Java EE 5 SDK, which includes Sun
One Application Server 9.0. The server includes the Java DB database, which is based on Apache Derby.
13
After installing the SDK, start the included Java DB database and Sun One Application Server 9.0. On
Windows,
14
you can select Start Java DB in the Sun One Application Server 9.0’s Programs menu to
start the database, and select Start Default Server to start the server.
After starting the database and the server, go to http://localhost:8080/ in a browser, and verify
that the server is running. When the server starts, it prints the ports it is listening on, so if http://
localhost:8080/ does not work, try the other ports listed by server, such as http://localhost:2492/.
After the server is running, you can go to http://localhost:4848/ to access the Sun One
Application Server 9.0 administration console. If you are asked to log in, specify the username and
password you configured during the server installation. The administration console provides the
Enterprise Applications link for deploying enterprise applications and the Web Services link for
deploying web services.
Setting Up the Eclipse Project
You will need J2SE 5.0 to build your Eclipse project. Therefore, install J2SE 5.0, in case you have not
already done so.
Next, you need to download the Chapter14 project from and import
the project into Eclipse by selecting File ➤ Import. It is important that your Eclipse workspace not
contain any spaces in its file system path; otherwise, you will run into problems later in this chapter,
as you go through the steps for building the example web service. Figure 14-6 shows the Chapter14
project directory structure.
Figure 14-6. Project directory structure
13. Apache Derby is part of the Apache DB project ( />14. For other platforms, follow the product documentation.
Vohra_706-0C14.fm Page 386 Saturday, August 12, 2006 5:18 AM
CHAPTER 14 ■ BUILDING XML-BASED WEB SERVICES

387
The project folders are as follows:
•The wsclient folder contains Java files corresponding to the web service clients, used to
interact with the example web service.
•The wsdl folder has the web service WSDL 1.1 document (services.wsdl), the WSDL 1.1
customization file (svcbindings.xml) used for customizing WSDL 1.1 to Java mappings, the
schema document (types.xsd), and the JAXB 2.0 binding customization file (binding.xjb)
used for customizing JAXB 2.0 object bindings.
•The web folder has Java files, XML documents, and properties files related to Java Server Faces
(JSF)–based implementations of web pages. Understanding the contents of this folder is not
central to understanding web services, and this content appears in this chapter solely because
we wanted to show how to build a complete working example. JSF is part of Java EE 5 and is a
server-based technology for constructing a web-based user interface. JSF is beyond the scope
of this book. However, if you are interested in learning more about JSF, we recommend Pro
JSF and Ajax: Building Rich Internet Components.
15
•The ejb folder contains Java code related to application logic and database persistence, based
on the Enterprise Java Beans (EJB) 3.0 technology. EJB 3.0 is part of Java EE 5 and is a tech-
nology for implementing object-relational mapping, automatic database persistence, and
application logic. EJB 3.0 is beyond the scope of this chapter. For a more detailed look at EJB
3.0, we recommend Pro EJB3: Java Persistence API.
16
•The wsgen folder is for Java source files generated by the wsimport tool. When you initially
import the project into Eclipse, this folder will be empty. The generated Java files correspond
to JAXB 2.0 object binding files and web service interfaces.
•The wsimpl folder has Java files for implementing web service interfaces. These implementa-
tion files use EJBs to implement the application logic and interact with the database.
•The app directory has the application.xml deployment descriptor in the config folder. In this
project, we will show how to build an enterprise application archive, which will be deployed
in the server. This archive will contain the example web service. The application.xml deploy-

ment descriptor specifies deployment directives for the enterprise application, when the
application is deployed in the Sun One Application Server 9.0. For more details about this, we
recommend the Java EE 5 tutorial at />•The jsp directory has the JSF pages for the web services application.
•The Testproject.zip file is an example ZIP file that will be used by the web service client to
upload documents to a project using the web service.
Figure 14-7 shows the Chapter14 project Java build path.
15. Pro JSF and Ajax: Building Rich Internet Components (Apress, 2006) by Jonas Jacobi and John Fallows.
16. Pro EJB3: Java Persistence API (Apress, 2006) by Mike Keith and Merrick Schincariol.
Vohra_706-0C14.fm Page 387 Saturday, August 12, 2006 5:18 AM
388
CHAPTER 14
■ BUILDING XML-BASED WEB SERVICES
Figure 14-7. Chapter14 project Java build path
Setting Up the wsimport Tool
The wsimport tool processes a WSDL 1.1 document as follows:
• It generates the SEI, the service, and the JAXB 2.0 object bindings, based on the contents of
the WSDL 1.1 document.
• The SEI is a Java interface corresponding to a wsdl:portType definition within a WSDL 1.1
document. The provider agent that implements the web service provides a concrete imple-
mentation for an SEI.
• The service is a class that can be used by a web service client to interact with the web service.
• The JAXB 2.0 object bindings correspond to the schema types in the WSDL 1.1 document.
These object bindings are used for marshaling and unmarshaling web service data types to
and from XML content encapsulated within SOAP 1.1 messages.
You will use wsimport to generate the SEI, the service, and the JAXB 2.0 object bindings for the
services.wsdl WSDL 1.1 document.
To use the wsimport tool, you need to first create an external tools configuration for wsimport by
selecting Run ➤ External Tools ➤ External Tools. To create an external tools configuration, go through
the following steps:
1. Right-click the Program node in the External Tools area, and select New.

2. Specify a name for the configuration, such as wsimport.
3. Specify the wsimport.bat file in the Location field.
Vohra_706-0C14.fm Page 388 Saturday, August 12, 2006 5:18 AM
CHAPTER 14 ■ BUILDING XML-BASED WEB SERVICES
389
4. In the Working Directory field, specify ${project_loc}, and in the Arguments field, you need
to specify the following arguments: -s wsgen -d bin -keep -verbose -b wsdl/binding.xjb
-b wsdl/svcbindings.xml wsdl/${resource_name}.
5. Click the Apply button. An external tools configuration gets configured for the wsimport tool,
as shown in Figure 14-8.
Figure 14-8. wsimport external tools configuration
You also need to add the environment variable JAVA_HOME by selecting the Environment tab and
subsequently clicking the New button. To add the wsimport external tools configuration to the Favorites
menu, select the Common tab, and select the External Tools box in the Display in Favorites menu.
WSDL 1.1 to Java Mapping
Before you run the wsimport tool to generate the WSDL 1.1 to Java mapping for services.wsdl, we
will cover the general concepts of this mapping process (we refer to the concept of customizations,
which we will cover later in the section “Customizing WSDL 1.1 to Java Mapping”):
•Each wsdl:portType within a WSDL 1.1 document is mapped to a Java SEI.
•Each wsdl:operation within a wsdl:portType is mapped to a Java method within the SEI.
• In the absence of customizations, the name of the mapped Java method is the same as the
name of the wsdl:operation name attribute. By default, since the wsdl:operation name within
a wsdl:portType is unique, there will be no overloaded methods. It is best to adhere to unique
method names if you are using customizations.
•Each wsdl:operation must have one input message (wsdl:input). It may have zero or one
output messages (wsdl:output) and, if an output message is present, zero or more fault messages
(wsdl:fault).
Vohra_706-0C14.fm Page 389 Saturday, August 12, 2006 5:18 AM
390
CHAPTER 14

■ BUILDING XML-BASED WEB SERVICES
• The input and output messages are mapped to Java method parameters using either the
nonwrapper style or the wrapper style. For exhaustive rules governing mapping under these
styles, we recommend the JAX-WS 2.0 specification. However, the following details pertaining
to these styles should be sufficient for most purposes:
• In the nonwrapper style, if the wsdl:part is part of an input message, the wsdl:part element
is mapped to a Java method parameter. For output messages, the wsdl:part element is
mapped to either a holder class parameter or a return type. You can never go wrong if you
use the nonwrapper style—problem solved.
• The wrapper style is applicable only if the wsdl:message referred to by a wsdl:input or a
wsdl:output has only one wsdl:part. In our opinion, don’t bother with it. However, if you
must, read the next point.
• In the wrapper style, the wsdl:part element is deemed to be a wrapper element (which is
how the style gets its name). The children of the wrapper element are mapped to Java
method parameters if the wsdl:part is part of an input message. If the wsdl:part is part of
an output message and the wrapper element has more than one child, the children are
mapped to Java method parameters using a holder class; for one child, it is just mapped to
a Java method return type. If the wsdl:part is part of both input and output messages, the
holder class method parameter is the answer.
• The fault message is mapped to a custom Java exception class.
In the next section, we will discuss how to customize the WSDL 1.1 to Java mapping.
Customizing the WSDL 1.1 to Java Mapping
You can customize the WSDL 1.1 to Java mapping for services.wsdl through an external customiza-
tion file. For an exhaustive survey of all the possible customizations, we recommend the JAX-WS 2.0
specification.
17
However, we will discuss some of the more commonly used customizations in the
following sections.
One quick observation: the scope of the various bindings is determined through XPath expres-
sions addressing the WSDL 1.1 document node. For example, the node="//wsdl:portType[@name=

'ProjectPortType']" XPath expression addresses ProjectPortType wsdl:portType in services.wsdl.
Package Name
You can customize the Java bindings package name as shown here:
<jaxws:package name="com.apress.javaxml.ws" >
</jaxws:package>
MIME Content
Remember, we had some wsdl:parts in services.wsdl that were bound to SOAP 1.1 mime:content,
as shown here in an excerpt from Listing 14-10:
<mime:part>
<mime:content part="zip" type="application/zip" >
</mime:content>
</mime:part>
17. The JAX-WS 2.0 specification is available for download at />Vohra_706-0C14.fm Page 390 Saturday, August 12, 2006 5:18 AM
CHAPTER 14 ■ BUILDING XML-BASED WEB SERVICES
391
If you want to bind the mime:content to the most specific Java type allowed by metadata in the
type attribute, then you can specify that in the customization, as shown here:
<jaxws:enableMIMEContent>true</jaxws:enableMIMEContent>
Method Name
If you want to customize the Java method name corresponding to a wsdl:operation, you can do so
as shown here for download wsdl:operation:
<jaxws:bindings
node="//wsdl:portType[@name='ProjectPortType']/wsdl:operation[@name='download']" >
<jaxws:method name="downloadProject" ></jaxws:method>
</jaxws:bindings>
In the previous example, the download wsdl:operation name is mapped to the downloadProject
Java method name.
Handler Chains
It is possible to specify a handler chain that intercedes between a web service client and an SEI for
messages traveling in either direction. The following example specifies a handler chain for a logging

handler:
<javaee:handler-chains>
<javaee:handler-chain>
<javaee:handler>
<javaee:handlerclass>
com.apress.javaxml.ws.impl.LoggingHandler
</javaee:handler-class>
</javaee:handler>
</javaee:handler-chain>
</javaee:handler-chains>
The LoggingHandler.java of course is a custom class and is included in the Eclipse project for
this chapter.
Complete Customization File
The svcbindings.xml file, shown in Listing 14-11, contains customizations for WSDL 1.1 to Java
bindings: services.wsdl.
Listing 14-11. Customizations for WSDL 1.1 to Java Mapping: svcbindings.xml
<?xml version='1.0' encoding='UTF-8' ?>
<jaxws:bindings wsdlLocation="services.wsdl"
xmlns:jaxws=" /> xmlns:wsdl=" /> xmlns:xs=" >
<jaxws:package name="com.apress.javaxml.ws" >
</jaxws:package>
<jaxws:enableMIMEContent>true</jaxws:enableMIMEContent>
<jaxws:bindings node="//wsdl:portType[@name='ProjectPortType']" >
<jaxws:enableWrapperStyle>true</jaxws:enableWrapperStyle>
Vohra_706-0C14.fm Page 391 Saturday, August 12, 2006 5:18 AM
392
CHAPTER 14
■ BUILDING XML-BASED WEB SERVICES
<jaxws:bindings node="//wsdl:portType
[@name='ProjectPortType']/wsdl:operation

[@name='download']" >
<jaxws:method name="downloadProject" ></jaxws:method>
</jaxws:bindings>
<jaxws:bindings node="//wsdl:portType
[@name='ProjectPortType']/wsdl:operation
[@name='upload']" >
<jaxws:method name="uploadProject" ></jaxws:method>
</jaxws:bindings>
<jaxws:bindings node="//wsdl:portType
[@name='ProjectPortType']/wsdl:operation
[@name='remove']" >
<jaxws:method name="removeProject" ></jaxws:method>
</jaxws:bindings>
</jaxws:bindings>
<jaxws:bindings node="wsdl:definitions"
xmlns:javaee=" >
<javaee:handler-chains>
<javaee:handler-chain>
<javaee:handler>
<javaee:handlerclass>
com.apress.javaxml.ws.impl.LoggingHandler
</javaee:handler-class>
</javaee:handler>
</javaee:handler-chain>
</javaee:handler-chains>
</jaxws:bindings>
</jaxws:bindings>
In the next section, we will discuss how to customize JAXB 2.0 bindings.
Customizing JAXB 2.0 Bindings
The binding.xjb shown in Listing 14-12 contains external JAXB 2.0 customizations, which are applied

to the types.xsd schema. These customizations specify the Java package for the object bindings and
whether to generate value classes; they should be fairly obvious, and if they are not, we recommend
reviewing Chapter 6, which covers JAXB in detail.
Listing 14-12. JAXB 2.0 Customizations: binding.xjb
<?xml version='1.0' encoding='utf-8' ?>
<jxb:bindings version="2.0"
xmlns:jxb="
xmlns:xs=" >
<jxb:bindings node="/xs:schema"
schemaLocation="types.xsd" >
<jxb:globalBindings generateValueClass="true" >
</jxb:globalBindings>
Vohra_706-0C14.fm Page 392 Saturday, August 12, 2006 5:18 AM
CHAPTER 14 ■ BUILDING XML-BASED WEB SERVICES
393
<jxb:schemaBindings>
<jxb:package name="com.apress.javaxml.ws" ></jxb:package>
</jxb:schemaBindings>
</jxb:bindings>
</jxb:bindings>
Now, you are ready to run the wsimport tool.
Running wsimport
To run the wsimport tool, first select the services.wsdl WSDL 1.1 document, and then select Run ➤
External Tools ➤ wsimport.
Running the wsimport tool maps the services.wsdl document to the SEI and service Java types
and generates JAXB 2.0 object bindings, as per the customizations passed as arguments to wsimport.
Remember, the arguments to wsimport are -s wsgen -d bin -keep -verbose -b wsdl/binding.xjb
-b wsdl/svcbindings.xml wsdl/${resource_name}. In the arguments, binding.xjb refers to an external
customization file for the JAXB 2.0 bindings, and svcbindings.xml refers to an external customiza-
tion file for the WSDL 1.1 to Java mappings.

The Java files corresponding to the SEI, the service, and the JAXB 2.0 object bindings for the
services.wsdl document get generated in the wsgen folder in the com.apress.javaxml.ws package.
To bring the generated files into the Eclipse project view, you need to refresh the Chapter14 project
files by selecting File ➤ Refresh. Listing 14-13 shows the output from the wsimport tool.
■Note If you see an error at this point instead of the output shown, make sure the absolute file system path to
the Eclipse project location has no spaces in it.
Listing 14-13. Output from wsimport
com\apress\javaxml\ws\AuthDetail.java
com\apress\javaxml\ws\AuthScope.java
com\apress\javaxml\ws\DocumentInfo.java
com\apress\javaxml\ws\FaultDetail.java
com\apress\javaxml\ws\FolderInfo.java
com\apress\javaxml\ws\ObjectFactory.java
com\apress\javaxml\ws\ProjectInfo.java
com\apress\javaxml\ws\ProjectPortType.java
com\apress\javaxml\ws\ProjectPortTypeImplService.java
com\apress\javaxml\ws\Projects.java
com\apress\javaxml\ws\ProjectsDetail.java
com\apress\javaxml\ws\UserInfo.java
com\apress\javaxml\ws\package-info.java
com\apress\javaxml\ws\AuthDetail.java
com\apress\javaxml\ws\AuthScope.java
com\apress\javaxml\ws\DocumentInfo.java
com\apress\javaxml\ws\FaultDetail.java
com\apress\javaxml\ws\FolderInfo.java
com\apress\javaxml\ws\ObjectFactory.java
com\apress\javaxml\ws\ProjectFault.java
com\apress\javaxml\ws\ProjectInfo.java
com\apress\javaxml\ws\ProjectPortType.java
com\apress\javaxml\ws\ProjectPortTypeImplService.java

com\apress\javaxml\ws\Projects.java
Vohra_706-0C14.fm Page 393 Saturday, August 12, 2006 5:18 AM
394
CHAPTER 14
■ BUILDING XML-BASED WEB SERVICES
com\apress\javaxml\ws\ProjectsDetail.java
com\apress\javaxml\ws\UserInfo.java
com\apress\javaxml\ws\package-info.java
The generated file ProjectPortType.java in the com.apress.javaxml.ws package defines the
SEI; ProjectPortTypeImplService.java implements the service. All the other generated files in the
com.apress.javaxml.ws package correspond to JAXB 2.0 object bindings.
ProjectPortType SEI
The generated code for SEI in ProjectPortType.java uses a number of different Java annotation tags,
which are explained in Table 14-3.
The ProjectPortType SEI mapping contains the Java mapping for ProjectPortType
wsdl:portType, as per the rules described in the section “WSDL 1.1 to Java Mapping.” For example,
the download wsdl:operation is mapped to a Java method as shown here:
Table 14-3. Annotation Tags Used in ProjectPortType.java
Tag Name Description
WebService When used with a Java interface, it defines an SEI. The name attribute specifies
the name of the web service, and the targetNamespace attribute defines the
target namespace of the corresponding wsdl:portType.
HandlerChain Associates this web service with an externally defined handler chain, and
the file attribute defines the location of the handler chain file. The handler
chain is invoked before the SEI is invoked.
SOAPBinding Specifies how the web service is mapped to the SOAP 1.1 message body. The
paramterStyle attribute specifies whether the parameters are directly put
into the message body (ParameterStyle.BARE) or whether they are wrapped in
an element that bears the name of the operation (ParameterStyle.WRAPPED).
Basically, BARE corresponds to the document style, and WRAPPED corresponds

to the rpc style.
WebMethod This specifies a method that is exposed as a web service operation. The
operationName attribute specifies the name of the wsdl:operation. The action
attribute specifies the corresponding soapAction.
WebParam This specifies a method parameter that is mapped to a wsdl:part. The name
attribute specifies the name of this parameter. The partName specifies the
name of the wsdl:part. The header attribute specifies whether the parameter is
contained with a SOAP 1.1 header or body. The targetNamespace specifies the
XML namespace associated with the parameter.
WebResult This specifies a return value that is mapped to a wsdl:part. The name attribute
specifies the name of this return value. The partName specifies the name
of the wsdl:part. The header attribute specifies whether the parameter is
contained with a SOAP 1.1 header or body. The targetNamespace specifies
the XML namespace associated with the parameter.
OneWay This specifies there is only an input message with no response.
Vohra_706-0C14.fm Page 394 Saturday, August 12, 2006 5:18 AM