Apache CXF and Axis2 Web services

The JAX-WS implementation built into the JDK really is just the basic soap stuf. If you
nee any of the more comple! WS-" thin#s li$e WS-Security% WS-&'% WS-(olicy% etc...%
you nee to use one of the alternati)es li$e *X+ or 'etro or A!is,. It can also epen
on -hat you are tryin# to inte#rate -ith. +or e!ample% *X+ has top notch Sprin#
support as -ell as )ery #oo .S/i support.
*X+ also has other thin#s besies just JAX-WS. It has a compliant JAX-&S
implementation as -ell an supports e!posin# ser)ices as both &0ST an S.A( )ery
-ell. 1as a W2* compliant S.A(3J'S implementation if that type of thin#s is
re4uire. 5asically% lots of stuf not a)ailable from the in-j$ JAX-WS impl.
Inte#ration - *X+ has much better Sprin# inte#ration if you use Sprin#. All the
con6#uration an such is one throu#h Sprin#. Also% people ten to consier *X+ as
more 7embeable7 8I9)e ne)er loo$e at A!is, from this perspecti)e: into other
applications. ;ot sure if thin#s li$e that matter to you.
(erformance - they both perform )ery -ell. I thin$ A!is,9s proprietary AD5
atabinin# is a bit faster than *X+% but if you use JAX5 8stanars base A(I9s
a#ain:% *X+ is a bit faster. When usin# more comple! scenarios li$e WS-Security% the
unerlyin# security 7en#ine7 8WSS<J: is the same for both so the performance is
completely comparable.
=ou nee to o-nloa
>. JDK ?
,. 0clipse 2.@
2. *X+-,.@.,
<. Tomcat @
+ollo-in# jar must be in *lass(ath
>. aopalliance->.A.jar
,. commons-lo##in#->.>.>.jar
2. c!f-,.@.,.jar
<. httpasyncclient-<.A-beta2.jar
B. httpclient-<.,.>.jar
?. httpcore-<.,.,.jar
@. httpcore-nio-<.,.,.jar
C. neethi-2.A.,.jar
D. sprin#-aop-2.A.@.&0E0AS0.jar
>A. sprin#-asm-2.A.@.&0E0AS0.jar
>>. sprin#-beans-2.A.@.&0E0AS0.jar
>,. sprin#-conte!t-2.A.@.&0E0AS0.jar
>2. sprin#-core-2.A.@.&0E0AS0.jar
><. sprin#-e!pression-2.A.@.&0E0AS0.jar
>B. sprin#--eb-2.A.@.&0E0AS0.jar
>?. -sl<j->.?.,.jar
>@. !mlschema-core-,.A.2.jar
Developing a Service using JAX-WS
=ou can e)elop a ser)ice usin# one of t-o approachesF
Start -ith a WSDE contract an #enerate Ja)a objects to implement the
ser)ice.
Start -ith a Ja)a object an ser)ice enable it usin# annotations.
+or ne- e)elopment the preferre path is to esi#n your ser)ices in WSDE an then
#enerate the coe to implement them. This approach enforces the concept that a
ser)ice is an abstract entity that is implementation neutral. It also means you can
spen more time -or$in# out the e!act interface your ser)ice re4uires before you
start coin#.
1o-e)er% there are many cases -here you may nee to ser)ice enable an e!istin#
application. While JAX-WS eases the process% it oes re4uire that you ma$e some
chan#es to source coe of your application. =ou -ill nee to a annotations to the
source. It also re4uires that you mi#rate your coe to Ja)a B.A.
WSDL First Development
Gsin# the WSDE 6rst moel of ser)ice e)elopment% you start -ith a WSDE ocument
that e6nes the ser)ice you -ish to implement. This WSDE ocument coul be
obtaine from another e)eloper% a system architect% a GDDI re#istry% or you coul
-rite it yourself. The ocument must contain at least a fully speci6e lo#ical interface
before you can be#in #eneratin# coe from it.
.nce you ha)e a WSDE ocument% the process for e)elopin# a JAX-WS ser)ice is
three stepsF
>. /enerate startin# point coe.
,. Implement the ser)ice9s operations.
2. (ublish the implemente ser)ice.
enerating the Starting !oint Code
JAX-WS speci6es a etaile mappin# from a ser)ice e6ne in WSDE to the Ja)a
classes that -ill implement that ser)ice. The lo#ical interface% e6ne by the
-slFportType element% is mappe to a ser)ice enpoint interface 8S0I:. Any comple!
types e6ne in the WSDE are mappe into Ja)a classes follo-in# the mappin#
e6ne by the Ja)a Architecture for X'E 5inin# 8JAX5: speci6cation. The enpoint
e6ne by the -slFser)ice element is also #enerate into a Ja)a class that is use
by consumers to access enpoints implementin# the ser)ice.
The -sl,ja)a comman automates the #eneration of this coe. It also pro)ies
options for #eneratin# startin# point coe for your implementation an an ant base
ma$e6le to buil the application. -sl,ja)a pro)ies a number of ar#uments for
controllin# the #enerate coe.
"unning #sdl2$ava
=ou can #enerate the coe neee to e)elop your ser)ice usin# the follo-in#
commanF
-sl,ja)a -ant -impl -ser)er - outputDir mySer)ice.-sl
The comman oes the follo-in#F
The -ant ar#ument #enerates a Ant ma$e6le% calle buil.!ml% for your
application.
The -impl ar#ument #enerates a shell implementation class for each portType
element in the WSDE ocument.
The -ser)er ar#ument #enerates a simple main8: to launch your ser)ice as a
stan alone application.
The - outputDir ar#ument tells -sl,ja)a to -rite the #enerate coe to a
irectory calle outputDir.
mySer)ice.-sl is the WSDE ocument from -hich coe is #enerate.
enerated code
Table> escribes the 6les #enerate for creatin# a ser)ice.
Table >F /enerate *lasses for a Ser)ice
+ile Description
portType;ame.ja)a
The S0I. This 6le contains the interface
your ser)ice implements. =ou shoul not
eit this 6le.
ser)ice;ame.ja)a
The enpoint. This 6le contains the Ja)a
class your clients -ill use to ma$e re4uests
on the ser)ice.
portType;ameImpl.ja)a
The s$eleton implementation class. =ou -ill
moify this 6le to implement your ser)ice.
portType;ameHportType;ameImpl(ortHSer
)er.ja)a
A basic ser)er main8: that allo-s you to
eploy your ser)ice as a stan alone
process
%mplementing the Service
.nce the startin# point coe is #enerate% you must pro)ie the business lo#ic for
each of the operations e6ne in the ser)ice9s interface.
enerating the implementation code
=ou #enerate the implementation class for your ser)ice -ith -sl,ja)a9s -impl Ia#.
enerated code
The ser)ice implementation coe consists of t-o 6lesF
portType;ame.ja)a is the ser)ice interface8S0I: for the ser)ice.
portType;ameImpl.ja)a is the class you -ill use to implement the operations
e6ne for the ser)ice.
%mplement the operation&s logic
=ou pro)ie the business lo#ic for your ser)ice9s operations by completin# the stub
methos in portType;ameImpl.ja)a. +or the most part% you use stanar Ja)a to
implement the business lo#ic. If your ser)ice uses custom X'E Schema types% you
-ill nee to use the #enerate classes for each type to manipulate them. There are
also some *X+ speci6c A(Is that you can use to access some a)ance features.
Java First Development
To create a ser)ice startin# from Ja)a you nee to o the follo-in#F
>. *reate a Ser)ice 0npoint Interface 8S0I: that e6nes the methos you -ish to
e!pose as a ser)ice.
'ip
=ou can -or$ irectly from a Ja)a class% but -or$in# from an interface is the
recommene approach. Interfaces are better for sharin# -ith the
e)elopers -ho -ill be responsible for e)elopin# the applications
consumin# your ser)ice. The interface is smaller an oes not pro)ie any
of the ser)ice9s implementation etails.
,. A the re4uire annotations to your coe.
2. /enerate the WSDE contract for your ser)ice.
'ip
If you inten to use the S0I as the ser)ice9s contract% it is not necessary to
#enerate a WSDE contract
<. (ublish the ser)ice.
Creating the S(%
The ser)ice enpoint interface 8S0I: is the piece of Ja)a coe that is share bet-een
a ser)ice an the consumers that ma$e re4uests on it. When startin# -ith a WSDE
contract% the S0I is #enerate by the coe #enerators. 1o-e)er% -hen startin# from
Ja)a% it is the up to a e)eloper to create the S0I.
There are t-o basic patterns for creatin# an S0IF
/reen 6el e)elopment
=ou are e)elopin# a ne- ser)ice from the #roun up. When startin# fresh% it
is best to start by creatin# the S0I 6rst. =ou can then istribute the S0I to any
e)elopers that are responsible for implementin# the ser)ices an consumers
that use the S0I.
)ote
The recommene -ay to o #reen 6el ser)ice e)elopment is to start by
creatin# a WSDE contract that e6nes the ser)ice an its interfaces.
Ser)ice enablement
In this pattern% you typically ha)e an e!istin# set of functionality that is
implemente as a Ja)a class an you -ant to ser)ice enable it. This means
that you -ill nee to o t-o thin#sF
>. *reate an S0I that contains onl* the operations that are #oin# to be
e!pose as part of the ser)ice.
,. 'oify the e!istin# Ja)a class so that it implements the S0I.
)ote
=ou can a the JAX-WS annotations to a Ja)a class% but that is not
recommene.
Writing the inter+ace
The S0I is a stanar Ja)a interface. It e6nes a set of methos that a class -ill
implement. It can also e6ne a number of member 6els an constants to -hich the
implementin# class has access.
In the case of an S0I the methos e6ne are intene to be mappe to operations
e!pose by a ser)ice. The S0I correspons to a -slFportType element. The methos
e6ne by the S0I correspon to -slFoperation elements in the -slFportType
element.
'ip
JAX-WS e6nes an annotation that allo-s you to specify methos that are not
e!pose as part of a ser)ice. 1o-e)er% the best practice is to lea)e such methos
out of the S0I.
package org.apache.cxf;
public interface QuoteReporter
{
public Quote getQuote(String ticker);
}
Implementing the interface

Developing a Service using JAX-WS

o WSDL First Development
Generating the Starting Point Code
Running sdl!"ava
Generated code
#mplementing the Service
Generating the implementation code
Generated code
#mplement the operation$s logic
%&ample
o Java First Development
Creating the S%#
Writing the inter'ace
#mplementing the inter'ace
Annotating the Code
Re(uired Annotations
)he @WebService annotation
Annotating the S%#
Annotating the service implementation
*ptional Annotations
De'ining the +inding Properties ith Annotations
)he @SO!"in#ing annotation
De'ining *peration Properties ith Annotations
)he @Web$etho# annotation
)he @Re%ue&tWrapper annotation
)he @Re&pon&eWrapper annotation
)he @Web'ault annotation
)he @One(a) annotation
%&ample
De'ining Parameter Properties ith Annotations
)he @Web!ara* annotation
)he @WebRe&ult annotation
%&ample
Generating WSDL
%&ample
Developing a Service using JAX-WS
=ou can e)elop a ser)ice usin# one of t-o approachesF
Start -ith a WSDE contract an #enerate Ja)a objects to implement the
ser)ice.
Start -ith a Ja)a object an ser)ice enable it usin# annotations.
+or ne- e)elopment the preferre path is to esi#n your ser)ices in WSDE an then
#enerate the coe to implement them. This approach enforces the concept that a
ser)ice is an abstract entity that is implementation neutral. It also means you can
spen more time -or$in# out the e!act interface your ser)ice re4uires before you
start coin#.
1o-e)er% there are many cases -here you may nee to ser)ice enable an e!istin#
application. While JAX-WS eases the process% it oes re4uire that you ma$e some
chan#es to source coe of your application. =ou -ill nee to a annotations to the
source. It also re4uires that you mi#rate your coe to Ja)a B.A.
WSDL First Development
Gsin# the WSDE 6rst moel of ser)ice e)elopment% you start -ith a WSDE ocument
that e6nes the ser)ice you -ish to implement. This WSDE ocument coul be
obtaine from another e)eloper% a system architect% a GDDI re#istry% or you coul
-rite it yourself. The ocument must contain at least a fully speci6e lo#ical interface
before you can be#in #eneratin# coe from it.
.nce you ha)e a WSDE ocument% the process for e)elopin# a JAX-WS ser)ice is
three stepsF
>. /enerate startin# point coe.
,. Implement the ser)ice9s operations.
2. (ublish the implemente ser)ice.
enerating the Starting !oint Code
JAX-WS speci6es a etaile mappin# from a ser)ice e6ne in WSDE to the Ja)a
classes that -ill implement that ser)ice. The lo#ical interface% e6ne by the
-slFportType element% is mappe to a ser)ice enpoint interface 8S0I:. Any comple!
types e6ne in the WSDE are mappe into Ja)a classes follo-in# the mappin#
e6ne by the Ja)a Architecture for X'E 5inin# 8JAX5: speci6cation. The enpoint
e6ne by the -slFser)ice element is also #enerate into a Ja)a class that is use
by consumers to access enpoints implementin# the ser)ice.
The #sdl2$ava comman automates the #eneration of this coe. It also pro)ies
options for #eneratin# startin# point coe for your implementation an an ant base
ma$e6le to buil the application. #sdl2$ava pro)ies a number of ar#uments for
controllin# the #enerate coe.
"unning #sdl2$ava
=ou can #enerate the coe neee to e)elop your ser)ice usin# the follo-in#
commanF
-sl,ja)a -ant -impl -ser)er - outputDir mySer)ice.-sl
The comman oes the follo-in#F
The -ant ar#ument #enerates a Ant ma$e6le% calle buil.!ml% for your
application.
The -impl ar#ument #enerates a shell implementation class for each portType
element in the WSDE ocument.
The -ser)er ar#ument #enerates a simple main8: to launch your ser)ice as a
stan alone application.
The - outputDir ar#ument tells #sdl2$ava to -rite the #enerate coe to a
irectory calle outputDir.
mySer)ice.-sl is the WSDE ocument from -hich coe is #enerate.
enerated code
Table> escribes the 6les #enerate for creatin# a ser)ice.
'able ,- enerated Classes +or a Service
File Description
portTypeName.ja)a The S0I. This 6le contains the interface
your ser)ice implements. =ou shoul not
eit this 6le.
serviceName.ja)a
The enpoint. This 6le contains the Ja)a
class your clients -ill use to ma$e re4uests
on the ser)ice.
portTypeNameImpl.ja)a
The s$eleton implementation class. =ou -ill
moify this 6le to implement your ser)ice.
portTypeNameHportTypeNameImpl(ortHSe
r)er.ja)a
A basic ser)er main8: that allo-s you to
eploy your ser)ice as a stan alone
process.
%mplementing the Service
.nce the startin# point coe is #enerate% you must pro)ie the business lo#ic for
each of the operations e6ne in the ser)ice9s interface.
enerating the implementation code
=ou #enerate the implementation class for your ser)ice -ith #sdl2$ava9s -impl Ia#.
'ip
If your ser)ice9s contract inclue any custom types e6ne in X'E Schema% you
-ill also nee to ensure that the classes for the types are also #enerate an
a)ailable.
enerated code
The ser)ice implementation coe consists of t-o 6lesF
portTypeName.ja)a is the ser)ice interface8S0I: for the ser)ice.
portTypeNameImpl.ja)a is the class you -ill use to implement the operations
e6ne for the ser)ice.
%mplement the operation&s logic
=ou pro)ie the business lo#ic for your ser)ice9s operations by completin# the stub
methos in portTypeNameImpl.ja)a. +or the most part% you use stanar Ja)a to
implement the business lo#ic. If your ser)ice uses custom X'E Schema types% you
-ill nee to use the #enerate classes for each type to manipulate them. There are
also some *X+ speci6c A(Is that you can use to access some a)ance features.
(xample
+or e!ample% an implementation class for a ser)ice that e6ne the operations say1i
an #reet'e may loo$ li$e the follo-in#F
%mplementation o+ the reeter Service
pac$a#e emo.h-.ser)erJ
import or#.apache.helloH-orlHsoapHhttp./reeterJ
Kja)a!.j-s.WebSer)ice8port;ame L 7Soap(ort7% ser)ice;ame L 7S.A(Ser)ice7%
tar#et;amespace L 7httpF33apache.or#3helloH-orlHsoapHhttp7%
enpointInterface L 7or#.apache.helloH-orlHsoapHhttp./reeter7:
public class /reeterImpl implements /reeter M
public Strin# #reet'e8Strin# me:
M
System.out.println870!ecutin# operation #reet'e7:J
System.out.println87'essa#e recei)eF 7 N me N 7On7:J
return 71ello 7 N meJ
P
public Strin# say1i8:
M
System.out.println870!ecutin# operation say1iOn7:J
return 75onjour7J
P
P
Java First Development
To create a ser)ice startin# from Ja)a you nee to o the follo-in#F
>. *reate a Ser)ice 0npoint Interface 8S0I: that e6nes the methos you -ish to
e!pose as a ser)ice.
'ip
=ou can -or$ irectly from a Ja)a class% but -or$in# from an interface is the
recommene approach. Interfaces are better for sharin# -ith the
e)elopers -ho -ill be responsible for e)elopin# the applications
consumin# your ser)ice. The interface is smaller an oes not pro)ie any
of the ser)ice9s implementation etails.
,. A the re4uire annotations to your coe.
2. /enerate the WSDE contract for your ser)ice.
'ip
If you inten to use the S0I as the ser)ice9s contract% it is not necessary to
#enerate a WSDE contract
<. (ublish the ser)ice.
Creating the S(%
The ser)ice enpoint interface 8S0I: is the piece of Ja)a coe that is share bet-een
a ser)ice an the consumers that ma$e re4uests on it. When startin# -ith a WSDE
contract% the S0I is #enerate by the coe #enerators. 1o-e)er% -hen startin# from
Ja)a% it is the up to a e)eloper to create the S0I.
There are t-o basic patterns for creatin# an S0IF
/reen 6el e)elopment
=ou are e)elopin# a ne- ser)ice from the #roun up. When startin# fresh% it
is best to start by creatin# the S0I 6rst. =ou can then istribute the S0I to any
e)elopers that are responsible for implementin# the ser)ices an consumers
that use the S0I.
)ote
The recommene -ay to o #reen 6el ser)ice e)elopment is to start by
creatin# a WSDE contract that e6nes the ser)ice an its interfaces.
Ser)ice enablement
In this pattern% you typically ha)e an e!istin# set of functionality that is
implemente as a Ja)a class an you -ant to ser)ice enable it. This means
that you -ill nee to o t-o thin#sF
>. *reate an S0I that contains onl* the operations that are #oin# to be
e!pose as part of the ser)ice.
,. 'oify the e!istin# Ja)a class so that it implements the S0I.
)ote
=ou can a the JAX-WS annotations to a Ja)a class% but that is not
recommene.
Writing the inter+ace
The S0I is a stanar Ja)a interface. It e6nes a set of methos that a class -ill
implement. It can also e6ne a number of member 6els an constants to -hich the
implementin# class has access.
In the case of an S0I the methos e6ne are intene to be mappe to operations
e!pose by a ser)ice. The S0I correspons to a -slFportType element. The methos
e6ne by the S0I correspon to -slFoperation elements in the -slFportType
element.
'ip
JAX-WS e6nes an annotation that allo-s you to specify methos that are not
e!pose as part of a ser)ice. 1o-e)er% the best practice is to lea)e such methos
out of the S0I.
The belo- sho-s a simple S0I for a stoc$ upatin# ser)ice.
Simple S(%
pac$a#e or#.apache.c!fJ
public interface Quote&eporter
M
public Quote #etQuote8Strin# tic$er:J
P
%mplementing the inter+ace
5ecause the S0I is a stanar Ja)a interface% the class that implements it is just a
stanar Ja)a class. If you starte -ith a Ja)a class you -ill nee to moify it to
implement the interface. If you are startin# fresh% the implementation class -ill nee
to implement the S0I.
The belo- sho-s a class for implementin# the abo)e interface.
pac$a#e or#.apache.c!fJ
import ja)a.util."J
public class Stoc$Quote&eporter implements Quote&eporter
M
...
public Quote #etQuote8Strin# tic$er:
M
Quote retRal L ne- Quote8:J
retRal.setID8tic$er:J
retRal.setRal85oar.chec$8tic$er::JS>T
Date retDate L ne- Date8:J
retRal.setTime8retDate.toStrin#8::J
return8retRal:J
P
P
Annotating the Code
JAX-WS relies on the annotation feature of Ja)a B. The JAX-WS annotations are use to
specify the metaata use to map the S0I to a fully speci6e ser)ice e6nition.
Amon# the information pro)ie in the annotations are the follo-in#F
The tar#et namespace for the ser)ice.
The name of the class use to hol the re4uest messa#e.
The name of the class use to hol the response messa#e.
If an operation is a one -ay operation.
The binin# style the ser)ice uses.
The name of the class use for any custom e!ceptions.
The namespaces uner -hich the types use by the ser)ice are e6ne.
"e.uired Annotations
In orer to create a ser)ice from Ja)a coe you are only re4uire to a one
annotation to your coe. =ou must a the KWebSer)ice8: annotation on both the S0I
an the implementation class.
The @WebService annotation
The KWebSer)ice annotation is e6ne by the ja)a!.j-s.WebSer)ice interface an it
is place on an interface or a class that is intene to be use as a ser)ice.
KWebSer)ice has the follo-in# propertiesF
!ropert* Description
name
Speci6es the name of the ser)ice interface. This property is mappe to
the name attribute of the -slFportType element that e6nes the
ser)ice9s interface in a WSDE contract. The efault is to appen
(ortType to the name of the implementation class.
tar#et;amesp
ace
Speci6es the tar#et namespace uner -hich the ser)ice is e6ne. If
this property is not speci6e% the tar#et namespace is eri)e from
the pac$a#e name.
ser)ice;ame
Speci6es the name of the publishe ser)ice. This property is mappe
to the name attribute of the -slFser)ice element that e6nes the
publishe ser)ice. The efault is to use the name of the ser)ice9s
implementation class. )ote- ;ot allo-e on the S0I
-slEocation
Speci6es the G&I at -hich the ser)ice9s WSDE contract is store. The
efault is the G&I at -hich the ser)ice is eploye.
enpointInterf
ace
Speci6es the full name of the S0I that the implementation class
implements. This property is only use -hen the attribute is use on a
ser)ice implementation class. )ote- ;ot allo-e on the S0I
port;ame
Speci6es the name of the enpoint at -hich the ser)ice is publishe.
This property is mappe to the name attribute of the -slFport
element that speci6es the enpoint etails for a publishe ser)ice. The
efault is the appen (ort to the name of the ser)ice9s implementation
class. )ote- ;ot allo-e on the S0I
Annotating the SEI
pac$a#e com.mycompany.emoJ
import ja)a!.j-s."J
/WebService0name12.uote3pdater24
target)amespace12http-55cx+6apache6org24
#sdlLocation12http-55some#here6com5.uote(xampleService7#sdl28
public interface Quote&eporter
M
public Quote #etQuote8KWeb(aram8nameL7tic$er7: Strin# tic$er:J
P
The KWebSer)ice annotation abo)e oes the follo-in#F
>. Speci6es that the )alue of the name attribute of the -slFportType element
e6nin# the ser)ice interface is 4uoteGpater.
,. Speci6es that the tar#et namespace of the ser)ice is httpF33c!f.apache.or#.
2. Speci6es that the ser)ice -ill use the pre-e6ne WSDE contract -hich is
publishe at httpF33some-here.com34uote0!ampleSer)iceU-sl.
Annotating the service implementation
In aition to annotatin# the S0I -ith the KWebSer)ice annotation% you also ha)e to
annotate the ser)ice implementation class -ith the KWebSer)ice annotation. When
ain# the annotation to the ser)ice implementation class you only nee to specify
the enpointInterface property. As sho-n in belo- the property nees to be set to the
full name of the S0I.
pac$a#e or#.apache.c!fJ
import ja)a!.j-s."J
/WebService0endpoint%nter+ace12org6apache6cx+6.uote"eporter24
target)amespace12http-55cx+6apache6org24
port)ame12Stoc9:uote!ort24
service)ame12Stoc9:uote"eporter24
8
public class Stoc$Quote&eporter implements Quote&eporter
M
public Quote #etQuote8Strin# tic$er:
M
...
P
P
The @SOAPBining annotation
The KS.A(5inin# annotation is e6ne by the ja)a!.j-s.soap.S.A(5inin#
interface. It pro)ies etails about the S.A( binin# use by the ser)ice -hen it is
eploye. If the KS.A(5inin# annotation is not speci6e% a ser)ice is publishe
usin# a -rappe oc3literal S.A( binin#.
=ou can put the KS.A(5inin# annotation on the S0I an any of the S0I9s methos.
When it is use on a metho% settin# of the metho9s KS.A(5inin# annotation ta$e
preceent.
The follo-in# table sho-s the properties for the KS.A(5inin# annotation.
!ropert* ;alues Description
style
Style.D.*G'0;T
8efault:
Style.&(*
Speci6es the style of the S.A( messa#e. If &(*
style is speci6e% each messa#e part -ithin the
S.A( boy is a parameter or return )alue an -ill
appear insie a -rapper element -ithin the
soapFboy element. The messa#e parts -ithin the
-rapper element correspon to operation
parameters an must appear in the same orer as
the parameters in the operation. If D.*G'0;T
style is speci6e% the contents of the S.A( boy
must be a )ali X'E ocument% but its form is not
as ti#htly constraine.
use
Gse.EIT0&AE 8efault:
Gse.0;*.D0D
Speci6es ho- the ata of the S.A( messa#e is
streame.
parameterSt
yle
(arameterStyle.5A&0
(arameterStyle.W&A(
(0D 8efault:
Speci6es ho- the metho parameters% -hich
correspon to messa#e parts in a WSDE contract%
are place into the S.A( messa#e boy. A
parameter style of 5A&0 means that each
parameter is place into the messa#e boy as a
chil element of the messa#e root. A parameter
style of W&A((0D means that all of the input
parameters are -rappe into a sin#le element on
a re4uest messa#e an that all of the output
parameters are -rappe into a sin#le element in
the response messa#e. If you set the style to &(*
you must use the W&A((0D parameter style.
package org.eric.#e*o;
i*port +avax.+(&.,;
i*port +avax.+(&.&oap.,;
i*port +avax.+(&.&oap.SO!"in#ing.,;
@WebService(name="quoteReporter")
@SOAPBinding(style=StyleRP!" use=$se%&'(RA%)
public interface QuoteReporter
{
...
}
The @Web!etho annotation
The KWeb'etho annotation is e6ne by the ja)a!.j-s.Web'etho interface. It is
place on the methos in the S0I. The KWeb'etho annotation pro)ies the
information that is normally represente in the -slFoperation element escribin# the
operation to -hich the metho is associate.
The follo-in# table escribes the properties of the KWeb'etho annotation.
!ropert* Description
operation;a
me
Speci6es the )alue of the associate -slFoperation element9s name.
The efault )alue is the name of the metho.
action
Speci6es the )alue of the soapAction attribute of the soapFoperation
element #enerate for the metho. The efault )alue is an empty strin#.
e!clue
Speci6es if the metho shoul be e!clue from the ser)ice interface.
The efault is false.
The @"e#$estWrapper annotation
The K&e4uestWrapper annotation is e6ne by the ja)a!.!ml.-s.&e4uestWrapper
interface. It is place on the methos in the S0I. As the name implies%
K&e4uestWrapper speci6es the Ja)a class that implements the -rapper bean for the
metho parameters that are inclue in the re4uest messa#e sent in a remote
in)ocation. It is also use to specify the element names% an namespaces% use by
the runtime -hen marshallin# an unmarshallin# the re4uest messa#es.
The follo-in# table escribes the properties of the K&e4uestWrapper annotation.
!ropert* Description
local;ame
Speci6es the local name of the -rapper element in the X'E
representation of the re4uest messa#e. The efault )alue is the name
of the metho or the )alue of the KWeb'etho annotation9s
operation;ame property.
tar#et;amesp
ace
Speci6es the namespace uner -hich the X'E -rapper element is
e6ne. The efault )alue is the tar#et namespace of the S0I.
class;ame
Speci6es the full name of the Ja)a class that implements the -rapper
element.
'ip
.nly the class;ame property is
re4uire.
The @"esponseWrapper annotation
The K&esponseWrapper annotation is e6ne by the ja)a!.!ml.-s.&esponseWrapper
interface. It is place on the methos in the S0I. As the name implies%
K&esponseWrapper speci6es the Ja)a class that implements the -rapper bean for
the metho parameters that are inclue in the response messa#e sent in a remote
in)ocation. It is also use to specify the element names% an namespaces% use by
the runtime -hen marshallin# an unmarshallin# the response messa#es.
The follo-in# table escribes the properties of the K&esponseWrapper annotation.
!ropert* Description
local;ame
Speci6es the local name of the -rapper element in the X'E
representation of the response messa#e. The efault )alue is the name
of the metho -ith &esponse appene or the )alue of the
KWeb'etho annotation9s operation;ame property -ith &esponse
appene.
tar#et;amesp
ace
Speci6es the namespace uner -hich the X'E -rapper element is
e6ne. The efault )alue is the tar#et namespace of the S0I.
class;ame
Speci6es the full name of the Ja)a class that implements the -rapper
element.
'ip
.nly the class;ame property is
re4uire.
The @WebFa$lt annotation
The KWeb+ault annotation is e6ne by the ja)a!.!ml.-s.Web+ault interface. It is
place on e!ceptions that are thro-n by your S0I. The KWeb+ault annotation is use
to map the Ja)a e!ception to a -slFfault element. This information is use to
marshall the e!ceptions into a representation that can be processe by both the
ser)ice an its consumers.
The follo-in# table escribes the properties of the KWeb+ault annotation.
!ropert* Description
name Speci6es the local name of the fault element.
tar#et;amesp
ace
Speci6es the namespace uner -hich the fault element is e6ne. The
efault )alue is the tar#et namespace of the S0I.
fault;ame
Speci6es the full name of the Ja)a class that implements the
e!ception.
pac$a#e or#.apache.c!fJ
import ja)a!.j-s."J
import ja)a!.!ml.-s."J
/WebService0name12.uote"eporter28
public interface Quote&eporter
M
/Web<ethod0operation)ame12getStoc9:uote28

/"e.uestWrapper0target)amespace12http-55demo6m*compan*6com5t*pes24
class)ame12$ava6lang6String28

/"esponseWrapper0target)amespace12http-55demo6m*compan*6com5t*pes
24
class)ame12org6eric6demo6:uote28
public Quote #etQuote8Strin# tic$er:J
P
Java Web services- JAX= and JAX-WS in Axis2
The ori#inal Apache A!is -as base on the 6rst Ja)a stanar for Web ser)ices% JAX-
&(*. This turne out not to be a #reat approach% because JAX-&(* constraine the
internal esi#n of the A!is coe an contribute to both performance issues an a
lac$ of Ie!ibility. JAX-&(* also mae some assumptions about the irection of Web
ser)ices e)elopment that turne out to be -ron#.
5y the time the A!is, efort -as starte% a replacement for JAX-&(* -as alreay in
the -or$s% so A!is, -as esi#ne to be Ie!ible enou#h to implement support for the
replacement Web ser)ices stanar on top of the base frame-or$. &ecent )ersions of
A!is, ha)e implemente support for both the JAX5 ,.! Ja)a X'E ata-binin#
stanar an the JAX-WS ,.! Ja)a Web ser)ices stanar that replace JAX-&(*. This
article sho-s ho- to use JAX5 an JAX-WS -ith A!is, an ienti6es some of the
limitations of A!is,9s current support for these stanars.
JAX= in Axis2
A!is, implements support for JAX5 ,.! as one of the ata-binin# alternati)es you
can choose -hen #eneratin# coe from a Web Ser)ices Description Ean#ua#e 8WSDE:
ser)ice e6nition -ith WSDE,Ja)a. 8See 7Ja)a Web Ser)icesF A!is, Data 5inin#7 for a
iscussion of the other main alternati)es.: As -ith most of the other alternati)es%
#eneratin# coe from WSDE usin# JAX5 ,.! creates both a set of lin$a#e classes an
a set of ata moel classes. The lin$a#e classes% incluin# a client-sie stub an a
ser)er-sie messa#e recei)er% interface bet-een your application coe an A!is,.
The ata moel classes represent the actual messa#e ata.
JAX5 ,.! uses annotations in the ata moel classes to control ho- ata is con)erte
to an from X'E. The annotations approach allo-s you to use iferent JAX5
implementations at run time -ithout neein# to chan#e your source coe or
recompile your classes. It9s up to the JAX5 implementation to access the annotation
information from the ata moel classes an apply these annotations -hen
con)ertin# to an from X'E.
Using the CXF Servlet
The *X+ ser)let% -hich acts as an aapter for the Web ser)ice enpoints. The *X+
ser)let is the easiest metho for eployin# Web ser)ices into a ser)let container.
Deploye WA& 6le V Ser)ice pro)iers are eploye to the ser)let container
in a Web Archi)e 8WA&: 6le. The eploye WA& 6le containsF
o the compile coe for the ser)ice pro)ier bein# eploye
o the WSDE 6le e6nin# the ser)ice
o the +use Ser)ices +rame-or$ con6#uration 6le
This 6le% calle c!f-ser)let.!ml% is stanar +use Ser)ices +rame-or$
con6#uration 6le that e6nes all of the enpoints containe in the
WA&.
o the Web application eployment escriptor
All +use Ser)ices +rame-or$ Web applications usin# the stanar *X+
ser)let nee to loa the or#.apache.c!f.transport.ser)let.*X+Ser)let
class.
*X+ ser)let V The *X+ ser)let is a stanar ser)let pro)ie by +use Ser)ices
+rame-or$. It acts as an aapter for Web ser)ice enpoints an is part of the
+use Ser)ices +rame-or$ runtime. The *X+ ser)let is implemente by the
or#.apache.c!f.transport.ser)let.*X+Ser)let class.
Deplo*ment steps
To eploy a +use Ser)ices +rame-or$ enpoint to a ser)let container you mustF
>. 5uil a WA& that contains your application an all the re4uire support 6les.
,. Deploy the WA& 6le to your ser)let container.
=uilding a WA"
To eploy your application to a ser)let container% you must buil a WA& 6le. The WA&
6le9s W05-I;+ foler shoul inclue the follo-in#F
c!f-ser)let.!ml V a +use Ser)ices +rame-or$ con6#uration 6le specifyin# the
enpoints that plu# into the *X+ ser)let. When the *X+ ser)let starts up% it
reas the ja!-sFenpoint elements from this 6le% an initialiWes a ser)ice
enpoint for each one. See Ser)let con6#uration 6le for more information.
-eb.!ml V a stanar -eb application 6le that instructs the ser)let container
to loa the or#.apache.c!f.transport.ser)let.*X+Ser)let class.
'ip
A reference )ersion of this 6le is containe in your InstallDir3etc irectory.
=ou can use this reference copy -ithout ma$in# chan#es to it.
classes V a foler incluin# your Web ser)ice implementation class an any
other classes re4uire to support the implementation.
-sl V a foler incluin# the WSDE 6le that e6nes the ser)ice you are
eployin#.
lib V a foler incluin# any JA&s re4uire by your application.
Servlet con>guration >le
The c!f-ser)let.!ml 6le is a +use Ser)ices +rame-or$ con6#uration 6le that con6#ures
the enpoints that plu# into the *X+ ser)let. When the *X+ ser)let starts up it reas
the ja!-sFenpoint elements in this 6le an initialiWes a ser)ice enpoint for each
one.
0!ample ?.> sho-s a simple c!f-ser)let.!ml 6le.
(xample ?6,6 CXF Servlet Con>guration File
XU!ml )ersionL7>.A7 encoin#L7GT+-C7UY
Xbeans !mlnsL7httpF33---.sprin#frame-or$.or#3schema3beans7
!mlnsF!siL7httpF33---.-2.or#3,AA>3X'ESchema-instance
!mlnsFja!-sL7httpF33c!f.apache.or#3ja!-s7
!mlnsFsoapL7httpF33c!f.apache.or#3binin#s3soap7
!siFschemaEocationL7
httpF33---.sprin#frame-or$.or#3schema3beans
httpF33---.sprin#frame-or$.or#3schema3beans3sprin#-beans-,.A.!s
httpF33c!f.apache.or#3binin#s3soap
httpF33c!f.apache.or#3schemas3con6#uration3soap.!s
httpF33c!f.apache.or#3ja!-s httpF33c!f.apache.or#3schemas3ja!-s.!s7Y
Xja!-sFenpoint
iL7helloH-orl7
implementorL7emo.h-.ser)er./reeterImpl7
-slEocationL7W05-I;+3-sl3helloH-orl.-sl7
aressL73helloH-orl7Y
Xja!-sFfeaturesY
Xbean classL7or#.apache.c!f.feature.Eo##in#+eature73Y
X3ja!-sFfeaturesY
X3ja!-sFenpointY
X3beansY
The coe sho-n in 0!ample ?.> is e!plaine as follo-sF
The Sprin# beans element is re4uire at the be#innin# of e)ery +use Ser)ices
+rame-or$ con6#uration 6le. It is the only Sprin# element that you nee to be
familiar -ith.
The ja!-sFenpoint element e6nes a ser)ice pro)ier enpoint. The
ja!-sFenpoint element has the follo-in# attributesF
i V Sets the enpoint i.
implementor V Speci6es the class implementin# the ser)ice.
%mportant
This class nees to be inclue in the WA&9s W05-
I;+3classes foler.
-slEocation V Speci6es the WSDE 6le that contains the ser)ice
e6nition.
%mportant
The WSDE 6le location is relati)e to the WA&9s W05-
I;+3-sl foler.
aress V Speci6es the aress of the enpoint as e6ne in the
ser)ice9s WSDE 6le that e6nes ser)ice that is bein# eploye.
ja!-sFfeatures V De6nes features that can be ae to your enpoint.
+or more information on con6#urin# a ja!-sFenpoint element% see Gsin# the
ja!-sFenpoint 0lement.
Web application con>guration
=ou must inclue a -eb.!ml eployment escriptor 6le that instructs the ser)let
container to loa the *X+ ser)let. 0!ample ?., sho-s a -eb.!ml 6le. It is not
necessary to chan#e this 6le. A reference copy is locate in the InstallDir3etc
irectory.
(xample ?626 A #eb6xml Deplo*ment Descriptor File
XU!ml )ersionL7>.A7 encoin#L7GT+-C7UY
XZD.*T=(0 -eb-app (G5EI* 7-33Sun 'icrosystems% Inc.33DTD Web Application
,.2330;7 7httpF33ja)a.sun.com3t3-eb-appH,H2.t7Y
X-eb-appY
Xisplay-nameYc!fX3isplay-nameY
XescriptionYc!fX3escriptionY
Xser)letY
Xser)let-nameYc!fX3ser)let-nameY
Xisplay-nameYc!fX3isplay-nameY
XescriptionYApache *X+ 0npointX3escriptionY
Xser)let-classYor#.apache.c!f.transport.ser)let.*X+Ser)letX3ser)let-classY
Xloa-on-startupY>X3loa-on-startupY
X3ser)letY
Xser)let-mappin#Y
Xser)let-nameYc!fX3ser)let-nameY
Xurl-patternY3ser)ices3"X3url-patternY
X3ser)let-mappin#Y
Xsession-con6#Y
Xsession-timeoutY?AX3session-timeoutY
X3session-con6#Y
X3-eb-appY
+uilding Clients
o WSDL!Java generated Client
o JAX-WS Pro&,
o JAX-WS Dispatch AP#s
o Simple Frontend Client Pro&,
o D,namic Client
D*namicClientFactor* and JaxWsD*namicClientFactor*
*X+ pro)ies t-o factory classes for ynamic classes. If your ser)ice is e6ne in
terms of JAX-WS concepts% you shoul use the Ja!WsDynamic*lient+actory. If you o
not -ant or nee JAX-WS semantics% use the Dynamic*lient+actory.
Ja!WsDynamic*lient+actory cf L Ja!WsDynamic*lient+actory.ne-Instance8:J
*lient client L cf.create*lient87echo.-sl7:J
.bjectST res L client.in)o$e87echo7% 7test echo7:J
System.out.println870cho responseF 7 N resSAT:J
'any WSDEs -ill ha)e more comple! types thou#h. In this case the
Ja!WsDynamic*lient+actory ta$es care of #eneratin# Ja)a classes for these types. +or
e!ample% -e may ha)e a (eople ser)ice -hich $eeps trac$ of people in an
or#aniWation. In the sample belo- -e create a (erson object that -as #enerate for
us ynamically an sen it to the ser)er usin# the a(erson operationF
Ja!WsDynamic*lient+actory cf L Ja!WsDynamic*lient+actory.ne-Instance8:J
*lient client L cf.create*lient87people.-sl7% classEoaer:J
.bject person L
Threa.currentThrea8:.#et*onte!t*lassEoaer8:.loa*lass87com.acme.(erson7:.ne-I
nstance8:J
'etho m L person.#et*lass8:.#et'etho87set;ame7% Strin#.class:J
m.in)o$e8person% 7Joe Schmoe7:J
client.in)o$e87a(erson7% person:J
The Ja!WsDynamic*lient+actory sets the Threa conte!t *lassEoaer to a ne-
*lassEoaer that contains the classes for the #enerate types. If you nee the
ori#inal *lassEoaer% ma$e sure you sa)e it prior to callin# create*lient.
@elloWorld
Ja!WsDynamic*lient+actory cf L Ja!WsDynamic*lient+actory.newInstance8:J
33*lient client L cf.create*lient873-sls31elloWorl.-sl7:J
*lient client L
cf.create*lient87httpF33localhostFCACC3*X+Tutorial31elloWorlU-sl7:J
.bjectST res L client.in)o$e87say1i7% 7test echo7:J
System.out.println870cho responseF 7 N resSAT:J
StudentDetails
Ja!WsDynamic*lient+actory cf L Ja!WsDynamic*lient+actory.newInstance8:J
*lient client L
cf.create*lient87httpF33localhostFCACC3*X+Tutorial3*han#eStuentU-sl7:J
.bject stuent L
Threa.currentThread8:.#et*onte!t*lassEoaer8:.loa*lass87com.stuent.Stuent7:.n
e-Instance8:J
'etho metho L stuent.#et*lass8:.#et'etho87set;ame7%
Strin#.class:J
metho.in)o$e8stuent% 7Tumuluri &a)i Kumar7:J
.bjectST res L client.in)o$e87chan#e;ame7% stuent:J
'etho metho> L stuent.#et*lass8:.#et'etho87#et;ame7:J
System.out.println870cho responseF 7 N resSAT:J
System.out.println870cho responseF 7 N metho>.in)o$e8stuent::J
De)elopin# a Ser)ice usin# JAX-WS
WSDE +irst De)elopment
/eneratin# the Startin# (oint *oe
o &unnin# -sl,ja)a
o /enerate coe
Implementin# the Ser)ice
o /eneratin# the implementation coe
o /enerate coe
o Implement the operation9s lo#ic
o 0!ample
Developing a Service using JAX-WS
WSDL First Development
Gsin# the WSDE 6rst moel of ser)ice e)elopment% you start -ith a WSDE ocument
that e6nes the ser)ice you -ish to implement. This WSDE ocument coul be
obtaine from another e)eloper% a system architect% a GDDI re#istry% or you coul
-rite it yourself. The ocument must contain at least a fully speci6e lo#ical interface
before you can be#in #eneratin# coe from it.
.nce you ha)e a WSDE ocument% the process for e)elopin# a JAX-WS ser)ice is
three stepsF
>. /enerate startin# point coe.
,. Implement the ser)ice9s operations.
2. (ublish the implemente ser)ice.
JAX-WS speci6es a etaile mappin# from a ser)ice e6ne in WSDE to the Ja)a
classes that -ill implement that ser)ice. The lo#ical interface% e6ne by the
#sdl-port'*pe element% is mappe to a ser)ice enpoint interface 8S0I:. Any
comple! types e6ne in the WSDE are mappe into Ja)a classes follo-in# the
mappin# e6ne by the Java Architecture +or X<L =inding 0JAX=8 speci>cation.
The enpoint e6ne by the #sdl-service element is also #enerate into a Ja)a
class that is use by consumers to access enpoints implementin# the ser)ice.
The #sdl2$ava comman automates the #eneration of this coe. It also pro)ies
options for #eneratin# startin# point coe for your implementation an an ant base
ma$e6le to buil the application. #sdl2$ava pro)ies a number of ar#uments for
controllin# the #enerate coe.
=ou can #enerate the coe neee to e)elop your ser)ice usin# the follo-in#
commanF
-sl,ja)a -ant -impl -ser)er - outputDir mySer)ice.-sl
The comman oes the follo-in#F
The -ant ar#ument #enerates a Ant ma$e6le% calle buil.!ml% for your
application.
The -impl ar#ument #enerates a shell implementation class for each portType
element in the WSDE ocument.
The -ser)er ar#ument #enerates a simple main8: to launch your ser)ice as a
stan alone application.
The - outputDir ar#ument tells #sdl2$ava to -rite the #enerate coe to a
irectory calle outputDir.
mySer)ice.-sl is the WSDE ocument from -hich coe is #enerate.
enerated code
Table> escribes the 6les #enerate for creatin# a ser)ice.
'able ,- enerated Classes +or a Service
File Description
portTypeName.ja)a
The S0I. This 6le contains the interface
your ser)ice implements. =ou shoul not
eit this 6le.
serviceName.ja)a
The enpoint. This 6le contains the Ja)a
class your clients -ill use to ma$e re4uests
on the ser)ice.
portTypeNameImpl.ja)a
The s$eleton implementation class. =ou -ill
moify this 6le to implement your ser)ice.
portTypeNameHportTypeNameImpl(ortHSe
r)er.ja)a
A basic ser)er main8: that allo-s you to
eploy your ser)ice as a stan alone
process.
%mplementing the Service
.nce the startin# point coe is #enerate% you must pro)ie the business lo#ic for
each of the operations e6ne in the ser)ice9s interface.
enerating the implementation code
=ou #enerate the implementation class for your ser)ice -ith #sdl2$ava9s -impl Ia#.
enerated code
The ser)ice implementation coe consists of t-o 6lesF
portTypeName.ja)a is the ser)ice interface8S0I: for the ser)ice.
portTypeNameImpl.ja)a is the class you -ill use to implement the operations
e6ne for the ser)ice.
%mplement the operation&s logic
=ou pro)ie the business lo#ic for your ser)ice9s operations by completin# the stub
methos in portTypeNameImpl.ja)a. +or the most part% you use stanar Ja)a to
implement the business lo#ic. If your ser)ice uses custom X'E Schema types% you
-ill nee to use the #enerate classes for each type to manipulate them. There are
also some *X+ speci6c A(Is that you can use to access some a)ance features.
Java First Development
To create a ser)ice startin# from Ja)a you nee to o the follo-in#F
>. *reate a Ser)ice 0npoint Interface 8S0I: that e6nes the methos you -ish to
e!pose as a ser)ice.
'ip
=ou can -or$ irectly from a Ja)a class% but -or$in# from an interface is the
recommene approach. Interfaces are better for sharin# -ith the
e)elopers -ho -ill be responsible for e)elopin# the applications
consumin# your ser)ice. The interface is smaller an oes not pro)ie any
of the ser)ice9s implementation etails.
,. A the re4uire annotations to your coe.
2. /enerate the WSDE contract for your ser)ice.
'ip
If you inten to use the S0I as the ser)ice9s contract% it is not necessary to
#enerate a WSDE contract
<. (ublish the ser)ice.
Creating the S(%
The ser)ice enpoint interface 8S0I: is the piece of Ja)a coe that is share bet-een
a ser)ice an the consumers that ma$e re4uests on it. When startin# -ith a WSDE
contract% the S0I is #enerate by the coe #enerators. 1o-e)er% -hen startin# from
Ja)a% it is the up to a e)eloper to create the S0I.
There are t-o basic patterns for creatin# an S0IF
/reen 6el e)elopment
=ou are e)elopin# a ne- ser)ice from the #roun up. When startin# fresh% it
is best to start by creatin# the S0I 6rst. =ou can then istribute the S0I to any
e)elopers that are responsible for implementin# the ser)ices an consumers
that use the S0I.
)ote
The recommene -ay to o #reen 6el ser)ice e)elopment is to start by
creatin# a WSDE contract that e6nes the ser)ice an its interfaces.
Ser)ice enablement
In this pattern% you typically ha)e an e!istin# set of functionality that is
implemente as a Ja)a class an you -ant to ser)ice enable it. This means
that you -ill nee to o t-o thin#sF
>. *reate an S0I that contains onl* the operations that are #oin# to be
e!pose as part of the ser)ice.
,. 'oify the e!istin# Ja)a class so that it implements the S0I.
)ote
=ou can a the JAX-WS annotations to a Ja)a class% but that is not
recommene.
Writing the inter+ace
The S0I is a stanar Ja)a interface. It e6nes a set of methos that a class -ill
implement. It can also e6ne a number of member 6els an constants to -hich the
implementin# class has access.
In the case of an S0I the methos e6ne are intene to be mappe to operations
e!pose by a ser)ice. The S0I correspons to a -slFportType element. The methos
e6ne by the S0I correspon to -slFoperation elements in the -slFportType
element.
'ip
JAX-WS e6nes an annotation that allo-s you to specify methos that are not
e!pose as part of a ser)ice. 1o-e)er% the best practice is to lea)e such methos
out of the S0I.
The belo- sho-s a simple S0I for a stoc$ upatin# ser)ice.
Simple S(%
pac$a#e or#.apache.c!fJ
public interface Quote&eporter
M
public Quote #etQuote8Strin# tic$er:J
P
%mplementing the inter+ace
5ecause the S0I is a stanar Ja)a interface% the class that implements it is just a
stanar Ja)a class. If you starte -ith a Ja)a class you -ill nee to moify it to
implement the interface. If you are startin# fresh% the implementation class -ill nee
to implement the S0I.
The belo- sho-s a class for implementin# the abo)e interface.
%mplementation +or S(%
pac$a#e or#.apache.c!fJ
import ja)a.util."J
public class Stoc$Quote&eporter implements Quote&eporter
M
...
public Quote #etQuote8Strin# tic$er:
M
Quote retRal L ne- Quote8:J
retRal.setID8tic$er:J
retRal.setRal85oar.chec$8tic$er::JS>T
Date retDate L ne- Date8:J
retRal.setTime8retDate.toStrin#8::J
return8retRal:J
P
P
Annotating the Code
JAX-WS relies on the annotation feature of Ja)a B. The JAX-WS annotations are use to
specify the metaata use to map the S0I to a fully speci6e ser)ice e6nition.
Amon# the information pro)ie in the annotations are the follo-in#F
The tar#et namespace for the ser)ice.
The name of the class use to hol the re4uest messa#e.
The name of the class use to hol the response messa#e.
If an operation is a one -ay operation.
The binin# style the ser)ice uses.
The name of the class use for any custom e!ceptions.
The namespaces uner -hich the types use by the ser)ice are e6ne.
'ip
'ost of the annotations ha)e sensible efaults an o not nee to be
speci6e. 1o-e)er% the more information you pro)ie in the annotations%
the better e6ne your ser)ice e6nition. A soli ser)ice e6nition
increases the li$ely hoo that all parts of a istribute application -ill -or$
to#ether.
"e.uired Annotations
In orer to create a ser)ice from Ja)a coe you are only re4uire to a one
annotation to your coe. =ou must a the KWebSer)ice8: annotation on both the S0I
an the implementation class.
The @WebService annotation
The KWebSer)ice annotation is e6ne by the ja)a!.j-s.WebSer)ice interface an it
is place on an interface or a class that is intene to be use as a ser)ice.
KWebSer)ice has the follo-in# propertiesF
!ropert* Description
name
Speci6es the name of the ser)ice interface. This property is mappe to
the name attribute of the -slFportType element that e6nes the
ser)ice9s interface in a WSDE contract. The efault is to appen
(ortType to the name of the implementation class.
tar#et;amesp
ace
Speci6es the tar#et namespace uner -hich the ser)ice is e6ne. If
this property is not speci6e% the tar#et namespace is eri)e from
the pac$a#e name.
ser)ice;ame
Speci6es the name of the publishe ser)ice. This property is mappe
to the name attribute of the -slFser)ice element that e6nes the
publishe ser)ice. The efault is to use the name of the ser)ice9s
implementation class. )ote- ;ot allo-e on the S0I
-slEocation
Speci6es the G&I at -hich the ser)ice9s WSDE contract is store. The
efault is the G&I at -hich the ser)ice is eploye.
enpointInterf
ace
Speci6es the full name of the S0I that the implementation class
implements. This property is only use -hen the attribute is use on a
ser)ice implementation class. )ote- ;ot allo-e on the S0I
port;ame
Speci6es the name of the enpoint at -hich the ser)ice is publishe.
This property is mappe to the name attribute of the -slFport
element that speci6es the enpoint etails for a publishe ser)ice. The
efault is the appen (ort to the name of the ser)ice9s implementation
class. )ote- ;ot allo-e on the S0I
'ip
=ou o not nee to pro)ie )alues for any of the KWebSer)ice
annotation9s properties. 1o-e)er% it is recommene that you pro)ie
as much information as you can.
Annotating the SEI
The S0I re4uires that you a the KWebSer)ice annotation. Since the S0I is the
contract that e6nes the ser)ice% you shoul specify as much etail as you can about
the ser)ice in the KWebSer)ice annotation9s properties.
The coe belo- sho-s the interface e6ne abo)e -ith the KWebSer)ice annotation.
%nter+ace #ith the /WebService Annotation
pac$a#e com.mycompany.emoJ
import ja)a!.j-s."J
KWebSer)ice8nameL74uoteGpater7%
tar#et;amespaceL7httpF33c!f.apache.or#7%
-slEocationL7httpF33some-here.com34uote0!ampleSer)iceU-sl7:
public interface Quote&eporter
M
public Quote #etQuote8KWeb(aram8nameL7tic$er7: Strin# tic$er:J
P
The KWebSer)ice annotation abo)e oes the follo-in#F
>. Speci6es that the )alue of the name attribute of the -slFportType element
e6nin# the ser)ice interface is 4uoteGpater.
,. Speci6es that the tar#et namespace of the ser)ice is httpF33c!f.apache.or#.
2. Speci6es that the ser)ice -ill use the pre-e6ne WSDE contract -hich is
publishe at httpF33some-here.com34uote0!ampleSer)iceU-sl.
The KWeb(aram annotation is necessary as ja)a interfaces o not store the
(arameter name in the .class 6le. So if you lea)e out the annotation your parameter
-ill be name ar#A.
Annotating the service implementation
In aition to annotatin# the S0I -ith the KWebSer)ice annotation% you also ha)e to
annotate the ser)ice implementation class -ith the KWebSer)ice annotation. When
ain# the annotation to the ser)ice implementation class you only nee to specify
the enpointInterface property. As sho-n in belo- the property nees to be set to the
full name of the S0I.
Annotated Service %mplementation Class
pac$a#e or#.apache.c!fJ
import ja)a!.j-s."J
KWebSer)ice8enpointInterfaceL7or#.apache.c!f.4uote&eporter7%
tar#et;amespaceL7httpF33c!f.apache.or#7%
port;ameL7Stoc$Quote(ort7%
ser)ice;ameL7Stoc$Quote&eporter7%
:
public class Stoc$Quote&eporter implements Quote&eporter
M
public Quote #etQuote8Strin# tic$er:
M
...
P
P
Aptional Annotations
While the KWebSer)ice annotation is su[cient for ser)ice enablin# a Ja)a interface
or a Ja)a class% it oes not pro)ie a lot of information about ho- the ser)ice -ill be
e!pose as an enpoint. The JAX-WS pro#rammin# moel uses a number of optional
annotations for ain# etails about your ser)ice% such as the binin# it uses% to the
Ja)a coe. =ou a these annotations to the ser)ice9s S0I.
'ip
The more etails you pro)ie in the S0I% the easier it -ill be for e)elopers to
implement applications that can use the functionality it e6nes. It -ill also pro)ie
for better #enerate WSDE contracts.
De%ning the Bining Properties &ith Annotations
If you are usin# a S.A( binin# for your ser)ice% you can use JAX-WS annotations to
specify a number of the binin#s properties. These properties correspon irectly to
the properties you can specify in a ser)ice9s WSDE contract.
The @SOAPBining annotation
The KS.A(5inin# annotation is e6ne by the ja)a!.j-s.soap.S.A(5inin#
interface. It pro)ies etails about the S.A( binin# use by the ser)ice -hen it is
eploye. If the KS.A(5inin# annotation is not speci6e% a ser)ice is publishe
usin# a -rappe oc3literal S.A( binin#.
=ou can put the KS.A(5inin# annotation on the S0I an any of the S0I9s methos.
When it is use on a metho% settin# of the metho9s KS.A(5inin# annotation ta$e
preceent.
The follo-in# table sho-s the properties for the KS.A(5inin# annotation.
!ropert* ;alues Description
style
Style.D.*G'0;T
8efault:
Style.&(*
Speci6es the style of the S.A( messa#e. If &(*
style is speci6e% each messa#e part -ithin the
S.A( boy is a parameter or return )alue an -ill
appear insie a -rapper element -ithin the
soapFboy element. The messa#e parts -ithin the
-rapper element correspon to operation
parameters an must appear in the same orer as
the parameters in the operation. If D.*G'0;T
style is speci6e% the contents of the S.A( boy
must be a )ali X'E ocument% but its form is not
as ti#htly constraine.
use Gse.EIT0&AE 8efault: Speci6es ho- the ata of the S.A( messa#e is
Gse.0;*.D0D streame.
parameterSt
yle
(arameterStyle.5A&0
(arameterStyle.W&A(
(0D 8efault:
Speci6es ho- the metho parameters% -hich
correspon to messa#e parts in a WSDE contract%
are place into the S.A( messa#e boy. A
parameter style of 5A&0 means that each
parameter is place into the messa#e boy as a
chil element of the messa#e root. A parameter
style of W&A((0D means that all of the input
parameters are -rappe into a sin#le element on
a re4uest messa#e an that all of the output
parameters are -rappe into a sin#le element in
the response messa#e. If you set the style to &(*
you must use the W&A((0D parameter style.
An S0I that uses rpc3literal S.A( messa#es is as follo-sF
Speci+*ing an "!C5L%'("AL SAA! =inding
pac$a#e or#.eric.emoJ
import ja)a!.j-s."J
import ja)a!.j-s.soap."J
import ja)a!.j-s.soap.S.A(5inin#."J
KWebSer)ice8nameL74uote&eporter7:
KS.A(5inin#8styleLStyle.&(*% useLGse.EIT0&AE:
public interface Quote&eporter
M
...
P
De%ning Operation Properties &ith Annotations
When the runtime maps your Ja)a metho e6nitions into X'E operation e6nitions it
6lls in etails such asF
-hat the e!chan#e messa#es loo$ li$e in X'E.
if the messa#e can be optimiWe as a one -ay messa#e.
the namespaces -here the messa#es are e6ne.
The @Web!etho annotation
The KWeb'etho annotation is e6ne by the ja)a!.j-s.Web'etho interface. It is
place on the methos in the S0I. The KWeb'etho annotation pro)ies the
information that is normally represente in the -slFoperation element escribin# the
operation to -hich the metho is associate.
The follo-in# table escribes the properties of the KWeb'etho annotation.
!ropert* Description
operation;a
me
Speci6es the )alue of the associate -slFoperation element9s name.
The efault )alue is the name of the metho.
action Speci6es the )alue of the soapAction attribute of the soapFoperation
element #enerate for the metho. The efault )alue is an empty strin#.
e!clue
Speci6es if the metho shoul be e!clue from the ser)ice interface.
The efault is false.
The @"e#$estWrapper annotation
The K&e4uestWrapper annotation is e6ne by the ja)a!.!ml.-s.&e4uestWrapper
interface. It is place on the methos in the S0I. As the name implies%
K&e4uestWrapper speci6es the Ja)a class that implements the -rapper bean for the
metho parameters that are inclue in the re4uest messa#e sent in a remote
in)ocation. It is also use to specify the element names% an namespaces% use by
the runtime -hen marshallin# an unmarshallin# the re4uest messa#es.
The follo-in# table escribes the properties of the K&e4uestWrapper annotation.
!ropert* Description
local;ame
Speci6es the local name of the -rapper element in the X'E
representation of the re4uest messa#e. The efault )alue is the name
of the metho or the )alue of the KWeb'etho annotation9s
operation;ame property.
tar#et;amesp
ace
Speci6es the namespace uner -hich the X'E -rapper element is
e6ne. The efault )alue is the tar#et namespace of the S0I.
class;ame
Speci6es the full name of the Ja)a class that implements the -rapper
element.
'ip
.nly the class;ame property is
re4uire.
The @"esponseWrapper annotation
The K&esponseWrapper annotation is e6ne by the ja)a!.!ml.-s.&esponseWrapper
interface. It is place on the methos in the S0I. As the name implies%
K&esponseWrapper speci6es the Ja)a class that implements the -rapper bean for
the metho parameters that are inclue in the response messa#e sent in a remote
in)ocation. It is also use to specify the element names% an namespaces% use by
the runtime -hen marshallin# an unmarshallin# the response messa#es.
The follo-in# table escribes the properties of the K&esponseWrapper annotation.
!ropert* Description
local;ame
Speci6es the local name of the -rapper element in the X'E
representation of the response messa#e. The efault )alue is the name
of the metho -ith &esponse appene or the )alue of the
KWeb'etho annotation9s operation;ame property -ith &esponse
appene.
tar#et;amesp
ace
Speci6es the namespace uner -hich the X'E -rapper element is
e6ne. The efault )alue is the tar#et namespace of the S0I.
class;ame
Speci6es the full name of the Ja)a class that implements the -rapper
element.
'ip
.nly the class;ame property is
re4uire.
The @WebFa$lt annotation
The KWeb+ault annotation is e6ne by the ja)a!.!ml.-s.Web+ault interface. It is
place on e!ceptions that are thro-n by your S0I. The KWeb+ault annotation is use
to map the Ja)a e!ception to a -slFfault element. This information is use to
marshall the e!ceptions into a representation that can be processe by both the
ser)ice an its consumers.
The follo-in# table escribes the properties of the KWeb+ault annotation.
!ropert* Description
name Speci6es the local name of the fault element.
tar#et;amespa
ce
Speci6es the namespace uner -hich the fault element is e6ne.
The efault )alue is the tar#et namespace of the S0I.
fault;ame
Speci6es the full name of the Ja)a class that implements the
e!ception.
%mportant
The name property is re4uire.
+i!'eF fault;ame is e6ne as bean;ame by the Sun Ja)a 00 B SDK at
httpF33ja)a.sun.com3ja)aee3B3ocs3api3ja)a!3!ml3-s3Web+ault.html.
The @One&a' annotation
The K.ne-ay annotation is e6ne by the ja)a!.j-s..ne-ay interface. It is place
on the methos in the S0I that -ill not re4uire a response from the ser)ice. The
K.ne-ay annotation tells the run time that it can optimiWe the e!ecution of the
metho by not -aitin# for a response an not reser)in# any resources to process a
response.
E(ample
The belo- sho-s an S0I -hose methos are annotate.
S(% #ith Annotated <ethods
pac$a#e or#.apache.c!fJ
import ja)a!.j-s."J
import ja)a!.!ml.-s."J
KWebSer)ice8nameL74uote&eporter7:
public interface Quote&eporter
M
KWeb'etho8operation;ameL7#etStoc$Quote7:
K&e4uestWrapper8tar#et;amespaceL7httpF33emo.mycompany.com3types7%
class;ameL7ja)a.lan#.Strin#7:
K&esponseWrapper8tar#et;amespaceL7httpF33emo.mycompany.com3types7%
class;ameL7or#.eric.emo.Quote7:
public Quote #etQuote8Strin# tic$er:J
P
De%ning Parameter Properties &ith Annotations
The metho parameters in the S0I correspon to the -slFmessa#e elements an
their -slFpart elements. JAX-WS pro)ies annotations that allo- you to escribe the
-slFpart elements that are #enerate for the metho parameters.
The @WebParam annotation
The KWeb(aram annotation is e6ne by the ja)a!.j-s.Web(aram interface. It is
place on the parameters on the methos e6ne in the S0I. The KWeb(aram
annotation allo-s you to specify the irection of the parameter% if the parameter -ill
be place in the S.A( heaer% an other properties of the #enerate -slFpart.
The follo-in# table escribes the properties of the KWeb(aram annotation.
!ropert* ;alues Description
name
Speci6es the name of the parameter as it appears in the
WSDE. +or &(* binin#s% this is name of the -slFpart
representin# the parameter. +or ocument binin#s% this is
the local name of the X'E element representin# the
parameter. (er the JAX-WS speci6cation% the efault is
argN% -here N is replace -ith the Wero-base ar#ument
ine! 8i.e.% arg0% arg1% etc.:
tar#et;amesp
ace

Speci6es the namespace for the parameter. It is only use
-ith ocument binin#s -here the parameter maps to an
X'E element. The efaults is to use the ser)ice9s
namespace.
moe
'oe.I;
8efault:
'oe..GT
'oe.I;.G
T
Speci6es the irection of the parameter.
heaer
false
8efault:
true
Speci6es if the parameter is passe as part of the S.A(
heaer.
part;ame
Speci6es the )alue of the name attribute of the -slFpart
element for the parameter -hen the binin# is ocument.
The @Web"es$lt annotation
The KWeb&esult annotation is e6ne by the ja)a!.j-s.Web&esult interface. It is
place on the methos e6ne in the S0I. The KWeb&esult annotation allo-s you to
specify the properties of the #enerate -slFpart that is #enerate for the metho9s
return )alue.
The follo-in# table escribes the properties of the KWeb&esult annotation.
!ropert* Description
name
Speci6es the name of the return )alue as it appears in the WSDE. +or
&(* binin#s% this is name of the -slFpart representin# the return
)alue. +or ocument binin#s% this is the local name of the X'E
element representin# the return )alue. The efault )alue is return.
tar#et;amesp
ace
Speci6es the namespace for the return )alue. It is only use -ith
ocument binin#s -here the return )alue maps to an X'E element.
The efaults is to use the ser)ice9s namespace.
heaer Speci6es if the return )alue is passe as part of the S.A( heaer.
part;ame
Speci6es the )alue of the name attribute of the -slFpart element for
the return )alue -hen the binin# is ocument.
E(ample
The ne!t e!ample sho-s an S0I that is fully annotate.
Full* Annotated S(%
pac$a#e or#.apache.c!fJ
import ja)a!.j-s."J
import ja)a!.!ml.-s."J
import ja)a!.j-s.soap."J
import ja)a!.j-s.soap.S.A(5inin#."J
import ja)a!.j-s.Web(aram."J
KWebSer)ice8nameL74uote&eporter7:
KS.A(5inin#8styleLStyle.&(*% useLGse.EIT0&AE:
public interface Quote&eporter
M
KWeb'etho8operation;ameL7#etStoc$Quote7:
K&e4uestWrapper8tar#et;amespaceL7httpF33emo.mycompany.com3types7%
class;ameL7ja)a.lan#.Strin#7:
K&esponseWrapper8tar#et;amespaceL7httpF33emo.mycompany.com3types7%
class;ameL7or#.eric.emo.Quote7:
KWeb&esult8tar#et;amespaceL7httpF33emo.mycompany.com3types7%
nameL7upateQuote7:
public Quote #etQuote8
KWeb(aram8tar#et;amespaceL7httpF33emo.mycompany.com3types7%
nameL7stoc$Tic$er7%
moeL'oe.I;:
Strin# tic$er
:J
P
enerating WSDL
.nce you ha)e annotate your coe% you can #enerate a WSDE contract for your
ser)ice usin# the $ava2#sdl comman.
(xample
The ne!t e!ample sho-s the WSDE contract #enerate for the S0I sho-n abo)eF
enerated WSDL +rom an S(%
XU!ml )ersionL7>.A7 encoin#L7GT+-C7UY
X-slFe6nitions tar#et;amespaceL7httpF33emo.eric.or#37
!mlnsFtnsL7httpF33emo.eric.or#37
!mlnsFns>L77
!mlnsF!sL7httpF33---.-2.or#3,AA>3X'ESchema7
!mlnsFns,L7httpF33emo.eric.or#3types7
!mlnsFsoapL7httpF33schemas.!mlsoap.or#3-sl3soap37
!mlnsF-slL7httpF33schemas.!mlsoap.or#3-sl37Y
X-slFtypesY
X!sFschemaY
X!sFcomple!Type nameL74uote7Y
X!sFse4uenceY
X!sFelement nameL7ID7 typeL7!sFstrin#7 min.ccursL7A73Y
X!sFelement nameL7time7 typeL7!sFstrin#7 min.ccursL7A73Y
X!sFelement nameL7)al7 typeL7!sFIoat73Y
X3!sFse4uenceY
X3!sFcomple!TypeY
X3!sFschemaY
X3-slFtypesY
X-slFmessa#e nameL7#etStoc$Quote7Y
X-slFpart nameL7stoc$Tic$er7 typeL7!sFstrin#7Y
X3-slFpartY
X3-slFmessa#eY
X-slFmessa#e nameL7#etStoc$Quote&esponse7Y
X-slFpart nameL7upateQuote7 typeL7tnsF4uote7Y
X3-slFpartY
X3-slFmessa#eY
X-slFportType nameL74uote&eporter7Y
X-slFoperation nameL7#etStoc$Quote7Y
X-slFinput nameL7#etQuote7 messa#eL7tnsF#etStoc$Quote7Y
X3-slFinputY
X-slFoutput nameL7#etQuote&esponse7
messa#eL7tnsF#etStoc$Quote&esponse7Y
X3-slFoutputY
X3-slFoperationY
X3-slFportTypeY
X-slFbinin# nameL74uote&eporter5inin#7 typeL7tnsF4uote&eporter7Y
XsoapFbinin# styleL7rpc7 transportL7httpF33schemas.!mlsoap.or#3soap3http73Y
X-slFoperation nameL7#etStoc$Quote7Y
XsoapFoperation styleL7rpc73Y
X-slFinput nameL7#etQuote7Y
XsoapFboy useL7literal73Y
X3-slFinputY
X-slFoutput nameL7#etQuote&esponse7Y
XsoapFboy useL7literal73Y
X3-slFoutputY
X3-slFoperationY
X3-slFbinin#Y
X-slFser)ice nameL74uote&eporterSer)ice7Y
X-slFport nameL74uote&eporter(ort7 binin#L7tnsF4uote&eporter5inin#7Y
XsoapFaress locationL7httpF33localhostFDAAA34uote&eporterSer)ice73Y
X3-slFportY
X3-slFser)iceY
X3-slFe6nitionsY
CXF Avervie#
JAX-WS Support
*X+ implements the JAX-WS A(Is -hich ma$e builin# -eb ser)ices easy. JAX-WS
encompasses many iferent areasF
/eneratin# WSDE from Ja)a classes an #eneratin# Ja)a classes from WSDE
(ro)ier A(I -hich allo-s you to create simple messa#in# recei)in# ser)er
enpoints
Dispatch A(I -hich allo-s you to sen ra- X'E messa#es to ser)er enpoints
Spring %ntegration
Sprin# is a 6rst class citiWen -ith Apache *X+. *X+ supports the Sprin# ,.A X'E
synta!% ma$in# it tri)ial to eclare enpoints -hich are bac$e by Sprin# an inject
clients into your application.
Aegis Databinding
Ae#is Databinin# 8,.A.!: is our o-n atabinin# library that ma$es e)elopment of
coe-6rst -eb ser)ices increibly easy. Gnli$e JAX5% you on9t nee annotations at all.
It also -or$s correctly -ith a )ariety of atatypes such as Eists% 'aps% Dates% etc.
ri#ht out of the bo!. If you9re builin# a prototype -eb ser)ices that9s really
in)aluable as it means you ha)e to o )ery little -or$ to #et up an runnin# 8an one
of the primary reasons X+ire -as starte a -hile bac$:
WS-B Support
*X+ supports a )ariety of -eb ser)ice speci6cations incluin# WS-Aressin#% WS-
(olicy% WS-&eliable'essa#in# an WS-Security.
'ransports
*X+ -or$s -ith many iferent transports. *urrently *X+ inclues support for 1TT(%
J'S% an Eocal 8that is% 7in-JR'7: transports. The local transport is uni4ue in that it -ill
not -or$ across machines% but simply sens messa#es in memory. =ou can also
con6#ure the local transport to a)oi serialiWation by usin# the .bject binin# or the
colocation feature if esire. =ou can also -rite your o-n transport.
=indings
5inin#s map a particular ser)ice9s messa#es to a particular protocol. *X+ inclues
support for se)eral iferent binin#s. The S.A( binin#% -hich is the efault% maps
messa#es to S.A( an can be use -ith the )arious WS-" moules insie *X+. The
(ure X'E binin# a)ois serialiWation of a S.A( en)elope an just sens a ra- X'E
messa#e. There is also an 1TT( 5inin# -hich maps a ser)ice to 1TT( usin# &0STful
semantics.
<essage %nterception and <odi>cation
'any times you may -ant to pro)ie functionality for your application that -or$s at a
lo- le)el -ith X'E messa#es. This commonly occurs throu#h functionality referre to
as 1anlers or Interceptors. 1anlers3Interceptors are useful forF
(erformin# authentication base on 1eaers
(rocessin# custom heaers
Transformin# a messa#e 8i.e. )ia XSET or /\ip:
&eirectin# a messa#e
/ettin# access to the ra- I3. or X'E stream
JA)*WS +anlers
If you are usin# the JAX-WS fronten% JAX-WS supports the concept of lo#ical an
protocol hanlers. (rotocol hanlers allo- you to manipulate the messa#e in its ra-%
often X'E-base% form - i.e. a SAAJ S.A('essa#e. Eo#ical hanlers allo- you to
manipulate the messa#e after its alreay been boun from the protocol to the JAX5
object that your ser)ice -ill recei)e. See this article to learn more about JAX-WS
hanlers.
'ransmitting =inar* Data
*X+ pro)ies facilities to transmit binary ata e[ciently )ia a stanar calle 'T.'.
;ormally binary ata insie an X'E messa#e must be 5ase?< encoe. This results
in processin# o)erhea an increases messa#e siWe by 2A]. If you use 'T.'% *X+
-ill sen3recei)e 'I'0 messa#es -ith the messa#e store as a 'I'0 attachment%
just li$e email. This results in much more e[cient communication an allo-s you to
transmit messa#es much lar#er than memory.
WS-B
*X+ pro)ies support for a )ariety of WS-" speci6cations.
WS-Aressin#
WS-(olicy
WS-Security
WS-&eliable'essa#in#
*X+ pro)ies you -ith many options to buil ser)ices. This #uie is meant to #i)e you
a 4uic$ o)er)ie- of those options an help you orient yourself 4uic$ly -ith *X+.
Diferent Types .f Ser)ices
JAX-WS Annotate Ser)ices from Ja)a
JAX-WS Annotate Ser)ices from WSDE
JAX-WS (ro)iers
Ja)ascript
DiCerent '*pes o+ Services
*X+ support three major types of ser)icesF
S.A( - this pa#e summariWes the options for creatin# S.A( ser)ices.
&0ST-ful - &0ST support is escribe here.
*.&5A
JAX-WS Annotated Services +rom Java
The JAX-WS A(Is inclue a set of annotations -hich allo- you to buil ser)ices usin#
annotate classes. These ser)ices are base on a sin#le class -hich contains a set of
operations.
1ere9s a simple e!ampleF
KWebSer)ice
public class 1ello M
public Strin# say1i8Strin# name: M
return 71ello 7 N nameJ
P
P
JAX-WS inclues many more annotations as -ell such asF
KWeb'etho - allo-s you to customiWe the operation name% e!clue the
operation from inclusion in the ser)ice% etc
KWeb(aram - allo-s you to customiWe a parameter9s name% namespace%
irection 8I; or .GT:% etc
KWeb&esult - allo-s you to customiWe the return )alue of the -eb ser)ice call
Data is marshalle from X'E to Ja)a an )ice )ersa )ia the JAX5 ata-binin#.
Ser)ices are publish )ia one of t-o meansF
The JAX-WS stanar 0npoint A(Is
*X+9s X'E con6#uration format - i.e. Xja!-sFenpoint ... 3Y
'ore InformationF A simple JAX-WS ser)ice% De)elopin# a JAX-WS Ser)ice 8#oes into
much more epth:% Writin# a ser)ice -ith Sprin#
JAX-WS Annotated Services +rom WSDL
If you ha)e e!istin# WSDEs for your ser)ice or -ish to -rite your WSDE 6rst an then
#enerate classes% *X+ has many tools to help you o this.
The WSDE,Ja)a tool -ill #enerate a JAX-WS annotate ser)ice an ser)er stub from
your WSDE. =ou can run it one of three -aysF
The comman line
The 'a)en (lu#in
With the WSDE,Ja)a A(I
;ote that *X+ #enerally restricts WSDE support to WSI-5(% not the full WSDE >.>
speci6cation.
There is also a Simple +ronten that allo-s you to create ser)ices -ithout usa#e of
Ja)a annotations% usin# X'E con6#uration 6les instea.
JAX-WS !roviders
JAX-WS (ro)iers allo- you to create ser)ices -hich -or$ at the messa#e le)el - as
oppose to the operation le)el as -ith annotate classes. The ha)e a sin#le
operation 7in)o$e7 -hich recei)es either the messa#e payloa 8i.e. the S.A( 5oy: or
the -hole messa#e itself 8i.e. the S.A( 0n)elope:.
1ere9s a simple e!ampleF
KWebSer)ice(ro)ier
public class 1ello(ro)ier M
public Source in)o$e8Source re4uest: M
return ....J
P
P
Ser)ices are publish )ia one of t-o meansF
The JAX-WS stanar 0npoint A(Is
*X+9s X'E con6#uration format - i.e. Xja!-sFenpoint ... 3Y
'ore InformationF De)elopin# a JAX-WS Ser)ice
Javascript
*X+ pro)ies a Ja)ascript moule -hich allo-s you to buil ser)ices in Ja)ascript -ith
the Ja)a &hino library. .ne a)anta#e of this is that you can use 0<X to interact more
easily -ith the X'E. +or more information see the Ja)aScript pa#e.
AX%S2 (ngine
Installing Axis2 engine on Tomcat
;o- to install the A!is, en#ine copy a!is,.-ar into Tomcat9s -ebapps irectory. ;o-
start the Tomcat ser)er.
'esting the Axis2 %nstallation
Try usin# this httpF33localhostFCACA3a!is,. =our bro-ser -ill isplay the A!is, home
pa#e an it shoul loo$ li$eF
Developing Web service
The e)elopment of Web ser)ices is easy process. =ou can start from the WSDE
6le8Contract >rst approach: or from the Ser)ice coe8Code >rst approach:. 'ost
e)eloper prefers the coe 6rst approach. We -ill start -ith the source an create
the Web ser)ice. 1ere are the steps in)ol)e in creatin# the ne- Web ser)ices -ith
coe 6rst approach in Apache A!is,
>. De)elop the Ser)ice *lass
,. De)elop the ser)ice escriptor e.#. ser)ices.!ml
2. *ompile an Ser)ice class an create the Web ser)ices achie)e 6le 8.aar:
Web Services Descriptor
In A!is, the ser)ice con6#uration 6le use is services6xml. The ser)ices.!ml 6le
must present in the <('A-%)F irectory of the ser)ice achie)e. =ou can ha)e
multiple ser)ices in the ser)ices.!ml 6le. The Xser)iceY...X3ser)iceY ta# is use to
con6#ure the Web ser)ice.
Xser)ice Y
XZ-- *on6#uration of the ser)ice --Y
X3ser)iceY
1ere is the services6xml 6le for our applicationF
Xser)iceY
Xparameter nameL7Ser)ice*lass7 loc$eL7false7Y
coma)is*+sservice.@elloWorldServiceX3parameterY
Xoperation nameL7say1ello7Y
Xmessa#e&ecei)er
classL7org6apache6axis26rpc6receivers6"!C<essage"eceiver73Y
X3operationY
X3ser)iceY
.ur ser)ice class is coma)is*+sservice.@elloWorldService an the messa#e
recei)er is org6apache6axis26rpc6receivers6"!C<essage"eceiver6 The operation
-e are e!posin# is sa*@ello6
Compiling and building the service archieve
/o to the C-DWor9spacesD(uropaDAxis2'utorialD irectory an compile the ja)a
class usin# follo-in# commanF
C-DWor9spacesD(uropaDAxis2'utorialD E$avac net5roseindia5B6$ava
*reate the ser)ice achie)e usin# the follo-in# commanF
C-DWor9spacesD(uropaDAxisFirst!ro$DsrcE$ar -cv+ @elloWorldAxis6aar com
<('A-%)F
added mani+est
adding- com50in 1 F8 0out1 F80stored FG8
adding- com5axis250in 1 F8 0out1 F80stored FG8
adding- com5axis25#s50in 1 F8 0out1 F80stored FG8
adding- com5axis25#s5service50in 1 F8 0out1 F80stored FG8
adding- com5axis25#s5service5@elloWorldService6class0in 1 H2F8 0out1 IJ?8
0deKated IIG8
adding- com5axis25#s5service5@elloWorldService6$ava0in 1 2F,8 0out1 ,II8
0deKated 2HG8
ignoring entr* <('A-%)F5
adding- <('A-%)F5services6xml0in 1 2L,8 0out1 ,LI80deKated MMG8
C-DWor9spacesD(uropaDAxis2'utorialD Y
Deplo*ing the Web Services
;o- copy the 1elloWorlSer)ice.aar into -ebapps3a!is,3W05-I;+3ser)ices irectory
an restart the Tomcat. The Apache A!is, en#ine -ill eploy the ser)ice on the
ser)er. ;o- open the bro-ser an bro-ser the url
httpF33localhostFCACA3a!is,3ser)ices3listSer)ices.