Did you know ... | Search Documentation: |
library(stomp): STOMP client. |
This module provides a STOMP (Simple (or Streaming) Text Orientated Messaging Protocol) client. This client is based on work by Hongxin Liang. The current version is a major rewrite, both changing the API and the low-level STOMP frame (de)serialization.
The predicate stomp_connection/5 is used to register a connection. The connection is established by stomp_connect/1, which is lazily called from any of the predicates that send a STOMP frame. After establishing the connection two threads are created. One receives STOMP frames and the other manages and watches the heart beat.
Upon receiving a frame the callback registered with stomp_connection/5 is called in the context of the receiving thread. More demanding applications may decide to send incomming frames to a SWI-Prolog message queue and have one or more worker threads processing the input. Alternatively, frames may be inspected by the receiving thread and either processed immediately or be dispatched to either new or running threads. The best scenario depends on the message rate, processing time and concurrency of the Prolog application.
All message sending predicates of this library are thread safe. If two threads send a frame to the same connection the library ensures that both frames are properly serialized.
By default this library tries to establish the connection and the
user gets notified by means of a disconnected
pseudo frame
that the connection is lost. Using the Options argument of stomp_connection/6
the system can be configured to try and keep connecting if the server is
not available and reconnect if the connection is lost. See the pong.pl
example.
call(Callback, Command, Connection, Header, Body)
Where command is one of the commands below. Header is a
dict holding the STOMP frame header, where all values are strings except
for the 'content-length'
key value which is passed as an
integer.
Body is a string or, if the data is of the type
application/json
, a dict.
content-type
of the message is
application/json
and a string otherwise.message
.Note that stomp_teardown/1 causes the receiving and heartbeat thread to be signalled with abort/0.
Options processed:
false
600
(10 minutes).application/json
content to Prolog. Default is []
.Address | is a valid address for tcp_connect/3.
Normally a term
Host:Port, e.g., localhost:32772 . |
Host | is a path denoting the STOMP host.
Often just / . |
Headers | is a dict with STOMP headers used
for the CONNECT request. |
Connection | is an opaque ground term that identifies the connection. |
inf
or infinite
,
keep retrying forever.CONNECT
frame. Protocol version and heartbeat
negotiation will be handled. STOMP
frame is not used for
backward compatibility.
This predicate waits for the connection handshake to have completed. Currently it waits for a maximum of 10 seconds after establishing the socket for the server reply.
Calling this on an established connection has no effect.
stomp_error(connect, Connection, Detail)
if no connection
could be established.SEND
frame. If content-type
is not
provided,
text/plain
will be used. content-length
will
be filled in automatically.
SEND
frame. JSON
can be either a JSON
term or a dict.
content-type
is filled in automatically as application/json
and content-length
will be filled in automatically as well.
SUBSCRIBE
frame.
UNSUBSCRIBE
frame.
ACK
frame. See stomp_ack/2
for simply passing the header received with the message we acknowledge.
NACK
frame. See stomp_nack/2
for simply passing the header received with the message we acknowledge.
ack
field in the header and
reply with an id
. For STOMP 1.2 we reply with the message-id
and
subscription
that we received with the message.BEGIN
frame. @see http://stomp.github.io/stomp-specification-1.2.html\#BEGINCOMMIT
frame.
ABORT
frame.
SEND
messages inside the transaction with the transaction id. If Goal
fails or raises an exception the transaction is aborted. Failure or
exceptions cause the transaction to be aborted using stomp_abort/2,
after which the result is forwarded.DISCONNECT
frame. If the connection has the reconnect
property set to true
, this will be reset to disconnected
to avoid reconnecting. A subsequent stomp_connect/2
resets the reconnect status.