Internal Training Document

EMS Fundamentals
Internal Training Document
Index
S.No Chapter Page
1 Introduction 3
2 Client API 5
3 Destinations 12
4 Messages in JMS 2
5 !sing Con"iguration #iles 24
$ !sing Ad%inistration !tilit& 24
' Authentication and Per%issions 25
( #ault )olerance 2'
Internal Training Document
Introduction
*MS+ *nterprise Message Ser,ice is a JMS i%ple%entation pro,ided -& )i-co.
)his docu%ent discusses the current release "eatures o" *MS 4.2 ./eleased Ma&
250. *arlier ,ersions include1 4.1.+ 4.+ 3.1.2+ 3.1.1+ 3.1+ 3...
)he JMS "ra%e2or3 .an inter"ace speci"ication+ not an i%ple%entation0 is
designed to suppl& a -asis "or M4M de,elop%ent. )I5C4 *nterprise Message
Ser,ice i%ple%ents and integrates se,eral %essage ser,ices+ including JMS.
)he creator o" the %essage is 3no2n as the producer and the recei,er o" the
%essage is 3no2n as the consumer. )he )I5C4 *MS ser,er acts as an
inter%ediar& "or the %essage and sends it to the correct destination. )he ser,er
also pro,ides enterprise6class "unctionalit& such as "ault6tolerance+ %essage
routing+ and co%%unication 2ith other %essaging s&ste%s+ such as )I5C4
/ende7,ous8 and )I5C4 S%artSoc3ets.
EMS Message Model
Figure 1 Message Delivery
JMS supports t2o %essaging %odels1
9 Point6to6point .:ueues0
9 Pu-lish and su-scri-e .topics0
.
Point-to-Point Delivery
Point6to6point %essaging has one producer and one consu%er per %essage.
)his st&le o" %essaging uses a queue to store %essages until the& are recei,ed.
)he %essage producer sends the %essage to the :ueue; the %essage
Producer Consumer
EMS
Server
Message Message
Ack Ack
Internal Training Document
consu%er retrie,es %essages "ro% the :ueue and sends ac3no2ledge%ent that
the %essage 2as recei,ed. More than one producer can send %essages to the
sa%e :ueue+ and %ore than one consu%er can retrie,e %essages "ro% the
sa%e :ueue.
Publish and Subscribe
In a pu-lish and su-scri-e %essage s&ste%+ producers address %essages to a
topic. In this %odel+ the producer is 3no2n as a pu-lisher and the consu%er is
3no2n as a su-scri-er. Man& pu-lishers can pu-lish to the sa%e topic+ and a
%essage "ro% a single pu-lisher can -e recei,ed -& %an& su-scri-ers.
Su-scri-ers su-scri-e to topics+ and all %essages pu-lished to the topic are
recei,ed -& all su-scri-ers to the topic. )his t&pe o" %essage protocol is also
3no2n as -roadcast %essaging -ecause %essages are sent o,er the net2or3
and recei,ed -& all interested su-scri-ers+ si%ilar to ho2 radio or tele,ision
signals are -roadcast and recei,ed.
Internal Training Document
Chapter 2 - Client PIs
Ja,a applications use the <a,a=.<%s pac3age to send or recei,e JMS %essages.
)his is a standard set o" inter"aces+ speci"ied -& the JMS speci"ication+ "or
creating the connection to the *MS ser,er+ speci"&ing the t&pe o" %essage to
send+ and creating the destination .topic or :ueue0 to send to or recei,e "ro%.
>ou can "ind a description o" the <a,a=.<%s pac3age in )I5C4 *nterprise
Message Ser,ice Ja,a API /e"erence included in the online docu%entation.
)I5C4 *nterprise Message Ser,ice includes a Ja,a class that allo2s
pure Ja,a )I5C4 /ende7,ous applications to connect directl& 2ith the
)I5C4 *nterprise Message Ser,ice ser,er.
)I5C4 *nterprise Message Ser,ice pro,ides a pac3age containing
classes and constants "or all )I5C46speci"ic aspects o" )I5C4 *nterprise
Message Ser,ice. See the description o" the co%.ti-co.ti-e%s pac3age in
TIBCO Enterprise Message Service Java !I "e#erence included in the
online docu%entation.
)I5C4 *nterprise Message Ser,ice includes parallel APIs "or clients
2ritten in C or in C?. #or details+ see TIBCO Enterprise Message Service
C $ COBO% !I "e#erence .online docu%entation0+ and TIBCO
Enterprise Message Service &'ET !I "e#erence.
Internal Training Document
)he "igure a-o,e sho2s the progra%%ing %odel in *MS 2ith the actual
inter"aces in use. )he ta-le -elo2 descri-es the inter"aces.
Queue
Or
Topic
Queue
Or
Topic
Queue
Or
Topic
Queue
Or
Topic
QueueReceiver,
QueueBrowser, or
Topic Subscriber
QueueSender
Or
TopicPublisher
Message
Message Listener
Creates
Creates
Creates
Creates
Sends To
Receives From
Registers with
Internal Training Document
Common Facilities
Inter!ace
Speci!ic Inter!ace Description
Session @ueueSession
)opicSession
A session is a single6
threaded o-<ect that
creates instances o"
%essage producers+
%essage consu%ers+
%essages and transacted
%essage groups.
Sessions can also -e
transacted. In a
transacted session+ a
group o" %essages are
sent and recei,ed in a
single transaction.
MessageProducer @ueueSender
)opicPu-lisher
A %essage producer is
an o-<ect created -& a
session that is used "or
sending %essages to
a destination.
MessageConsu%er @ueue5ro2ser
@ueue/ecei,er
)opicSu-scri-er
A %essage consu%er is
an o-<ect created -&
a session that recei,es
%essages sent to a
destination.
MessageAistener A %essage listener is an
o-<ect that acts as an
as&nchronous e,ent
handler "or %essages.
Message listeners %ust
-e registered 2ith a
speci"ic
MessageConsu%er.
MessageSelector Message selectors are
optional "ilters that can -e
used -& the application.
)he& trans"er the "iltering
2or3 to the %essage
pro,ider+ rather than the
%essage consu%er.
A %essage selector is a
Internal Training Document
String that contains an
e=pression. )he s&nta= o"
the e=pression is -ased
on a su-set o" the S@AB2
conditional e=pression
s&nta=.
Message Se,eral t&pes o"
%essage -odies are
a,aila-le "or :ueues and
topics.
@ueue
)opic
@ueue
)opic
)he destination that
%essages can -e sent to
or recei,ed "ro%.
Nor%all& these are
created and %anaged -&
the ser,er+ -ut clients can
create destinations
d&na%icall& -& using
%ethods on the
Session o-<ect.
"ey Inter!aces Explained
ConnectionFactory#
)he Connection#actor& o-<ect encapsulates a set o" connection con"iguration
para%eters. Chen a client starts+ it t&picall& per"or%s a Ja,a Na%ing and
Director& Inter"ace .JNDI0 loo3up "or the Connection#actories that it needs. #or
e=a%ple+ the "ollo2ing code retrie,es the InitialConte=t using the JNDI properties
speci"ied -& en,+ then loo3s up a Connection#actor& na%ed
%&Connection#actor&.
Conte(t ct( ) ne* InitialConte(t+env,-
ConnectionFactory myConnectionFactory )
+ConnectionFactory, ct(&loo.up+/myConnectionFactory/,-
Connection#
A Connection o-<ect encapsulates a ,irtual connection 2ith the ser,er.
Connection#actor& o-<ects create Connection o-<ects. >ou use a Connection to
create one or %ore Session o-<ects. #or e=a%ple+ using the
%&Connection#actor& o-<ect created in Connection#actor& on page 25+ the
"ollo2ing creates a Connection1
Internal Training Document
Connection myConnection )
myConnectionFactory&createConnection+,
Chen a client application co%pletes+ all open connections %ust -e closed.
!nused open connections are e,entuall& closed+ -ut the& do consu%e resources
that could -e used "or other applications. Closing a connection also closes an&
Sessions created -& the Connection. )o close a connection+ use the close.0
%ethod. #or e=a%ple1
myConnection&close+,-
Session#
A Session is a single6threaded conte=t "or producing or consu%ing %essages.
>ou create MessageProducers or MessageConsu%ers using Session o-<ects.
#or e=a%ple+ using the %&Connection o-<ect created in Connection a-o,e+ the
"ollo2ing creates a Session1
Session mySession )
myConnection&createSession+#alse0 Session&1TO2C3'O4%ED5E,-
)he "irst para%eter to the CreateSession.0 %ethod deter%ines 2hether the
Session is transactional or not. )he second para%eter speci"ies the ac3no2ledge
%ode o" %essages recei,ed -& the session.
MessageProducer#
A MessageProducer o-<ect is created -& a Session o-<ect and is used "or
sending %essages to destinations. #or e=a%ple+ using the %&Session o-<ect
created in Session a-o,e+ the "ollo2ing creates a MessageProducer that sends
%essages to a :ueue na%ed %&@ueue1
Message!roducer my6ueueSender ) mySession&create!roducer+my6ueue,-
4nce &ou ha,e created a MessageProducer+ &ou can use it to send %essages.
#or e=a%ple+ the "ollo2ing sends a %essage using the
:ueueSender created a-o,e1
my6ueueSender&send+message,-
>ou can create MessageProducers that do not identi"& a destination. Chen the
sender or pu-lisher does not speci"& a destination+ &ou %ust speci"& the
destination 2hen &ou send or pu-lish a %essage as the "irst para%eter o" the
send.0 or pu-lish.0 %ethod.
MessageConsumer#
A MessageConsu%er o-<ect is created -& a Session o-<ect and is used "or
recei,ing %essages sent to destinations. #or e=a%ple+ using the %&Session
Internal Training Document
o-<ect created in Session on page 2'+ the "ollo2ing creates a MessageConsu%er
that retrie,es %essages "ro% a :ueue na%ed %&@ueue1
MessageConsumer my6ueue"eceiver )
mySession&createConsumer+my6ueue,-
#or :ueues+ %essages re%ain on the :ueue until the& are consu%ed -& a
MessageConsu%er+ the %essage e=piration ti%e has -een reached+ or the
%a=i%u% si7e o" the :ueue is reached.
$a% Durable Subscribers !or &opics# 4nl& MessageConsu%ers 2hose
client applications are running recei,e %essages pu-lished on a topic. 4ptionall&+
Sessions can create dura-le su-scri-ers to ensure that %essages are recei,ed+
e,en i" the application is not currentl& running.
$b% Synchronous or synchronous Messages# )he API allo2s "or
s&nchronous or as&nchronous %essage consu%ption. #or s&nchronous
consu%ption+ the MessageConsu%er e=plicitl& calls the recei,e.0 %ethod on the
topic or :ueue. #or as&nchronous consu%ption+ the client registers a
MessageAistener "or the topic or :ueue. Chen a %essage arri,es at the
destination+ the )I5C4 *nterprise Message Ser,ice ser,er deli,ers the %essage
-& calling the listenerDs onMessage.0 %ethod.
Message'istener#
A MessageAistener o-<ect acts as an as&nchronous e,ent handler "or %essages.
)his o-<ect i%ple%ents the MessageAistener inter"ace and has one %ethod+
onMessage.0.)he onMessage.0 %ethod is called -& the )I5C4 *nterprise
Message Ser,ice ser,er 2hen a %essage arri,es on a destination. >ou
i%ple%ent the onMessage.0 %ethod in &our MessageAistener class to per"or%
the desired actions 2hen a %essage arri,es. >our i%ple%entation should handle
all e=ceptions+ and it should
not thro2 an& e=ceptions.
4nce &ou create a MessageAistener o-<ect+ &ou %ust register it 2ith a speci"ic
MessageConsu%er. )he "ollo2ing creates a :ueueAistener .an i%ple%entation o"
the MessageAistener inter"ace0 and registers it 2ith the
@ueue/ecei,er o-<ect1
Message%istener queue%istener ) ne* Message%istener+,-
my6ueue"eceiver&setMessage%istener+queue%istener,-
>ou should register the MessageAistener 2ith the MessageConsu%er -e"ore
calling the ConnectionDs start .0 %ethod to -egin recei,ing %essages.
Internal Training Document
Chapter (- Destinations
Destinations "or %essages can -e either )opics or @ueues. A destination can -e
created staticall& in the ser,er con"iguration "iles+ or d&na%icall& -& a client
application.
Static )ueues and &opics
Static @ueues and topics are ad%inistered -& the ser,er. )he con"iguration
in"or%ation is stored in the con"iguration "iles "or the )i-co *MS ser,er+ 2hich is
located in )I5C4EF4M*Ge%sG-in "older. )he "iles are :ueues.con" and
topics.con". Changes to the con"iguration in"or%ation can -e %ade in a ,ariet& o"
2a&s. )o %anage static destinations+ &ou can edit the con"iguration "iles using a
te=t editor or &ou can use the ad%inistration tool. An *MS Client retrie,es the
destination in"or%ation "ro% the JNDI.
Dynamic )ueues and &opics
D&na%ic :ueues and topics are created on6the6"l& -& applications using
@[email protected] and )opicSession.create)opic.0. D&na%ic
:ueues and topics do not appear in the con"iguration "iles+ and e=ist as long as
there are %essages or consu%ers on the destination. A client cannot use JNDI to
loo3up d&na%ic :ueues and topics.
Chen &ou use the sho2 :ueues or sho2 topics co%%and in the ad%inistration
tool+ &ou see -oth static and d&na%ic topics and :ueues. )he d&na%ic topics and
:ueues ha,e an asteris3 .H0 in "ront o" their na%e in the list o" topics or :ueues.
D&na%ic :ueues and topics inherit properties "ro% their respecti,e parents.
Chen sho2n -& the ad%inistration tool+ properties o" a :ueue or topic %a& ha,e
an asteris3 .H0 character in "ront o" its na%e. )his %eans that this propert& 2as
inherited "ro% the parent :ueue or topic and cannot -e changed.
&emporary )ueues and &opics
Ser,ers connected -& routes e=change %essages sent to te%porar& topics. As a
result+ te%porar& topics are ideal destinations "or repl& %essages in re:uestGrepl&
interactions.
Internal Training Document
Destination Properties
Destination properties are properties that can -e applied to :ueues andGor topics
that descri-e speci"ic -eha,ior o" the destination. *ach propert& is descri-ed in
short and please re"er the *MS docu%entation "or deeper understanding.
1. Failsa!e# #or 5oth @ueue and )opic
)I5C4 *nterprise Message Ser,ice pro,ides t2o %odes "or persisting
topicG:ueue %essages in e=ternal storage. )hese t2o %odes are1
9 nor%al
9 "ailsa"e
In Nor%al %ode all persistent %essages are 2ritten to the storage in an
as&nchronous %ode+ ie data %a& -e in the s&ste% -u""ers "or a short
duration -e"ore 2ritten to the dis3.
Chereas in "ailsa"e %ode+ data is not retained in the -u""ers and 2ritten to
the dis3 s&nchronousl&. )his ensures that in case o" an& so"t2are or
hard2are "ailure data is not lost.
In situations 2here loss o" data is not accepta-le+ use "ailsa"e. 4ne should
3eep in %ind that "ailsa"e %ode is a per"or%ance hit and should anal&7e
and care"ull& use this propert& -ased on the need.
2* secure# +oth !or )ueue and &opic
)he secure propert&+ 2hen set on a destination+ speci"ies per%issions
should -e chec3ed "or that destination. Chen a topic or a :ueue does not
ha,e the secure propert& turned on+ an& authenticated user can per"or%
an& actions 2ith that topic or :ueue. Chen the propert& is turned on+ the
ad%inistrator can assign per%issions to the users. #or this propert& to
2or3+ the aut7ori8ation propert& %ust also -e ena-les at the ser,er le,el
con"iguration "ile.
(* max+ytes# +oth !or )ueues and topics
)his propert& is use"ul "or li%iting the pending %essages on each
destination.
#or )ueues, it de"ines the %a=i%u% si7e .in -&tes0 o" all %essages that
can -e 2aiting in the :ueue. 5& de"ault+ or i" %a=-&tes is set to + there is
no li%it to the si7e o" a :ueue. I" a recei,er is o""6line "or a long ti%e+
%a=-&tes li%its the %e%or& allocation "or the recei,erDs pending
%essages. Messages that 2ould e=ceed the li%it 2ill not -e accepted into
storage and an error is returned to the %essage producer.
#or &opics %a=-&tes li%its the total si7e .in -&tes0 o" all %essages 2aiting
"or deli,er& to each dura-le su-scri-er on that topic. )he li%it applies
separatel& to each dura-le su-scri-er on the topic. #or e=a%ple+ 2hen a
dura-le su-scri-er is o""6line "or a long ti%e+ pending %essages
accu%ulate in the ser,er; %a=-&tes li%its the %e%or& allocation "or those
pending %essages "or the su-scri-er; 2hen the su-scri-er consu%es
%essages ."reeing storage0 the topic can deli,er additional %essages

Internal Training Document
-* global# +oth )ueues and &opics
Messages destined "or a topic or :ueue 2ith the glo-al propert& set are
routed to the other ser,ers that are participating in routing 2ith this ser,er.
.* sender/name# +oth )ueues and &opics
I" this propert& is set on the destination+ then ser,er copies the userna%e
o" the client to the %essage header propert&1 JMSE)I5C4ES*ND*/.
Fo2e,er i" the ti-co sender sets the propert&
JMSE)I5C4EDISA5A*ES*ND*/+ it can o,erride the -eha,ior o"
senderEna%e and the sender na%e 2ill not -e copied -& the ser,er
0* sender/name/en!orced# +oth )ueues and &opics
)he sender2name2en#orced propert& speci"ies that %essages sent to this
destination must include the senderDs user na%e. )he ser,er retrie,es the
user na%e o" the %essage producer using the sa%e procedure descri-ed
in the senderEna%e propert& a-o,e. Fo2e,er+ unli3e+ the senderEna%e
propert&+ there is no 2a& "or %essage producers to o,erride this propert&.
1* !lo2Control# +oth )ueues and &opics
)he "lo2Control propert& speci"ies the target %a=i%u% si7e the ser,er can
use to store pending %essages "or the destination. )his is use"ul 2hen
%essage producers send %essages %uch %ore :uic3l& than %essage
consu%ers can consu%e the%. >ou can speci"& the "lo2Control propert&
2ithout a ,alue to set it to the de"ault o" 25$I5. #lo2 control %ust -e
ena-led "or the ser,er -e"ore the ,alue in this propert& is en"orced -& the
ser,er.
Setting #lo* Control
#irst ena-le "lo2 control -& setting "lo2EcontrolJena-led in the
ti-e%sd.con" "ile. )hen set the "lo2Control propert& to the desired ,alue .in
-&tes0 on that destination.
9o* it *or.s
Chen the storage "or pending %essages is near the speci"ied li%it+ the
ser,er -loc3s all ne2 calls to send a %essage "ro% %essage producers.
)he calls do not return until the storage has decreased -elo2 the speci"ied
li%it. 4nce %essage consu%ers ha,e recei,ed %essages and the
pending %essage storage goes -elo2 the speci"ied li%it+ the ser,er allo2s
the send %essage calls to return to the caller and the %essage producers
can continue processing.
Destination :ridges and #lo* control
Pls. read 5ridges -e"ore reading this topic
Internal Training Document
#lo2 control can -e speci"ied on destinations that are -ridged to other
destinations. I" &ou 2ish the "lo2 o" %essages sent -& 2a& o" the -ridge to
slo2 do2n 2hen recei,ers on the -ridged6to destination cannot process
the %essages :uic3l& enough+ &ou %ust set the "lo2Control propert& on
-oth destinations on either side o" the -ridge.
"outes and #lo* Control
Pls. read /outes -e"ore reading this topic
#or glo-al topics 2here %essages are routed -et2een ser,ers+ "lo2
control can -e speci"ied "or a topic on either the ser,er 2here %essages
are produced or the ser,er 2here %essages are recei,ed. I" the
"lo2Control propert& is set on the topic on the ser,er recei,ing the
%essages+ 2hen the pending %essage si7e li%it is reached+ %essages
are not "or2arded -& 2a& o" the route until the topic su-scri-er recei,es
enough %essages to lo2er the pending %essage si7e -elo2 the speci"ied
li%it.
I" the "lo2Control propert& is set on the topic on the ser,er sending the
%essages+ the ser,er %a& -loc3 an& topic pu-lishers 2hen sending ne2
%essages i" %essages cannot -e sent :uic3l& enough -& 2a& o" the route.
)his could -e due to net2or3 latenc& -et2een the routed ser,ers or it
could -e -ecause "lo2 control on the other ser,er is pre,enting ne2
%essages "ro% -eing sent.
3* trace# +oth )ueues and &opics
Speci"ies that tracing should -e ena-led "or this destination. )his propert&
can -e speci"ied as either trace or traceJ-od&. Speci"&ing trace .2ithout
J-od&0+ generates trace %essages that include onl& the %essage
se:uence and %essage ID.
4* import# +oth )ueues and &opics
)he i%port propert& allo2s %essages pu-lished -& an e=ternal s&ste% to
-e recei,ed -& a )I5C4 *nterprise Message Ser,ice destination .a topic
or a :ueue0+ as long as the transport to the e=ternal s&ste% is con"igured.
Currentl& &ou can con"igure transports "or )I5C4 /ende7,ous relia-le
and certi"ied %essaging protocols. >ou can speci"& the na%e o" one or
%ore transports o" the sa%e t&pe in the i%port propert&.
56* export# 7nly )ueues
)he e=port propert& allo2s %essages pu-lished -& a client to a topic to -e
e=ported to the e=ternal s&ste%s 2ith con"igured transports. Currentl& &ou
can con"igure transports "or /ende7,ous relia-le and certi"ied %essaging
protocols. >ou can speci"& the na%e o" one or %ore transports o" the
sa%e t&pe in the e=port propert&.
55* max8edelivery# 7nly 9ueues
Internal Training Document
)he %a=/edeli,er& propert& speci"ies the nu%-er o" atte%pts the ser,er
should %a3e to redeli,er a %essage sent to a :ueue. )he ,alue o" this
para%eter can -e set to an integer -et2een 2 and 255. 4nce the ser,er
has atte%pted to deli,er the %essage the speci"ied nu%-er o" ti%es+ the
%essage is either destro&ed or it is placed on the undeli,ered :ueue+ i" the
JMSE)I5C4EP/*S*/K*E!ND*AIK*/*D propert& on the %essage is
set to true.
52* exclusive# 7nly )ueues
It de"ines ho2 the ser,er deli,ers %essages to :ueue consu%ers 2hen
%ultiple :ueue consu%ers are present. In e=clusi,e %ode+ the "irst :ueue
consu%er recei,es all o" the %essages until the consu%er "ails. At that
point+ %essages are deli,ered to the ne=t consu%er. )he "irst :ueue
consu%er is the "irst6acti,ated :ueue recei,er.
Cith non-exclusive 9ueues .e=clusi,e set to "alse0 the ser,er distri-utes
%essages in a round6ro-inLone to each recei,er that is read&. I" an&
recei,ers are still read& to accept additional %essages+ the ser,er
distri-utes another round o" %essagesLone to each recei,er that is still
read&. Chen none o" the recei,ers are read& to recei,e %ore %essages+
the ser,er 2aits until a :ueue recei,er reports that it can accept a
%essage. )his arrange%ent pre,ents a large -uildup o" %essages at one
recei,er and -alances the load o" inco%ing %essages across a set o"
:ueue recei,ers.
Internal Training Document
5(* pre!etch# 7nly )ueues
Deli,ering %essages "ro% the ser,er to a client progra% in,ol,es t2o
independent phasesL"etch and accept1
9 )he #etc7 phase is a t2o6step interaction -et2een a MessageConsu%er
o-<ect .in a client progra%0 and the ser,er.
L )he MessageConsu%er initiates the "etch phase -& signalling to
the ser,er that it is read& "or %ore %essages.
)he ser,er responds -& trans"erring one or %ore %essages to
the client+ 2hich stores the% in the MessageConsu%er o-<ect.
9 In the accept phase+ client code ta3es a %essage "ro% the
MessageConsu%er o-<ect.
)o reduce 2aiting ti%e "or client progra%s+ the MessageConsu%er can
pre#etc7 %essagesLthat is+ "etch a -atch o" %essages "ro% the ser,er+
and hold the% "or client code to accept+ one -& one. It can i%pro,e
per"or%ance -& decreasing or eli%inating client idle ti%e 2hile the ser,er
trans"ers a %essage.
Di""erent ,alues+
pre"etchJnone+ disa-le auto%atic pre"etching
pre"etchJ+ inherit "ro% the parent or set de"ault ,alue 2hich is 5
pre"etchJn+ pre"etch n nu%-er o" %essages "ro% ser,er
5-* expiration
)he ser,erDs e=piration propert& o,errides e=piration ,alues set -&
%essage producers .in client progra%s0. >ou can set this propert& "or an&
:ueue and an& topic.
I" this propert& is set "or a destination+ then 2hen the ser,er deli,ers a
%essage to that destination+ the ser,er replaces the producerDs e=piration
,alue 2ith this ,alue.
:ildcards $; and <%
)he 2ildcard H %eans that an& to3en can -e in the place o" H. #or e=a%ple1
!oo*; %atches all t2o6part destination na%es -eginning 2ith
"oo. including "oo.-ar and "oo.-oo+ -ut not "oo.-ar.-oo.
)he 2ildcard M %atches one or %ore trailing ele%ents. #or e=a%ple+ "oo.M
%atches "oo.-ar and "oo.-ar.-oo
:ildcards in &opics#
>ou can su-scri-e to 2ildcard topics.
>ou cannot pu-lish to 2ildcard topics.
Internal Training Document
I" "oo.-ar is not in the con"iguration "ile+ then &ou can pu-lish to
"oo.-ar i" "oo.H or "oo.M e=ists in the con"iguration "ile.
:ildcards in )ueues#
>ou can not send or recei,e to 2ildcard :ueue na%es. Fo2e,er+ &ou can use
2ildcard :ueue na%es in the con"iguration "iles.
#or e=a%ple+ i" the :ueue con"iguration "ile includes a line1
"oo.H then users can create :ueues "oo.-ar+ "oo.-o-+ and so "orth+ -ut not
"oo.-ar.-o-.
+ridges bet2een Destinations
>ou can create -ridges -et2een destinations so that %essages sent to one
destination are also deli,ered to all -ridged destinations. 5ridges are created
-et2een one destination and one or %ore other destinations o" the sa%e or o"
di""erent t&pes. )hat is+ &ou can create a -ridge "ro% a topic to a :ueue or "ro%
a :ueue to a topic.
47y Bridge destinations;
So%e applications re:uire the sa%e %essage to -e sent to %ore than one
destination+ possi-l& o" di""erent t&pes. #or e=a%ple+ an application %a& send
%essages to a :ueue "or distri-uted load -alancing. )hat sa%e application+
ho2e,er+ %a& also need the %essages to -e pu-lished to se,eral %onitoring
applications. Another e=a%ple is an application that pu-lishes %essages to
se,eral topics. All %essages ho2e,er+ %ust also -e sent to a data-ase "or
-ac3up and "or data %ining. A :ueue is used to collect all %essages and send
the% to the data-ase.
5ridges are not transitive and the& are uni-directional. )hat is+ i" there is a
-ridge -et2een A to 5+ then %essage sent to A can onl& "lo2 to 5 and not the
other 2a&. Si%ilarl&+ i" there is a -ridge -et2een destination A to 5 and another
-ridge -et2een destination 5 and C. )hen an& %essage sent to A 2ill "lo2 to 5
-ut not to C.
Selecting Messages# 5& de"ault+ all %essages sent to a destination 2ith
a -ridge are sent to all -ridged destinations. )his can cause
unnecessar& net2or3 tra""ic i" each -ridged destination is onl& interested
in a su-set o" the %essages sent to the original destination. >ou can
optionall& speci"& a %essage selector "or each -ridge to deter%ine 2hich
%essages are sent o,er that -ridge.
ccess Control# Message producers %ust ha,e access to a destination
in order to send %essages to that destination. Messages can onl& -e
sent to -ridged destinations to 2hich the %essage producer has access.
&ransactions# Chen a %essage producer sends a %essage 2ithin a
transaction+ all %essages sent across a -ridge are part o" the
transaction. )here"ore+ i" the transaction succeeds+ all %essages are
Internal Training Document
deli,ered to all -ridged destinations. I" the transaction "ails+ no
consu%ers "or -ridged destinations recei,e the %essages.
Internal Training Document
Chapter -- Messages in =MS
A JMS %essage has the sa%e structure+ regardless o" 2hether it is addressed
to a topic or a :ueue. A JMS %essage has three sections1
Feader .so%e header "ields are re:uired0
Properties .optional0
5od& .optional0
)he Feader has 1 pre6de"ined "ields1
Feader #ield Set 5& Co%%ents
JMSDestination send or pu-lish
%ethods
Destination to 2hich
%essage is sent
JMSDeli,er&Mode send or pu-lish
%ethod
Persistent or non6
persistent %essage
JMS*=piration send or pu-lish
%ethod
Aength o" ti%e that
%essage 2ill li,e -e"ore
e=piration. I" set to +
%essage does not e=pire.
)he ti%e6to6li,e is
speci"ied in %illiseconds.
Chene,er &our
application uses non67ero
,alues "or %essage
e=piration+ &ou %ust
ensure that cloc3s are
s&nchroni7ed a%ong all
the host co%puters that
send and recei,e
%essages. S&nchroni7e
cloc3s to a tolerance that
is a ,er& s%all "raction o"
the s%allest %essage
e=piration ti%e.
JMSPriorit& send or pu-lish
%ethod
!ses a nu%erical
ran3ing+ -et2een and
B+ to de"ine %essage
priorit& as nor%al or
e=pedited.
Aarger nu%-ers
represent higher priorit&.
JMSMessageID send or pu-lish
%ethod
Kalue uni:uel& identi"ies
each %essage sent -& a
pro,ider.
Internal Training Document
JMS)i%esta%p send or pu-lish
%ethod
)i%esta%p o" ti%e 2hen
%essage 2as handed o""
to a pro,ider to -e sent.
Message %a& actuall& -e
sent later than this
ti%esta%p.
JMSCorrelationID %essage client )his ID can -e used to
lin3 %essages+ such as
lin3ing a response
%essage to a re:uest
%essage.
*ntering a ,alue in this
"ield is optional
JMS/epl&)o %essage client A destination to 2hich a
%essage repl& should -e
sent. *ntering a ,alue "or
this "ield is optional.
JMS)&pe %essage client %essage t&pe identi"ier
JMS/edeli,ered JMS pro,ider I" this "ield is set+ it is
possi-le that the
%essage
2as deli,ered to the
client earlier+ -ut not
ac3no2ledged at that
ti%e
Message Persistence
JMS de"ines t2o %essage deli,er& %odes+ persistent and non6persistent. )his
%ode is set -& the %essage sender or pu-lisher in the JMSDeli,er&Mode
%essage header "ield. Non6Persistent %essages are ne,er 2ritten to persistent
storage. Persistent %essages are logged to persistent storage 2hen the& are
sent. Messages 2ith the persistent deli,er& %ode are al2a&s 2ritten to persistent
storage+ e=cept 2hen the& are pu-lished to a topic that has no dura-le
su-scri-ers. Chen a topic has no dura-le su-scri-ers+ there are no su-scri-ers
that need %essages resent in the e,ent o" a ser,er "ailure. )here"ore+ %essages
do not need to -e sa,ed+ and per"or%ance is i%pro,ed -ecause dis3 IG4 is not
re:uired.
Message c>no2ledgement
)here are 3 le,els o" ac3no2ledge%ents1
D!PSE4IEACIN4CA*DN*+ "or consu%ers that are tolerant o" duplicate
%essages.
Internal Training Document
A!)4EACIN4CA*DN*+ in 2hich the session auto%aticall&
ac3no2ledges a clientDs receipt o" a %essage.
CAI*N)EACIN4CA*DN*+ in 2hich the client ac3no2ledges the
%essage -& calling the %essageDs ac3no2ledging %ethod.
)he "ollo2ing descri-es the steps in %essage deli,er& and ac3no2ledge%ent1
1. A %essage is sent "ro% the %essage producer to the %achine on
2hich the )I5C4 *nterprise Message Ser,ice ser,er resides.
2. )he *MS ser,er ac3no2ledges that the %essage 2as recei,ed.
3. )he ser,er sends the %essage to the consu%er.
4. )he consu%er sends ac3no2ledge%ent to the ser,er that the
%essage 2as recei,ed.
5. In %an& cases+ the ser,er then con"ir%s ac3no2ledge%ent to the
consu%er. Ac3no2ledge%ent "ro% the consu%er to the ser,er
pre,ents the deli,er& o" duplicate %essages.
?ndelivered Message )ueue
I" a %essage is to -e re%o,ed "ro% the s&ste% in an& 2a& -esides -eing
properl& consu%ed -& a %essage consu%er+ the ser,er chec3s the %essage "or
the JMSE)I5C4EP/*S*/K*E!ND*AIK*/*D propert&.
Chen JMSE)I5C4EP/*S*/K*E!ND*AIK*/*D is set to true+ the ser,er
%o,es the %essage to the undeli,ered %essage :ueue+ Os&s.undeli,ered*
)his undeli,ered %essage :ueue is a s&ste% :ueue that is al2a&s present and
can not -e deleted.
EMS Message Delivery Mode Extensions
)I5C4 *nterprise Message Ser,ice introduces t2o t&pes o" %essage deli,er&
2hich are e=tensions to the JMS speci"ication.
JMS deli,er& re:uire%ents ensure the deli,er& o" all %essages in al%ost all
circu%stances. Fo2e,er this re:uire%ents leads to a lot o" o,erheads in the
sense o" net2or3 tra""ic .%essage and a return %essage con"ir%ing the receipt o"
the %essage0 and the %e%or& allocated "or each persistent %essage and
dura-le su-scri-er.
#or higher throughput+ *MS has co%e up 2ith 2 2a&s o" reducing the a-o,e
o,erheads1
/elia-le Message Deli,er&
No6Ac3no2ledge%ent Deli,er& receipt
8eliable Message Delivery1
JMS has P*/SIS)*N) and N4NEP*/SIS)*N) deli,er& %odes "or -oth topic
and :ueue. In addition to these %odes+ &ou can use
)i-<%s./*AIA5A*ED*AIK*/> %ode "ro% )I5C4 *nterprise Message Ser,ice.
P*/SIS)*N) and N4NEP*/SIS)*N) deli,er& re:uire the ser,er to return a
s&ste% %essage to the client application to ensure proper handling o" %essages.
Internal Training Document
In relia-le deli,er& %ode+ the client application does not 2ait "or this s&ste%
%essage. )hus+ relia-le %ode decreases the ,olu%e o" %essage tra""ic+ allo2ing
-etter usage o" s&ste% resources+ and higher %essage rates.
@o-c>no2ledgement Message 8eceipt
In no6ac3no2ledge receipt %ode+ a"ter the ser,er sends a %essage to the client+
all in"or%ation regarding that %essage "or that consu%er is eli%inated "ro% the
ser,er. )here"ore+ there is no need "or the client application to send an
ac3no2ledge%ent to the ser,er a-out the recei,ed %essage. Not sending
ac3no2ledge%ents decreases the %essage tra""ic and sa,es ti%e "or the
recei,er+ there"ore allo2ing -etter utili7ation o" s&ste% resources.
Important#
Sessions created in no6ac3no2ledge receipt %ode cannot -e used to
create dura-le su-scri-ers.
Also+ :ueue recei,ers on a :ueue that is routed "ro% another ser,er are
not per%itted to speci"& N4EACIN4CA*DN* %ode.
Internal Training Document
Chapter .# ?sing the con!iguration Files
)he con"iguration "iles contain in"or%ation a-out the ,arious *MS o-<ects li3e
:ueues+ topics+ users+ -ridges etc. )hese "iles are located in
)I5C4EF4M*Ge%sG-in director&. )hese "iles can -e edited either directl& using a
te=tpad or using the co%%and line -ased ad%inistration tool. )he ad%inistration
tool 2ill e,entuall& readG2rite toG"ro% these con"iguration "iles. #ollo2ing are the
con"iguration "iles that are a,aila-le in *MS ser,er.
ti-e%sd.con" )his is the %ain con"iguration "ile. It has
properties that are concerned 2ith the
*MS ser,er
:ueues.con" @ueue con"iguration
topics.con" )opics con"iguration
users.con" All users con"iguration
acl.con" Per%ission settings "or users on
destinations
routes.con" /outes con"iguration
-ridges.con" 5ridges con"iguration
"actories.con" Connection #actories con"iguration
transports.con"
groups.con"
dura-les.con"
Please go through the corresponding chapter in the =MS documentation
!or !urther detailed in!ormation
Chapter 0# ?sing the dministration &ool
)he ad%inistration tool is located in &our PinstallationEpathM G-in director& and is
a stand6alone e=ecuta-le na%ed ti-e%sad%in on !ni= and ti-e%sad%in.e=e on
Cindo2s plat"or%s. )&pe ti-e%sad%in 6help to displa& in"or%ation a-out
ti-e%sad%in startup para%eters. All ti-e%sad%in para%eters are optional.
Please go through the corresponding chapter in the =MS documentation
!or !urther detailed in!ormation
Internal Training Document
Chapter 1# uthentication and Permissions
)I5C4 *nterprise Message Ser,ice allo2s &ou to control access to the ser,er -&
creating users and assigning pass2ords+ creating groups+ setting per%issions
etc. )he ser,er can also authenticate users de"ined in an e=ternal director& .such
as an ADAP ser,er0
Per%issions "or all users and groups %ust -e de"ined in the access control list "or
the )I5C4 *nterprise Message Ser,ice ser,er. )here are also ad%inistrator
per%issions that allo2 ad%inistrators to control 2hich actions users can per"or%
on the ser,er such as create destinations+ %odi"& users+ and ,ie2 routes.
Ad%inistrator per%issions can appl& glo-all&+ or the& can -e granted on speci"ic
destinations.
Enabling ccess Control
)here are t2o le,els 2here authori7ation is set.
Server1 )he authori7ation propert& in the %ain con"iguration "ile ena-les or
disa-les the chec3ing o" per%issions "or all destinations %anaged -& the ser,er.
)he authori7ation propert& also ena-les or disa-les ,eri"ication o" user na%es
and pass2ords.
)o ena-le authori7ation+ edit the ti-e%sd.con" "ile1
aut7ori8ation ) ena:led
#ro% the co%%and line ad%in utilit&1
set server aut7ori8ation ) ena:led
I" this is not set+ then the ser,er allo2s an& client connection and no per%issions
are chec3ed on an& destination. *na-ling authori7ation i%%ediatel& applies to
e=isting client connections .e=cept route connections0. )he ser,er -egins
chec3ing per%issions.

Destination# )he secure propert& o" the destinations is used to allo2 the ser,er
to chec3 per%issions o" a client connection "or that particular destination 2hen a
user atte%pts to per"or% an& operation on that destination
Setting Permissions
Per%issions are stored in the access control list and deter%ine the actions a user
can per"or% on a destination. Per%issions can onl& -e granted -& users that
ha,e the appropriate ad%inistrator per%issions.
6ueue !ermissions1
Internal Training Document
send
recei,e
-ro2se
Topic !ermissions
su-scri-e
pu-lish
dura-le
useEdura-le
*g1 I" in acl.con" &ou see1
!S*/J-o- )4PICJ"oo P*/MJpu-lish+ su-scri-e
)his set o" per%issions %eans that -o- can su-scri-e to topic "oo and pu-lish
%essages to it+ -ut -o- cannot create dura-le su-scri-ers to "oo.
I" -o- is a %e%-er o" group engineering and the group has the "ollo2ing entr& in
the acl "ile1
N/4!PJengineering )4PICJ-ar P*/MJsu-scri-e+pu-lish
)hen -o- can pu-lish and su-scri-e to topics "oo and -ar.
Please go through the corresponding chapter in the =MS documentation
!or !urther detailed in!ormation
Internal Training Document
Chapter 3# Fault &olerance
>ou can arrange )I5C4 *nterprise Message Ser,ice ser,ers "or "ault6tolerant
operation -& con"iguring a pair o" ser,ersLone pri%ar& and one -ac3up. )he
pri%ar& ser,er accepts client connections+ and interacts 2ith clients to deli,er
%essages. I" the pri%ar& ser,er "ails+ the -ac3up ser,er resu%es operation in its
place. .*MS does not support %ore than t2o ser,ers in a "ault6tolerant
con"iguration.0
Shared State# A pair o" "ault6tolerant ser,ers %ust ha,e access to shared state+
2hich consists o" in"or%ation a-out client connections and persistent %essages.
)his in"or%ation ena-les the -ac3up ser,er to properl& assu%e responsi-ilit& "or
those connections and %essages.
Ser,er state includes 3 categories o" in"or%ation1
Persistent %essages
Client connections o" the pri%ar& ser,er
Metadata a-out %essage deli,er& .stored in the %eta.d- "ile0
Persistent %essages are stored in 2 "iles1 as&nc6%sgs.d- "ile+ 2hich contains all
the %essages stored under nor%al %ode+ and s&nc6%sgs.d- "ile that contains all
%essages that are "or "ailsa"e destinations
'oc>ing# )o pre,ent the -ac3up ser,er "ro% assu%ing the role o" the pri%ar&
ser,er+ the pri%ar& ser,er loc3s the shared state during nor%al operation. I" the
pri%ar& ser,er "ails+ the loc3 is released+ and the -ac3up ser,er can o-tain the
loc3.
Failover
Step 1
A -ac3up ser,er detects a "ailure o" the pri%ar& in either o" t2o 2a&s1
9 9eart:eat FailureLthe pri%ar& ser,er sends heart-eat %essages to the -ac3up
ser,er to indicate that it is still operating. Chen a net2or3 "ailure stops the
ser,ers "ro% co%%unicating 2ith each other+ the -ac3up ser,er detects the
interruption in the stead& strea% o" heart-eats.
9 Connection FailureLthe -ac3up ser,er can detect the "ailure o" its )CP
connection 2ith the pri%ar& ser,er. Chen the pri%ar& process ter%inates
une=pectedl&+ the -ac3up ser,er detects the -ro3en connection.
Step2
Chen a -ac3up ser,er .50 detects the "ailure o" the pri%ar& ser,er .A0+ then 5
atte%pts to assu%e the role o" pri%ar& ser,er. #irst+ 5 o-tains the loc3 on the
current shared state. Chen 5 can access this in"or%ation+ it -eco%es the ne2
pri%ar& ser,er.
I" 5 cannot o-tain the loc3 i%%ediatel&+ it alternates -et2een atte%pting to
o-tain the loc3 .and -eco%e the pri%ar& ser,er0+ and atte%pting to
Internal Training Document
reconnect to A .and resu%e as a -ac3up ser,er0Luntil one o" these
atte%pts succeeds.
Chen ser,er A co%es -ac3 again+ it -eco%es a -ac3up ser,er and ser,er
5 continues to -e the pri%ar&.
Clients o" A that are con"igured to "ailo,er to -ac3up ser,er 5 auto%aticall&
trans"er to 5 2hen it -eco%es the ne2 pri%ar& ser,er.
Step 31
A"ter a "ailure+ %essage redeli,er& is atte%pted -ased on the t&pe o" %essages
and destination con"iguration
!ersistent1 Chen a "ailure occurs+ %essages 2ith deli,er& %ode
P*/SIS)*N)+ that 2ere not success"ull& ac3no2ledged -e"ore the "ailure+
are redeli,ered.
Failsa#e1 *MS guarantees that a %essage 2ith P*/SIS)*N) deli,er&
%ode and a "ailsa"e destination 2ill not -e lost during a "ailure.
An& %essages that ha,e -een success"ull& ac3no2ledged or co%%itted
are not redeli,ered+ in co%pliance 2ith the JMS 1.1 speci"ication.
All topic su-scri-ers continue nor%al operation a"ter a "ailo,er.
@ueues1 #or :ueue recei,ers+ an& %essages that ha,e -een sent to
recei,ers+ -ut ha,e not -een ac3no2ledged -e"ore the "ailo,er+ %a& -e
sent to other recei,ers i%%ediatel& a"ter the "ailo,er. A recei,er tr&ing to
ac3no2ledge a %essage a"ter a "ailo,er %a& recei,e the
<a,a=.<%s.IllegalState*=ception. )his e=ception signi"ies that the
atte%pted ac3no2ledge%ent is "or a %essage that has alread& -een sent
to another :ueue recei,er.
A"ter a "ailo,er+ atte%pting to co%%it the acti,e transaction results in a
<a,a=.<%s.)ransaction/olled5ac3*=ception. Clients that use transactions
%ust handle this e=ception+ and resend an& %essages sent during the
transaction.
Aeartbeat Parameters
Chen the pri%ar& ser,er heart-eat stops+ the -ac3up ser,er 2aits "or its
acti,ation inter,al .elapsed ti%e since it detected the %ost recent heart-eat0;
then the -ac3up ser,er retrie,es in"or%ation "ro% shared storage and assu%es
the role o" pri%ar& ser,er.
)he de"ault heart-eat inter,al is 3 seconds+ and the de"ault acti,ation inter,al is
1 seconds. )he acti,ation inter,al %ust -e at least t2ice the heart-eat inter,al.
5oth inter,als are speci"ied in seconds. >ou can set these inter,als using the
ad%inistration tool or in the ser,er con"iguration "iles.
Con!iguring the Fault &olerant Servers
)o con"igure an *MS ser,er as a "ault6tolerant -ac3up+ set these para%eters in
its %ain con"iguration "ile .or on the ser,er co%%and line01
Internal Training Document
9 server Set this para%eter to the sa%e ser,er na%e in the con"iguration "iles o"
-oth the pri%ar& ser,er and the -ac3up ser,er.
9 !t/active In the con"iguration "ile o" the pri%ar& ser,er+ set this
para%eter to the !/A o" the -ac3up ser,er. In the con"iguration "ile o" the-ac3up
ser,er+ set this para%eter to the !/A o" the pri%ar& ser,er.
Chen the -ac3up ser,er starts+ it atte%pts to connect to the pri%ar& ser,er. I" it
esta-lishes a connection to the pri%ar&+ then the -ac3up ser,er enters stand-&
%ode. I" it cannot esta-lish a connection to the pri%ar&+ then the -ac3up ser,er
assu%es the role o" the pri%ar& ser,er .in acti,e %ode0. Chile the -ac3up ser,er
is in stand-& %ode+ it does not accept connections "ro% clients. )o ad%inister the
-ac3up ser,er+ the ad%in user can connect to it using the ad%inistration tool.
Chen a -ac3up ser,er assu%es the role o" the pri%ar& ser,er during "ailo,er+
clients atte%pt to reconnect to the -ac3up ser,er .that is+ the ne2 pri%ar&0 and
continue processing their current %essage state. As each client reconnects+ the
-ac3up ser,er reads its %essage state "ro% the shared state "iles. >ou can
instruct the ser,er to clean up state in"or%ation "or clients that do not reconnect
-e"ore a speci"ied ti%e li%it.
)he !t/reconnect/timeout con"iguration para%eter speci"ies that ti%e li%it .in
seconds0. )he de"ault ,alue is $ seconds
Con!iguring Clients !or Fault &olerance
)o ena-le a client to reconnect+ &ou %ust speci"& the !/As o" -oth ser,ers.
Speci"& %ultiple ser,ers as a co%%a6separated list o" !/As. 5oth !/As %ust
use the sa%e protocol .either tcp or ssl0.
In the "ollo2ing e=a%ples+ the "irst ser,er is tcp1GGser,er1'222+ and the second
ser,er is tcp1GGser,er11'344 .i" "irst ser,er is not a,aila-le0.