1.1

1.2

1.3

1.4

1.5

1.6

1.7

1.8

1.9

1.10

1.11

1.12

1.13

1.14

1.15

1.16

1.17

1.18

1.19

1.20

1.21

1.22

1.23

1.24

1.25

1.26

1.27

TableofContentsIntroduction

LegalNotice

Preface

ProjectInfo

MessagingConcepts

Architecture

UsingtheServer

UsingJMS

UsingCore

MappingJMSConceptstotheCoreAPI

TheClientClasspath

Examples

RoutingMessagesWithWildCards

UnderstandingtheApacheActiveMQArtemisWildcardSyntax

FilterExpressions

Persistence

ConfiguringTransports

ConfigurationReload

DetectingDeadConnections

DetectingSlowConsumers

ResourceManagerConfiguration

FlowControl

Guaranteesofsendsandcommits

MessageRedeliveryandUndeliveredMessages

MessageExpiry

LargeMessages

Paging

1

1.28

1.29

1.30

1.31

1.32

1.33

1.34

1.35

1.36

1.37

1.38

1.39

1.40

1.41

1.42

1.43

1.44

1.45

1.46

1.47

1.48

1.49

1.50

1.51

1.52

1.53

1.54

1.55

1.56

1.57

QueueAttributes

ScheduledMessages

Last-ValueQueues

MessageGrouping

ExtraAcknowledgeModes

Management

Security

ResourceLimits

TheJMSBridge

ClientReconnectionandSessionReattachment

DivertingandSplittingMessageFlows

CoreBridges

DuplicateMessageDetection

Clusters

HighAvailabilityandFailover

GracefulServerShutdown

LibaioNativeLibraries

Threadmanagement

Logging

RESTInterface

EmbeddingApacheActiveMQArtemis

ApacheKaraf

SpringIntegration

AeroGearIntegration

VertXIntegration

CDIIntegration

InterceptingOperations

ProtocolsandInteroperability

Tools

MavenPlugin

2

1.58

1.59

1.60

UnitTesting

TroubleshootingandPerformanceTuning

ConfigurationReference

3

ApacheActiveMQArtemisUserManualTheUsermanualisanindepthmanualonallaspectsofApacheActiveMQArtemis

Introduction

4

LegalNoticeLicensedtotheApacheSoftwareFoundation(ASF)underoneormorecontributorlicenseagreements.SeetheNOTICEfiledistributedwiththisworkforadditionalinformationregardingcopyrightownership.TheASFlicensesthisfiletoYouundertheApacheLicense,Version2.0(the"License");youmaynotusethisfileexceptincompliancewiththeLicense.YoumayobtainacopyoftheLicenseat

http://www.apache.org/licenses/LICENSE-2.0

Unlessrequiredbyapplicablelaworagreedtoinwriting,softwaredistributedundertheLicenseisdistributedonan"ASIS"BASIS,WITHOUTWARRANTIESORCONDITIONSOFANYKIND,eitherexpressorimplied.SeetheLicenseforthespecificlanguagegoverningpermissionsandlimitationsundertheLicense.

LegalNotice

5

http://www.apache.org/licenses/LICENSE-2.0

PrefaceWhatisApacheActiveMQArtemis?

ApacheActiveMQArtemisisanopensourceprojecttobuildamulti-protocol,embeddable,veryhighperformance,clustered,asynchronousmessagingsystem.

ApacheActiveMQArtemisisanexampleofMessageOrientedMiddleware(MoM).ForadescriptionofMoMsandothermessagingconceptspleaseseetheMessagingConcepts.

ForanswerstomorequestionsaboutwhatApacheActiveMQArtemisisandwhatitisn'tpleasevisittheFAQswikipage.

WhyuseApacheActiveMQArtemis?Herearejustafewofthereasons:

100%opensourcesoftware.ApacheActiveMQArtemisislicensedusingtheApacheSoftwareLicensev2.0tominimisebarrierstoadoption.

ApacheActiveMQArtemisisdesignedwithusabilityinmind.

WritteninJava.RunsonanyplatformwithaJava8+runtime,that'severythingfromWindowsdesktopstoIBMmainframes.

Amazingperformance.Ourground-breakinghighperformancejournalprovidespersistentmessagingperformanceatratesnormallyseenfornon-persistentmessaging,ournon-persistentmessagingperformancerockstheboattoo.

Fullfeatureset.Allthefeaturesyou'dexpectinanyseriousmessagingsystem,andothersyouwon'tfindanywhereelse.

Elegant,clean-cutdesignwithminimalthirdpartydependencies.RunActiveMQArtemisstand-alone,runitinintegratedinyourfavouriteJEEapplicationserver,orrunitembeddedinsideyourownproduct.It'suptoyou.

Seamlesshighavailability.WeprovideaHAsolutionwithautomaticclientfailoversoyoucanguaranteezeromessagelossorduplicationineventofserverfailure.

Hugelyflexibleclustering.Createclustersofserversthatknowhowtoloadbalancemessages.Linkgeographicallydistributedclustersoverunreliableconnectionstoformaglobalnetwork.Configureroutingofmessagesinahighlyflexibleway.

Preface

6

Preface

7

ProjectInformationTheofficialApacheActiveMQArtemisprojectpageishttp://activemq.apache.org/artemis/.

SoftwareDownloadThesoftwarecanbedownloadfromtheDownloadpage:http://activemq.apache.org/download.html

ProjectInformationIfyouhaveanyuserquestionspleaseuseouruserforum

Ifyouhavedevelopmentrelatedquestions,pleaseuseourdeveloperforum

PopinandchattousinourIRCchannel

ApacheActiveMQArtemisGitrepositoryishttps://github.com/apache/activemq-artemis

Allreleasetagsareavailablefromhttps://github.com/apache/activemq-artemis/releases

Andmanythankstoallourcontributors,botholdandnewwhohelpedcreateApacheActiveMQArtemis.

ProjectInfo

8

http://activemq.apache.org/artemis/http://activemq.apache.org/download.htmlhttp://activemq.2283324.n4.nabble.com/ActiveMQ-User-f2341805.htmlhttp://activemq.2283324.n4.nabble.com/ActiveMQ-Dev-f2368404.htmlirc://irc.freenode.net:6667/apache-activemqhttps://github.com/apache/activemq-artemishttps://github.com/apache/activemq-artemis/releases

MessagingConceptsApacheActiveMQArtemisisanasynchronousmessagingsystem,anexampleofMessageOrientedMiddleware,we'lljustcallthemmessagingsystemsintheremainderofthisbook.

We'llfirstpresentabriefoverviewofwhatkindofthingsmessagingsystemsdo,wherethey'reusefulandthekindofconceptsyou'llhearaboutinthemessagingworld.

Ifyou'realreadyfamiliarwithwhatamessagingsystemisandwhatit'scapableof,thenyoucanskipthischapter.

MessagingConceptsMessagingsystemsallowyoutolooselycoupleheterogeneoussystemstogether,whilsttypicallyprovidingreliability,transactionsandmanyotherfeatures.

UnlikesystemsbasedonaRemoteProcedureCall(RPC)pattern,messagingsystemsprimarilyuseanasynchronousmessagepassingpatternwithnotightrelationshipbetweenrequestsandresponses.Mostmessagingsystemsalsosupportarequest-responsemodebutthisisnotaprimaryfeatureofmessagingsystems.

Designingsystemstobeasynchronousfromend-to-endallowsyoutoreallytakeadvantageofyourhardwareresources,minimizingtheamountofthreadsblockingonIOoperations,andtouseyournetworkbandwidthtoitsfullcapacity.WithanRPCapproachyouhavetowaitforaresponseforeachrequestyoumakesoarelimitedbythenetworkroundtriptime,orlatencyofyournetwork.Withanasynchronoussystemyoucanpipelineflowsofmessagesindifferentdirections,soarelimitedbythenetworkbandwidthnotthelatency.Thistypicallyallowsyoutocreatemuchhigherperformanceapplications.

Messagingsystemsdecouplethesendersofmessagesfromtheconsumersofmessages.Thesendersandconsumersofmessagesarecompletelyindependentandknownothingofeachother.Thisallowsyoutocreateflexible,looselycoupledsystems.

Often,largeenterprisesuseamessagingsystemtoimplementamessagebuswhichlooselycouplesheterogeneoussystemstogether.MessagebusesoftenformthecoreofanEnterpriseServiceBus.(ESB).Usingamessagebustode-coupledisparatesystems

MessagingConcepts

9

http://en.wikipedia.org/wiki/Message_oriented_middlewarehttp://en.wikipedia.org/wiki/Remote_procedure_callhttp://en.wikipedia.org/wiki/Enterprise_service_bus

canallowthesystemtogrowandadaptmoreeasily.Italsoallowsmoreflexibilitytoaddnewsystemsorretireoldonessincetheydon'thavebrittledependenciesoneachother.

MessagingstylesMessagingsystemsnormallysupporttwomainstylesofasynchronousmessaging:messagequeuemessaging(alsoknownaspoint-to-pointmessaging)andpublishsubscribemessaging.We'llsummarisethembrieflyhere:

TheMessageQueuePattern

Withthistypeofmessagingyousendamessagetoaqueue.Themessageisthentypicallypersistedtoprovideaguaranteeofdelivery,thensometimelaterthemessagingsystemdeliversthemessagetoaconsumer.Theconsumerthenprocessesthemessageandwhenitisdone,itacknowledgesthemessage.Oncethemessageisacknowledgeditdisappearsfromthequeueandisnotavailabletobedeliveredagain.Ifthesystemcrashesbeforethemessagingserverreceivesanacknowledgementfromtheconsumer,thenonrecovery,themessagewillbeavailabletobedeliveredtoaconsumeragain.

Withpoint-to-pointmessaging,therecanbemanyconsumersonthequeuebutaparticularmessagewillonlyeverbeconsumedbyamaximumofoneofthem.Senders(alsoknownasproducers)tothequeuearecompletelydecoupledfromreceivers(alsoknownasconsumers)ofthequeue-theydonotknowofeachother'sexistence.

Aclassicexampleofpointtopointmessagingwouldbeanorderqueueinacompany'sbookorderingsystem.Eachorderisrepresentedasamessagewhichissenttotheorderqueue.Let'simaginetherearemanyfrontendorderingsystemswhichsendorderstotheorderqueue.Whenamessagearrivesonthequeueitispersisted-thisensuresthatiftheservercrashestheorderisnotlost.Let'salsoimaginetherearemanyconsumersontheorderqueue-eachrepresentinganinstanceofanorderprocessingcomponent-thesecanbeondifferentphysicalmachinesbutconsumingfromthesamequeue.Themessagingsystemdeliverseachmessagetooneandonlyoneoftheorderingprocessingcomponents.Differentmessagescanbeprocessedbydifferentorderprocessors,butasingleorderisonlyprocessedbyoneorderprocessor-thisensuresordersaren'tprocessedtwice.

MessagingConcepts

10

http://en.wikipedia.org/wiki/Message_queuehttp://en.wikipedia.org/wiki/Publish_subscribe

Asanorderprocessorreceivesamessage,itfulfillstheorder,sendsorderinformationtothewarehousesystemandthenupdatestheorderdatabasewiththeorderdetails.Onceit'sdonethatitacknowledgesthemessagetotelltheserverthattheorderhasbeenprocessedandcanbeforgottenabout.Oftenthesendtothewarehousesystem,updateindatabaseandacknowledgementwillbecompletedinasingletransactiontoensureACIDproperties.

ThePublish-SubscribePattern

Withpublish-subscribemessagingmanysenderscansendmessagestoanentityontheserver,oftencalledatopic(e.g.intheJMSworld).

Therecanbemanysubscriptionsonatopic,asubscriptionisjustanotherwordforaconsumerofatopic.Eachsubscriptionreceivesacopyofeachmessagesenttothetopic.Thisdiffersfromthemessagequeuepatternwhereeachmessageisonlyconsumedbyasingleconsumer.

Subscriptionscanoptionallybedurablewhichmeanstheyretainacopyofeachmessagesenttothetopicuntilthesubscriberconsumesthem-eveniftheservercrashesorisrestartedinbetween.Non-durablesubscriptionsonlylastamaximumofthelifetimeoftheconnectionthatcreatedthem.

Anexampleofpublish-subscribemessagingwouldbeanewsfeed.Asnewsarticlesarecreatedbydifferenteditorsaroundtheworldtheyaresenttoanewsfeedtopic.Therearemanysubscribersaroundtheworldwhoareinterestedinreceivingnewsitems-eachonecreatesasubscriptionandthemessagingsystemensuresthatacopyofeachnewsmessageisdeliveredtoeachsubscription.

DeliveryguaranteesAkeyfeatureofmostmessagingsystemsisreliablemessaging.Withreliablemessagingtheservergivesaguaranteethatthemessagewillbedeliveredonceandonlyoncetoeachconsumerofaqueueoreachdurablesubscriptionofatopic,evenintheeventofsystemfailure.Thisiscrucialformanybusinesses;e.g.youdon'twantyourordersfulfilledmorethanonceoranyofyourorderstobelost.

Inothercasesyoumaynotcareaboutaonceandonlyoncedeliveryguaranteeandarehappytocopewithduplicatedeliveriesorlostmessages-anexampleofthismightbetransientstockpriceupdates-whicharequicklysupersededbythenextupdateonthe

MessagingConcepts

11

http://en.wikipedia.org/wiki/ACID

samestock.Themessagingsystemallowsyoutoconfigurewhichdeliveryguaranteesyourequire.

TransactionsMessagingsystemstypicallysupportthesendingandacknowledgementofmultiplemessagesinasinglelocaltransaction.ApacheActiveMQArtemisalsosupportsthesendingandacknowledgementofmessageaspartofalargeglobaltransaction-usingtheJavamappingofXA:JTA.

DurabilityMessagesareeitherdurableornondurable.Durablemessageswillbepersistedinpermanentstorageandwillsurviveserverfailureorrestart.Nondurablemessageswillnotsurviveserverfailureorrestart.Examplesofdurablemessagesmightbeordersortrades,wheretheycannotbelost.Anexampleofanondurablemessagemightbeastockpriceupdatewhichistransitoryanddoesn'tneedtosurvivearestart.

MessagingAPIsandprotocolsHowdoclientapplicationsinteractwithmessagingsystemsinordertosendandconsumemessages?

SeveralmessagingsystemsprovidetheirownproprietaryAPIswithwhichtheclientcommunicateswiththemessagingsystem.

Therearealsosomestandardwaysofoperatingwithmessagingsystemsandsomeemergingstandardsinthisspace.

Let'stakeabrieflookatthese:

JavaMessageService(JMS)

JMSispartofOracle'sJEEspecification.It'saJavaAPIthatencapsulatesbothmessagequeueandpublish-subscribemessagingpatterns.JMSisalowestcommondenominatorspecification-i.e.itwascreatedtoencapsulatecommonfunctionalityofthealreadyexistingmessagingsystemsthatwereavailableatthetimeofitscreation.

MessagingConcepts

12

http://en.wikipedia.org/wiki/Java_Message_Service

JMSisaverypopularAPIandisimplementedbymostmessagingsystems.JMSisonlyavailabletoclientsrunningJava.

JMSdoesnotdefineastandardwireformat-itonlydefinesaprogrammaticAPIsoJMSclientsandserversfromdifferentvendorscannotdirectlyinteroperatesinceeachwillusethevendor'sowninternalwireprotocol.

ApacheActiveMQArtemisprovidesafullycompliantJMS1.1andJMS2.0API.

SystemspecificAPIs

ManysystemsprovidetheirownprogrammaticAPIforwhichtointeractwiththemessagingsystem.Theadvantageofthisitallowsthefullsetofsystemfunctionalitytobeexposedtotheclientapplication.API'slikeJMSarenotnormallyrichenoughtoexposealltheextrafeaturesthatmostmessagingsystemsprovide.

ApacheActiveMQArtemisprovidesitsowncoreclientAPIforclientstouseiftheywishtohaveaccesstofunctionalityoverandabovethataccessibleviatheJMSAPI.

RESTfulAPI

RESTapproachestomessagingareshowingalotinterestrecently.

ItseemsplausiblethatAPIstandardsforcloudcomputingmayconvergeonaRESTstylesetofinterfacesandconsequentlyaRESTmessagingapproachisaverystrongcontenderforbecomingthede-factomethodformessaginginteroperability.

WithaRESTapproachmessagingresourcesaremanipulatedasresourcesdefinedbyaURIandtypicallyusingasimplesetofoperationsonthoseresources,e.g.PUT,POST,GETetc.RESTapproachestomessagingoftenuseHTTPastheirunderlyingprotocol.

TheadvantageofaRESTapproachwithHTTPisinitssimplicityandthefacttheinternetisalreadytunedtodealwithHTTPoptimally.

PleaseseeRestInterfaceforusingApacheActiveMQArtemis'sRESTfulinterface.

STOMP

Stompisaverysimpletextprotocolforinteroperatingwithmessagingsystems.Itdefinesawireformat,sotheoreticallyanyStompclientcanworkwithanymessagingsystemthatsupportsStomp.Stompclientsareavailableinmanydifferentprogramminglanguages.

MessagingConcepts

13

http://en.wikipedia.org/wiki/Representational_State_Transferhttp://stomp.github.io/

PleaseseeStompforusingSTOMPwithApacheActiveMQArtemis.

AMQP

AMQPisaspecificationforinteroperablemessaging.Italsodefinesawireformat,soanyAMQPclientcanworkwithanymessagingsystemthatsupportsAMQP.AMQPclientsareavailableinmanydifferentprogramminglanguages.

ApacheActiveMQArtemisimplementstheAMQP1.0specification.Anyclientthatsupportsthe1.0specificationwillbeabletointeractwithApacheActiveMQArtemis.

HighAvailabilityHighAvailability(HA)meansthatthesystemshouldremainoperationalafterfailureofoneormoreoftheservers.ThedegreeofsupportforHAvariesbetweenvariousmessagingsystems.

ApacheActiveMQArtemisprovidesautomaticfailoverwhereyoursessionsareautomaticallyreconnectedtothebackupserveroneventofliveserverfailure.

FormoreinformationonHA,pleaseseeHighAvailabilityandFailover.

ClustersManymessagingsystemsallowyoutocreategroupsofmessagingserverscalledclusters.Clustersallowtheloadofsendingandconsumingmessagestobespreadovermanyservers.Thisallowsyoursystemtoscalehorizontallybyaddingnewserverstothecluster.

Degreesofsupportforclustersvariesbetweenmessagingsystems,withsomesystemshavingfairlybasicclusterswiththeclustermembersbeinghardlyawareofeachother.

ApacheActiveMQArtemisprovidesveryconfigurablestate-of-the-artclusteringmodelwheremessagescanbeintelligentlyloadbalancedbetweentheserversinthecluster,accordingtothenumberofconsumersoneachnode,andwhethertheyarereadyformessages.

ApacheActiveMQArtemisalsohastheabilitytoautomaticallyredistributemessagesbetweennodesofaclustertopreventstarvationonanyparticularnode.

MessagingConcepts

14

http://en.wikipedia.org/wiki/AMQPhttps://www.oasis-open.org/committees/tc_home.php?wg_abbrev=amqp

Forfulldetailsonclustering,pleaseseeClusters.

BridgesandroutingSomemessagingsystemsallowisolatedclustersorsinglenodestobebridgedtogether,typicallyoverunreliableconnectionslikeawideareanetwork(WAN),ortheinternet.

Abridgenormallyconsumesfromaqueueononeserverandforwardsmessagestoanotherqueueonadifferentserver.Bridgescopewithunreliableconnections,automaticallyreconnectingwhentheconnectionsbecomesavailableagain.

ApacheActiveMQArtemisbridgescanbeconfiguredwithfilterexpressionstoonlyforwardcertainmessages,andtransformationcanalsobehookedin.

ApacheActiveMQArtemisalsoallowsroutingbetweenqueuestobeconfiguredinserversideconfiguration.Thisallowscomplexroutingnetworkstobesetupforwardingorcopyingmessagesfromonedestinationtoanother,formingaglobalnetworkofinterconnectedbrokers.

FormoreinformationpleaseseeCoreBridgesandDivertingandSplittingMessageFlows.

MessagingConcepts

15

ArchitectureInthissectionwewillgiveanoverviewoftheApacheActiveMQArtemishighlevelarchitecture.

CoreArchitectureApacheActiveMQArtemiscoreisdesignedsimplyassetofPlainOldJavaObjects(POJOs)-wehopeyoulikeitsclean-cutdesign.

We'vealsodesignedittohaveasfewdependenciesonexternaljarsaspossible.Infact,ApacheActiveMQArtemiscorehasonlyonejardependency,netty.jar,otherthanthestandardJDKclasses!Thisisbecauseweusesomeofthenettybufferclassesinternally.

ThisallowsApacheActiveMQArtemistobeeasilyembeddedinyourownproject,orinstantiatedinanydependencyinjectionframeworksuchasSpringorGoogleGuice.

EachApacheActiveMQArtemisserverhasitsownultrahighperformancepersistentjournal,whichitusesformessageandotherpersistence.

Usingahighperformancejournalallowsoutrageouspersistencemessageperformance,somethingnotachievablewhenusingarelationaldatabaseforpersistence.

ApacheActiveMQArtemisclients,potentiallyondifferentphysicalmachinesinteractwiththeApacheActiveMQArtemisserver.ApacheActiveMQArtemiscurrentlyprovidestwoAPIsformessagingattheclientside:

1. CoreclientAPI.ThisisasimpleintuitiveJavaAPIthatallowsthefullsetofmessagingfunctionalitywithoutsomeofthecomplexitiesofJMS.

2. JMSclientAPI.ThestandardJMSAPIisavailableattheclientside.

ApacheActiveMQArtemisalsoprovidesdifferentprotocolimplementationsontheserversoyoucanuserespectiveclientsfortheseprotocols:

1. Stomp2. OpenWire3. AMQP

Architecture

16

JMSsemanticsareimplementedbyaJMSfacadelayerontheclientside.

TheApacheActiveMQArtemisserverdoesnotspeakJMSandinfactdoesnotknowanythingaboutJMS,itisaprotocolagnosticmessagingserverdesignedtobeusedwithmultipledifferentprotocols.

WhenauserusestheJMSAPIontheclientside,allJMSinteractionsaretranslatedintooperationsontheApacheActiveMQArtemiscoreclientAPIbeforebeingtransferredoverthewireusingtheApacheActiveMQArtemiswireformat.

TheserveralwaysjustdealswithcoreAPIinteractions.

Aschematicillustratingthisrelationshipisshowninfigure3.1below:

Architecture

17

Architecture

18

Figure3.1showstwouserapplicationsinteractingwithanApacheActiveMQArtemisserver.UserApplication1isusingtheJMSAPI,whileUserApplication2isusingthecoreclientAPIdirectly.

YoucanseefromthediagramthattheJMSAPIisimplementedbyathinfacadelayerontheclientside.

ApacheActiveMQArtemisembeddedinyourownapplicationApacheActiveMQArtemiscoreisdesignedasasetofsimplePOJOssoifyouhaveanapplicationthatrequiresmessagingfunctionalityinternallybutyoudon'twanttoexposethatasanApacheActiveMQArtemisserveryoucandirectlyinstantiateandembedApacheActiveMQArtemisserversinyourownapplication.

FormoreinformationonembeddingApacheActiveMQArtemis,seeEmbeddingApacheActiveMQArtemis.

ApacheActiveMQArtemisintegratedwithaJavaEEapplicationserverApacheActiveMQArtemisprovidesitsownfullyfunctionalJavaConnectorArchitecture(JCA)adaptorwhichenablesittobeintegratedeasilyintoanyJavaEEcompliantapplicationserverorservletengine.

JavaEEapplicationserversprovideMessageDrivenBeans(MDBs),whichareaspecialtypeofEnterpriseJavaBeans(EJBs)thatcanprocessmessagesfromsourcessuchasJMSsystemsormailsystems.

ProbablythemostcommonuseofanMDBistoconsumemessagesfromaJMSmessagingsystem.

AccordingtotheJavaEEspecification,aJavaEEapplicationserverusesaJCAadaptertointegratewithaJMSmessagingsystemsoitcanconsumemessagesforMDBs.

However,theJCAadapterisnotonlyusedbytheJavaEEapplicationserverforconsumingmessagesviaMDBs,itisalsousedwhensendingmessagetotheJMSmessagingsysteme.g.frominsideanEJBorservlet.

Architecture

19

WhenintegratingwithaJMSmessagingsystemfrominsideaJavaEEapplicationserveritisalwaysrecommendedthatthisisdoneviaaJCAadaptor.Infact,communicatingwithaJMSmessagingsystemdirectly,withoutusingJCAwouldbeillegalaccordingtotheJavaEEspecification.

Theapplicationserver'sJCAserviceprovidesextrafunctionalitysuchasconnectionpoolingandautomatictransactionenlistment,whicharedesirablewhenusingmessaging,say,frominsideanEJB.ItispossibletotalktoaJMSmessagingsystemdirectlyfromanEJB,MDBorservletwithoutgoingthroughaJCAadapter,butthisisnotrecommendedsinceyouwillnotbeabletotakeadvantageoftheJCAfeatures,suchascachingofJMSsessions,whichcanresultinpoorperformance.

Figure3.2belowshowsaJavaEEapplicationserverintegratingwithaApacheActiveMQArtemisserverviatheApacheActiveMQArtemisJCAadaptor.NotethatallcommunicationbetweenEJBsessionsorentitybeansandMessageDrivenbeansgothroughtheadaptorandnotdirectlytoApacheActiveMQArtemis.

ThelargearrowwiththeprohibitedsignshowsanEJBsessionbeantalkingdirectlytotheApacheActiveMQArtemisserver.Thisisnotrecommendedasyou'llmostlikelyendupcreatinganewconnectionandsessioneverytimeyouwanttointeractfromtheEJB,whichisananti-pattern.

Architecture

20

FormoreinformationonusingtheJCAadaptor,pleaseseeApplicationServerIntegrationandJavaEE.

Architecture

21

ApacheActiveMQArtemisstand-aloneserverApacheActiveMQArtemiscanalsobedeployedasastand-aloneserver.ThismeansafullyindependentmessagingservernotdependentonaJavaEEapplicationserver.

Thestandardstand-alonemessagingserverconfigurationcomprisesacoremessagingserverandaJMSservice.

TheroleoftheJMSServiceistodeployanyJMSQueue,TopicandConnectionFactoryinstancesfromanyserversideJMSconfiguration.ItalsoprovidesasimplemanagementAPIforcreatinganddestroyingQueuesandTopicswhichcanbeaccessedviaJMXortheconnection.ItisaseparateservicetotheActiveMQArtemiscoreserver,sincethecoreserverisJMSagnostic.Ifyoudon'twanttodeployanyJMSQueueorTopicviaserversideXMLconfigurationanddon'trequireaJMSmanagementAPIontheserversidethenyoucandisablethisservice.

Thestand-aloneserverconfigurationusesAirlineforbootstrappingtheBroker.

Thestand-aloneserverarchitectureisshowninfigure3.3below:

Architecture

22

https://github.com/airlift/airline

FormoreinformationonserverconfigurationfilesseeServerConfiguration

Architecture

23

Architecture

24

UsingtheServerThischapterwillfamiliariseyouwithhowtousetheApacheActiveMQArtemisserver.

We'llshowwhereitis,howtostartandstopit,andwe'lldescribethedirectorylayoutandwhatallthefilesareandwhattheydo.

FortheremainderofthischapterwhenwetalkabouttheApacheActiveMQArtemisserverwemeantheApacheActiveMQArtemisstandaloneserver,initsdefaultconfigurationwithaJMSServiceenabled.

ThisdocumentwillrefertothefullpathofthedirectorywheretheActiveMQdistributionhasbeenextractedtoas${ARTEMIS_HOME}directory.

InstallationAfterdownloadingthedistribution,thefollowinghighlightssomeimportantfoldersonthedistribution:

|___bin||___web||___user-manual||___api||___examples||___core||___javaee||___jms||___lib||___schema

bin--binariesandscriptsneededtorunActiveMQArtemis.

web--ThefolderwherethewebcontextisloadedwhenActiveMQArtemisruns.

user-manual--Theusermanualisplacedunderthewebfolder.

api--Theapidocumentationisplacedunderthewebfolder

UsingtheServer

25

examples--JMSandJavaEEexamples.Pleaserefertothe'runningexamples'chapterfordetailsonhowtorunthem.

lib--jarsandlibrariesneededtorunActiveMQArtemis

licenses--licensesforActiveMQArtemis

schemas--XMLSchemasusedtovalidateActiveMQArtemisconfigurationfiles

CreatingaBrokerInstanceAbrokerinstanceisthedirectorycontainingalltheconfigurationandruntimedata,suchaslogsanddatafiles,associatedwithabrokerprocess.Itisrecommendedthatyoudonotcreatetheinstancedirectoryunder${ARTEMIS_HOME}.ThisseparationisencouragedsothatyoucanmoreeasilyupgradewhenthenextversionofActiveMQArtemisisreleased.

OnUnixsystems,itisacommonconventiontostorethiskindofruntimedataunderthe/var/libdirectory.Forexample,tocreateaninstanceat'/var/lib/mybroker',runthefollowingcommandsinyourcommandlineshell:

cd/var/lib${ARTEMIS_HOME}/bin/artemiscreatemybroker

Abrokerinstancedirectorywillcontainthefollowingsubdirectories:

bin:holdsexecutionscriptsassociatedwiththisinstance.etc:holdtheinstanceconfigurationfilesdata:holdsthedatafilesusedforstoringpersistentmessageslog:holdsrotatinglogfilestmp:holdstemporaryfilesthataresafetodeletebetweenbrokerruns

Atthispointyoumaywanttoadjustthedefaultconfigurationlocatedintheetcdirectory.

Options

Thereareseveraloptionsyoucanusewhencreatinganinstance.

Forafulllistofupdatedpropertiesalwaysuse:

UsingtheServer

26

$./artemishelpcreateNAMEartemiscreate-createsanewbrokerinstance

SYNOPSISartemiscreate[--allow-anonymous][--cluster-password][--cluster-user][--clustered][--data][--encoding][--force][--home][--host][--java-options][--password][--port-offset][--replicated][--role][--shared-store][--silent][--user][--]

OPTIONS--allow-anonymousEnablesanonymousconfigurationonsecurity(Default:input)

--cluster-passwordTheclusterpasswordtouseforclustering.(Default:input)

--cluster-userTheclusterusertouseforclustering.(Default:input)

--clusteredEnableclustering

--dataDirectorywhereActiveMQDataisused.Patharerelativetoartemis.instance/bin

--encodingTheencodingthattextfilesshoulduse

--forceOverwriteconfigurationatdestinationdirectory

--homeDirectorywhereActiveMQArtemisisinstalled

--hostThehostnameofthebroker(Default:0.0.0.0orinputifclustered)

--java-optionsExtrajavaoptionstobepassedtotheprofile

--passwordTheuser'spassword(Default:input)

--port-offset

UsingtheServer

27

Offsetsthedefaultports

--replicatedEnablebrokerreplication

--roleThenamefortherolecreated(Default:amq)

--shared-storeEnablebrokersharedstore

--silentItwilldisablealltheinputs,anditwouldmakeabestguessforanyrequiredinput

--userTheusername(Default:input)

--Thisoptioncanbeusedtoseparatecommand-lineoptionsfromthelistofargument,(usefulwhenargumentsmightbemistakenforcommand-lineoptions

Theinstancedirectorytoholdthebroker'sconfigurationanddata

Someofthesepropertiesmaybemandatoryincertainconfigurationsandthesystemmayaskyouforadditionalinput.

UsingtheServer

28

./artemiscreate/usr/serverCreatingActiveMQArtemisinstanceat:/user/server

--user:ismandatorywiththisconfiguration:Pleaseprovidethedefaultusername:admin

--password:ismandatorywiththisconfiguration:Pleaseprovidethedefaultpassword:

--allow-anonymous:ismandatorywiththisconfiguration:Allowanonymousaccess?(Y/N):y

Youcannowstartthebrokerbyexecuting:

"/user/server/bin/artemis"run

Oryoucanrunthebrokerinthebackgroundusing:

"/user/server/bin/artemis-service"start

StartingandStoppingaBrokerInstance

Assumingyoucreatedthebrokerinstanceunder/var/lib/mybrokerallyouneedtodostartrunningthebrokerinstanceisexecute:

/var/lib/mybroker/bin/artemisrun

Nowthatthebrokerisrunning,youcanoptionallyrunsomeoftheincludedexamplestoverifythethebrokerisrunningproperly.

TostoptheApacheActiveMQArtemisinstanceyouwillusethesameartemisscript,butwiththestopargument.Example:

/var/lib/mybroker/bin/artemisstop

PleasenotethatApacheActiveMQArtemisrequiresaJava7orlaterruntimetorun.

Bydefaulttheetc/bootstrap.xmlconfigurationisused.Theconfigurationcanbechangede.g.byrunning./artemisrun--xml:path/to/bootstrap.xmloranotherconfigofyourchoosing.

UsingtheServer

29

Environmentvariablesareusedtoprovideeaseofchangingports,hostsanddatadirectoriesusedandcanbefoundinetc/artemis.profileonlinuxandetc\artemis.profile.cmdonWindows.

ServerJVMsettingsTherunscriptssetsomeJVMsettingsfortuningthegarbagecollectionpolicyandheapsize.WerecommendusingaparallelgarbagecollectionalgorithmtosmoothoutlatencyandminimiselargeGCpauses.

BydefaultApacheActiveMQArtemisrunsinamaximumof1GiBofRAM.Toincreasethememorysettingschangethe-Xmsand-XmxmemorysettingsasyouwouldforanyJavaprogram.

IfyouwishtoaddanymoreJVMargumentsortunetheexistingones,therunscriptsaretheplacetodoit.

Pre-configuredOptionsThedistributioncontainsseveralstandardconfigurationsetsforrunning:

Nonclusteredstand-alone.

Clusteredstand-alone

Replicatedstand-alone

Shared-storestand-alone

Youcanofcoursecreateyourownconfigurationandspecifyanyconfigurationwhenrunningtherunscript.

LibraryPathIfyou'reusingtheAsynchronousIOJournalonLinux,youneedtospecifyjava.library.pathasapropertyonyourJavaoptions.Thisisdoneautomaticallyinthescripts.

Ifyoudon'tspecifyjava.library.pathatyourJavaoptionsthentheJVMwillusetheenvironmentvariableLD_LIBRARY_PATH.

UsingtheServer

30

YouwillneedtomakesurelibaioisinstalledonLinux.FormoreinformationrefertothelibaiochapteratRuntimeDependencies

SystempropertiesApacheActiveMQArtemiscantakeasystempropertyonthecommandlineforconfiguringlogging.

Formoreinformationonconfiguringlogging,pleaseseethesectiononLogging.

ConfigurationfilesTheconfigurationfileusedtobootstraptheserver(e.g.bootstrap.xmlbydefault)referencesthespecificbrokerconfigurationfiles.

broker.xml.ThisisthemainActiveMQconfigurationfile.Alltheparametersinthisfilearedescribedhere

Itisalsopossibletousesystempropertysubstitutioninalltheconfigurationfiles.byreplacingavaluewiththenameofasystemproperty.Hereisanexampleofthiswithaconnectorconfiguration:

tcp://${activemq.remoting.netty.host:localhost}:${activemq.remoting.netty.port:61616}

Hereyoucanseewehavereplaced2valueswithsystempropertiesactivemq.remoting.netty.hostandactivemq.remoting.netty.port.Thesevalueswillbereplacedbythevaluefoundinthesystempropertyifthereisone,ifnottheydefaultbacktolocalhostor61616respectively.Itisalsopossibletonotsupplyadefault.i.e.${activemq.remoting.netty.host},howeverthesystempropertymustbesuppliedinthatcase.

BootstrapFileThestand-aloneserverisbasicallyasetofPOJOswhichareinstantiatedbyAirlinecommands.

Thebootstrapfileisverysimple.Let'stakealookatanexample:

UsingtheServer

31

core-Instantiatesacoreserverusingtheconfigurationfilefromtheconfigurationattribute.ThisisthemainbrokerPOJOnecessarytodoalltherealmessagingwork.InadditionallJMSobjectssuchas:Queues,TopicsandConnectionFactoryinstancesareconfiguredhere.

Themainconfigurationfile.TheconfigurationfortheApacheActiveMQArtemiscoreserveriscontainedinbroker.xml.ThisiswhattheFileConfigurationbeanusestoconfigurethemessagingserver.

TherearemanyattributeswhichyoucanconfigureApacheActiveMQArtemis.Inmostcasesthedefaultswilldofine,infacteveryattributecanbedefaultedwhichmeansafilewithasingleemptyconfigurationelementisavalidconfigurationfile.Thedifferentconfigurationwillbeexplainedthroughoutthemanualoryoucanrefertotheconfigurationreferencehere.

WindowsServerOnwindowsyouwillhavetheoptiontorunActiveMQArtemisasaservice.Justusethefollowingcommandtoinstallit:

$./artemis-service.exeinstall

Thecreateprocessshouldgiveyouahintoftheavailablecommandsavailablefortheartemis-service.exe

UsingtheServer

32

UsingtheServer

33

UsingJMSAlthoughApacheActiveMQArtemisprovidesaJMSagnosticmessagingAPI,manyuserswillbemorecomfortableusingJMS.

JMSisaverypopularAPIstandardformessaging,andmostmessagingsystemsprovideaJMSAPI.IfyouarecompletelynewtoJMSwesuggestyoufollowtheOracleJMStutorial-afullJMStutorialisoutofscopeforthisguide.

ApacheActiveMQArtemisalsoshipswithawiderangeofexamples,manyofwhichdemonstrateJMSAPIusage.AgoodplacetostartwouldbetoplayaroundwiththesimpleJMSQueueandTopicexample,butwealsoprovideexamplesformanyotherpartsoftheJMSAPI.AfulldescriptionoftheexamplesisavailableinExamples.

Inthissectionwe'llgothroughthemainstepsinconfiguringtheserverforJMSandcreatingasimpleJMSprogram.We'llalsoshowhowtoconfigureanduseJNDI,andalsohowtouseJMSwithApacheActiveMQArtemiswithoutusinganyJNDI.

AsimpleorderingsystemForthischapterwe'regoingtouseaverysimpleorderingsystemasourexample.Itisasomewhatcontrivedexamplebecauseofitsextremesimplicity,butitservestodemonstratetheverybasicsofsettingupandusingJMS.

WewillhaveasingleJMSQueuecalledOrderQueue,andwewillhaveasingleMessageProducersendinganordermessagetothequeueandasingleMessageConsumerconsumingtheordermessagefromthequeue.

Thequeuewillbeadurablequeue,i.e.itwillsurviveaserverrestartorcrash.Wealsowanttopre-deploythequeue,i.e.specifythequeueintheserverconfigurationsoitiscreatedautomaticallywithoutushavingtoexplicitlycreateitfromtheclient.

JNDIConfiguration

UsingJMS

34

http://docs.oracle.com/javaee/7/tutorial/partmessaging.htm

TheJMSspecificationestablishestheconventionthatadministeredobjects(i.e.JMSqueue,topicandconnectionfactoryinstances)aremadeavailableviatheJNDIAPI.BrokersarefreetoimplementJNDIastheyseefitassumingtheimplementationfitstheAPI.ApacheActiveMQArtemisdoesnothaveaJNDIserver.Rather,itusesaclient-sideJNDIimplementationthatreliesonspecialpropertiessetintheenvironmenttoconstructtheappropriateJMSobjects.Inotherwords,noobjectsarestoredinJNDIontheApacheActiveMQArtemisserver,insteadtheyaresimplyinstantiatedontheclientbasedontheprovidedconfiguration.Let'slookatthedifferentkindsofadministeredobjectsandhowtoconfigurethem.

Note

ThefollowingconfigurationpropertiesarestrictlyrequiredwhenApacheActiveMQArtemisisrunninginstand-alonemode.WhenApacheActiveMQArtemisisintegratedtoanapplicationserver(e.g.Wildfly)theapplicationserveritselfwillalmostcertainlyprovideaJNDIclientwithitsownproperties.

ConnectionFactoryJNDIAJMSconnectionfactoryisusedbytheclienttomakeconnectionstotheserver.Itknowsthelocationoftheserveritisconnectingto,aswellasmanyotherconfigurationparameters.

Here'sasimpleexampleoftheJNDIcontextenvironmentforaclientlookingupaconnectionfactorytoaccessanembeddedinstanceofApacheActiveMQArtemis:

java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactoryconnectionFactory.invmConnectionFactory=vm://0

InthisinstancewehavecreatedaconnectionfactorythatisboundtoinvmConnectionFactory,anyentrywithprefixconnectionFactory.willcreateaconnectionfactory.

IncertainsituationstherecouldbemultipleserverinstancesrunningwithinaparticularJVM.InthatsituationeachserverwouldtypicallyhaveanInVMacceptorwithauniqueserver-ID.AclientusingJMSandJNDIcanaccountforthisbyspecifyingaconnctionfactoryforeachserver,likeso:

UsingJMS

35

java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactoryconnectionFactory.invmConnectionFactory0=vm://0connectionFactory.invmConnectionFactory1=vm://1connectionFactory.invmConnectionFactory2=vm://2

HereisalistofallthesupportedURLschemes:

vm

tcp

udp

jgroups

Mostclientswon'tbeconnectingtoanembeddedbroker.Clientswillmostcommonlyconnectacrossanetworkaremotebroker.Here'sasimpleexampleofaclientconfiguringaconnectionfactorytoconnecttoaremotebrokerrunningonmyhost:5445:

java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactoryconnectionFactory.ConnectionFactory=tcp://myhost:5445

IntheexampleabovetheclientisusingthetcpschemefortheproviderURL.Aclientmayalsospecifymultiplecomma-delimitedhost:portcombinationsintheURL(e.g.(tcp://remote-host1:5445,remote-host2:5445)).Whetherthereisoneormanyhost:portcombinationsintheURLtheyaretreatedastheinitialconnector(s)fortheunderlyingconnection.

Theudpschemeisalsosupportedwhichshoulduseahost:portcombinationthatmatchesthegroup-addressandgroup-portfromthecorrespondingbroadcast-groupconfiguredontheActiveMQArtemisserver(s).

EachschemehasaspecificsetofpropertieswhichcanbesetusingthetraditionalURLquerystringformat(e.g.scheme://host:port?key1=value1&key2=value2)tocustomizetheunderlyingtransportmechanism.Forexample,ifaclientwantedtoconnecttoaremoteserverusingTCPandSSLitwouldcreateaconnectionfactorylikeso,tcp://remote-host:5445?ssl-enabled=true.

AllthepropertiesavailableforthetcpschemearedescribedinthedocumentationregardingtheNettytransport.

UsingJMS

36

Noteifyouareusingthetcpschemeandmultipleaddressesthenaquerycanbeappliedtoalltheurl'sorjusttoanindividualconnector,sowhereyouhave

(tcp://remote-host1:5445?httpEnabled=true,remote-host2:5445?httpEnabled=true)?

clientID=1234

thenthehttpEnabledpropertyisonlysetontheindividualconnectorswhereastheclientIdissetontheactualconnectionfactory.AnyconnectorspecificpropertiessetonthewholeURIwillbeappliedtoalltheconnectors.

Theudpschemesupports4properties:

localAddress-Ifyouarerunningwithmultiplenetworkinterfacesonthesamemachine,youmaywanttospecifythatthediscoverygrouplistensonlyonlyaspecificinterface.Todothisyoucanspecifytheinterfaceaddresswiththisparameter.

localPort-Ifyouwanttospecifyalocalporttowhichthedatagramsocketisboundyoucanspecifyithere.Normallyyouwouldjustusethedefaultvalueof-1whichsignifiesthatananonymousportshouldbeused.ThisparameterisalwaysspecifiedinconjunctionwithlocalAddress.

refreshTimeout-Thisistheperiodthediscoverygroupwaitsafterreceivingthelastbroadcastfromaparticularserverbeforeremovingthatserversconnectorpairentryfromitslist.Youwouldnormallysetthistoavaluesignificantlyhigherthanthebroadcast-periodonthebroadcastgroupotherwiseserversmightintermittentlydisappearfromthelisteventhoughtheyarestillbroadcastingduetoslightdifferencesintiming.Thisparameterisoptional,thedefaultvalueis10000milliseconds(10seconds).

discoveryInitialWaitTimeout-Iftheconnectionfactoryisusedimmediatelyaftercreationthenitmaynothavehadenoughtimetoreceivedbroadcastsfromallthenodesinthecluster.Onfirstusage,theconnectionfactorywillmakesureitwaitsthislongsincecreationbeforecreatingthefirstconnection.Thedefaultvalueforthisparameteris10000milliseconds.

Lastly,thejgroupsschemeissupportedwhichprovidesanalternativetotheudpschemeforserverdiscovery.TheURLpatterniseitherjgroups://channelName?file=jgroups-xml-conf-filenamewherejgroups-xml-conf-filenamereferstoanXMLfileontheclasspaththatcontainstheJGroupsconfigurationoritcanbejgroups://channelName?properties=some-jgroups-properties.InbothinstancethechannelNameisthenamegiventothejgroupschannelcreated.

UsingJMS

37

TherefreshTimeoutanddiscoveryInitialWaitTimeoutpropertiesaresupportedjustlikewithudp.

Thedefaulttypeforthedefaultconnectionfactoryisoftypejavax.jms.ConnectionFactory.Thiscanbechangedbysettingthetypelikeso

java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactoryjava.naming.provider.url=tcp://localhost:5445?type=CF

Inthisexampleitisstillsettothedefault,belowshowsalistoftypesthatcanbeset.

ConfigurationforConnectionFactoryTypes

type interface

CF(default) javax.jms.ConnectionFactory

XA_CF javax.jms.XAConnectionFactory

QUEUE_CF javax.jms.QueueConnectionFactory

QUEUE_XA_CF javax.jms.XAQueueConnectionFactory

TOPIC_CF javax.jms.TopicConnectionFactory

TOPIC_XA_CF javax.jms.XATopicConnectionFactory

DestinationJNDI

JMSdestinationsarealsotypicallylookedupviaJNDI.Aswithconnectionfactories,destinationscanbeconfiguredusingspecialpropertiesintheJNDIcontextenvironment.Thepropertynameshouldfollowthepattern:queue.ortopic..ThepropertyvalueshouldbethenameofthequeuehostedbytheApacheActiveMQArtemisserver.Forexample,iftheserverhadaJMSqueueconfiguredlikeso:

Andiftheclientwantedtobindthisqueueto"queues/OrderQueue"thentheJNDIpropertieswouldbeconfiguredlikeso:

UsingJMS

38

java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactoryjava.naming.provider.url=tcp://myhost:5445queue.queues/OrderQueue=OrderQueue

Itisalsopossibletolook-upJMSdestinationswhichhaven'tbeenconfiguredexplicitlyintheJNDIcontextenvironment.ThisispossibleusingdynamicQueues/ordynamicTopics/inthelook-upstring.Forexample,iftheclientwantedtolook-uptheaforementioned"OrderQueue"itcoulddososimplybyusingthestring"dynamicQueues/OrderQueue".Note,thetextthatfollowsdynamicQueues/ordynamicTopics/mustcorrespondexactlytothenameofthedestinationontheserver.

Thecode

Here'sthecodefortheexample:

Firstwe'llcreateaJNDIinitialcontextfromwhichtolookupourJMSobjects.Iftheabovepropertiesaresetinjndi.propertiesanditisontheclasspaththenanynew,emptyInitialContextwillbeinitializedusingthoseproperties:

UsingJMS

39

InitialContextic=newInitialContext();

//Nowwe'lllookuptheconnectionfactoryfromwhichwecancreate//connectionstomyhost:5445:

ConnectionFactorycf=(ConnectionFactory)ic.lookup("ConnectionFactory");

//AndlookuptheQueue:

QueueorderQueue=(Queue)ic.lookup("queues/OrderQueue");

//NextwecreateaJMSconnectionusingtheconnectionfactory:

Connectionconnection=cf.createConnection();

//AndwecreateanontransactedJMSSession,withAUTO\_ACKNOWLEDGE//acknowledgemode:

Sessionsession=connection.createSession(false,Session.AUTO_ACKNOWLEDGE);

//WecreateaMessageProducerthatwillsendorderstothequeue:

MessageProducerproducer=session.createProducer(orderQueue);

//AndwecreateaMessageConsumerwhichwillconsumeordersfromthe//queue:

MessageConsumerconsumer=session.createConsumer(orderQueue);

//Wemakesurewestarttheconnection,ordeliverywon'toccuronit:

connection.start();

//WecreateasimpleTextMessageandsendit:

TextMessagemessage=session.createTextMessage("Thisisanorder");producer.send(message);

//Andweconsumethemessage:

TextMessagereceivedMessage=(TextMessage)consumer.receive();System.out.println("Gotorder:"+receivedMessage.getText());

Itisassimpleasthat.ForawiderangeofworkingJMSexamplespleaseseetheexamplesdirectoryinthedistribution.

UsingJMS

40

Warning

PleasenotethatJMSconnections,sessions,producersandconsumersaredesignedtobere-used.

Itisananti-patterntocreatenewconnections,sessions,producersandconsumersforeachmessageyouproduceorconsume.Ifyoudothis,yourapplicationwillperformverypoorly.ThisisdiscussedfurtherinthesectiononperformancetuningPerformanceTuning.

DirectlyinstantiatingJMSResourceswithoutusingJNDI

AlthoughitisaverycommonJMSusagepatterntolookupJMSAdministeredObjects(that'sJMSQueue,TopicandConnectionFactoryinstances)fromJNDI,insomecasesyoujustthink"WhydoIneedJNDI?Whycan'tIjustinstantiatetheseobjectsdirectly?"

WithApacheActiveMQArtemisyoucandoexactlythat.ApacheActiveMQArtemissupportsthedirectinstantiationofJMSQueue,TopicandConnectionFactoryinstances,soyoudon'thavetouseJNDIatall.

Forafullworkingexampleofdirectinstantiationpleaselookatthe"InstantiateJMSObjectsDirectly"exampleundertheJMSsectionoftheexamples.SeetheExamplessectionformoreinfo.

Here'soursimpleexample,rewrittentonotuseJNDIatall:

WecreatetheJMSConnectionFactoryobjectviatheActiveMQJMSClientUtilityclass,noteweneedtoprovideconnectionparametersandspecifywhichtransportweareusing,formoreinformationonconnectorspleaseseeConfiguringtheTransport.

UsingJMS

41

TransportConfigurationtransportConfiguration=newTransportConfiguration(NettyConnectorFactory.class.getName());

ConnectionFactorycf=ActiveMQJMSClient.createConnectionFactoryWithoutHA(JMSFactoryType.CF,transportConfiguration);

//WealsocreatetheJMSQueueobjectviatheActiveMQJMSClientUtility//class:

QueueorderQueue=ActiveMQJMSClient.createQueue("OrderQueue");

//NextwecreateaJMSconnectionusingtheconnectionfactory:

Connectionconnection=cf.createConnection();

//AndwecreateanontransactedJMSSession,withAUTO\_ACKNOWLEDGE//acknowledgemode:

Sessionsession=connection.createSession(false,Session.AUTO_ACKNOWLEDGE);

//WecreateaMessageProducerthatwillsendorderstothequeue:

MessageProducerproducer=session.createProducer(orderQueue);

//AndwecreateaMessageConsumerwhichwillconsumeordersfromthe//queue:

MessageConsumerconsumer=session.createConsumer(orderQueue);

//Wemakesurewestarttheconnection,ordeliverywon'toccuronit:

connection.start();

//WecreateasimpleTextMessageandsendit:

TextMessagemessage=session.createTextMessage("Thisisanorder");producer.send(message);

//Andweconsumethemessage:

TextMessagereceivedMessage=(TextMessage)consumer.receive();System.out.println("Gotorder:"+receivedMessage.getText());

SettingTheClientID

ThisrepresentstheclientidforaJMSclientandisneededforcreatingdurablesubscriptions.ItispossibletoconfigurethisontheconnectionfactoryandcanbesetviatheclientIdelement.Anyconnectioncreatedbythisconnectionfactorywillhavethis

UsingJMS

42

setasitsclientid.

SettingTheBatchSizeforDUPS_OK

WhentheJMSacknowledgemodeissettoDUPS_OKitispossibletoconfiguretheconsumersothatitsendsacknowledgementsinbatchesratherthatoneatatime,savingvaluablebandwidth.ThiscanbeconfiguredviatheconnectionfactoryviathedupsOkBatchSizeelementandissetinbytes.Thedefaultis1024*1024bytes=1MiB.

SettingTheTransactionBatchSize

Whenreceivingmessagesinatransactionitispossibletoconfiguretheconsumertosendacknowledgementsinbatchesratherthanindividuallysavingvaluablebandwidth.ThiscanbeconfiguredontheconnectionfactoryviathetransactionBatchSizeelementandissetinbytes.Thedefaultis1024*1024.

UsingJMS

43

UsingCoreApacheActiveMQArtemiscoreisacompletelyJMS-agnosticmessagingsystemwithitsownnon-JMSAPI.WecallthisthecoreAPI.

Ifyoudon'twanttouseJMSyoucanusethecoreAPIdirectly.ThecoreAPIprovidesallthefunctionalityofJMSbutwithoutmuchofthecomplexity.ItalsoprovidesfeaturesthatarenotavailableusingJMS.

CoreMessagingConceptsSomeofthecoremessagingconceptsaresimilartoJMSconcepts,butcoremessagingconceptsdifferinsomeways.IngeneralthecoremessagingAPIissimplerthantheJMSAPI,sinceweremovedistinctionsbetweenqueues,topicsandsubscriptions.We'lldiscusseachofthemajorcoremessagingconceptsinturn,buttoseetheAPIindetail,pleaseconsulttheJavadoc.

Message

Amessageistheunitofdatawhichissentbetweenclientsandservers.

Amessagehasabodywhichisabuffercontainingconvenientmethodsforreadingandwritingdataintoit.

Amessagehasasetofpropertieswhicharekey-valuepairs.Eachpropertykeyisastringandpropertyvaluescanbeoftypeinteger,long,short,byte,byte[],String,double,floatorboolean.

Amessagehasanaddressitisbeingsentto.Whenthemessagearrivesontheserveritisroutedtoanyqueuesthatareboundtotheaddress-ifthequeuesareboundwithanyfilter,themessagewillonlyberoutedtothatqueueifthefiltermatches.Anaddressmayhavemanyqueuesboundtoitorevennone.Theremayalsobeentitiesotherthanqueues,likedivertsboundtoaddresses.

Messagescanbeeitherdurableornondurable.Durablemessagesinadurablequeuewillsurviveaservercrashorrestart.Nondurablemessageswillneversurviveaservercrashorrestart.

UsingCore

44

Messagescanbespecifiedwithapriorityvaluebetween0and9.0representsthelowestpriorityand9representsthehighest.ApacheActiveMQArtemiswillattempttodeliverhigherprioritymessagesbeforelowerpriorityones.

Messagescanbespecifiedwithanoptionalexpirytime.ApacheActiveMQArtemiswillnotdelivermessagesafteritsexpirytimehasbeenexceeded.

Messagesalsohaveanoptionaltimestampwhichrepresentsthetimethemessagewassent.

ApacheActiveMQArtemisalsosupportsthesending/consumingofverylargemessagesmuchlargerthancanfitinavailableRAMatanyonetime.

Address

Aservermaintainsamappingbetweenanaddressandasetofqueues.Zeroormorequeuescanbeboundtoasingleaddress.Eachqueuecanbeboundwithanoptionalmessagefilter.Whenamessageisrouted,itisroutedtothesetofqueuesboundtothemessage'saddress.Ifanyofthequeuesareboundwithafilterexpression,thenthemessagewillonlyberoutedtothesubsetofboundqueueswhichmatchthatfilterexpression.

Otherentities,suchasdivertscanalsobeboundtoanaddressandmessageswillalsoberoutedthere.

Note

Incore,thereisnoconceptofaTopic,TopicisaJMSonlyterm.Instead,incore,wejustdealwithaddressesandqueues.

Forexample,aJMStopicwouldbeimplementedbyasingleaddresstowhichmanyqueuesarebound.Eachqueuerepresentsasubscriptionofthetopic.AJMSQueuewouldbeimplementedasasingleaddresstowhichonequeueisbound-thatqueuerepresentstheJMSqueue.

Queue

Queuescanbedurable,meaningthemessagestheycontainsurviveaservercrashorrestart,aslongasthemessagesinthemaredurable.Nondurablequeuesdonotsurviveaserverrestartorcrashevenifthemessagestheycontainaredurable.

UsingCore

45

Queuescanalsobetemporary,meaningtheyareautomaticallydeletedwhentheclientconnectionisclosed,iftheyarenotexplicitlydeletedbeforethat.

Queuescanbeboundwithanoptionalfilterexpression.Ifafilterexpressionissuppliedthentheserverwillonlyroutemessagesthatmatchthatfilterexpressiontoanyqueuesboundtotheaddress.

Manyqueuescanbeboundtoasingleaddress.Aparticularqueueisonlyboundtoamaximumofoneaddress.

ServerLocator

ClientsuseServerLocatorinstancestocreateClientSessionFactoryinstances.ServerLocatorinstancesareusedtolocateserversandcreateconnectionstothem.

InJMStermsthinkofaServerLocatorinthesamewayyouwouldaJMSConnectionFactory.

ServerLocatorinstancesarecreatedusingtheActiveMQClientfactoryclass.

ClientSessionFactory

ClientsuseClientSessionFactoryinstancestocreateClientSessioninstances.ClientSessionFactoryinstancesarebasicallytheconnectiontoaserver

InJMStermsthinkofthemasJMSConnections.

ClientSessionFactoryinstancesarecreatedusingtheServerLocatorclass.

ClientSession

AclientusesaClientSessionforconsumingandproducingmessagesandforgroupingthemintransactions.ClientSessioninstancescansupportbothtransactionalandnontransactionalsemanticsandalsoprovideanXAResourceinterfacesomessagingoperationscanbeperformedaspartofaJTAtransaction.

ClientSessioninstancesgroupClientConsumersandClientProducers.

ClientSessioninstancescanberegisteredwithanoptionalSendAcknowledgementHandler.Thisallowsyourclientcodetobenotifiedasynchronouslywhensentmessageshavesuccessfullyreachedtheserver.ThisuniqueApacheActiveMQArtemisfeature,allowsyoutohavefullguaranteesthatsentmessageshavereachedtheserverwithouthaving

UsingCore

46

http://www.oracle.com/technetwork/java/javaee/tech/jta-138684.html

toblockoneachmessagesentuntilaresponseisreceived.Blockingoneachmessagessentiscostlysinceitrequiresanetworkroundtripforeachmessagesent.BynotblockingandreceivingsendacknowledgementsasynchronouslyyoucancreatetrueendtoendasynchronoussystemswhichisnotpossibleusingthestandardJMSAPI.FormoreinformationonthisadvancedfeaturepleaseseethesectionGuaranteesofsendsandcommits.

ClientConsumer

ClientsuseClientConsumerinstancestoconsumemessagesfromaqueue.CoreMessagingsupportsbothsynchronousandasynchronousmessageconsumptionsemantics.ClientConsumerinstancescanbeconfiguredwithanoptionalfilterexpressionandwillonlyconsumemessageswhichmatchthatexpression.

ClientProducer

ClientscreateClientProducerinstancesonClientSessioninstancessotheycansendmessages.ClientProducerinstancescanspecifyanaddresstowhichallsentmessagesarerouted,ortheycanhavenospecifiedaddress,andtheaddressisspecifiedatsendtimeforthemessage.

Warning

PleasenotethatClientSession,ClientProducerandClientConsumerinstancesaredesignedtobere-used.

It'sananti-patterntocreatenewClientSession,ClientProducerandClientConsumerinstancesforeachmessageyouproduceorconsume.Ifyoudothis,yourapplicationwillperformverypoorly.ThisisdiscussedfurtherinthesectiononperformancetuningPerformanceTuning.

AsimpleexampleofusingCoreHere'saverysimpleprogramusingthecoremessagingAPItosendandreceiveamessage.Logicallyit'scomprisedoftwosections:firstlysettinguptheproducertowriteamessagetoanaddresss,andsecondly,creatingaqueuefortheconsumer,creatingtheconsumerandstartingit.

UsingCore

47

ServerLocatorlocator=ActiveMQClient.createServerLocatorWithoutHA(newTransportConfiguration(InVMConnectorFactory.class.getName()));

//Inthissimpleexample,wejustuseonesessionforbothproducingandreceiving

ClientSessionFactoryfactory=locator.createClientSessionFactory();ClientSessionsession=factory.createSession();

//Aproducerisassociatedwithanaddress...

ClientProducerproducer=session.createProducer("example");ClientMessagemessage=session.createMessage(true);message.getBodyBuffer().writeString("Hello");

//Weneedaqueueattachedtotheaddress...

session.createQueue("example","example",true);

//Andaconsumerattachedtothequeue...

ClientConsumerconsumer=session.createConsumer("example");

//Oncewehaveaqueue,wecansendthemessage...

producer.send(message);

//Weneedtostartthesessionbeforewecan-receive-messages...

session.start();ClientMessagemsgReceived=consumer.receive();

System.out.println("message="+msgReceived.getBodyBuffer().readString());

session.close();

UsingCore

48

MappingJMSConceptstotheCoreAPIThischapterdescribeshowJMSdestinationsaremappedtoApacheActiveMQArtemisaddresses.

ApacheActiveMQArtemiscoreisJMS-agnostic.ItdoesnothaveanyconceptofaJMStopic.AJMStopicisimplementedincoreasanaddress(thetopicname)withzeroormorequeuesboundtoit.Eachqueueboundtothataddressrepresentsatopicsubscription.Likewise,aJMSqueueisimplementedasanaddress(theJMSqueuename)withonesinglequeueboundtoitwhichrepresentstheJMSqueue.

Byconvention,allJMSqueuesmaptocorequeueswherethecorequeuenamehasthestringjms.queue.prependedtoit.E.g.theJMSqueuewiththename"orders.europe"wouldmaptothecorequeuewiththename"jms.queue.orders.europe".Theaddressatwhichthecorequeueisboundisalsogivenbythecorequeuename.

ForJMStopicstheaddressatwhichthequeuesthatrepresentthesubscriptionsareboundisgivenbyprependingthestring"jms.topic."tothenameoftheJMStopic.E.g.theJMStopicwithname"news.europe"wouldmaptothecoreaddress"jms.topic.news.europe"

InotherwordsifyousendaJMSmessagetoaJMSqueuewithname"orders.europe"itwillgetroutedontheservertoanycorequeuesboundtotheaddress"jms.queue.orders.europe".IfyousendaJMSmessagetoaJMStopicwithname"news.europe"itwillgetroutedontheservertoanycorequeuesboundtotheaddress"jms.topic.news.europe".

IfyouwanttoconfiguresettingsforaJMSQueuewiththename"orders.europe",youneedtoconfigurethecorrespondingcorequeue"jms.queue.orders.europe":

jms.queue.expiry.europe...

MappingJMSConceptstotheCoreAPI

49

TheClientClasspathApacheActiveMQArtemisrequiresseveraljarsontheClientClasspathdependingonwhethertheclientusesApacheActiveMQArtemisCoreAPI,JMS,andJNDI.

Warning

AllthejarsmentionedherecanbefoundinthelibdirectoryoftheApacheActiveMQArtemisdistribution.Besureyouonlyusethejarsfromthecorrectversionoftherelease,youmustnotmixandmatchversionsofjarsfromdifferentApacheActiveMQArtemisversions.Mixingandmatchingdifferentjarversionsmaycausesubtleerrorsandfailurestooccur.

ApacheActiveMQArtemisCoreClientIfyouareusingjustapureApacheActiveMQArtemisCoreclient(i.e.noJMS)thenyouneedactivemq-core-client.jar,activemq-commons.jar,andnetty.jaronyourclientclasspath.

JMSClientIfyouareusingJMSontheclientside,thenyouwillalsoneedtoincludeactivemq-jms-client.jarandgeronimo-jms_2.0_spec.jar.

Note

geronimo-jms_2.0_spec.jarjustcontainsJavaEEAPIinterfaceclassesneededforthejavax.jms.*classes.Ifyoualreadyhaveajarwiththeseinterfaceclassesonyourclasspath,youwillnotneedit.

TheClientClasspath

50

ExamplesTheApacheActiveMQArtemisdistributioncomeswithover90runout-of-the-boxexamplesdemonstratingmanyofthefeatures.

Theexamplesareavailableinboththebinaryandsourcedistributionundertheexamplesdirectory.Examplesaresplitbythefollowingsourcetree:

features-Examplescontainingbrokerspecificfeatures.ha-examplesshowingfailoverandreconnectioncapabilities.clustered-examplesshowingloadbalancinganddistributioncapabilities.perf-examplesallowingyoutorunafewperformancetestsontheserversub-modules-examplesofintegratedexternalmodules.

protocols-Protocolspecificexamplesopenwiremqttstompamqp

AsetofJavaEEexamplesarealsoprovidedwhichneedWildFlyinstalledtobeabletorun.

RunnningtheExamplesTorunanyexample,simplycdintotheappropriateexampledirectoryandtypemvnverifyormvninstall(Fordetailspleasereadthereadme.htmlineachexampledirectory).

Youcanusetheprofile-Pexamplestorunmultipleexamplesunderanyexampletree.

Foreachserver,youwillhaveacreatedserverunder./target/server0(someexamplesusemorethanoneserver).

Youhavetheoptiontopreventtheexamplefromstartingtheserver(e.g.ifyouwanttostarttheservermanually)bysimplyspecifyingthe-PnoServerprofile,e.g.:

#runninganexamplewithoutrunningtheservermvnverify-PnoServer

Examples

51

Alsounder./targettherewillbeascriptrepeatingthecommandstocreateeachserver.Hereisthecreate-server0.shgeneratedbytheQueueexample.Thisisusefultoseeexactlywhatcommand(s)arerequiredtoconfiguretheserver(s).

#Thesearethecommandsusedtocreateserver0/myInstallDirectory/apache-artemis-1.1.0/bin/artemiscreate--allow-anonymous--silent--force--no-web--userguest--passwordguest--roleguest--port-offset0--data./data--allow-anonymous--no-autotune--verbose/myInstallDirectory/apache-artemis-1.1.0/examples/features/standard/queue/target/server0

SeveralexamplesuseUDPclusteringwhichmaynotworkinyourenvironmentbydefault.Onlinuxthecommandwouldbe:

routeadd-net224.0.0.0netmask240.0.0.0devlo

Thiscommandshouldberunasroot.Thiswillredirectanytrafficdirectedto224.0.0.0totheloopbackinterface.OnMacOSX,thecommandisslightlydifferent:

sudorouteadd224.0.0.0127.0.0.1-netmask240.0.0.0

AlltheexamplesusetheMavenplugin,whichcanbeusefulforrunningyourtestserversaswell.

Thisisthecommonoutputwhenrunninganexample.OnthiscasetakenfromtheQueueexample:

[INFO]Scanningforprojects...[INFO][INFO]------------------------------------------------------------------------[INFO]BuildingActiveMQArtemisJMSQueueExample1.1.0[INFO]------------------------------------------------------------------------[INFO][INFO]---maven-enforcer-plugin:1.4:enforce(enforce-java)@queue---[INFO][INFO]---maven-remote-resources-plugin:1.5:process(default)@queue---[INFO][INFO]---maven-resources-plugin:2.6:resources(default-resources)@queue---[INFO]Using'UTF-8'encodingtocopyfilteredresources.[INFO]Copying1resource[INFO]Copying3resources[INFO][INFO]---maven-compiler-plugin:3.1:compile(default-compile)@queue---[INFO]Changesdetected-recompilingthemodule![INFO]Compiling1sourcefileto/work/apache-artemis-1.1.0/examples/features/sta

Examples

52

ndard/queue/target/classes[INFO][INFO]---maven-checkstyle-plugin:2.16:check(default)@queue---[INFO][INFO]---apache-rat-plugin:0.11:check(default)@queue---[INFO]RATwillnotexecutesinceitisconfiguredtobeskippedviasystemproperty'rat.skip'.[INFO][INFO]---maven-resources-plugin:2.6:testResources(default-testResources)@queue---[INFO]Using'UTF-8'encodingtocopyfilteredresources.[INFO]skipnonexistingresourceDirectory/work/apache-artemis-1.1.0/examples/features/standard/queue/src/test/resources[INFO]Copying3resources[INFO][INFO]---maven-compiler-plugin:3.1:testCompile(default-testCompile)@queue---[INFO]Nosourcestocompile[INFO][INFO]---maven-surefire-plugin:2.18.1:test(default-test)@queue---[INFO][INFO]---maven-jar-plugin:2.4:jar(default-jar)@queue---[INFO]Buildingjar:/work/apache-artemis-1.1.0/examples/features/standard/queue/target/queue-1.1.0.jar[INFO][INFO]---maven-site-plugin:3.3:attach-descriptor(attach-descriptor)@queue---[INFO][INFO]>>>maven-source-plugin:2.2.1:jar(attach-sources)>generate-sources@queue>>>[INFO][INFO]---maven-enforcer-plugin:1.4:enforce(enforce-java)@queue---[INFO][INFO]generate-sources@queue>>>[INFO][INFO]---maven-enforcer-plugin:1.4:enforce(enforce-java)@queue---[INFO][INFO]always]

Examples

53

[INFO]Entries.size2[INFO]...key=project=MavenProject:org.apache.activemq.examples.broker:queue:1.1.0@/work/apache-artemis-1.1.0/examples/features/standard/queue/pom.xml[INFO]...key=pluginDescriptor=ComponentDescriptor:role:'org.apache.maven.plugin.Mojo',implementation:'org.apache.activemq.artemis.maven.ArtemisCLIPlugin',rolehint:'org.apache.activemq:artemis-maven-plugin:1.1.0:cli'role:'org.apache.maven.plugin.Mojo',implementation:'org.apache.activemq.artemis.maven.ArtemisCreatePlugin',rolehint:'org.apache.activemq:artemis-maven-plugin:1.1.0:create'role:'org.apache.maven.plugin.Mojo',implementation:'org.apache.activemq.artemis.maven.ArtemisClientPlugin',rolehint:'org.apache.activemq:artemis-maven-plugin:1.1.0:runClient'---Executingorg.apache.activemq.artemis.cli.commands.Createcreate--allow-anonymous--silent--force--no-web--userguest--passwordguest--roleguest--port-offset0--data./data--allow-anonymous--no-autotune--verbose/work/apache-artemis-1.1.0/examples/features/standard/queue/target/server0Home::/work/apache-artemis-1.1.0/examples/features/standard/queue/../../../..,Instance::.CreatingActiveMQArtemisinstanceat:/work/apache-artemis-1.1.0/examples/features/standard/queue/target/server0

Youcannowstartthebrokerbyexecuting:

"/work/apache-artemis-1.1.0/examples/features/standard/queue/target/server0/bin/artemis"run

Oryoucanrunthebrokerinthebackgroundusing:

"/work/apache-artemis-1.1.0/examples/features/standard/queue/target/server0/bin/artemis-service"start

[INFO]###################################################################################################[INFO]create-server0.shcreatedwithcommandstoreproduceserver0[INFO]under/work/apache-artemis-1.1.0/examples/features/standard/queue/target[INFO]###################################################################################################[INFO][INFO]---artemis-maven-plugin:1.1.0:cli(start)@queue---[INFO]awaitingservertostart[INFO]awaitingservertostartserver-out:___server-out:/\____||________(_)_____server-out:/_\|_\__|/_\\/||/__/server-out:/___\|\/|_/__/|\/|||\___\server-out:/_/\_\|\__\____|_||_|_|/___/server-out:ApacheActiveMQArtemis1.1.0server-out:server-out:server-out:17:30:25,091INFO[org.apache.activemq.artemis.integration.bootstrap]

Examples

54

AMQ101000:StartingActiveMQArtemisServerserver-out:17:30:25,120INFO[org.apache.activemq.artemis.core.server]AMQ221000:liveMessageBrokerisstartingwithconfigurationBrokerConfiguration(clustered=false,journalDirectory=./data/journal,bindingsDirectory=./data/bindings,largeMessagesDirectory=./data/large-messages,pagingDirectory=./data/paging)server-out:17:30:25,152INFO[org.apache.activemq.artemis.core.server]AMQ221013:UsingNIOJournalserver-out:17:30:25,195INFO[org.apache.activemq.artemis.core.server]AMQ221043:Protocolmodulefound:[artemis-server].Addingprotocolsupportfor:COREserver-out:17:30:25,199INFO[org.apache.activemq.artemis.core.server]AMQ221043:Protocolmodulefound:[artemis-amqp-protocol].Addingprotocolsupportfor:AMQPserver-out:17:30:25,209INFO[org.apache.activemq.artemis.core.server]AMQ221043:Protocolmodulefound:[artemis-hornetq-protocol].Addingprotocolsupportfor:HORNETQserver-out:17:30:25,211INFO[org.apache.activemq.artemis.core.server]AMQ221043:Protocolmodulefound:[artemis-mqtt-protocol].Addingprotocolsupportfor:MQTTserver-out:17:30:25,214INFO[org.apache.activemq.artemis.core.server]AMQ221043:Protocolmodulefound:[artemis-openwire-protocol].Addingprotocolsupportfor:OPENWIREserver-out:17:30:25,335INFO[org.apache.activemq.artemis.core.server]AMQ221043:Protocolmodulefound:[artemis-stomp-protocol].Addingprotocolsupportfor:STOMP[INFO]awaitingservertostartserver-out:17:30:25,781INFO[org.apache.activemq.artemis.core.server]AMQ221003:tryingtodeployqueuejms.queue.DLQserver-out:17:30:25,835INFO[org.apache.activemq.artemis.core.server]AMQ221003:tryingtodeployqueuejms.queue.ExpiryQueueserver-out:17:30:25,933INFO[org.apache.activemq.artemis.core.server]AMQ221020:StartedAcceptorat0.0.0.0:61616forprotocols[CORE,MQTT,AMQP,HORNETQ,STOMP,OPENWIRE]server-out:17:30:25,936INFO[org.apache.activemq.artemis.core.server]AMQ221020:StartedAcceptorat0.0.0.0:5445forprotocols[HORNETQ,STOMP]server-out:17:30:25,939INFO[org.apache.activemq.artemis.core.server]AMQ221020:StartedAcceptorat0.0.0.0:5672forprotocols[AMQP]server-out:17:30:25,944INFO[org.apache.activemq.artemis.core.server]AMQ221020:StartedAcceptorat0.0.0.0:1883forprotocols[MQTT]server-out:17:30:25,948INFO[org.apache.activemq.artemis.core.server]AMQ221020:StartedAcceptorat0.0.0.0:61613forprotocols[STOMP]server-out:17:30:25,949INFO[org.apache.activemq.artemis.core.server]AMQ221007:Serverisnowliveserver-out:17:30:25,949INFO[org.apache.activemq.artemis.core.server]AMQ221001:ApacheActiveMQArtemisMessageBrokerversion1.1.0[nodeID=a855176b-50f0-11e5-937e-2fe9bb000966][INFO]Serverstarted[INFO][INFO]---artemis-maven-plugin:1.1.0:runClient(runClient)@queue---Sentmessage:ThisisatextmessageReceivedmessage:Thisisatextmessage[INFO][INFO]---artemis-maven-plugin:1.1.0:cli(stop)@queue---server-out:17:30:27,476INFO[org.apache.activemq.artemis.core.server]AMQ221002:ApacheActiveMQArtemisMessageBrokerversion1.0.1-SNA

Examples

55

[INFO]------------------------------------------------------------------------[INFO]BUILDSUCCESS[INFO]------------------------------------------------------------------------[INFO]Totaltime:7.840s[INFO]Finishedat:2015-09-01T17:30:27-04:00[INFO]FinalMemory:42M/508M[INFO]------------------------------------------------------------------------

ListThisincludesapreviewlistofafewexamplesthatwedistributewithArtemis.Pleaserefertothedistributionforamoreaccuratelist.

AppletThisexampleshowsyouhowtosendandreceiveJMSmessagesfromanApplet.

Application-LayerFailoverApacheActiveMQArtemisalsosupportsApplication-Layerfailover,usefulinthecasethatreplicationisnotenabledontheserverside.

WithApplication-Layerfailover,it'suptotheapplicationtoregisteraJMSExceptionListenerwithApacheActiveMQArtemiswhichwillbecalledbyApacheActiveMQArtemisintheeventthatconnectionfailureisdetected.

ThecodeintheExceptionListenerthenrecreatestheJMSconnection,session,etconanothernodeandtheapplicationcancontinue.

Application-layerfailoverisanalternativeapproachtoHighAvailability(HA).Application-layerfailoverdiffersfromautomaticfailoverinthatsomeclientsidecodingisrequiredinordertoimplementthis.Also,withApplication-layerfailover,sincetheoldsessionobjectdiesandanewoneiscreated,anyuncommittedworkintheoldsessionwillbelost,andanyunacknowledgedmessagesmightberedelivered.

CoreBridgeExample

Examples

56

Thebridgeexampledemonstratesacorebridgedeployedononeserver,whichconsumesmessagesfromalocalqueueandforwardsthemtoanaddressonasecondserver.

CorebridgesareusedtocreatemessageflowsbetweenanytwoApacheActiveMQArtemisserverswhichareremotelyseparated.Corebridgesareresilientandwillcopewithtemporaryconnectionfailureallowingthemtobeanidealchoiceforforwardingoverunreliableconnections,e.g.aWAN.

BrowserThebrowserexampleshowsyouhowtouseaJMSQueueBrowserwithApacheActiveMQArtemis.

QueuesareastandardpartofJMS,pleaseconsulttheJMS1.1specificationforfulldetails.

AQueueBrowserisusedtolookatmessagesonthequeuewithoutremovingthem.Itcanscantheentirecontentofaqueueoronlymessagesmatchingamessageselector.

ClientKickoffTheclient-kickoffexampleshowshowtoterminateclientconnectionsgivenanIPaddressusingtheJMXmanagementAPI.

ClientsidefailoverlistenerTheclient-side-failoverlistenerexampleshowshowtoregisteralistenertomonitorfailoverevents

Client-SideLoad-BalancingTheclient-side-load-balancingexampledemonstrateshowsessionscreatedfromasingleJMSConnectioncanbecreatedtodifferentnodesofthecluster.InotherwordsitdemonstrateshowApacheActiveMQArtemisdoesclient-sideload-balancingofsessionsacrossthecluster.

Examples

57

ClusteredDurableSubscriptionThisexampledemonstratesaclusteredJMSdurablesubscription

ClusteredGroupingThisissimilartothemessagegroupingexampleexceptthatitdemonstratesitworkingoveracluster.Messagessenttodifferentnodeswiththesamegroupidwillbesenttothesamenodeandthesameconsumer.

ClusteredQueueTheclustered-queueexampledemonstratesaJMSqueuedeployedontwodifferentnodes.Thetwonodesareconfiguredtoformacluster.Wethencreateaconsumerforthequeueoneachnode,andwecreateaproducerononlyoneofthenodes.Wethensendsomemessagesviatheproducer,andweverifythatbothconsumersreceivethesentmessagesinaround-robinfashion.

ClusteringwithJGroupsTheclustered-jgroupsexampledemonstrateshowtoformatwonodeclusterusingJGroupsasitsunderlyingtopologydiscoverytechnique,ratherthanthedefaultUDPbroadcasting.Wethencreateaconsumerforthequeueoneachnode,andwecreateaproducerononlyoneofthenodes.Wethensendsomemessagesviatheproducer,andweverifythatbothconsumersreceivethesentmessagesinaround-robinfashion.

ClusteredStandaloneTheclustered-standaloneexampledemonstrateshowtoconfigureandstarts3clusternodesonthesamemachinetoformacluster.AsubscriberforaJMStopiciscreatedoneachnode,andwecreateaproducerononlyoneofthenodes.Wethensendsomemessagesviatheproducer,andweverifythatthe3subscribersreceiveallthesentmessages.

Examples

58

ClusteredStaticDiscoveryThisexampledemonstrateshowtoconfigureaclusterusingalistofconnectorsratherthanUDPfordiscovery

ClusteredStaticClusterOneWayThisexampledemonstrateshowtosetupaclusterwhereclusterconnectionsareoneway,i.e.serverA->ServerB->ServerC

ClusteredTopicTheclustered-topicexampledemonstratesaJMStopicdeployedontwodifferentnodes.Thetwonodesareconfiguredtoformacluster.Wethencreateasubscriberonthetopiconeachnode,andwecreateaproducerononlyoneofthenodes.Wethensendsomemessagesviatheproducer,andweverifythatbothsubscribersreceiveallthesentmessages.

MessageConsumerRateLimitingWithApacheActiveMQArtemisyoucanspecifyamaximumconsumerateatwhichaJMSMessageConsumerwillconsumemessages.Thiscanbespecifiedwhencreatingordeployingtheconnectionfactory.

IfthisvalueisspecifiedthenApacheActiveMQArtemiswillensurethatmessagesareneverconsumedataratehigherthanthespecifiedrate.Thisisaformofconsumerthrottling.

DeadLetterThedead-letterexampleshowsyouhowtodefineanddealwithdeadlettermessages.Messagescanbedeliveredunsuccessfully(e.g.ifthetransactedsessionusedtoconsumethemisrolledback).

Examples

59

SuchamessagegoesbacktotheJMSdestinationreadytoberedelivered.However,thismeansitispossibleforamessagetobedeliveredagainandagainwithoutanysuccessandremaininthedestination,cloggingthesystem.

Topreventthis,messagingsystemsdefinedeadlettermessages:afteraspecifiedunsuccessfuldeliveryattempts,themessageisremovedfromthedestinationandputinsteadinadeadletterdestinationwheretheycanbeconsumedforfurtherinvestigation.

DelayedRedeliveryThedelayed-redeliveryexampledemonstrateshowApacheActiveMQArtemiscanbeconfiguredtoprovideadelayedredeliveryinthecaseamessageneedstoberedelivered.

Delayingredeliverycanoftenbeusefulinthecasethatclientsregularlyfailorroll-back.Withoutadelayedredelivery,thesystemcangetintoa"thrashing"state,withdeliverybeingattempted,theclientrollingback,anddeliverybeingre-attemptedinquicksuccession,usingupvaluableCPUandnetworkresources.

DivertApacheActiveMQArtemisdivertsallowmessagestobetransparently"diverted"orcopiedfromoneaddresstoanotherwithjustsomesimpleconfigurationdefinedontheserverside.

DurableSubscriptionThedurable-subscriptionexampleshowsyouhowtouseadurablesubscriptionwithApacheActiveMQArtemis.DurablesubscriptionsareastandardpartofJMS,pleaseconsulttheJMS1.1specificationforfulldetails.

Unlikenon-durablesubscriptions,thekeyfunctionofdurablesubscriptionsisthatthemessagescontainedinthempersistlongerthanthelifetimeofthesubscriber-i.e.theywillaccumulatemessagessenttothetopicevenifthereisnoactivesubscriberonthem.Theywillalsosurviveserverrestartsorcrashes.Notethatforthemessagestobepersisted,themessagessenttothemmustbemarkedasdurablemessages.

Examples

60

EmbeddedTheembeddedexampleshowshowtoembedJMSwithinyourowncodeusingPOJOinstantiationandnoconfigfiles.

EmbeddedSimpleTheembeddedexampleshowshowtoembedJMSwithinyourowncodeusingregularApacheActiveMQArtemisXMLfiles.

MessageExpirationTheexpiryexampleshowsyouhowtodefineanddealwithmessageexpiration.Messagescanberetainedinthemessagingsystemforalimitedperiodoftimebeforebeingremoved.JMSspecificationstatesthatclientsshouldnotreceivemessagesthathavebeenexpired(butitdoesnotguaranteethiswillnothappen).

ApacheActiveMQArtemiscanassignanexpiryaddresstoagivenqueuesothatwhenmessagesareexpired,theyareremovedfromthequeueandsenttotheexpiryaddress.These"expired"messagescanlaterbeconsumedfromtheexpiryaddressforfurtherinspection.

ApacheActiveMQArtemisResourceAdapterexampleThisexamplesshowshowtobuildtheactivemqresourceadaptersararfordeploymentinotherApplicationServer's

HTTPTransportThehttp-transportexampleshowsyouhowtoconfigureApacheActiveMQArtemistousetheHTTPprotocolasitstransportlayer.

InstantiateJMSObjectsDirectly

Examples

61

Usually,JMSObjectssuchasConnectionFactory,QueueandTopicinstancesarelookedupfromJNDIbeforebeingusedbytheclientcode.Thisobjectsarecalled"administeredobjects"inJMSterminology.

However,insomecasesaJNDIservermaynotbeavailableordesired.TocometotherescueApacheActiveMQArtemisalsosupportsthedirectinstantiationoftheseadministeredobjectsontheclientsidesoyoudon'thavetouseJNDIforJMS.

InterceptorApacheActiveMQArtemisallowsanapplicationtouseaninterceptortohookintothemessagingsystem.InterceptorsallowyoutohandlevariousmessageeventsinApacheActiveMQArtemis.

JAASThejaasexampleshowsyouhowtoconfigureApacheActiveMQArtemistouseJAASforsecurity.ApacheActiveMQArtemiscanleverageJAAStodelegateuserauthenticationandauthorizationtoexistingsecurityinfrastructure.

JMSAutoClosableThejms-auto-closeableexampleshowshowJMSresources,suchasconnections,sessionsandconsumers,inJMS2canbeautomaticallyclosedonerror.

JMSCompletionListenerThejms-completion-listenerexampleshowshowtosendamessageasynchronouslytoApacheActiveMQArtemisanduseaCompletionListenertobenotifiedoftheBrokerreceivingit.

JMSBridgeThejms-brigdeexampleshowshowtosetupabridgebetweentwostandaloneApacheActiveMQArtemisservers.

Examples

62

JMSContextThejms-contextexampleshowshowtosendandreceiveamessagetoaJMSQueueusingApacheActiveMQArtemisbyusingaJMSContext.

AJMSContextispartofJMS2.0andcombinestheJMSConnectionandSessionObjectsintoasimpleInterface.

JMSSharedConsumerThejms-shared-consumerexampleshowsyouhowcanusesharedconsumerstoshareasubscriptiononatopic.InJMS1.1thiswasnotallowedandsocausedascalabilityissue.InJMS2thisrestrictionhasbeenliftedsoyoucansharetheloadacrossdifferentthreadsandconnections.

JMXManagementThejmxexampleshowshowtomanageApacheActiveMQArtemisusingJMX.

LargeMessageThelarge-messageexampleshowsyouhowtosendandreceiveverylargemessageswithApacheActiveMQArtemis.ApacheActiveMQArtemissupportsthesendingandreceivingofhugemessages,muchlargerthancanfitinavailableRAMontheclientorserver.Effectivelytheonlylimittomessagesizeistheamountofdiskspaceyouhaveontheserver.

Largemessagesarepersistedontheserversotheycansurviveaserverrestart.InotherwordsApacheActiveMQArtemisdoesn'tjustdoasimplesocketstreamfromthesendertotheconsumer.

Last-ValueQueueThelast-value-queueexampleshowsyouhowtodefineanddealwithlast-valuequeues.Last-valuequeuesarespecialqueueswhichdiscardanymessageswhenanewermessagewiththesamevalueforawell-definedlast-valuepropertyisputinthe

Examples

63

queue.Inotherwords,alast-valuequeueonlyretainsthelastvalue.

Atypicalexampleforlast-valuequeueisforstockprices,whereyouareonlyinterestedbythelatestpriceforaparticularstock.

ManagementThemanagementexampleshowshowtomanageApacheActiveMQArtemisusingJMSMessagestoinvokemanagementoperationsontheserver.

ManagementNotificationThemanagement-notificationexampleshowshowtoreceivemanagementnotificationsfromApacheActiveMQArtemisusingJMSmessages.ApacheActiveMQArtemisserversemitmanagementnotificationswheneventsofinterestoccur(consumersarecreatedorclosed,addressesarecreatedordeleted,securityauthenticationfails,etc.).

MessageCounterThemessage-countersexampleshowsyouhowtousemessagecounterstoobtainmessageinformationforaJMSqueue.

MessageGroupThemessage-groupexampleshowsyouhowtoconfigureandusemessagegroupswithApacheActiveMQArtemis.Messagegroupsallowyoutopinmessagessotheyareonlyconsumedbyasingleconsumer.Messagegroupsaresetsofmessagesthathasthefollowingcharacteristics:

Messagesinamessagegroupsharethesamegroupid,i.e.theyhavesameJMSXGroupIDstringpropertyvalues

Theconsumerthatreceivesthefirstmessageofagroupwillreceiveallthemessagesthatbelongstothegroup

MessageGroup

Examples

64

Themessage-group2exampleshowsyouhowtoconfigureandusemessagegroupswithApacheActiveMQArtemisviaaconnectionfactory.

MessagePriorityMessagePrioritycanbeusedtoinfluencethedeliveryorderformessages.

Itcanberetrievedbythemessage'sstandardheaderfield'JMSPriority'asdefinedinJMSspecificationversion1.1.

Thevalueisoftypeinteger,rangingfrom0(thelowest)to9(thehighest).Whenmessagesarebeingdelivered,theirprioritieswilleffecttheirorderofdelivery.Messagesofhigherprioritieswilllikelybedeliveredbeforethoseoflowerpriorities.

Messagesofequalprioritiesaredeliveredinthenaturalorderoftheirarrivalattheirdestinations.PleaseconsulttheJMS1.1specificationforfulldetails.

MultipleFailoverThisexampledemonstrateshowtosetupaliveserverwithmultiplebackups

MultipleFailoverFailbackThisexampledemonstrateshowtosetupaliveserverwithmultiplebackupsbutforcingfailoverbacktotheoriginalliveserver

NoConsumerBufferingBydefault,ApacheActiveMQArtemisconsumersbuffermessagesfromtheserverinaclientsidebufferbeforeyouactuallyreceivethemontheclientside.Thisimprovesperformancesinceotherwiseeverytimeyoucalledreceive()orhadprocessedthelastmessageinaMessageListeneronMessage()method,theApacheActiveMQArtemisclientwouldhavetogotheservertorequestthenextmessage,whichwouldthengetsenttotheclientside,ifonewasavailable.

Examples

65

Thiswouldinvolveanetworkroundtripforeverymessageandreduceperformance.Therefore,bydefault,ApacheActiveMQArtemispre-fetchesmessagesintoabufferoneachconsumer.

Insomecasebufferingisnotdesirable,andApacheActiveMQArtemisallowsittobeswitchedoff.Thisexampledemonstratesthat.

Non-TransactionFailoverWithServerDataReplicationThenon-transaction-failoverexampledemonstratestwoserverscoupledasalive-backuppairforhighavailability(HA),andaclientusinganon-transactedJMSsessionfailingoverfromlivetobackupwhentheliveserveriscrashed.

ApacheActiveMQArtemisimplementsfailoverofclientconnectionsbetweenliveandbackupservers.Thisisimplementedbythereplicationofstatebetweenliveandbackupnodes.Whenreplicationisconfiguredandalivenodecrashes,theclientconnectionscancarryandcontinuetosendandconsumemessages.Whennon-transactedsessionsareused,onceandonlyoncemessagedeliveryisnotguaranteedanditispossiblethatsomemessageswillbelostordeliveredtwice.

OpenWireTheOpenwireexampleshowshowtoconfigureanApacheActiveMQArtemisservertocommunicatewithanApacheActiveMQArtemisJMSclientthatusesopen-wireprotocol.

Youwillfindthequeueexampleforopenwire,andthechatexample.

PagingThepagingexampleshowshowApacheActiveMQArtemiscansupporthugequeuesevenwhentheserverisrunninginlimitedRAM.Itdoesthisbytransparentlypagingmessagestodisk,anddepagingthemwhentheyarerequired.

Pre-Acknowledge

Examples

66

StandardJMSsupportsthreeacknowledgementmodes:AUTO_ACKNOWLEDGE,CLIENT_ACKNOWLEDGE,andDUPS_OK_ACKNOWLEDGE.ForafulldescriptiononthesemodespleaseconsulttheJMSspecification,oranyJMStutorial.

Allofthesestandardmodesinvolvesendingacknowledgementsfromtheclienttotheserver.Howeverinsomecases,youreallydon'tmindlosingmessagesineventoffailure,soitwouldmakesensetoacknowledgethemessageontheserverbeforedeliveringittotheclient.ThisexampledemonstrateshowApacheActiveMQArtemisallowsthiswithanextraacknowledgementmode.

MessageProducerRateLimitingTheproducer-rte-limitexampledemonstrateshow,withApacheActiveMQArtemis,youcanspecifyamaximumsendrateatwhichaJMSmessageproducerwillsendmessages.

QueueAsimpleexampledemonstratingaJMSqueue.

MessageRedistributionThequeue-message-redistributionexampledemonstratesmessageredistributionbetweenqueueswiththesamenamedeployedindifferentnodesofacluster.

QueueRequestorAsimpleexampledemonstratingaJMSqueuerequestor.

QueuewithMessageSelectorThequeue-selectorexampleshowsyouhowtoselectivelyconsumemessagesusingmessageselectorswithqueueconsumers.

Examples

67

ReattachNodeexampleTheReattachNodeexampleshowshowaclientcantrytoreconnecttothesameserverinsteadoffailingtheconnectionimmediatelyandnotifyinganyuserExceptionListenerobjects.ApacheActiveMQArtemiscanbeconfiguredtoautomaticallyretrytheconnection,andreattachtotheserverwhenitbecomesavailableagainacrossthenetwork.

ReplicatedFailbackexampleAnexampleshowinghowfailbackworkswhenusingreplication,InthisexamplealiveserverwillreplicateallitsJournaltoabackupserverasitupdatesit.Whentheliveservercrashesthebackuptakesoverfromtheliveserverandtheclientreconnectsandcarriesonfromwhereitleftoff.

ReplicatedFailbackstaticexampleAnexampleshowinghowfailbackworkswhenusingreplication,butthistimewithstaticconnectors

ReplicatedmultiplefailoverexampleAnexampleshowinghowtoconfiguremultiplebackupswhenusingreplication

ReplicatedFailovertransactionexampleAnexampleshowinghowfailoverworkswithatransactionwhenusingreplication

Request-ReplyexampleAsimpleexampleshowingtheJMSrequest-responsepattern.

ScheduledMessage

Examples

68

Thescheduled-messageexampleshowsyouhowtosendascheduledmessagetoaJMSQueuewithApacheActiveMQArtemis.Scheduledmessageswon'tgetdelivereduntilaspecifiedtimeinthefuture.

SecurityThesecurityexampleshowsyouhowconfigureanduserolebasedqueuesecuritywithApacheActiveMQArtemis.

SendAcknowledgementsThesend-acknowledgementsexampleshowsyouhowtouseApacheActiveMQArtemis'sadvancedasynchronoussendacknowledgementsfeaturetoobtainacknowledgementfromtheserverthatsendshavebeenreceivedandprocessedinaseparatestreamtothesentmessages.

SpringIntegrationThisexampleshowshowtouseembeddedJMSusingApacheActiveMQArtemis'sSpringintegration.

SSLTransportThessl-enabledshowsyouhowtoconfigureSSLwithApacheActiveMQArtemistosendandreceivemessage.

StaticMessageSelectorThestatic-selectorexampleshowsyouhowtoconfigureanApacheActiveMQArtemiscorequeuewithstaticmessageselectors(filters).

StaticMessageSelectorUsingJMS

Examples

69

Thestatic-selector-jmsexampleshowsyouhowtoconfigureanApacheActiveMQArtemisqueuewithstaticmessageselectors(filters)usingJMS.

StompThestompexampleshowsyouhowtoconfigureanApacheActiveMQArtemisservertosendandreceiveStompmessages.

Stomp1.1ThestompexampleshowsyouhowtoconfigureanApacheActiveMQArtemisservertosendandreceiveStompmessagesviaaStomp1.1connection.

Stomp1.2ThestompexampleshowsyouhowtoconfigureanApacheActiveMQArtemisservertosendandreceiveStompmessagesviaaStomp1.2connection.

StompOverWebSocketsThestomp-websocketsexampleshowsyouhowtoconfigureanApacheActiveMQArtemisservertosendandreceiveStompmessagesdirectlyfromWebbrowsers(providedtheysupportWebSockets).

SymmetricClusterThesymmetric-clusterexampledemonstratesasymmetricclusterset-upwithApacheActiveMQArtemis.

ApacheActiveMQArtemishasextremelyflexibleclusteringwhichallowsyoutoset-upserversinmanydifferenttopologies.Themostcommontopologythatyou'llperhapsbefamiliarwithifyouareusedtoapplicationserverclusteringisasymmetriccluster.

Examples

70

Withasymmetriccluster,theclusterishomogeneous,i.e.eachnodeisconfiguredthesameaseveryothernode,andeverynodeisconnectedtoeveryothernodeinthecluster.

TemporaryQueueAsimpleexampledemonstratinghowtouseaJMStemporaryqueue.

TopicAsimpleexampledemonstratingaJMStopic.

TopicHierarchyApacheActiveMQArtemissupportstopichierarchies.Withatopichierarchyyoucanregisterasubscriberwithawild-cardandthatsubscriberwillreceiveanymessagessenttoanaddressthatmatchesthewildcard.

TopicSelector1Thetopic-selector-example1exampleshowsyouhowtosendmessagetoaJMSTopic,andsubscribethemusingselectorswithApacheActiveMQArtemis.

TopicSelector2Thetopic-selector-example2exampleshowsyouhowtoselectivelyconsumemessagesusingmessageselectorswithtopicconsumers.

TransactionFailoverThetransaction-failoverexampledemonstratestwoserverscoupledasalive-backuppairforhighavailability(HA),andaclientusingatransactedJMSsessionfailingoverfromlivetobackupwhentheliveserveriscrashed.

Examples

71

ApacheActiveMQArtemisimplementsfailoverofclientconnectionsbetweenliveandbackupservers.Thisisimplementedbythesharingofajournalbetweentheservers.Whenalivenodecrashes,theclientconnectionscancarryandcontinuetosendandconsumemessages.Whentransactedsessionsareused,onceandonlyoncemessagedeliveryisguaranteed.

FailoverWithoutTransactionsThestop-server-failoverexampledemonstratesfailoveroftheJMSconnectionfromonenodetoanotherwhentheliveservercrashesusingaJMSnon-transactedsession.

TransactionalSessionThetransactionalexampleshowsyouhowtouseatransactionalSessionwithApacheActiveMQArtemis.

XAHeuristicThexa-heuristicexampleshowsyouhowtomakeanXAheuristicdecisionthroughApacheActiveMQArtemisManagementInterface.AheuristicdecisionisaunilateraldecisiontocommitorrollbackanXAtransactionbranchafterithasbeenprepared.

XAReceiveThexa-receiveexampleshowsyouhowmessagereceivingbehavesinanXAtransactioninApacheActiveMQArtemis.

XASendThexa-sendexampleshowsyouhowmessagesendingbehavesinanXAtransactioninApacheActiveMQArtemis.

CoreAPIExamples

Examples

72

Torunacoreexample,simplycdintotheappropriateexampledirectoryandtypeant

EmbeddedTheembeddedexampleshowshowtoembedtheApacheActiveMQArtemisserverwithinyourowncode.

Examples

73

RoutingMessagesWithWildCardsApacheActiveMQArtemisallowstheroutingofmessagesviawildcardaddresses.

Ifaqueueiscreatedwithanaddressofsayqueue.news.#thenitwillreceiveanymessagessenttoaddressesthatmatchthis,forinstancequeue.news.europeorqueue.news.usaorqueue.news.usa.sport.Ifyoucreateaconsumeronthisqueue,thisallowsaconsumertoconsumemessageswhicharesenttoahierarchyofaddresses.

Note

InJMSterminologythisallows"topichierarchies"tobecreated.

Toenablethisfunctionalitysetthepropertywild-card-routing-enabledinthebroker.xmlfiletotrue.Thisistruebydefault.

Formoreinformationonthewildcardsyntaxtakealookatwildcardsyntaxchapter,alsoseethetopichierarchyexampleintheexamples.

RoutingMessagesWithWildCards

74

UnderstandingtheApacheActiveMQArtemisWildcardSyntaxApacheActiveMQArtemisusesaspecificsyntaxforrepresentingwildcardsinsecuritysettings,addresssettingsandwhencreatingconsumers.

ThesyntaxissimilartothatusedbyAMQP.

AnApacheActiveMQArtemiswildcardexpressioncontainswordsdelimitedbythecharacter'.'(fullstop).

Thespecialcharacters'#'and'*'alsohavespecialmeaningandcantaketheplaceofaword.

Thecharacter'#'means'matchanysequenceofzeroormorewords'.

Thecharacter'*'means'matchasingleword'.

Sothewildcard'news.europe.#'wouldmatch'news.europe','news.europe.sport','news.europe.politics',and'news.europe.politics.regional'butwouldnotmatch'news.usa','news.usa.sport'nor'entertainment'.

Thewildcard'news.*'wouldmatch'news.europe',butnot'news.europe.sport'.

Thewildcard'news.*.sport'wouldmatch'news.europe.sport'andalso'news.usa.spo