Download - Table of Contents - Apache ActiveMQ · Apache ActiveMQ Artemis is an asynchronous messaging system, an example of Message Oriented Middleware , we'll just call them messaging systems

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