# stomp gem examples

This is to describe the existing stomp gem examples.

## Environment Variables

You will likely need to use supported environment variables to
define example related data elements for your system. See example
stomp_common.rb for details of support of this functionality.

         Environment Variable
    
         Description

         STOMP_LOGIN
    
         The user ID when connecting to a broker.
    Default: guest.

         STOMP_PASSCODE
    
         The user password when connecting to a broker.
    Deault: guest.

         STOMP_HOST
    
         The broker host name.
    Default: localhost.

         STOMP_PORT
    
         The broker port number.
    Default: 61613.

         STOMP_VHOST
    
         The name of the broker's virtual host for 1.1+ connections.
    Default: localhost.

         STOMP_PROTOCOL
    
         The Stomp protocol level to use.
    Default: 1.2.

         STOMP_HEARTBEATS
    
         The Stomp heart beat parameters to use.
    Default: nil/none.

         STOMP_NMSGS
    
         The number of messages to put and/or get.
    Default: 1.

         STOMP_DEST
    
         The default name of a Stomp destination.
    Default: /queue/(time-stamp).

         STOMP_SUPPRESS_CL
    
         Whether to include a 'suppress_content_length' header in a message.
    Default: false.

         STOMP_SSL
    
         Whether to use an SSL connection.
    Default: false.

## General Examples

Note: you will need a running broker to use these examples.

### examples/client_conndisc.rb

A plain example of using a `Stomp#Client` to:

* Connect to a broker
* Disconnect from the broker

### examples/client_putget.rb

An example of using a `Stomp#Client` to:

* Connect to a broker
* Send and receive some message(s)
* Disconnect from the broker

### examples/conn_conndisc.rb

A plain example of using a `Stomp#Connection` to connect to:

* Connect to a broker
* Disconnect from the broker

### examples/conn_putget.rb

An example of using a `Stomp#Connection` to:

* Connect to a broker
* Send and receive some message(s)
* Disconnect from the broker

### examples/examplogger.rb

This example shows how to write a Stomp gem callback logger.

A callback logger can be used to greatly enhance understanding of
application flow, and the gem actions resulting from that flow.

### examples/logexamp.rb

This example shows how to use the example callback logger in
'examples/examplogger.rb'.

### examples/putget_file.rb

This example is primarily meant to measure performance when sending
 (possibly) large messages.

This example show how to:

* Open a file
* Read the entire file into a buffer
* Close the file
* Connect to a broker
* Send the entire file as a single message
* Disconnect from the broker

### examples/putget_rephdrs.rb

The Stomp 1.1+ specifications describe functionality for supporting multiple user supplied
headers with the same header key.

Experience shows that various real world brokers support this functionality
in a variety of ways.

The gem supports multiple headers with the same key.  This example
demonstrates that support.

However, given the variety of broker support, this example works only with the
(now defunct?) Apache Apollo broker.

You should modify the example to work with other brokers.

## Artemis Specific Examples

The Apache Artemis broker exhibits some behavior that is unusual for a
Stomp broker.

This behavior is to sever connections fairly quickly if there is no
activity on the connection.  The current default is 1 minute of
inactivity.

There are several approaches that a client can use to 'bypass' this
behavior.

### examples/artemis/cliwaiter_not_reliable.rb

This example uses a `Stomp#Client` that specifies `:reliable => false` in the
connection parameters.

### examples/artemis/cliwaiter_reliable_hb.rb

This example uses a `Stomp#Client` that specifies `:reliable => true` in the
connection parameters and also uses Stomp heart beats to help keep a connection
alive.


## Historical Examples

These are examples that are bing kept for historical reasons.  They
have been part of the gem's history since very early days of development.

### examples/historical/consumer.rb

The classical message consumer.

### examples/historical/producer.rb

The classical message producer.

### examples/historical/topic_consumer.rb

The classical message consumer (from a topic).

### examples/historical/topic_producer.rb

The classical message producer (to a topic).
