5%&@      !"#$%&'()*+,-./0123456789:;<=>?This is a receipt. +No receipt was sent with this interaction.  Receiving a  is not an error, 6 but the result of an inconsistent - but harmless -  use of  writeQWith on a queue that does not 4 send receipts. An application should, of course,  not try to wait for a . It will never be confirmed. A valid receipt @ABCDEOpaque Connection handle. * Only valid within the action passed to withConnection. FGHIJKLMNOPQRSTUV@ABCDEFGMNOP@BAABCEDDEFFGMNOPportable experimental 8The Stompl Client uses exceptions to communicate errors  to the user application. You hit a bug! ! This exception is only thrown * when something really strange happened  Thrown by abort 'Thrown when an error frame is received Should be thrown  by user-defined converters Thrown on connection errors, e.g.  connection was disconnected Thrown on transaction errors, e.g.  pending acks  Thrown on wrong uses of queues, e.g. $ use of a queue outside its scope Thrown when something ! against the protocol happens, e.g. # an unexpected frame is received  or a message from a queue  that was not subscribed Thrown  on problems with the socket, e.g. ! when a message cannot be sent  Catches any  , B including asynchronous exceptions coming from internal threads Throws   ! to signal a conversion error.     WXYZ[\]^_`abcdefghijklmW[cfgijkW[cfgijkI"Any content received from a queue  is wrapped in a message. - It is, in particular, the return value of readQ. noThe message Identifier pThe subscription qThe destination The Stomp headers  that came with the message The MIME type of the content The length of the  encoded content rThe transaction, in which  the message was received !The encoded content sThe content tMessage Identifier uvwxyz{|}~'nopqrstuvw|' nopqrsnopqrstvuuvw|k!Options passed to a transaction. 'If a message has been received from a  queue with OMode option other  than # and this message has not yet been . acknowledged when the transaction is ready  to terminate, the ack is missing. & With this option, the transaction  will not commit with missing acks,  but abort and raise . This option has two effects: / 1) Internal interactions of the transaction - with the broker will request receipts; % 2) before ending the transaction, * the library will check for receipts 5 that have not yet been confirmed by the broker 2 (including receipts requested by user calls  such as writeQ or ackWith). .If receipts are pending, when the transaction  is ready to terminate and  with  a value > 0 is given, the transaction will ( wait for pending receipts; otherwise ( the transaction will be aborted with . 5 Note that it, usually, does not make sense to use  this options without , 2 since it is in all probability that a receipt ? has not yet been confirmed when the transaction terminates. 0The timeout in milliseconds (not microseconds!)  to wait for pending receipts. 1 If receipts are pending, when the transaction  is ready to terminate,  and no timeout or a timeout <= 0 is given,  and the option   was passed to withTransaction, ( the transaction will be aborted with ; , otherwise it will wait until all pending / ineractions with the broker have terminated 6 or the timeout has expired - whatever comes first. ! If the timeout expires first,  is raised. Options passed to a connection "Authentication: user and password This option defines the client's bid $ for negotiating heart beats (see ). 3 By default, no heart beats are sent or accepted !The maximum size of TCP/ IP packets. - Indirectly, this options also defines the ! maximum message size which is 10 * maxReceive. 6 By default, the maximum packet size is 1024 bytes. "Tells the connection to wait n milliseconds for the #  sent with  at the end of the session.  The Stomp( protocol advises to request a receipt 3 and to wait for it before actually closing the * socket. Many brokers, however, do not < implement this feature (or implement it inappropriately, 8 closing the connection immediately after having sent  the receipt).  withConnection, for this reason, ignores 7 the receipt by default and simply closes the socket  after having sent the  frame. . If your broker shows a correct behaviour, ' it is advisable to use this option. #Just a nicer word for  $2Returns the content of the message in the format % produced by an in-bound converter      G !"#$    G"!  !" #$    portable experimentalG%'Out-bound converters are much simpler. * Since the application developer knows,  which encoding to use, the MIME type is not needed. 1 The converter receives only the value of type a  and converts it into a . 6 A simple example to create an out-bound converter  for plain strings could be: ! let oconv = return . fromString &/Converters are user-defined actions passed to  1 (&) and  2 (%)  that convert a  to a value of type a (&) or  a value of type a to  (%). % Converters are, hence, similar to put and get in the Binary  monad. 8The reason for using explicit, user-defined converters  instead of Binary encode and decode & is that the conversion with queues ? may be much more complex, involving reading configurations  or other  actions. ? Furthermore, we have to distinguish between data types and 5 there binary encoding when sent over the network.  This distinction is made by MIME types. 1 Two applications may send the same data type,  but one encodes this type as "text/plain",  the other as "text/xml".  &" conversions have to consider the MIME type ; and, hence, need more input parameters than provided by decode.  encode and decode , however, 6 can be used internally by user-defined converters. The parameters expected by an & converter are:  the MIME type of the content  the content size  the list of  coming with the message  the contents encoded as . ;The simplest possible in-bound converter for plain strings  may be created like this: % let iconv _ _ _ = return . toString 'Options that may be passed  to 1 and 2 and their variants. (A queue created with ( will throw   when used outside a . )Expression often used by Ren Artois.  What he tries to say is: If * is either   or , send an acknowledgment ? automatically when a message has been read from the queue. *The option defines the  of the queue,  which is relevant for - only.   is one of:  , , . If * is not given,  is assumed as default. For more details, see . +A queue created with + will wait for the receipt G before returning from a call that has issued a request for receipt. B This implies that the current thread will yield the processor.  63 will internally create a request for receipt and @ wait for the broker to confirm the receipt before returning.  Note that, for 1!, there is no difference between  + and ,. Either option will cause 9 the thread to preempt until the receipt is confirmed. 7On writing a message, this is not always the preferred : method. You may want to fire and forget - for a while, 9 before you check that your message has actually been < handled by the broker. In this case, you will create the  . with , only and, later, after having  sent a message with 7, wait for the receipt using  > . Note that + without ,  has no meaning with 6 and 7. ! If you want to send a receipt ; and wait for the broker to confirm it, you have to use  both options. It is good practice to use timeout with all calls  that may wait for receipts,  ie 1 and 3  with options , or +,  or 6 and 7 with options +,  or 9 and ;. ,A queue created with , will request a receipt ( on all interactions with the broker. B The handling of receipts may be transparent to applications or  may be made visible by using 7. = Note that the option has effect right from the beginning, i.e.  a - created with , will B issue a request for receipt when subscribing to a Stomp queue. -A Queue for receiving messages .A Queue for sending messages.  !"#$%&'(/ A variant of 0 that returns nothing 0)Initialises a connection and executes an  action. 9 The connection life time is the scope of this action.  The connection handle, , that is passed to the action  should not be returned from 0. 6 Connections, however, can be shared among threads. 1 In this case, the programmer has to take care 8 not to terminate the action before all other threads , working on the connection have finished.  Paramter:  ) : The broker's hostname or IP-address  * : The broker's port  +: Control options passed to the connection  ( ->  a): The action to execute. B The action receives the connection handle 4 and returns a value of type a  in the  monad. 02 returns the result of the action passed into it. 0) will always disconnect from the broker A when the action has terminated, even if an exception is raised.  Example:  0 withConnection "localhost" 61613 [] $ \c -> do DThis would connect to a broker listening to the loopback interface,  port number 61613. ! The action is defined after the  hanging do. 0Internally, connections use concurrent threads; 0 errors are communicated by throwing exceptions ' to the owner of the connection, where 5 the owner is the thread that created the connection  by calling 0. : It is therefore advisable to start different connections 8 in different threads, so that each thread will receive : only exceptions related to the connection it has opened.  Example: ? t <- forkIO $ withConnection_ "127.0.0.1" 61613 [] $ \c -> do +,-./01 Creates a -& with the life time of the connection . D Creating a receiving queue involves interaction with the broker; 6 this may result in preempting the calling thread,  depending on the options ['].  Parameters:  The connection handle  9 A queue name that should be unique in your application. > The queue name is useful for debugging, since it appears  in error messages.  The Stomp destination, i.e. the name of the queue : as it is known to the broker and other applications.  A list of options (').  A list of headers (), ) which will be passed to the broker.  the 3 parameter is actually a breach in the abstraction = from the Stomp protocol. A header may be, for instance, ? a selector that restricts the subscription to this queue, 6 such that only messages with certain attributes  (i.e.7 specific headers) are sent to the subscribing client. ; Selectors are broker-specific and typically expressed  as SQL or XPath.  An in-bound converter. A usage example to create a -  with  c and the in-bound converter  iconv would be:  4 q <- newReader c "TestQ" "/queue/test" [] [] iconv  A call to 1 may result in preemption when  one of the options + or , are given;  an example for such a call  with tmo an * value representing a timeout  in microseconds and  the result mbQ of type 1 is: P mbQ <- timeout tmo $ newReader c "TestQ" "/queue/test" [OWaitReceipt] [] oconv  case mbQ of  Nothing -> -- handle error  Just q -> do -- ... 2 Creates a .& with the life time of the connection . I Creating a sending queue does not involve interaction with the broker , and will not preempt the calling thread. 5A sending queue may be created like in the following  code fragment, where oconv is + an already defined out-bound converter: 4 q <- newWriter c "TestQ" "/queue/test" [] [] oconv 3 Creates a - with limited life time. 7 The queue will live only in the scope of the action & that is passed as last parameter. & The function is useful for readers " that are used only temporarly, e.g. during initialisation. = When the action terminates, the client unsubscribes from 6 the broker queue - even if an exception is raised. 3# returns the result of the action. > Since the life time of the queue is limited to the action,  it should not be returned. ( Any operation on a reader created by 3 ! outside the action will raise . A usage example is: @ x <- withReader c "TestQ" "/queue/test" [] [] iconv $ \q -> do 4 A variant of 3 , for actions that do not return anything. 2345*Removes the oldest message from the queue  and returns it as . - The message cannot be read from the queue  by another call to 5 within the same connection. = Wether other connections will receive the message as well ? depends on the broker and the queue patterns it implements. $ If the queue is currently empty, 4 the thread will preempt until a message arrives. If the queue was created with  * other than   and with ) , then an ack - will be automatically sent to the broker;  if ) was not set, - the message will be registered as pending ack. Note that, when 5 sends an ack internally, 2 it will not request a receipt from the broker. 0 The rationale for this design is simplicity. ( If the function expected a receipt, 0 it would have to either wait for the receipt  or return it. , In the first case, it would be difficult < for the programmer to distinguish, on a timeout, between  no message available and  no receipt arrived. # In the second case, the receipt  would need to be returned. 3 This would unnecessarily blow up the interface. , If you need the reliability of receipts, ' you should create the queue without )  and use 9 to acknowledge  the message explicitly. 6Adds the value a% as message at the end of the queue. ) The Mime type as well as the headers  are added to the message. )If the queue was created with the option  ,,  6) will request a receipt from the broker. . If the queue was additionally created with  +,  6. will preempt until the receipt is confirmed. )The Stomp headers are useful for brokers  that provide selectors on  subscribe,  see 1 for details. A usage example for a . q of type )  may be (nullType is defined as text/plain in Codec.MIME):  % writeQ q nullType [] "hello world!" For a . that was created  with , and +, & the function should be called with timeout: : mbR <- timeout tmo $ writeQ q nullType [] "hello world!"  case mbR of  Nothing -> -- error handling  Just r -> do -- ... 7This is a variant of 6 + that is particularly useful for queues  created with ,, but without +.  It returns the #, so that it can be waited for  later, using >. Note that the behaviour of 7, 4 besides of returning the receipt, is the same as 6,  i.e., on a queue with , and +  7, will wait for the receipt being confirmed. 4 In this case, the returned receipt is, in fact, * of no further use for the application. The function is used like: . r <- writeQWith q nullType [] "hello world!" 8Acknowledges the arrival of  to the broker.  It is used with a  c and a  x like:  ack c x 9Acknowledges the arrival of  to the broker, 7 requests a receipt and waits until it is confirmed. ) Since it preempts the calling thread,  it is usually used with timeout,  for a  c, a  x  and a timeout in microseconds tmo like: % mbR <- timeout tmo $ ackWith c x  case mbR of  Nothing -> -- error handling  Just _ -> do -- ... :'Negatively acknowledges the arrival of  to the broker.  For more details see 8. ;'Negatively acknowledges the arrival of  to the broker, 7 requests a receipt and waits until it is confirmed.  For more details see 9. 5< Variant of = that does not return anything. =-Starts a transaction and executes the action  in the last parameter. # After the action has finished, 7 the transaction will be either committed or aborted $ even if an exception was raised. ( Note that, depending on the options, 1 the way a transaction is terminated may vary,  refer to  for details. -Transactions cannot be shared among threads. 1 Transactions are internally protected against @ access from any thread that has not started the transaction. It is not advisable to use = with timeout.  It is preferred to use timeout on the 1 the actions executed within this transaction. 4 Whether and how much time the transaction itself K shall wait for the completion of on-going interactions with the broker, # in particular pending receipts,  shall be controlled  by the  option. =# returns the result of the action. "The simplest usage example with a  c is:  & r <- withTransaction c [] $ \_ -> do GIf the transaction shall use receipts and, before terminating, wait 100ms 2 for all receipts to be confirmed by the broker  = is called like:  G eiR <- try $ withTransaction c [OTimeout 100, OWithReceipts] \_ -> do  case eiR of  Left e -> -- error handling  Right x -> do -- ..  Note that  is used to catch any  . >Waits for the # to be confirmed by the broker. ? Since the thread will preempt, the call should be protected  with timeout, e.g.:  mb_ <- waitReceipt c r  case mb_ of  Nothing -> -- error handling  Just _ -> do -- ... ?.Aborts the transaction immediately by raising  .  The string passed in to ? will be added to the  exception message. 6789:;<=>?@ABCDE@  !"#$%&'()*+,-./0123456789:;<=>?80/"! -.1234',+*)(&%567$#>=<?89:;%&',+*)(()*+,-./0123456789:;<=>?F      !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIHJKJLMNOPQRSTUVWXYZ[66\]^^_`abcdefghijklmnopqrstuvwvxJyz{||}~ikG@Bl||M      !"#$  %&'()*+",-./0123456789:;<=>?@ABstomp-queue-0.0.1Network.Mom.Stompl.Client.Queue#Network.Mom.Stompl.Client.ExceptionFactorySocketProtocolState stompl-0.0.1Network.Mom.Stompl.FrameHeartAutoClient ClientIndiAckModeRecNoRecConStomplException OuchException AppExceptionBrokerExceptionConvertExceptionConnectException TxExceptionQueueExceptionProtocolExceptionSocketExceptiontry convertErrorMessagemsgHdrsmsgTypemsgLenmsgRawToptOAbortMissingAcks OWithReceiptsOTimeoutCoptOAuth OHeartBeatOMaxRecv OWaitBrokerReceipt msgContentOutBoundInBoundQoptOForceTxOAckOMode OWaitReceipt OWithReceiptReaderWriterwithConnection_withConnection newReader newWriter withReader withReader_readQwriteQ writeQWithackackWithnacknackWithwithTransaction_withTransaction waitReceiptabortTxNoTxSubNoSubparseRecnumericconidsubidtxidrecc mkUniqueConId mkUniqueSubId mkUniqueTxId mkUniqueRecc mkUniqueIdincConincSubincTxincReccincXlockreleaseReceiver getBuffer putBufferResultmaxStepgetput initReceiverlockSock releaseSock initWriterconnect tryConnect disconnectsendreceive handlePartialgetInputMsgmsgIdmsgSubmsgDestmsgTxmsgContMsgIdNoMsg SubscriptionsubIdsubNamesubMode ConnectionconAddrconPortconVersconBeatconSrvconSesconUsrconPwdconMaxconSockconRcvconWrtconErrMconTcpconBrk defVersionmkSub mkMessage mkConnection incompleteErrgetSockgetWrgetRc connectedgetErr getVersionbegincommit subscribe unsubscribesendBeat sendFramedisc connectBrokerhandleConnectederrToMsg mkReceiptmkConFmkDiscFmkSubFmkUnSubFmkSendFmkAckFmkBeginF mkCommitFmkAbortFTxStateTxEnded TxStarted TransactionTrntxIdtxStatetxTmo txAbrtAcktxAbrtRctxAckstxRecs ThreadEntry DestEntrySubEntry HeartBeat DisconnectconIdconConconOwner conHisBeat conMyBeatconWaitconSubsconDestsconThrdsconErrsconRecsconAcksmseqisnoWaitstdRecvnoBeatnoAuth oWaitBrokeroMaxRecv oHeartBeatoAuthfindCon addAckToCon rmAckFromCon addRecToCon rmRecFromConcheckReceiptCon addSubToCongetSub rmSubFromCon addDestToCongetDest rmDestFromCon setHisTime setMyTimeupdConfindTxmkTrnhasTopttmo setTxState addAckToTx rmAckFromTx addRecToTx rmRecFromTxcheckReceiptTx txPendingAck txReceiptsconaddCongetConrmConwithConlogTimelogSend logReceiveaddSubaddDestrmSubrmDestaddTxgetTxupdTx updTxStategetCurTxupdCurTxaddAckrmAckaddRecrmRec forceRmRec checkCurTx checkReceiptrmThisTxrmTxbytestring-0.9.2.0Data.ByteString.Internal ByteStringghc-prim GHC.TypesIOHeaderRecvQrConrSubrDestrNamerModerAutorRecrFromSendQwConwDestwNamewRecwWaitwTxwToversbaseGHC.BaseStringInt whenConnectedisThrdthrdwaitConhasQoptackMode Data.MaybeMaybenewSendQnewRecvQunsuback' terminateTxstartTxendTxwaitTxfrmToMsglisten handleMessage handleError throwToOwner handleReceipt handleBeat heartBeatmyMusthisMusttimeAdd ms2nominal