Habari Active MQ Getting Started

Getting started with
Habari Client for

ActiveMQ
Version 3.7
Trademarks
Habari is a registered trademark of Michael Justin and is protected by the laws of Germany and other
countries. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Embarcadero the
Embarcadero !echnologies logos and all other Embarcadero !echnologies product or service names are
trademarks service marks and/or registered trademarks of Embarcadero !echnologies "nc. and are pro#
tected by the laws of the $nited %tates and other countries. Microsoft &indows &indows '! and/or
other Microsoft products referenced herein are either registered trademarks or trademarks of Microsoft
(orporation in the $nited %tates and/or other countries. Other brands and their products are trademarks
of their respective holders.
2 Habari Client for ActiveMQ 3.7
Contents
Introduction..........................................................................................5
About Habari Client Libraries............................................................................5
How can I use Habari Client for ActiveMQ?.......................................................5
Wat!s new in version ".#?...................................................................$
%ew.................................................................................................................. $
Can&ed......................................................................................................... '(
)i*ed.............................................................................................................. '(
+roker s,ecific can&es..................................................................................''
Installation.........................................................................................'-
.e/uirements.................................................................................................'-
TC01I0 Communication Libraries....................................................................'-
2tartin& ActiveMQ...............................................................................'"
.unnin& te +roker........................................................................................'"
Monitorin& ActiveMQ......................................................................................'3
2to,,in& ActiveMQ.........................................................................................'3
Communication Ada,ters....................................................................'5
Introduction................................................................................................... '5
Te 0ro&rammin& Model.....................................................................'$
Connections and 2essions...................................................................'4
2te,5b652te, 7*am,le....................................................................................'4
2ession t6,es overview..................................................................................-'
Connection 8.L ,arameters...........................................................................--
Transacted 2essions.......................................................................................-3
)ailover 2u,,ort.............................................................................................-9
0ooled Connection )actor6.............................................................................-#
:estinations........................................................................................-4
Introduction................................................................................................... -4
Create a new :estination...............................................................................-4
:estination ;,tions........................................................................................"(
0roducer and Consumer......................................................................"-
Messa&e 0roducer.........................................................................................."-
Messa&e Consumer........................................................................................."-
<M2 2electors................................................................................................. ""
8sin& =0at to filter messa&es.......................................................................""
Te*t Messa&es....................................................................................."5
2endin& a Te*tMessa&e.................................................................................."5
.eceive Te*t Messa&es..................................................................................."5
+inar6 Messa&es................................................................................."$
2end +inar6 Messa&es...................................................................................."$
;b>ect Messa&es................................................................................."4
Introduction................................................................................................... "4
3
Messa&e Transformers in Habari Client for ActiveMQ......................................3'
Code 7*am,les............................................................................................... 3'
Ma, Messa&es.....................................................................................35
Introduction................................................................................................... 35
:urable 2ubscri,tions.........................................................................3#
:escri,tion..................................................................................................... 3#
?irtual :estinations........................................................................................3$
2tom, '.'............................................................................................34
Connection Confi&uration...............................................................................34
2endHeartbart@ sendin& client5side eartbeat si&nals....................................5(
CeckHeartbeat@ ceckin& for server5side eartbeats....................................5'
.eceiveHeartbeat@ readin& server5side eartbeats.........................................5'
7*am,le A,,lications..........................................................................5-
+roker5inde,endent e*am,le ,ro>ects............................................................5"
+roker5s,ecific ,re,aration............................................................................5"
2ared units for demo ,ro>ects......................................................................5"
22L communication ada,ter units...................................................................5"
ConsumerTool................................................................................................ 53
0roducerTool..................................................................................................59
0erformance Test...........................................................................................5$
Trou&,ut Test Tool.....................................................................................9(
+roker 2,ecific :emos........................................................................9-
+roker 2tatistics 7*am,le...............................................................................9"
:ela6 and 2cedule Messa&e :eliver6............................................................95
Messa&e ;,tions.................................................................................99
<M2 2tandard 0ro,erties................................................................................99
8ser :efined 0ro,erties..................................................................................9#
Tem,orar6 Queues..............................................................................94
Introduction................................................................................................... 94
How sould I im,lement re/uest res,onse wit <M2?....................................94
Lo&&in& wit Lo&3:............................................................................#(
Introduction................................................................................................... #(
I:7 confi&uration...........................................................................................#(
Minimal e*am,le............................................................................................ #(
Lo&3: confi&uration file.................................................................................#(
0atces for new :el,i versions and )ree 0ascal...........................................#-
Conditional 26mbols............................................................................#3
HA+A.IAL;BBI%B..........................................................................................#3
HA+A.IA.AWAT.AC7.....................................................................................#3
Librar6 Limitations..............................................................................#5
2ession........................................................................................................... #5
Messa&eConsumer..........................................................................................#5
Messa&e 0ro,erties........................................................................................#5
Multi Treadin&.............................................................................................. #9
I2A0I modules............................................................................................... #9
+roker5s,ecific limitations..................................................................##
:efault 0riorit6...............................................................................................##
;nline .esources................................................................................#$
Tird50art6 Libraries......................................................................................#$
2,ecifications................................................................................................. #4
;nline Articles................................................................................................#4
;nline ?ideos................................................................................................. $(
2u,,ort...............................................................................................$'
+u& re,orts.................................................................................................... $'
2u,,ort in/uiries............................................................................................$'
Inde*..................................................................................................$-
Introduction 5
Introduction
About Habari Client Libraries
&ith Habari (lient libraries )elphi and *ree +ascal developers can take advantage of
message broker technology which is distributedC loosel6 cou,ledC reliable and
as6ncronous and build integrated systems connecting clients using the peer,to,peer
or the publish and subscribe communication model. )elphi and *ree +ascal applications -
including multi,threaded servers services "%.+" and stand,alone web applications - can
communicate at high speed e/changing up to thousands of messages per second.
%ince 0112 Habari (lient libraries provide access to standards5based enterprise 3uality
messaging solutions. %upported message brokers now include .pache .ctiveM4 .pollo
Hornet4 Open M4 and 5abbitM4. !hese open source message brokers also support
clients for other languages and protocols which is a key to integration of cross,language /
cross,platform systems with )elphi and *ree +ascal applications.
6ast but not least Habari (lient libraries can also be used for integration with Java7 EE
application servers such as !omEE Geronimo Glass*ish J8oss / &ild*ly and &eb6ogic
which have been tested with open source message brokers or use them as their default
messaging service implementation.
How can I use Habari Client for ActiveMQ?
Here are some e/amples for software solutions built on top of a message broker9
Client notification in multi5tiered a,,lications@ middle tier applications can use
publish/subscribe channels to let clients 3uickly know when there is new data :see
*irebird )atabase Events and Message,oriented Middleware;
Load balancin&9 using the point,to,point or 3ueueing model many <workers< can
run and every new message sent to the 3ueue will be delivered only to one client
Inter,rocess Communication9 applications can use point,to,point messages to
e/change information even if the receiver currently is not running
Lo&&in&9 cross,language applications can send log messages to a centrali=ed
logging infrastructure
Internet a,,lication inte&ration@ "%.+" +H+ or Java7 based web applications
can use message brokers to improve reaction times and connect to )elphi and *ree
+ascal back,end systems
7*am,le illustrations
0eer to ,eer and ,ublis1subscribe communication
!his illustration shows different )elphi applications running in a local network using
Habari (lient libraries to implement Inter,rocess communication9 applications use
point,to,point messages to e/change information between each other even if the receiver
currently is not running.
$sing the ,ublis1subscribe communication model news can be delivered to all
registered client applications. !he message sender works like a broadcast station and
does not care if clients don<t listen.
2ared business lo&ic 1 cross5lan&ua&e communication
)elphi and *ree +ascal applications can use Habari (lient libraries to provide central
business logic to other processes written in other languages and running on other
platforms.
Workstation 1
Application A
Application A
Messaging Infrastructure
Messaging Infrastructure
Application B
Application B
Workstation 2
Application A
Application A
Application B
Application B
Introduction 7
"n this illustration the business logic is implemented in a )elphi application working in the
<middle tier< of a multitier arcitecture. "nstead of talking to the middle tier application
directly all client applications use the message broker to implement a loosel65cou,led
s6stem. !he result is a fle/ible system where many aspects of the middle tier service can
be redesigned without affecting clients.
(lient applications also can send messages to the middle tier even if the destination
services currently are not running. !he message broker takes care of message delivery
when the application is back online.
!emporary 4ueues
>
can be used to implement .emote 0rocedure Call D.0CE,style
message e/change using a re3uest/reply communication pattern.
Load balancin&
$sing the 3ueuing model many <worker< applications can be installed on different
computers. Every new message sent to the messa&e /ueue will be delivered only to one
client. !he message broker will keep messages until they are e/pired or delivered to a
client.
> Only on message brokers with support for temporary destinations :see feature matri/;
Wat!s new in version ".#?
%ew
Transaction su,,ort for messa&e recei,t acknowled&ement
!ransactional sending of messages was already supported in all versions of Habari (lient
libraries.
%ome library versions
0
now also support transactions for the acknowledgement of received
messages.
&hen a transaction is rolled back or the connection is closed without a commit messages
which have been acknowledged after the transaction start will return to unacknowledged
state.
(ode e/ample9
// receive in a transacted session
Session := Connection.CreateSession(True, amClientAcknowledge);
Queue := Session.CreateQueue(etQueue!ame);
Consumer := Session.CreateConsumer(Queue);
"sg := Consumer.#eceive($%%%);
// &rocess t'e message
...
// acknowledge t'e message
"sg.Acknowledge;
...
// in case o( errors, roll )ack all acknowledgments
Session.#oll)ack;
!his is an e/perimental feature. "t re3uires usage of the %!OM+ >.0 communication
protocol.
0 !ested with .pache .ctiveM4 ?.@.1 .pollo >.A and 5abbitM4 B.0.0
What! ne" in ver!ion 3.7# $
)0C8nit tests
*+($nit tests can be found in common-tests-fpc.
7*am,le code for te Fwild5cardG destination feature
%ome message brokers support wild,cards in destination names :for e/ample CDE or CFE;
for subscriptions. !his feature is not standardi=ed so every message broker uses its own
wild,card specification.
*or the .ctiveM4 message broker it is documented at
http9//activem3.apache.org/wildcards.html.
'ew tests have been added to the )$nit proGect common-tests/Unittests9
wild,card 3ueue subscriptions :using the CDE wild,card;
wild,card topic subscriptions :using the CDE wild,card;
!he tests are contained in unit WildcardTests.
!he proGect enables these tests only for supported brokers.
%& Habari Client for ActiveMQ 3.7
Can&ed
8nit tests &rou,ed into cate&ories
$nit tests now have top,level categories9 off,line tests :which run without a broker; and
on,line tests :which run only when the local message broker is running;.
Im,roved error andlin&
)etailed logging has been added for frames which start with an invalid command header
byte in 8!%tomp)ecoder.(reate*rame :bug id @A@;.
)i*ed
Com,iler errors wit )ree 0ascal -.#.'
!he trunk version of the *ree +ascal 0.H.> compiler reports errors in I"* e/pressions. :bug
id @BJ;
.e,lace ard T+6tesDE casts wit To+6tes function
$se function BTTypes.ToBytes instead of hard type casts :bug id @B1;
Autentication wit em,t6 credentials values fails
%!OM+ headers CloginE and CpasscodeE will not be sent if the user name is empty. :bug id
@0@;
2u,,ort for encoded carria&e return DFHrGE in 2T;M0 '.-
eaders
!he %!OM+ >.0 specification allows encoded carriage return :CKrE; characters in header
values they are now supported in Habari (lient libraries. :bug id @0A;
Te AddConsumer metod was called twice for new
consumers
!he unnecessary calls have been removed. :bug id @0>;
What! ne" in ver!ion 3.7# %%
2u,,ort for e/ual si&ns and colons in 2T;M0 eaders
!he %!OM+ specification allows e3ual signs and escaped colons in header values they are
now supported in Habari (lient libraries. :bug id @>2;
2u,,ort for em,t6 2T;M0 eader values
!he %!OM+ specification allows empty header values
B
they are now supported in Habari
(lient libraries. :bug id @>H;
+roker s,ecific can&es
)i*ed bu&s
Habari,@AA E/change destination support inconsistency :5abbitM4;
Habari,@B> !est%erver(loses(onnection fails :Open M4;
Habari,@>@ .pp crash when 6ogJ) is enabled :.pollo;
Habari,ABH !ests for wild,card destinations have been added - see unit
C&ildcard!estsE in common,tests :.ctiveM4 .ctiveM4
OpenM4 and 5abbitM4;
B http9//stomp.github.io/stomp,specification,>.0.htmlL.ugmentedM8'*
%2 Habari Client for ActiveMQ 3.7
Installation
.e/uirements
:evelo,ment 7nvironment
7mbarcadero :el,i 011@ $pdate J or higher
)ree 0ascal 0.A.1 or higher
TC01I0 Communication Libraries
2u,,orted libraries
Internet :irect DInd6E '(.9
!he communication adapter for "ndy supports both G$",based and console mode
applications and works with )elphi 011@ and higher and *ree +ascal 0.A.1 or higher.
26na,se .elease 3(
!he communication adapter for %ynapse supports both G$",based and console mode
applications and works with )elphi 011@ and higher and *ree +ascal 0.A.1 or higher.
'tartin( ActiveMQ %3
2tartin& ActiveMQ
.unnin& te +roker
!hese commands will launch the broker9
cd \apache-activemq-5.9.0\bin
activemq-admin.bat start

Illu!tration %) ActiveMQ 5.$.& runnin(
Monitorin& ActiveMQ
!here are various ways to monitor .ctiveM4. "n the demo configuration you can monitor
.ctiveM4 using the &eb (onsole at http9//localhost92>A>/admin
2to,,in& ActiveMQ
*or both &indows and $ni/ installations terminate .ctiveM4 by typing N(!56,(N in the
console or command shell in which it is running. "n newer releases of the broker you can
also use the activem3,admin script in the bin directory9
cd \apache-activemq-5.9.0\bin
activemq-admin.bat stop
Co**unication Ada+ter! %5
Communication Ada,ters
Introduction
Habari (lient for .ctiveM4 uses communication adapters as an abstraction layer for the
!(+/"+ library. .ll connections create their own internal instances of the adapter class.
Confi&uration of communication ada,ters
'o configuration is re3uired for the communication adapters. .pplications specify
communication and connection options in $56 parameters or connection class properties
or connection factory settings.
.e&istration of communication ada,ter class
. communication adapter implementation can be prepared for usage by simply adding its
)elphi unit to the proGect. E/ample9
program ClientUsingIndy;
uses
BTCommAdapterIndy, // use Internet Direct (Indy)
BTJMConnection!actory, BTJMInter"aces,
ysUtils;
###
8ehind the scenes the communication adapter class will register itself with the
communication adapter manager in the 8!.dapter5egistry unit.
:efault ada,ter class
.pplications typically use only one of the available communication adapter classes for all
connections.
!he library allows to register two or more adapter classes and switch at run,time using
methods in the adapter registry in unit 8!.dapter5egistry , this feature is mainly for
tests and demonstration purposes.
"f more than one communication adapter is in the proGect the first adapter class in the
list will be the default adapter class. E/ample9
program ClientUsingIndy$rynapse;
uses
BTCommAdapterIndy, // use Internet Direct (Indy) as de"ault adapter class
BTCommAdapterynapse, // and register t%e ynapse adapter class
BTJMConnection!actory, BTJMInter"aces,
ysUtils;
###
!he default adapter class can be changed at run,time by setting the adapter class either
by its name or by its class type.
Available communication ada,ters
!he library includes two adapter classes for !(+/"+ libraries one for "ndy :"nternet )irect;
and one for %ynapse.
Ada,ter Class 8nit
!8!(omm.dapter"ndy 8!(omm.dapter"ndy
!8!(omm.dapter%ynapse 8!(omm.dapter%ynapse
,able %) Co**unication Ada+ter!
Wic communication ada,ter class sould I use?
!he "nternet )irect :"ndy; communication adapter class is recommended.
Limitations of te 26na,se communication ada,ter class
!he %ynapse library does not support the (onnect!imeout property in synchronous
socket operation mode as connect timeouts are handled by the operating system.
"ndy uses a background thread to abort the connect operation.
J
5elease J1 of .rarat %ynapse is used for Habari (lient library development and
tests. !his is the last announced release dated .pril 0J 01>0. "f you use a newer
release of .rarat %ynapse please let me know if you encounter any .+"
incompatibilities or other problems.
22L communication ada,ter classes
!he library also includes two e/perimental adapter classes for usage with Open%%6 one
for "ndy :"nternet )irect; and one for %ynapse. %upport for these adapter classes is not
included in the basic support package. !he units for these classes are in the common,ssl
folders. . demo application is included in common,producertool,ssl.
J http9//www.ararat.c=/synapse/doku.php/public9howto9connecttimeout
Co**unication Ada+ter! %7
Ada,ter Class 8nit
!8!(omm.dapter"ndy%%6 8!(omm.dapter"ndy%%6
!8!(omm.dapter%ynapse%%6 8!(omm.dapter%ynapse%%6
,able 2) Co**unication Ada+ter! "ith ''- 'u++ort
Te 0ro&rammin& Model
Habari (lient libraries use a programming model which is based on message producers
and message consumers sessions connections and connection factories.
!he basic .+" is the same for all library versions to allow easy migration between
supported message brokers :with the e/ception of broker,specific features;.
Illu!tration 2) .ro(ra**in( Model
Connection
Factory
Session
Message
Consumer
Message
Producer
Destination Destination
Msg
Creates
Creates
Creates Creates
Sends to Creates Receives from
Connection
Connection! and 'e!!ion! %$
Connections and 2essions
2te,5b652te, 7*am,le
;verview
!his e/ample will send a single message to a destination 3ueue :E/ample4ueue;.
?
Add re/uired units
!hree units are re3uired for this e/ample
a communication adapter unit :e. g. 8!(omm.dapter"ndy;
a connection factory unit :8!JM%(onnection*actory or 8!JM%(onnection;
the unit containing the interface declarations :8!JM%"nterfaces;
!he %ys$tils unit is necessary for the e/ception handling.
program end$neMessage;
&'A((T)(* C$+$,*-
uses
BTCommAdapterIndy,
BTJMConnection!actory,
BTJMInter"aces,
ysUtils;
###
Creatin& a new Connection
!o create a new connection
declare a variable of type "(onnection
use the helper method Make(onnection of the !8!JM%(onnection class to create
and configure a new connection with user name password and the broker $56
or
use an instance of !8!JM%(onnection*actory to create connections
%ince "(onnection is an interface type the connection instance will be destroyed
automatically if there are no more references to it in the program.
? (ompatibility note9 non,e/isting 3ueues are created automatically by the broker , with the
e/ception of Hornet4 which re3uires them to be configured before usage
2& Habari Client for ActiveMQ 3.7
)irst alternative@ usin& T+T<M2Connection
.ar
Connection/ IConnection;
ession/ Iession;
Destination/ IDestination;
(roducer/ IMessage(roducer;
0egin
Connection /1 TBTJMConnection#Ma2eConnection(33, 33, 3stomp///local%ost3);
Connection#tart;
2econd alternative@ usin& T+T<M2Connection)actor6
.ar
!actory/ IConnection!actory;
###
0egin
!actory /1 TBTJMConnection!actory#Create(3user3, 3pass4ord3, 3stomp///local%ost3);
Connection /1 !actory#CreateConnection;
###
Local Connection
"f you Gust need a connection to the broker on the local computer using default port
number and login credentials you can call Make(onnection without parameters9
Connection /1 TBTJMConnection#Ma2eConnection;
Connection 8.L 0arameters
(onnection $56 parameters are documented in chapter N(onnection $56 parametersN and
in chapter N%!OM+ >.>N.
Creatin& a 2ession
!o create the communication session
declare a variable of type *Session
use the helper method CreateSession of the connection and specify the
acknowledgment mode
+lease check the .+" documentation for the different session types and acknowledgement
modes.
%ince *Session is an interface type the session instance will be destroyed automatically if
there are no more references to it in the program.
Connection! and 'e!!ion! 2%
ession /1 Connection#Createession(!alse, amAutoAc2no4ledge);
8sin& te 2ession
!he %ession variable is ready to use now. )estinations producers and consumers will be
covered in the ne/t chapters.
Destination /1 ession#Create5ueue(3*6ample5ueue3);
(roducer /1 ession#Create(roducer(Destination);
(roducer#end(ession#CreateTe6tMessage(3T%is is a test message3));
Closin& a Connection
*inally the application closes the connection. !he client will disconnect from the message
broker. (losing a connection also implicitly closes all open sessions.
"inally
Connection#Close;
end;
end#
'ote9 (lose will be called automatically if the connection is destroyed.
8ut because unclosed connections use resources (lose should
be called when the connection is no longer needed. &hen
logging is enabled the connection class will also log a message
when a connection is destroyed without calling (lose.
2ession t6,es overview
!he table below shows the supported parameter combinations for the
(onnection.(reate%ession method and their effect on the session transaction and
acknowledgment features.
0arameters Client M82T
acknowled&e
messa&e
recei,t
9
Transaction
su,,ort for
2T;M0
?ersion %end .ck
(reate%ession:*alse am.uto.cknowledge; 'o , , >.1
(reate%ession:*alse am(lient.cknowledge; Oes :cumulative
effect;
, , >.1
A http9//stomp.github.io/stomp,specification,>.0.htmlL%$8%(5"8EMackMHeader
(reate%ession:*alse am(lient"ndividual; Oes , , >.>
(reate%ession:!rue am.uto.cknowledge; 'o , >.1
(reate%ession:!rue am(lient.cknowledge; Oes :cumulative
effect;
>.1
(reate%ession:!rue am(lient"ndividual; Oes >.>
(reate%ession:!rue am!ransactional; 'o , >.1
- %upported by .ctiveM4 ?.@.1 .pollo >.A and 5abbitM4 B.0.B
,able 3) 'e!!ion creation +ara*eter!
Connection 8.L ,arameters
Messa&e .ecei,ts
!he %!OM+ standard supports individual message receipts which are sent back to the
client for every message.
H
!he library supports this feature with an optional connection $56 parameter send.receipt.
E/ample9
!actory /1 TBTJMConnection!actory#Create(3user3, 3pass4ord3, 3stomp///local%ost7
send#receipt1true3);
"f the broker does not send a receipt within a time,out interval the client library will raise
an e/ception.
'ote9 for additional reliability the client can use transactional send
:see section N!ransacted %essionsN;.
2ubscri,tion .ecei,ts
!he %!OM+ standard supports subscription receipts which are sent back to the client for
every subscription command.
!he library supports this feature with an optional connection $56 parameter
subscribe.receipt.
E/ample9
su0scri0e#receipt1true3);
H http9//stomp.github.com/stomp,specification,>.>.htmlLHeaderMreceipt
Connection! and 'e!!ion! 23
"f the broker does not send a receipt within a time,out interval the client library will raise
an e/ception.
:isconnect .ecei,ts
!he %!OM+ specification recommends to re3uest a broker confirmation for the
)"%(O''E(! frame to do a graceful shutdown where the client is assured that all
previous frames have been received by the server.
2
!he library supports this feature with an optional connection $56 parameter
disconnect.receipt.
E/ample9
disconnect#receipt1true3);
&ithout this parameter the client will disconnect the socket connection immediately after
sending the )"%(O''E(! frame to the broker.
&ith disconnect.receiptPtrue the client will send the )"%(O''E(! frame and then wait
for up to ?111 milliseconds for the broker receipt frame. If te broker does not
answerC te client librar6 will raise an e*ce,tion. !he client application should treat
its messages as undelivered.
'ote9 for additional reliability the client can use transactional send
:see section N!ransacted %essionsN; and message receipts :see
section NMessage 5eceiptsN;.
TC0 Iee,5Alive
!he library supports !(+ keep,alive with an optional connection $56 parameter
tcp.keepalive.
!he parameter takes two arguments. On 6inu/ the first argument is the initial delay
before the first keep,alive the second argument specifies the interval :both values are in
milliseconds;. On the &indows platform the values of these arguments are ignored and
the operating system uses default values for initial delay
@
and interval
>1
which can be
modified in the registry.
E/ample9
tcp#2eepali.e18999,89993);
2 http9//stomp.github.com/stomp,specification,>.>.htmlL)"%(O''E(!
@ http9//technet.microsoft.com/en,us/library/cc@?H?J@.asp/
>1http9//technet.microsoft.com/en,us/library/cc@?H?J2.asp/
'ote !(+ keep,alive is currenctly only supported by the "ndy
communication adapter
"mportant !o enable !(+ keep,alive the proGect must be compiled with
the conditional symbol H.8.5"M!(+MQEE+.6"RE
Heart5beatin& 2u,,ort
%!OM+ >.> introduced heart,beating its configuration is covered in the chapter %!OM+
>.>
Transacted 2essions
. session may be specified as transacted. Each transacted session supports a single series
of transactions.
7ac transaction &rou,s a set of messa&e sends into an atomic unit of work.
. transaction is completed using either its session<s (ommit method or its session<s
5ollback method. !he completion of a session<s current transaction automatically begins
the ne/t. !he result is that a transacted session always has a current transaction within
which its work is done.
Create a transacted session
!o create a transacted session set the parameter of (reate%ession to am!ransactional as
shown in the code e/ample9
ession /1 Connection#Createession(amTransactional);
or :using the older .+" version;
ession /1 Connection#Createession(True, amTransactional);
!his code will automatically start a new transaction for this session.
2end messa&es
'ow send messages using the transacted session.
Destination /1 ession#Create5ueue(3test:ueue3);
(roducer#end(ession#CreateTe6tMessage(3T%is is a test message3));
Committin& a transaction
"f your client code has successfully sent its messages the transaction must be committed
to make the messages visible on the destination.
// send messages ###
"inally
// commit all messages
ession#Commit;
end;
'ote9 commiting a transaction automatically starts a new transaction
.ollin& back a transaction
"f your client code runs wants to undo the sending of its messages the transaction may
be rolled back and the messages will not become visible on the destination.
// send messages ###
e6cept
###
// error;
ession#<oll0ac2;
###
end;
'ote9 rolling back a transaction automatically starts a new
transaction. . transacted session will be rolled back
automatically if the connection is closed.
Transacted messa&e acknowled&ement
%ome library versions
>>
support transactions also for the acknowledgement of received
messages.
&hen a transaction is rolled back or the connection is closed without a commit messages
which have been acknowledged after the transaction start will return to unacknowledged
state.
(ode e/ample9
>>!ested with .pache .ctiveM4 ?.@.1 .pollo >.A and 5abbitM4 B.0.0
// receive in a transacted session
Session := Connection.CreateSession(True, amClientAcknowledge);
Queue := Session.CreateQueue(etQueue!ame);
Consumer := Session.CreateConsumer(Queue);
"sg := Consumer.#eceive($%%%);
// &rocess t'e message
...
// acknowledge t'e message
"sg.Acknowledge;
...
// in case o( errors, roll )ack all acknowledgements
Session.#oll)ack;
!his is an e/perimental feature. "t re3uires usage of the %!OM+ >.0 communication
protocol.
)ailover 2u,,ort
!he *ailover transport layers reconnect logic on top of the %tomp transport.
>0

!he *ailover configuration synta/ allows you to specify any number of composite $5"s.
!he *ailover transport randomly chooses one of the composite $5" and attempts to
establish a connection to it. "f it does not succeed a new connection is established to one
of the other $5"s in the list.
E/ample for a failover $5"9
failover!stomp//primary"#"#$%stomp//secondary"#"#$&
>0http9//activem3.apache.org/failover,transport,reference.html
)ailover Trans,ort ;,tions
;,tion %ame :efault
?alue
:escri,tion
initial5econnect)elay >1 How long to wait before the first reconnect attempt :in ms;
ma/5econnect)elay B1111 !he ma/imum amount of time we ever wait between reconnect
attempts :in ms;
backOffMultiplier 0.1 !he e/ponent used in the e/ponential backoff attempts
ma/5econnect.ttempts ,> ,> is default and means retry forever 1 means don<t retry :only try
connection once but no retry;
"f set to F 1 then this is the ma/imum number of reconnect attempts
before an error is sent back to the client
randomi=e true use a random algorithm to choose the the $5" to use for reconnect
from the list provided
,able 4) /ailover ,ran!+ort 0+tion!
E/ample $5"9
failover!stomp//localhost"#"#"%stomp//remotehost"#"#"&'
initial(econnect)elay*#00+ma,(econnect-ttempts*#0
E/ample code9
!actory /1 TBTJMConnection!actory#Create(3"ailo.er/
(stomp///primary/=8=8=,stomp///local%ost/=8=8>)7ma6<econnectAttempts1>?randomi@e1"alse3) do
try
Conn /1 !actory#CreateConnection;
Conn#tart;
###
Conn#top;
"inally
Conn#Close;
end;
0ooled Connection )actor6
. basic implementation of a connection pool class is included in the
li)raries+o),ect&ool folder. &ith this class multi,threaded applications can limit
resource usage by reusing instances of "(onnection.
!o create a connection pool the new class T-T.oola)leConnection/actor0 has been
introduced. !his class implements the *.oola)le*nter(ace/actor0 interface. "t inherits
from T-T1"SConnection/actor0 which makes it a drop,in replacement with the same
methods to create and configure a classic non,poolable connection factory.
!hreads which have a reference to a T-TConnection.ool obGect then can use the methods
-orrowConnection and #eturnConnection to ac3uire and release connections9
+orrowConnection - this method returns a started "(onnection instance
.eturnConnection - this method returns the instance back to the pool
// ac2uire a connection
Conn := .ool.-orrowConnection;
tr0
// ... use t'e connection
(inall0
// return to &ool
.ool.#eturnConnection(Conn);
end;
!he connection pool behaviour when the pool si=e is e/hausted can be controlled by a
constructor parameter with two different values ea/ail and earow. !he first value
ea/ail will raise an e/ception to notify the caller of the e/hausted pool so the caller
needs to retry :or give up; when the pool has no free connection. !he second value
earow will simply create another connection when no free connection is available.
(onnections returned by -orrowConnection will be in started mode and remain in this
mode when they are returned to the pool.
'ote9 heart,beating is not supported because connections in the pool will not
automatically send heartbeats to the message broker.
. demo program is included in the li)raries/o),ect&ool folder.
7*,erimental Code !his code is still in an e/perimental stage and might change or
be removed in later versions
1e!tination! 2$
:estinations
Introduction
!he JM% .+" supports two models9
>B
>. point,to,point or 3ueuing model
0. publish and subscribe model
"n the point,to,point or 3ueuing model a producer posts messages to a particular 3ueue
and a consumer reads messages from the 3ueue. Here the producer knows the
destination of the message and posts the message directly to the consumer<s 3ueue. "t is
characteri=ed by following9
Only one consumer will get the message
!he producer does not have to be running at the time the receiver consumes the
message nor does the receiver need to be running at the time the message is sent
Every message successfully processed is acknowledged by the receiver
!he publish/subscribe model supports publishing messages to a particular message topic.
Sero or more subscribers may register interest in receiving messages on a particular
message topic. "n this model neither the publisher nor the subscriber know about each
other. . good metaphor for it is anonymous bulletin board. !he following are
characteristics of this model9
Multiple consumers can get the message
!here is a timing dependency between publishers and subscribers. !he publisher
has to create a subscription in order for clients to be able to subscribe. !he
subscriber has to remain continuously active to receive messages unless it has
established a durable subscription. "n that case messages published while the
subscriber is not connected will be redistributed whenever it reconnects.
Create a new :estination
Queues
. 3ueue can be created using the (reate4ueue method of the %ession. E/ample9
Destination /1 ession#Create5ueue(3"oo3);
Consumer /1 ession#CreateConsumer(Destination);
>BJava Message %ervice. :011H 'ovember 0>;. "n &ikipedia !he *ree Encyclopedia.
http9//en.wikipedia.org/wiki/JavaMMessageM%ervice
!he 3ueue can then be used to send or receive messages using implementations of the
"Message+roducer and "Message(onsumer interfaces. :%ee ne/t chapter for an e/ample;
To,ics
. topic can be created using the (reate!opic method of the %ession. E/ample9
Destination /1 ession#CreateTopic(30ar3);
!he topic can then be used to send or receive messages using implementations of the
"Message+roducer and "Message(onsumer interfaces. :%ee ne/t chapter for an e/ample;.
:estination ;,tions
)estination Options are a way to provide e/tended configuration options to a JM%
consumer without having to e/tend the JM% .+". !he options are encoded using $56
3uery synta/ in the destination name that the consumer is created on.
>J

E/ample9
Destination /1 ession#Create5ueue(3:ueue7acti.em:#retroacti.e1true3);
activem/.dis,atcAs6nc DbooleanE
%hould messages be dispatched synchronously or asynchronously from the producer
thread for non,durable topics in the brokerT *or fast consumers set this to false. *or slow
consumers set it to true so that dispatching will not block fast consumers.
activem/.e*clusive DbooleanE
" would like to be an E/clusive (onsumer on the 3ueue.
>?
activem/.ma*imum0endin&Messa&eLimit DintE
*or %low (onsumer Handling on non,durable topics by dropping old messages , we can
set a ma/imum,pending limit such that once a slow consumer backs up to this high water
mark we begin to discard old messages.
>A
activem/.,refetc2iJe DintE
%pecifies the ma/imum number of pending messages that will be dispatched to the client.
Once this ma/imum is reached no more messages are dispatched until the client
>Jhttp9//activem3.apache.org/destination,options.html
>?http9//activem3.apache.org/e/clusive,consumer.html
>Ahttp9//activem3.apache.org/slow,consumer,handling.html
1e!tination! 3%
acknowledges a message. %et to ' for very fair distribution of messages across consumers
where processing messages can be slow.
activem/.,riorit6 Db6teE
%ets the priority of the consumer so that dispatching can be weighted in priority order.
activem/.retroactive DbooleanE
. retroactive consumer is Gust a regular JM% consumer who indicates that at the start of a
subscription every attempt should be used to go back in time and send any old messages
:or the last message sent on that topic; that the consumer may have missed.
>H
>Hhttp9//activem3.apache.org/retroactive,consumer.html
0roducer and Consumer
Messa&e 0roducer
. client uses a Message+roducer obGect to send messages to a destination. .
Message+roducer obGect is created by passing a )estination obGect to a message,producer
creation method supplied by a session.
E/ample9
(roducer#end(ession#CreateTe6tMessage(3Test message3));
. client can specify a default delivery mode priority and time to live for messages sent
by a message producer. "t can also specify the delivery mode priority and time to live for
an individual message.
Messa&e Consumer
. client uses a Message(onsumer obGect to receive messages from a destination. .
Message(onsumer obGect is created by passing a )estination obGect to a message,
consumer creation method supplied by a session.
E/ample9
. message consumer can be created with a messa&e selector. . message selector
allows the client to restrict the messages delivered to the message consumer to those that
match the selector.
. client may either synchronously receive a message consumer<s messages or have the
consumer asynchronously deliver them as they arrive.
*or synchronous receipt a client can re3uest the ne/t message from a message consumer
using one of its receive methods. !here are several variations of receive that allow a client
to poll or wait for the ne/t message.
*or asynchronous delivery a client can register a Message6istener obGect with a message
consumer. .s messages arrive at the message consumer it delivers them by calling the
Message6istener<s OnMessage method.
.roducer and Con!u*er 33
<M2 2electors
%electors are a way of attaching a filter to a subscription to perform content based
routing. %electors are defined using %46 @0 synta/ and typically apply to message
headersU whether the standard properties available on a JM% message or custom headers
you can add via the JM% code.
>2
Here is an e/ample
./0Type * 1car1 -2) color * 1bl3e1 -2) 4ei5ht 6 7500
*or more documentation on the detail of selectors see the reference on
Gava/.Gm/.Message
>@
.
.ctiveM4 supports some JM% defined properties as well as some .ctiveM4 ones that the
selector can use.
%ote !he %tomp protocol used by Habari (lient for .ctiveM4 only
supports string type properties and operations in selectors.
%umeric selectors .pache .ctiveM4 ?.A introduced support for numeric
e/pressions in JM% selectors
01
.
)elphi e/ample9
MessageConsumer /1 ession#CreateConsumer(Destination, 3"oo 1 330ar333);
8sin& =0at to filter messa&es
.pache .ctiveM4 also supports V+ath based selectors when working with messages
containing VM6 bodies. !o use an V+ath selector use the following synta/
89-T: 1//title;<lan5*11en511=1
%ote !he standard installation of .ctiveM4 does not include the
Valan J.5 files which are necessary for V+.!H evaluation. !he
files /alan.Gar /erces"mpl.Gar and /ml,apis.Gar need to be
placed in the lib folder of .ctiveM4.
)elphi e/ample9
MessageConsumer /1 ession#CreateConsumer(Destination, 3A(ATB 33//titleCDlang1EenEF333);
>2 http9//activem3.apache.org/selectors.html
>@ http9//download.oracle.com/Gavaee/?/api/Gava//Gms/Message.html
01 https9//issues.apache.org/Gira/browse/.M4,>A1@
,e2t Me!!a(e! 35
Te*t Messa&es
2endin& a Te*tMessa&e
%ource code for a simple application which sends a test message to a broker running on
the local system using default credentials9
program end$neMessage;
&'A((T)(* C$+$,*-
uses
BTCommAdapterIndy, BTJMConnection, BTJMInter"aces,
ysUtils;
.ar
ession/ Iession;
(roducer/ IMessage(roducer;
0egin
try
Connection#tart;
Destination /1 ession#Create5ueue(3test:ueue3);
(roducer#end(ession#CreateTe6tMessage(3Test message3));
"inally
Connection#Close;
end;
end#
!he unit +TCommAda,terInd6 contains the "nternet )irect :"ndy; communication
adapter class. 8y including this unit it will register the adapter class with an internal list of
all available communication adapters. 8y default the first registered communication
adapter will be used.
.eceive Te*t Messa&es
As6ncronous receive
!o receive te/t messages asynchronously the client subscribes to a destination :which
can be a 3ueue or a topic; on the server.
!he messages will be delivered to an event handler which has to be provided by the client.
.ar
Consumer/ IMessageConsumer;
0egin
###
// create a destination :ueue
Destination /1 ession#Create5ueue(3test3);

// create a consumer
// set t%e message listener
Consumer#Message,istener /1 el";
###
end;
!he asynchronous Message6istener is an obGect which implements the "Message6istener
interface.
!his interface only contains one procedure OnMessage9
IMessage,istener 1 inter"ace(IInter"ace)
procedure $nMessage(Message/ IMessage);
end;
,e2t Me!!a(e! 37
26ncronous .eceive
. Message(onsumer offers a 5eceive method which can be used to consume e/actly one
message at a time.
E/ample9
4%ile I G *A(*CT*D do
0egin
Te6tMessage /1 Consumer#<ecei.e(8999) as ITe6tMessage;
i" Assigned(Te6tMessage) t%en
0egin
Inc(I);
Te6tMessage#Ac2no4ledge;
,#In"o(!ormat(3Hd Hs3, CI, Te6tMessage#Te6tF));
end;
end;
(ompared with a Message6istener the 5eceive method has the advantage that the
application can stop consuming messages at any point in time :for e/ample after
receiving 01 messages;. &ith an asynchronous Message6istener it is possible that the
Message(onsumer will still receive some messages after calling the close method.
.eceive and .eceive%oWait
!here are three different methods for synchronous receive9
.eceive !he 5eceive method with no arguments will block :wait until a
message is available;.
.eceiveDTime;utE !he 5eceive method with a timeout parameter will wait for the
given time in milliseconds. "f no message arrived it will return
nil.
.eceive%oWait !he 5eceive'owait method will return immediately. "f no
message arrived it will return nil.
+inar6 Messa&es
2end +inar6 Messa&es
.eadin& +inar6 Content usin& +T2treamHel,er
!he 8!%treamHelper unit contains the procedure 6oad8ytes*rom%tream which can be
used to read a file into a 8ytesMessage. E/ample9

// create t%e message
Msg /1 ession#CreateBytesMessage;
// open a "ile
! /1 T!iletream#Create(3"ilename#dat3, "m$pen<ead);
try
// read t%e "ile 0ytes into t%e message
,oadBytes!romtream(Msg, !);
i@e /1 ,engt%(Msg#Content);
// display message content si@e
Irite,n(IntTotr(i@e) J 3 Bytes3);
"inally
// release t%e "ile stream
!#!ree;
end;
0b3ect Me!!a(e! 3$
;b>ect Messa&es
Introduction
;b>ect 2erialiJation
ObGect seriali=ation is the process of saving an obGect<s state to a se3uence of bytes as
well as the process of rebuilding those bytes into a live obGect at some future time.
0>
"n
messaging applications obGect seriali=ation is re3uired to transfer obGects between clients
but also to store obGects on the broker if they are declared persistent.
.ctiveM4 supports obGect e/change between Java and non,Java clients using a Message
!ransformation between native Java obGects and VM6 or J%O' seriali=ed obGects.
00
F:el,i ;nl6G vs. FCross5Lan&ua&eG ;b>ect 7*can&e
Habari (lient for .ctiveM4 offers two obGect e/change methods.
Cross5Lan&ua&e ;b>ects on te broker are encoded usin& <ava binar6
serialiJation. !he )elphi application sends a J%O' or VM6
seriali=ed obGect to the broker who transforms it into a binary
seriali=ed Java obGect first before it can be consumed by JM%
clients. !his broker,side transformation re3uires that Java class
files for the class are in the broker<s class path.
:el,i ;nl6 ;b>ects on te broker are encoded usin& <2;% or =ML.
!he message broker e/changes the obGects between )elphi
:and other; clients seriali=ed as J%O' or VM6 te/t no special
Java support files are re3uired. Tis e*can&e metod is
new in version -.$ of Habari Client for ActiveMQ.
FCross5Lan&ua&eG ;b>ect 7*can&e
On the Java side a Java client application does not need any special preparation to send
and receive obGects over .ctiveM4. !he JM% .+" support for ObGectMessage provides all
necessary methods a session uses
Session3create4),ect"essage(Seriali5a)le o),ect)
0B
to create the message :passing
a Java obGect as argument; which then can be sent and received Gust like a !e/tMessage
or 8ytesMessage.
However for the message transformation to and from J%O' or VM6 this obGect e/change
methods re3uires that a J.5 containing a matching Java class file has to be deployed in
0>http9//Gava.sun.com/developer/technical.rticles/+rogramming/seriali=ation/
00http9//activem3.apache.org/message,transformation.html
0Bhttp9//download.oracle.com/Gavaee/>.J/api/Gava//Gms/%ession.htmlLcreateObGectMessage
W02Gava.io.%eriali=ableW0@
the message broker which will be used by the brokers message transformer. "f this Java
class is not compatible with the J%O' or VM6 structure the message transformation failsX
+ros
Java clients do not need any special modifications to e/change obGects with non,
Java clients )elphi clients can be connected :<plugged in<; / integrated easily with
an e/isting JM% infrastructure
%eriali=ation from / to obGects is performed on the server
%eriali=ation only occurs <on demand< when the non,Java client reads or writes
messages
(ons
5e3uires installation of a J.5 file in the message broker which contains the Java
class :unless the class is already in the brokers classpath;
!he transformation fails if the Java class and )elphi class declaration don<t match
!he transformation fails if the )elphi and Java transformer libraries :J%O' / VM6;
are not compatible
F:el,i ;nl6G ;b>ect 7*can&e
!here are almost no differences between in the )elphi code for C(ross,6anguageE and
C)elphi OnlyE obGect e/change methods. %witching to C)elphi OnlyE obGect e/change
re3uires only an additional property assignment on the obGect message. !he seriali=ed
obGects will be stored in the messages broker as !e/tMessage instances. !he VM6 or J%O'
te/t can be retrieved by a JM% Java client application Gust like any other JM% !e/tMessage.
Java clients can use a J%O' or VM6 parser to read the message content.
+ros
%imple usage no J.5 installation re3uired
Java JM% client applications are still able to receive the seriali=ed obGects - they will
appear as !e/tMessage instances containing the J%O' or VM6 te/t
(ons
)eseriali=ation of J%O' or VM6 seriali=ed )elphi obGects to Java obGects re3uires a
decoder library :V%tream or Jettison; on the Java client side
0b3ect Me!!a(e! 4%
Messa&e Transformers in Habari Client for ActiveMQ
Transformatio
n
Messa&e T6,e Librar6 8nit
=ML ;b>ectMessa&e ;mni=ML 8!Message!ransformerVM6Omni
=ML ;b>ectMessa&e %ative=ml 8!Message!ransformerVM6'ative
=ML Ma,Messa&e ;mni=ML 8!Message!ransformerVM6MapOmni
=ML Ma,Messa&e %ative=ml 8!Message!ransformerVM6Map'ative
<2;% ;b>ectMessa&e lk<2;% 8!Message!ransformerJ%O'lk
<2;% ;b>ectMessa&e 2u,er;b>ect 8!Message!ransformerJ%O'%uperObGect
,able 5) Me!!a(e ,ran!for*er I*+le*entation!
Memor6 Mana&ement
;ut&oin& ;b>ects
!he message transformer will not free obGects which have been sent. !o release the
memory the application has to e/plicitly free them when they are no longer used.
Incomin& ;b>ects
!he message transformer will create an obGect instance when a obGect message has been
received. !o avoid memory leaks the application must free this instance when it is no
longer in use.
Code 7*am,les
. complete code e/ample for C)elphi OnlyE obGect e/change is in chapter C*ehler9
5eferen= nicht gefundenE :p. *ehler9 5eferen= nicht gefunden;. Here are some basic code
e/cerpts to get you started.
Assi&n a Messa&e Transformer
!o insert a obGect decoder / encoder in the message processing chain create a message
transformer instance and assign it to the connection<s Message!ransformer property.
!he constructor of message transformers for obGect e/change takes one argument which
is the class of the seriali=ed obGect. "n this e/ample %ample+oGo is the class.

###

4it% (Connection as IMessageTrans"omerupport) do
0egin
MessageTrans"ormer /1 TBTMessageTrans"ormerAM,+ati.e#Create(ample(oKo);
end;
###
Connection#tart;
&ith version 0.2 and newer you can also use the helper procedure %et!ransformer in unit
8!JM%(onnection9
###
etTrans"ormer(Connection, TBTMessageTrans"ormerAM,+ati.e#Create(ample(oKo));
###
Connection#tart;
.e/uest te Transformation )ormat
!he .ctiveM4 8roker must know which seriali=ation format shall be used for the
connection.
!his information can be added to the destination name using a predefined constant for
the trans(ormation message option header and the transformation "). 'ote that the
transformation ") must match the ") of the used message transformer.
*or e/ample this code tells the broker to seriali=e messages in VM6 format9
const
Dest 1 3logTopic3
J 373 J BTtompTypes#BLT<A+!$<MATI$+
J 313 J BTerialInt"#T<A+!$<M*<LIDL$BJ*CTLAM,;
###
Destination /1 ession#CreateTopic(Dest);
###
Ralid transformation ") values are defined in unit 8!%erial"ntf.
Create and 2end an ;b>ectMessa&e
>. create a "ObGectMessage instance using "%essionL(reateObGectMessage
0. send the obGect message to the broker using "Message+roducerL%end

$0KectMessage /1 ession#Create$0KectMessage(Instance);
(roducer#end($0KectMessage);
0b3ect Me!!a(e! 43
Te transformation5custom Messa&e Header
!o send obGect messages without invoking of .ctiveM4 message transformations set the
<transformation,custom< header of the message to the transformation id of the message
transformer. E/ample9
$0KectMessage /1 ession#Create$0KectMessage(Instance);
// set t%e additional %eader (4e use J$+ o0Kect trans"ormation %ere)
$0KectMessage#ettring(roperty(3trans"ormationMcustom3, T<A+!$<M*<LIDL$BJ*CTLJ$+)
Com,lete 7*am,le usin& %ative=ml
*rom ObGectE/change!ests.pas.
%end9
procedure T$0*6TestCase#TestAM,+ati.e;
.ar
$0KectMessage/ I$0KectMessage;
$0K/ ample(oKo;
0egin
// send
try
Connection#tart;
Destination /1 ession#Create5ueue(3T$$,#$BJ*CT#AM,3);
$0K /1 ample(oKo#Create;
try
$0K#messageTe6t /1 3test3;
$0K#message+o /1 9;
$0KectMessage /1 ession#Create$0KectMessage($0K);
$0KectMessage#ettring(roperty(BLT<A+!$<MATI$+ J 3Mcustom3,
T<A+!$<M*<LIDL$BJ*CTLAM,); // re:uired "or EDelp%i $nlyE o0Kect e6c%ange
"inally
$0K#!ree;
end;
"inally
Connection#Close;
end;
5eceive9

try
Connection#tart;
ession /1 Connection#Createession(!alse, amClientAc2no4ledge);
Destination /1 ession#Create5ueue(3T$$,#$BJ*CT#AM,3);
$0KectMessage /1 Consumer#<ecei.e(8999) as I$0KectMessage;
i" Assigned($0KectMessage) t%en
0egin
$0KectMessage#Ac2no4ledge;
$0K /1 $0KectMessage#Net$0Kect as ample(oKo;
try
C%ec2*:uals(3test3, $0K#messageTe6t);
C%ec2*:uals(9, $0K#message+o);
"inally
$0K#!ree;
end;
end;
"inally
Connection#Close;
end;
end;
Ma+ Me!!a(e! 45
Ma, Messa&es
Introduction
!he JM% .+" supports map messages which consist of key,value pairs. Habari (lient for
.ctiveM4 includes e/perimental implementations :based on OmniVM6 and 'ativeVml; of
map message support. !hey seriali=e all entries as string values at the moment.
Map message transformers take a nil parameter as argument.
:el,i ;nl6 and Cross5Lan&ua&e
$nlike obGect messages map messages work both cross,language and between )elphi
applications without special message properties or class file deployments. !hey only
re3uire that the correct transformation ") is added to the destination name.
Com,lete 7*am,le
!his e/ample uses 'ativeVml and is taken from ObGectE/change!ests.pas.
%end9
procedure T$0*6TestCase#TestAM,Map+ati.e;
.ar
MapMessage/ IMapMessage;
0egin
// send
try
etTrans"ormer(Connection, TBTMessageTrans"ormerAM,Map+ati.e#Create(nil));
Connection#tart;
Destination /1 ession#Create5ueue(3T$$,#MA(#AM,3);
MapMessage /1 ession#CreateMapMessage;
MapMessage#ettring(3"irst3, 383);
MapMessage#ettring(3second3, 3O3);
(roducer#end(MapMessage);
"inally
Connection#Close;
end;
5eceive9
try
etTrans"ormer(Connection, TBTMessageTrans"ormerAM,Map+ati.e#Create(nil));
Connection#tart;
ession /1 Connection#Createession(!alse, amClientAc2no4ledge);
Destination /1 ession#Create5ueue(3T$$,#MA(#AM,3
J 37trans"ormation13 J T<A+!$<M*<LIDLMA(LAM,);
MapMessage /1 Consumer#<ecei.e(8999) as IMapMessage;
i" Assigned(MapMessage) t%en
0egin
MapMessage#Ac2no4ledge;
C%ec2*:uals(383, MapMessage#Nettring(3"irst3));
C%ec2*:uals(3O3, MapMessage#Nettring(3second3));
end;
"inally
Connection#Close;
end;
end;
1urable 'ub!cri+tion! 47
:urable 2ubscri,tions
:escri,tion
"f a client needs to receive all the messages published on a topic including the ones
published while the subscriber is inactive it uses a durable !opic%ubscriber. !he JM%
provider retains a record of this durable subscription and insures that all messages from
the topic<s publishers are retained until they are acknowledged by this durable subscriber
or they have e/pired.
0J
!he combination of the client"d and durable subscriber name
uni3uely identifies the durable topic subscription. .fter you restart your program and re,
subscribe the 8roker will know which messages you need that were published while you
were away.
*urther information can be found at
http9//activem3.apache.org/how,do,durable,3ueues,and,topics,work.html
Creation
!he %ession interface contains the (reate)urable%ubscriber method which creates a
durable subscriber to the specified topic. . JM% durable subscriber Message(onsumer is
created with a uni3ue JM% client") and durable subscriber name. Only one thread can be
actively consuming from a given logical topic subscriber.
%ote9 *or durable topic subscriptions you must specify the same
client"d on the connection and subscription'ame on the
subscribe.
. second option to create a durable topic subscriber is the web administration interface. "n
the default installation of .pache .ctiveM4 you can use the <%ubscribers< page at
http9//localhost92>A>/admin/subscribers.Gsp.
7*am,le
&ith the +roducer!ool and (onsumer!ool demo applications you can send messages to a
durable topic9
9rod3cerTool --/essa5e>o3nt*#000 --Topic --9ersistent --03b?ect*test-d3rable

and receive them from a client9
0Jhttp9//download.oracle.com/Gavaee/?/api/Gava//Gms/!opic%ession.html
>ons3merTool --/a,im3m/essa5es*#000 --Topic --03b?ect*test-d3rable --)3rable -->lient@)*#7$A5
-->ons3mer2ame*#7$A5 --Berbose
?irtual :estinations
.n alternative solution in .ctiveM4 which has some benefits compared with durable
subscriptions9 http9//activem3.apache.org/virtual,destinations.html
'to*+ %.% 4$
2tom, '.'
Connection Confi&uration
. connection string can use additional $56 parameters to configure %tomp >.>
.ll parameters can be omitted to use the default value.
2witc :escri,tion :efault
connect.accept,
version
0?
%upported %tomp versions in ascending order 'o default
connect.host
0A
Te name of a virtual ost tat te client
wises to connect to. "t is recommended
clients set this to the host name that the socket
was established against or to any name of their
choosing. "f this header does not match a known
virtual host servers supporting virtual hosting
M.O select a default virtual host or reGect the
connection.
%erver $5"
connect.heart,beat
0H
Heart beat :outgoing incoming; C11E
Connection )actor6 Code 7*am,le@
/actor0 := T-T1"SConnection/actor0.Create(
6stom&://local'ost:7$7$89connect.acce&t:version=$.$;connect.'eart:)eat=$%%%,%6);
!his e/ample creates a connection factory with these connection settings
host9 localhost
port9 A>A>B
accept,version9 >.>
heart,beat9 >1111
0?http9//stomp.github.com//stomp,specification,>.>.htmlLprotocolMnegotiation
0Ahttp9//stomp.github.com//stomp,specification,>.>.htmlL(O''E(!MorM%!OM+M*rame
0Hhttp9//stomp.github.com//stomp,specification,>.>.htmlLHeart,beating
virtual host is localhost
the client re3uests %tomp >.> protocol
client heart beat interval is >111 milliseconds no server heart beat signals
+roker s,ecific notes
5abbitM4 by default has one host defined which has the name N/N. (ode e/ample
#a))it"Q/actor0 := T-T1"SConnection/actor0.Create(
6stom&://local'ost:7$7$89connect.acce&t:version=$.$;connect.'ost=/6);
2,ecification
*or details see the %tomp specification page at
http9//stomp.github.com//stomp,specification,>.>.html
2endHeartbart@ sendin& client5side eartbeat si&nals
. client can use the 2endHeartbeat method of the connection obGect to send a heart,
beat byte :newline 1/1.;. %endHeartbeat is a method of the "Heartbeat interface which is
declared in the 8!%ession"ntf unit. . cast of the "(onnection obGect is re3uired to access
this method.
E/ample9
(Connection as *<eart)eat).Send<eart)eat;
'otes9
the client code is responsible for sending a heartbeat message within the ma/imum
interval which was specified in the connect parameter
client messages which are sent after the heart,beat interval e/pires may be lost
'to*+ %.% 5%
CeckHeartbeat@ ceckin& for server5side eartbeats
. client can use the CeckHeartbeat method of the connection obGect to detect wether
the server has sent data within the heartbeat interval.
E/ample9
(Connection as *<eart)eat).C'eck<eart)eat;
'otes9
calling the (heckHeartbeat method will raise an e/ception if the server did not send
any data within the heartbeat interval
calling (heckHeartbeat will raise an e/ception when the connection has not been
configured for server,side heart,beating
before calling (heckHeartbeat the application must have called either one of the
5eceive / 5eceive'o&ait methods or the 5eceiveHeartbeat :see below; to update
the internal timestamp of the last heart,beat
.eceiveHeartbeat@ readin& server5side eartbeats
"f the client never needs to consume any messages but still needs to check for server,
side heaertbeats it can use the .eceiveHeartbeat method of the connection obGect. !his
method takes one argument !imeOut.
'otes9
calling 5eceiveHeartbeat is only re3uired for applications which never call 5eceive
or 5eveive'o&ait because the server never sends any messages
if the server has sent messages to the client 5eceiveHeartbeat will not read past
them
7*am,le A,,lications
:irector6 :escri,tion
common
%hared units :see below;
common-chat
%imple chat client
common-cons3mertool
5eceive messages from broker
common-delphi53i
%ends and receives messages
common-heartbeat-server
$ses server,side heart,beating to check the
connection / server health :not supported on all
message brokers
02
;
common-performance
Multi,threaded performance test application
common-prod3certool
%end messages to broker
common-prod3certool-fpc
%end messages to broker :*ree +ascal /
6a=arus proGect;
common-prod3certool-ssl
%end messages to broker with %%6 connection
common-reconnect
%end messages and reconnect on connection
failure
common-rpc
$se temporary 3ueues to implement
re3uest/response style communication :not
supported on all message brokers
0@
;
common-ssl
%hared code for %%6 demo proGects
common-tests
)$nit tests :re3uires )$nit version @.J;
common-tests-fpc
*+($nit tests :re3uires 6a=arus >.1 or newer;
common-thro35hp3t
(ontinuously produces and consumes
messages to monitor the average message
throughput over time
,able 6) 42a*+le A++lication! 5in al+habetic order6
025e3uires %!OM+ >.> or >.0U not supported by OpenM4
0@'ot available with the Hornet4 message broker
42a*+le A++lication! 53
+roker5inde,endent e*am,le ,ro>ects
!he demo folder contains proGects for e/ample applications and unit tests. !heir folder
name begins with common, to indicate their code is shared between all Habari (lient
libraries.
+roker5s,ecific ,re,aration
"mportant note9 message brokers which do not automatically create destinations :such as
Hornet4; need to be configured before running the demos.
2ared units for demo ,ro>ects
!he directory demo/common contains shared units9
connection configuration form :(onn(fg*rm.pas/dfm;
command line parameter support class :(ommand6ine%upport.pas;
console appender for the 6ogJ) logging framework
22L communication ada,ter units
!he directory demo/common,ssl contains e/ample implementations of "ndy and %ynapse
adapter classes with Open%%6 support. +lease note that these are basic implementations
and not supported in the free basic support plan.
ConsumerTool
!he (onsumer!ool demo may be used to receive messages from a 3ueue or topic. !his
e/ample application is configurable by command line parameters all are optional.
0arameter :efault ?alue :escri,tion
AckMode (6"E'!M.(Q'O&6E)GE .cknowledgment mode possible values are9
(6"E'!M.(Q'O&6E)GE .$!OM.(Q'O&6E)GE
or %E%%"O'M!5.'%.(!E)
ClientId (lient "d for durable subscriber
Consumer%ame Habari name of the message consumer , for durable
subscriber
:urable false true9 use a durable subscriber
Ma*imumMessa&es >1 e/pected number of messages
0assword +assword
0ause+efore2ut:own false true9 wait for key press
.eceiveTime;ut 1 19 asynchronous receive F 19 consume messages
while they continue to be delivered within the
given time out
2lee,Time 1 time to sleep after asynchronous receive
2ub>ect !OO6.)E*.$6! 3ueue or topic name
To,ic false true9 topic false9 3ueue
Transacted false true9 transacted session
8.L localhost server url
8ser user name
?erbose true verbose output
,able 7) Con!u*er,ool Co**and -ine 0+tion!
Illu!tration 3) Con!u*er,ool de*o a++lication
7*am,les
5eceive >111 messages from local broker
>ons3merTool C-/a,im3m/essa5es*#000
5eceive >1 messages from local broker and wait for any key
>ons3merTool C-9a3seBefore0h3t)o4n
$se a transacted session to receive >1111 messages from local broker
>ons3merTool C-/a,im3m/essa5es*#0000 -CTransacted C--cD/ode*0E00@F2GT(-20->TE)
0roducerTool
!he +roducer!ool demo can be used to send messages to the broker. "t is configurable by
command line parameters all are optional.
0arameter :efault :escri,tion
Messa&eCount >1 'umber of messages
Messa&e2iJe 0?? 6ength of a message in bytes
0ersistent false )elivery mode <persistent<
2lee,Time 1 +ause between messages in milliseconds
2ub>ect !OO6.)E*.$6! )estination name
TimeToLive 1 Message e/piration time
To,ic false )estination is a topic
Transacted false $se a transaction
8.L localhost Message broker $56
?erbose true Rerbose output
8ser $ser name
0assword +assword
,able 8) .roducer,ool Co**and -ine 0+tion!
7*am,les
%end >1111 messages to the 3ueue T44=.>?/A@=T on the local broker
Illu!tration 4) .roducer,ool de*o a++lication
9rod3cerTool C-/essa5e>o3nt #0000
%end >1 messages to the topic E/ample!opic on the local broker
9rod3cerTool C-Topic C-03b?ect*E,ampleTopic
0erformance Test
!he performance test application provides a G$" for multi,threaded sending and receiving
of messages.
. broker configuration dialog can be invoked by clicking the $56 field
!he communication library :"ndy or %ynapse; can be selected
'umber and length of messages and thread number can be adGusted using the
sliders
*or every thread a message 3ueue with the name E/ample4ueue.YnF will be used.
Illu!tration 5) .erfor*ance ,e!t A++lication
42a*+le A++lication! 5$
Illu!tration 6) Clic7 in the 89- field to
o+en the confi(uration dialo(
Trou&,ut Test Tool
!his e/ample application is configurable by command line parameters all are optional.
0arameter :efault ?alue :escri,tion
0assword :broker,specific; +assword
2ub>ect E/ample!opic !opic name
8.L :broker,specific; (onnection $56
8ser :broker,specific; $ser name
,able $) ,hrou(h+ut ,e!t ,ool Co**and -ine 0+tion!
7*am,les
$se remote broker <mybroker< and specify user and password
tptest --3rl*stomp//mybroDer --3ser*test# --pass4ord*secret
Illu!tration 7) ,hrou(h+ut te!t tool out+ut
42a*+le A++lication! 6%
+roker 2,ecific :emos
:irector6 :escri,tion
activem3,schedule E/ample code for C)elay and %chedule Message )eliveryC :p. A?;
activem3,statistics E/ample code for C8roker %tatistics E/ampleC :p. AB;
loadbalancing !he Load2erver application will connect with .ctiveM4 on localhost and create
a directory for outgoing files. (opy a file to the files directory. !he 6oad%erver
will now send it every five seconds to a .ctiveM4 3ueue including the file
name file si=e and a se3uence number. :*or safety reasons in this demo the
file will not be deleted.;
!he LoadClient application will connect with .ctiveM4 and create a directory
for incoming files. "f the 6oad(lient finds a file it will be downloaded with a
filename including a time stamp.
"f you start 6oad(lient multiple times .ctiveM4 will distribute the files to all
running clients.
logJd G$" demo app which uses a 6ogJ) appender class :source code included; to
send log messages to a .ctiveM4 topic :JM%.ppender)emo.dpr re3uires the
Lo&3: logging framework logJd.sourceforge.net;
E/ample configuration in logJd.props9
3 Create a 1"S a&&ender
logAd.a&&ender.1ms$=T=og1"SA&&ender
logAd.a&&ender.1ms$.t'res'old=trace
logAd.a&&ender.1ms$.logTo&ic=T44=.>?/A@=T
logAd.a&&ender.1ms$.error<andler=T=og4nl04nce?rror<andler
logAd.a&&ender.1ms$.la0out=T=og.attern=a0out
logAd.a&&ender.1ms$.la0out.&attern= B& C Bd Bc : BmBn
logAd.a&&ender.1ms$.la0out.date/ormat='':nn:ss.555
logJGconsumer !hese demo apps subscribe to a topic which contains Lo&3< logger messages
and re3uest the messages seriali=ed in J%O' or VM6 format. . 6ogJJ Java app is
included in the logJGproducer folder in the Habari "ntegration E/amples
download.
tempdest %ee chapter C!emporary 4ueuesC :p. A@; , !emporary destinations
:!emp)est.dpr;.
,able %&) Advanced 1e*o A++lication!
:ro7er '+ecific 1e*o! 63
+roker 2tatistics 7*am,le
Introduction
.ctiveM4 supports 8roker plugins which allows the default functionality to be e/tended
and new with version ?.B of .pache .ctiveM4 is a %tatistics plugin which enables
statistics about the running broker or 4ueues and !opics to be 3ueried.
!he statistics plugin looks for messages sent to particular destinations. !o 3uery the
running statistics of a the message broker send an empty message to a )estination
:4ueue or !opic; named Active"Q.Statistics.-roker and set the JM%5eply!o field
with the )estination you want to receive the result on. !he statistics plugin will send a
"MapMessage filled with the statistics for the running .ctiveM4 broker.
%imilarly if you want to 3uery the statistics on a )estination send a message to the
)estination name prepended with .ctiveM4.%tatistics.)estination. *or e/ample to
retrieve the statistics on a 4ueue named test.foo send an empty message to the 4ueue
Active"Q.Statistics.>estinationTest./oo.
Oou can also use wildcards too and receive a separate message for every destination
matched.
Confi&uration
!o configure .ctiveM4 to use the statistics plugin add the following to the .ctiveM4 VM6
configuration9
...
D&luginsE
Dstatistics-roker.lugin/E
D/&luginsE
...
2ource Code
7*am,le ;ut,ut
&hen launched with parameter e/ample.. the demo application activem3,statistics will
retrieve the information for 3ueue e/ample.. and the output would look similar to this9
(eq3est statistics for -ctive/H.0tatistics.)estinatione,ample.- ...
memoryUsa5e*0
deq3e3e>o3nt*0
infli5ht>o3nt*0
messa5es>ached*0
avera5eEnq3e3eTime*0.0
destination2ame*q3e3e//e,ample.-
siIe*0
memory9ercentUsa5e*0
prod3cer>o3nt*0
cons3mer>o3nt*#
minEnq3e3eTime*0.0
ma,Enq3e3eTime*0.0
dispatch>o3nt*0
e,pired>o3nt*0
enq3e3e>o3nt*0
memoryJimit*"K#0LL"A
9ress any Dey
&ithout a parameter broker statistics will be returned9
(eq3est statistics for -ctive/H.0tatistics.BroDer ...
vm*vm//localhost
memoryUsa5e*0
storeUsa5e*""A$A775
temp9ercentUsa5e*0
open4ire*tcp//m?-9>"#"#"
broDer@d*@)m?-9>-5795L-#7K79K50"#"K7-00
cons3mer>o3nt*$
broDer2ame*localhost
e,pired>o3nt*0
dispatch>o3nt*7
ma,Enq3e3eTime*$.0
store9ercentUsa5e*0
deq3e3e>o3nt*7
infli5ht>o3nt*0
messa5es>ached*0
tempJimit*#0K$KA#L7A00
avera5eEnq3e3eTime*#.5
memory9ercentUsa5e*0
siIe*0
tempUsa5e*0
prod3cer>o3nt*0
minEnq3e3eTime*0.0
data)irectory*>\.ava\apache-activemq-5.$.#\data
enq3e3e>o3nt*"A
stomp*stomp//m?-9>"#"#$'transport.close-sync*false
storeJimit*#0K$KA#L7A00
memoryJimit*"K#0LL"A
9ress any Dey
:ro7er '+ecific 1e*o! 65
:ela6 and 2cedule Messa&e :eliver6
Introduction
.pache .ctiveM4 from version ?.J has a persistent scheduler built into the .ctiveM4
message broker. .n .ctiveM4 client can take advantage of a delayed delivery by using
message properties.
B1
8y setting properties of the JM% message a client can
set the time in milliseconds that a message will wait before being scheduled to be
delivered by the broker
set the time in milliseconds to wait after the start time to wait before scheduling
the message again
set the number of times to repeat scheduling a message for delivery
or use a (ron entry :for e/ample C& ; ; ; ;< to set the schedule
7*am,le
!he e/ample application shows how a message can be scheduled for delivery after ?
seconds.
B1 http9//activem3.apache.org/delay,and,schedule,message,delivery.html
Messa&e ;,tions
<M2 2tandard 0ro,erties
A0I :ocumentation
JM% %tandard properties are documented in more detail in the .+" documentation for the
!8!Message class. !he are based on the JM% specification of the Message interface.
B>
<M2 ,ro,erties for out&oin& messa&es
Messages sent by Habari (lient for .ctiveM4 can set these JM% standard properties9
<M2CorrelationI: !he correlation ") for the message.
<M27*,iration !he message<s e/piration value.
<M2:eliver6Mode &hether or not the message is persistent.
<M20riorit6 !he message priority level.
<M2.e,l6To !he )estination obGect to which a reply to this message
should be sent.
<M2 ,ro,erties for incomin& messa&es
Messages received by Habari (lient for .ctiveM4 may contain these JM% standard
properties9
<M2CorrelationI: !he correlation ") for the message.
<M27*,iration !he message<s e/piration value.
<M2:eliver6Mode &hether or not the message is persistent.
<M20riorit6 !he message priority level.
<M2Timestam, !he timestamp the broker added to the message.
<M2Messa&eId !he message ") which is set by the provider.
<M2.e,l6To !he )estination obGect to which a reply to this message
B>http9//download.oracle.com/Gavaee/?/api/Gava//Gms/Message.html
Me!!a(e 0+tion! 67
should be sent.
2tom, e*tensions for <M2 messa&e semantics
<M2=Brou,I:
!his message header specifies the Message Group
B0
.
Message groups are an enhancement to the E/clusive (onsumer feature to provide
guaranteed ordering of the processing of related messages across a single 3ueue
load balancing of the processing of messages across multiple consumers
high availability / auto,fail,over to other consumers if a JRM goes down
. way of e/plaining Message Groups is that it provides sticky load balancing of messages
across consumersU where the JM%VGroup") is like a H!!+ session ") or cookie value and
the message broker is acting like a H!!+ load balancer.
<M2=Brou,2e/
Optional header that specifies the se3uence number in the Message Group .
%ote !his %tomp e/tension in .ctiveM4 has not yet been tested with
Habari (lient for .ctiveM4 to verify it is working as e/pected. "f
you would like to see some )elphi e/amples included in the
demos or documentation please feel free to contact me.
8ser :efined 0ro,erties
2u,,orted :ata T6,es
!he %tomp protocol only supports string type properties. .pache .ctiveM4 ?.A introduced
support for numeric e/pressions in message selectors :see
https9//issues.apache.org/Gira/browse/.M4,>A1@;.
.eserved %ames
!he following names are reserved %tomp header properties and can not be used as names
for user defined properties9
activem3.D :everything starting with activem3 is a reserved name;
login
B0http9//activem3.apache.org/message,groups.html
passcode
transaction
session
message
destination
id
ack
selector
type
content,length
correlation,id
e/pires
persistent
priority
reply,to
message,id
timestamp
transformation
client,id
redelivered
!he client library detects overwriting of %tomp defined message properties. "t will raise an
E/ception if the application tries to send a message with a reserved property name.
,e*+orar= Queue! 6$
Tem,orar6 Queues
Introduction
C!emporary destinations :temporary 3ueues or temporary topics; are
proposed as a lightweight alternative in a scalable system
architecture that could be used as uni3ue destinations for replies.
%uch destinations have a scope limited to the connection that created
it and are removed on the server side as soon as the connection is
closed.E :C)esigning Messaging .pplications with !emporary 4ueuesE by !hakur
!hribhuvan
BB
;
.esource Mana&ement
!he session should be closed as soon as processing is completed so that
!emporary4ueues will be deleted on the server side.
How sould I im,lement re/uest res,onse wit <M2?
!he .ctiveM4 documentation presents a resource,friendly solution for re3uest,response
style communication which uses the JM%(orrelation") message property including
e/ample source. !he article can be found here9
http9//activem3.apache.org/how,should,i,implement,re3uest,response,with,Gms.html
BBhttp9//onGava.com/pub/a/onGava/011H/1J/>1/designing,messaging,applications,with,
temporary,3ueues.html
Lo&&in& wit Lo&3:
Introduction
Habari (lient libraries include the free open source library 6ogJ) as an optional
dependency. 'ote that the original source code 6ogJ) is included which is not patched to
work with newer )elphi versions. *or details on necessary patches see below.
I:7 confi&uration
"n order to compile with 6ogJ) support add the conditional symbol :-B-(@GJFMM@2M to the
proGect options9
in )elphi choose +roGect Z Options... Z )elphi (ompiler F (onditional defines and
add H.8.5"M6OGG"'G
in 6a=arus choose +roGect Z +roGect Options [ Z (ompiler Options F Other and add
,dH.8.5"M6OGG"'G in the (ustom options field
Minimal e*am,le
!o log to the CEvent logE window in the )elphi ")E Gust add the 6ogJ) unit to the uses list
and initiali=e 6ogJ) with this line9
Tlo5Basic>onfi53rator.>onfi53reN // creates F)0 !F3tp3t)eb350trin5& lo55er 4ith level 1error1

and set the log level to fatal error warn info debug or trace with another line9
TJo5Jo55er.Met(ootJo55er.Jevel * TraceN // or any other lo5 level
Lo&3: confi&uration file
6ogJ) can be configured in the source code at application start,up or using a
configuration file. . configuration allows to reconfigure logging without recompiling. 'ote
that the application only reads the configuration file at start,up so it needs to be restarted
after modifications.
"n your proGect start,up code configure the 6ogJ) framework with the path to a 6ogJ)
configuration file.
-o((in( "ith -o(41 7%
E/ample9
TJo59roperty>onfi53rator.>onfi53re!E,tractOile9ath!9aram0tr!0&& P 1confi5/lo5Ad.props1&N
7*am,le file Flo&3d.,ro,sG
!o log to the ")E output window using O)% :Output)ebug%tring; the minimal 6ogJ)
configuration shown below can be used9
Q 0et internal deb355in5
lo5Ad.confi5)eb35*false
Q Mlobal lo55in5 level
lo5Ad.threshold*info
Q 0et lo55er factory
lo5Ad.lo55erOactory*TJo5)efa3ltJo55erOactory
Q 0et root level
lo5Ad.rootJo55er*info%F)0
Q >reate root appender
lo5Ad.appender.F)0*TJo5F)0-ppender
lo5Ad.appender.F)0.layo3t*TJo59atternJayo3t
lo5Ad.appender.F)0.layo3t.pattern*Rp S Rc - RmRn
lo5Ad.appender.F)0.layo3t.dateOormat*nnss.III
Lo&&in& to ;:2 and to te console window
!he configuration below also logs messages to the console window. !his e/ample
configuration uses the unit 6og(onsole.ppender which is included in the demo/commons
folder. "t is not part of the 6ogJ) framework and only an e/ample implementation
provided for your convenience but without support.
Im,ortant !o use this configuration the main proGect file must contain the
6og(onsole.ppender unit
Q 0et internal deb355in5
lo5Ad.confi5)eb35*false
Q 0et lo55er factory
lo5Ad.lo55erOactory*TJo5)efa3ltJo55erOactory
Q 0et root level
lo5Ad.rootJo55er*info%F)0%>on#
Q >reate root appender
lo5Ad.appender.F)0*TJo5F)0-ppender
lo5Ad.appender.F)0.layo3t*TJo59atternJayo3t
lo5Ad.appender.F)0.layo3t.pattern*Rp S Rc - RmRn
lo5Ad.appender.F)0.layo3t.dateOormat*nnss.III
Q >reate a console appender
lo5Ad.appender.>on#*TJo5>onsole-ppender
lo5Ad.appender.>on#.append*tr3e
lo5Ad.appender.>on#.error:andler*TJo5FnlyFnceError:andler
lo5Ad.appender.>on#.layo3t*TJo59atternJayo3t
lo5Ad.appender.>on#.layo3t.pattern* R-5pS RmRn
lo5Ad.appender.>on#.layo3t.dateOormat*hhnnss.III
Lo& level
"n the configuration shown above the log level is set to CinfoE so it will only process log
messages with level info and higher :warnings and errors;9
*or debug purposes it can be helpful to show detailed messages. Oou can enable trace
logs by setting the global logging level or by setting the logging level for an individual log
appender.
lo5Ad.threshold*trace
0atces for new :el,i versions and )ree 0ascal
:el,i =7- and newer
!he 6ogJ) logging library uses the unit Consts. "n VE0 this unit is in the Rcl unit scope. "f
you see a compiler error about a missing >onsts unit add the unit scope name Rcl in the
8nit sco,e names option on the )elphi (ompiler page in +roGect Options.
BJ
:el,i =7" and newer
"n VEB %hort)ate*ormat has been moved to a new global variable *ormat%ettings in the
%ystem.%ys$tils unit.
"n the 6ogJ) source code replace 0etFption!)ateOormatFpt% 0hort)ateOormat&N with
0etFption!)ateOormatFpt% Oormat0ettin5s.0hort)ateOormat&N .
BJhttp9//docwiki.embarcadero.com/5.)%tudio/en/$nitM%copeM'ames
-o((in( "ith -o(41 73
)ree 0ascal
!o use 6ogJ) in *ree +ascal applications add this line to the 6ogJ) include file
libraries1lo&3d1:efines.inc9
FG>?/*!? >?=.<*HI@.J

!his will fi/ the compiler error message about the unknown type !(lass6ist.
Conditional 26mbols
HA+A.IAL;BBI%B
!his conditional symbol enables logging support. 6ogging support re3uires the open source
logging framework 6ogJ)
6ogJ) is available on %ourceforge at http9//logJd.sourceforge.net/
HA+A.IA.AWAT.AC7
Enables detailed logging of %tomp message frames.
"f this symbol is defined a compiler warning will be emitted9
>ompiled 4ith :-B-(@G(-WGT(->E
-ibrar= -i*itation! 75
Librar6 Limitations
2ession
Transacted 2essions
!he library supports transactional sendin& of messages with .ctiveM4 .pollo Hornet4
OpenM4 and 5abbitM4.
+roker5s,ecfic su,,ort
!ransactional acknowled&in& of incoming messages has been implemented and tested
with .pache .ctiveM4 ?.@.1 .pollo >.A and 5abbitM4 B.0.B.
Messa&eConsumer
How do I im,lement s6ncronous receive from multi,le
destinations?
!he library does not support synchronous receive from more than one destination over a
single connection. !o receive messages synchronously :using 5eceive and 5eceive'o&ait;
from two or more destinations create one connection per destination.
8ackground9 all pending messages in a connection are seriali=ed in one !(+ stream so
reading only the messages which come from one of the destinations would re3uire
<skipping< all messages for other destinations.
.synchronous receive using a Message6istener is not affected by this limitation.
Messa&e 0ro,erties
;nl6 strin& data t6,e su,,orted b6 2tom,
!he %!OM+ protocol uses string type key/value lists for the representation of message
properties. 5egardless of the method used to set message properties all message
properties will be interpreted as Java %trings by the Message 8roker.
.s a side effect the e/pressions in a %elector are limited to operations which are valid for
strings.
!imestamp properties are converted to a $ni/ time stamp value which is the internal
representation in Java. 8ut still these values can not be used with date type e/pressions.
+roker5s,ecific e*ce,tions
.pache .ctiveM4 ?.A introduced support for numeric e/pressions in JM% selectors
B?
.
Multi Treadin&
B8I a,,lication detection usin& 26stem.IsConsole
G$" applications re3uire thread synchroni=ation with the main R(6 thread.
!he library internally uses the S0stem.*sConsole flag to detect if it is a console or G$"
application and uses s0nc'roni5e() if S0stem.*sConsole is /alse.
However calling synchroni=e in a non,G$" application :for e/ample a "%.+" module; will
block the program e/ecution.
"f the library is used in a non,G$" application and the library seems to hang make sure
that S0stem.*sConsole is set to True.
%etting FGA..TK.? C4!S4=?J in the proGect source file is the easiest way to fi/ this.
;ter limitations
. session supports transactions and it is difficult to implement transactions that are multi,
threadedU a session should not be used concurrently by multiple threads.
I2A0I modules
"%.+" modules can use the library but they must set FGA..TK.? C4!S4=?J. !he Habari
(lient library internally uses the S0stem.*sConsole flag to detect if it is a console or G$"
application and uses s0nc'roni5e() if S0stem.*sConsole is /alse.
B? https9//issues.apache.org/Gira/browse/.M4,>A1@
:ro7er>!+ecific li*itation! 77
+roker5s,ecific limitations
:efault 0riorit6
!he JM% specification defines that the default priority value for a Message+roducer is J.
Habari (lient for .ctiveM4 adds a priority header to %tomp frames only if the message
producer has a non,default priority. !his has the advantage that the frame only has a
priority header when it is necessary to keep the message header small. However .pache
.ctiveM4 broker versions below ?.? use the value 1 :lowest; instead of J as default
priority for incoming %tomp messages.
%tarting with .pache .ctiveM4 ?.? the broker handles a missing priority header
correctly.
BA
BA https9//issues.apache.org/Gira/browse/.M4,B11A
;nline .esources
Tird50art6 Libraries
Internet :irect DInd6E
+roGect home http9//www.indyproGect.org/
)ocumentation http9//www.indyproGect.org/%ockets/)ocs/inde/.asp/
%napshot http9//indy.fulgan.com/S"+/
%ubversion https9//svn.ato=ed.com9JJJ/svn/"ndy>1/trunk
%ubversion docs http9//www.indyproGect.org/%ockets/)ownload/svn.asp/
26na,se
+roGect home http9//www.synapse.ararat.c=
%ubversion https9//synalist.svn.sourceforge.net/svnroot/synalist/trunk/
Lo&3:
+roGect home http9//sourceforge.net/proGects/logJd/
%ubversion svn9//svn.code.sf.net/p/logJd/code/trunk
%ative=ml
+roGect home http9//www.simdesign.nl//ml.html
Google home http9//simdesign.googlecode.com/
%ubversion http9//simdesign.googlecode.com/svn/trunk/
;mni=ML
+roGect home http9//code.google.com/p/omni/ml/
%ubversion http9//omni/ml.googlecode.com/svn/trunk/
0nline 9e!ource! 7$
2u,er;b>ect
+roGect home https9//code.google.com/p/superobGect/
G"! https9//code.google.com/p/superobGect/
2,ecifications
2tom, K %imple :or %treaming; !e/t Oriented Messaging
+rotocol
BH

%tomp home http9//stomp.github.io/inde/.html
%tomp >.1 http9//stomp.github.io/stomp,specification,>.1.html
%tomp >.> http9//stomp.github.io/stomp,specification,>.>.html
%tomp >.0 http9//stomp.github.io/stomp,specification,>.0.html
+roker5s,ecific documentation
.ctiveM4 http9//activem3.apache.org/stomp.html
.pollo http9//activem3.apache.org/apollo/documentation/stomp,manual.html
5abbitM4 https9//www.rabbitm3.com/stomp.html
;nline Articles
Title +roker
*irebird )atabase Events and Message,oriented Middleware
B2
.ll
"ntroducing connection pooling for Habari (lient libraries
B@
.ll
)iscover .ctiveM4 brokers with )elphi VEJ and "ndy >1.A
J1
.ctiveM4
BHhttp9//en.wikipedia.org/wiki/%treamingM!e/tMOrientedMMessagingM+rotocol
B2http9//mikeGustin.wordpress.com/01>0/>>/1A/firebird,database,events,and,message,
oriented,middleware/
B@http9//mikeGustin.wordpress.com/01>B/1A/1A/introducing,connection,pooling,for,habari,
client,libraries/
Official 5abbitM4 Management 5E%! .+" )ocumentation
J>
5abbitM4
How to use the 5abbitM4 &eb,%tomp +lugin
J0
5abbitM4
5+( with )elphi client and Java server using 5abbitM4
JB
5abbitM4
)elphi "ntegration with the Glass*ish vB .pplication %erver
JJ
OpenM4
;nline ?ideos
Title +roker
"ntroduction to Messaging &ith .pache .ctiveM4
J?
.ctiveM4
Glass*ish Message 4ueue , High .vailability (lusters
JA
OpenM4
J1http9//mikeGustin.wordpress.com/01>B/1H/1H/discover,activem3,brokers,with,delphi,/eJ,
and,indy,>1,A/
J>http9//mikeGustin.wordpress.com/01>0/>1/0A/official,rabbitm3,management,rest,api,
documentation/
J0http9//mikeGustin.wordpress.com/01>B/>>/0H/how,to,use,the,rabbitm3,web,stomp,plugin,
with,delphi,and,free,pascal/
JBhttp9//mikeGustin.wordpress.com/01>B/1?/0>/rpc,with,delphi,client,and,Gava,server,using,
rabbitm3/
JJhttps9//mikeGustin.fogbug=.com/default.aspT&>>
J?http9//vimeo.com/>0A?J?>B
JAhttp9//www.youtube.com/watchTvP5H$J8syBud$
'u++ort 8%
2u,,ort
+u& re,orts
. public bug tracking system is available at https9//mikeGustin.fogbug=.com/ , no login is
re3uired. +lease select the product from the list of proGects so we know which library
version is affected by the problem.
2u,,ort in/uiries
+lease send support in3uiries to support\habarisoft.com
!o allow fast processing of your in3uiry please provide a detailed problem description
including configuration and environment or code e/amples which help to reproduce the
problem.
Advanced su,,ort
.dvanced and e/perimental features such as :for e/ample; %%6 third party libraries *ree
+ascal 6inu/ non,$nicode )elphi versions and message broker configuration are not
covered by the basic support scheme.
Inde*
Reference
.pplication integration...........................?
.synchronous receive...........................H?
8inary Message...................................B2
8orrow(onnection...............................02
8roker %tatistics..................................AB
8!(omm.dapter"ndy...........................>@
8!JM%(onnection................................J0
8!%erial"ntf........................................J0
8!%treamHelper..................................B2
(lient notification..................................?
(onfiguration file.................................H1
(onnection.........................................>@
(onnection $56...................................01
(onnection*actory...............................>@
(onnect!imeout..................................>A
(onsts...............................................H0
(onsumer!ool.....................................?J
(reate)urable%ubscriber......................JH
(reateObGectMessage...........................J0
(ron..................................................A?
)efines.inc..........................................HB
)elayed )elivery.................................A?
)estination.........................................0@
)isconnect 5eceipts.............................0B
)isconnect.receipt...............................0B
*ailover %upport..................................0A
H.8.5"M6OGG"'G.........................H1 HJ
H.8.5"M5.&M!5.(E...........................HJ
"(onnection........................................>@
")estination......................................."9
"MapMessage......................................AB
"Message..........................................."9
"Message(onsumer............................."9
"Message6istener................................"9
"Message+roducer...............................J0
"nternet...............................................?
"nternet )irect :"ndy;..........................'-
"nterprocess (ommunication...................?
"+oolable"nterface*actory.....................0H
"%.+".............................................? HA
"s(onsole...........................................HA
"%ession.............................................J0
Java7..................................................?
JM% %elector.......................................BB
JM%(orrelation").................................AA
JM%)eliveryMode.................................AA
JM%E/piration.....................................AA
JM%Message"d.....................................AA
JM%+riority.........................................AA
JM%5eply!o...................................AB AA
JM%!imestamp....................................AA
JM%VGroup")......................................AH
JM%VGroup%e3....................................AH
6imitations....................................>A H?
6kJ%O'..............................................J>
6oad balancing......................................?
6oad8ytes*rom%tream.........................B2
6ocal (onnection.................................01
6ogJ)..........................................H1 HJ
6ogJ) configuration.............................H1
6ogJd.props........................................H>
6og(onsole.ppender............................H>
6ogging..........................................? H1
Map Message......................................J?
Message (onsumer..............................B0
Message +roducer................................B0
Message properties..............................H?
Message 5eceipts................................00
Message6istener..................................H?
Message!ransformer............................J>
Multi !hreading...................................HA
Multiple destinations............................H?
'ativeVml...........................................J>
ObGect Message...................................B@
O)%...................................................H>
OmniVM6............................................J>
OnMessage.........................................BA
Output)ebug%tring..............................H>
+H+.....................................................?
+oint,to,point..................................? 0@
+roducer!ool.......................................?A
+rogramming Model.............................>2
+ublish and subscribe...........................0@
+ublish/subscribe..................................?
4ueue................................................0@
5eceive..............................................BH
5eceive'o&ait....................................BH
5eturn(onnection................................02
Inde2 83
%ample+oGo........................................J>
%cheduler...........................................A?
%elector.............................................H?
%end.receipt.......................................00
%ession..............................................01
%et!ransformer...................................J0
%ubscribe.receipt.................................00
%uperObGect........................................J>
%ynapse.......................................'-C >A
%ynchronous receive............................H?
!8!(onnection+ool..............................02
!8!JM%(onnection...............................>@
!8!JM%(onnection*actory...............>@ 02
!8!+oolable(onnection*actory..............0H
!(+...................................................H?
!cp.keepalive......................................0B
!e/t Message......................................B?
!hroughput !est !ool...........................A1
!opic..................................................B1
!opic%ubscriber...................................JH
!ransacted %essions.......................0J H?
!ransactions.......................................HA
!ransformation....................................J0
!ransformation,custom........................JB
$nit scope names................................H0
Rcl.....................................................H0
VE0...................................................H0
V+ath.................................................BB
I.++!O+E...........................................HA
Table Index
(ommunication .dapters........................................................................................>A
(ommunication .dapters with %%6 %upport...............................................................>H
%ession creation parameters...................................................................................00
*ailover !ransport Options......................................................................................0H
Message !ransformer "mplementations....................................................................J>
E/ample .pplications :in alphabetic order;................................................................?0
(onsumer!ool (ommand 6ine Options......................................................................?J
+roducer!ool (ommand 6ine Options.......................................................................?A
!hroughput !est !ool (ommand 6ine Options............................................................A1
.dvanced )emo .pplications...................................................................................A0
Illustration Index
"llustration >9 .ctiveM4 ?.@.1 running......................................................................>B
"llustration 09 +rogramming Model...........................................................................>2
"llustration B9 (onsumer!ool demo application..........................................................?J
"llustration J9 +roducer!ool demo application............................................................?A
"llustration ?9 +erformance !est .pplication..............................................................?2
"llustration A9 (lick in the $56 field to open the configuration dialog.............................?@
"llustration H9 !hroughput test tool output................................................................A1

Habari Active MQ Getting Started

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Habari Active MQ Getting Started

Uploaded by

Copyright:

Available Formats

Getting started with

Habari Client for

You might also like