## Stomp Tutorial

### Telnet client

Because Stomp frames consist of plain text, it is possible to improvise a Stomp client by starting up a `telnet` session and entering Stomp frames directly at the keyboard. This can be a useful diagnostic tool and is also a good way to learn about the Stomp protocol.

### Typing the null character

While most characters in a Stomp frame are just plain text, there is one required character, null, that you might have difficulty typing at the keyboard. On some keyboards, you can type null as Ctrl-@. Other keyboards might require you to do a bit of research, however.

For example, to type a null character on the 101-key keyboard that is commonly used with a Windows PC, proceed as follows:

1. Enable `NumLock` on the numeric keypad (this is essential).

2. While holding down the `Alt` key, type zero, `0`, four times in succession on the numeric keypad.

### Tutorial steps

To send and receive messages over the Stomp protocol using telnet clients, perform the following steps:

1. Start the broker .

2. Start a telnet session for the producer .

3. Start a Stomp session for the producer .

4. Send a message to a queue .

5. Check the queue status using JMX .

6. Start a telnet session for the consumer .

7. Start a Stomp session for the consumer .

8. Subscribe to a queue .

9. Acknowledge a message .

10. Unsubscribe from the queue .

11. Disconnect the clients .

### Start the broker

Start the default broker by entering the following at a command prompt:

    activemq

Normally, the default broker is configured to initialize a Stomp connector that listens on port, 61613. Look for a line like the following in the broker’s log:

    INFO  TransportServerThreadSupport   - Listening for connections at:
    stomp://localhost:61613

If the Stomp connector is not present in the broker, you will have to configure it—see Configure the broker for details.

### Start a telnet session for the producer

Open a new command prompt and start a new `telnet` session for the producer client, by entering the following command:

    telnet

This command starts `telnet` in interactive mode. Now enter the following `telnet` commands (the `telnet` prompt that begins each line is implementation dependent):

    telnet> set localecho
    Local echo on
    telnet> open localhost 61613

After entering the `open` command, `telnet` should connect to the Stomp socket on your local ActiveMQ broker (where the Stomp port is presumed to be 61613 here). You should now see a blank screen, where you can directly type the contents of the Stomp frames you want to send over TCP.

### Start a Stomp session for the producer

Start a Stomp session for the producer by entering the following Stomp frame in the `telnet` window:

    CONNECT
    login:foo
    passcode:bar

    ^@

The `login` and `passcode` headers are currently ignored by the ActiveMQ broker, so you can enter any values you like for these headers. Don’t forget to insert a blank line after the headers. Finally, you must terminate the frame by typing the null character, `^@` (for notes on how to type the null character at your keyboard, see Typing the null character ).

If all goes well, you will see a response similar to the following:

    CONNECTED
    session:ID:fboltond820-2290-1190810591249-3:0

### Send a message to a queue

Send a message to the `FOO.BAR` queue by entering the following frame:

    SEND
    destination:/queue/FOO.BAR
    receipt:

    Hello, queue FOO.BAR
    ^@

As soon as you have finished typing the null character, `^@`, you should receive the following `RECEIPT` frame from the server:

    RECEIPT
    receipt-id:

It is a good idea to include a `receipt` header in the frames you send from a telnet client. It enables you to confirm that the connection is working normally.

### Check the queue status using JMX

The status of the ActiveMQ broker can be monitored through a JMX port. To monitor the broker, start a new command prompt and enter the following command:

    jconsole

The `jconsole` utility is a standard JMX client that is included with Sun’s Java Development Kit (JDK). When you start the `jconsole` utility, a dialog appears and prompts you to connect to a JMX process, as shown in Figure 3.1 .

Figure 3.1. Connecting to the ActiveMQ JMX Port

Select the ActiveMQ broker process and click Connect. The main `jconsole` window opens. To view the current status of the `FOO.BAR` message queue, click on the MBeans tab and use the tree on the left hand side to drill down to `org.apache.activemq/localhost/Queue/FOO.BAR`. Click on the `FOO.BAR` icon to view the current status, as shown in Figure 3.2 .

Figure 3.2. Monitoring the Status of the FOO.BAR Queue

The status shows an EnqueueCount of 1, which tells you that the producer has successfully enqueued one message in the `FOO.BAR` queue.

### Start a telnet session for the consumer

Open a new command prompt and start a new `telnet` session for the consumer client, by entering the following command:

    telnet

Enter the following `telnet` commands to connect to the Stomp socket on the broker:

    telnet> set localecho
    Local echo on
    telnet> open localhost 61613

### Start a Stomp session for the consumer

Start a Stomp session for the consumer by entering the following Stomp frame in the consumer’s `telnet` window:

    CONNECT
    login:foo
    passcode:bar

    ^@

If all goes well, you will see a response similar to the following:

    CONNECTED
    session:ID:fboltond820-2290-1190810591249-3:1

### Subscribe to a queue

Subscribe to the `FOO.BAR` queue by entering the following Stomp frame in the consumer’s `telnet` window:

    SUBSCRIBE
    destination:/queue/FOO.BAR
    ack:client

    ^@

The `ack` header is set to the value `client`, which implies that the consumer client is expected to acknowledge each message it receives from the broker. After typing the terminating null character, `^@`, the broker dispatches the sole message on the `FOO.BAR` queue by sending a `MESSAGE` frame, as follows:

    MESSAGE
    destination:/queue/FOO.BAR
    receipt:
    timestamp:1190811984837
    priority:0
    expires:0
    message-id:ID:fboltond820-2290-1190810591249-3:0:-1:1:1

    Hello, queue FOO.BAR

To see what effect this has on the queue status, go to the `jconsole` window and click Refresh on the MBeans tab. The DispatchCount attribute is now equal to 1, indicating that the broker has dispatched the message to the consumer. The DequeueCount is equal to 0, however; this is because the message is not considered to be dequeued until the consumer client sends an acknowledgement.

### Acknowledge a message

Acknowledge the received message by entering the following Stomp frame in the consumer’s `telnet` window:

    ACK
    message-id:ID:fboltond820-2290-1190810591249-3:0:-1:1:1

    ^@

Where the message ID must match the value from the `message-id` header in the received `MESSAGE` frame. To check that the acknowledgement has been effective, go back to the `jconsole` window and click Refresh on the MBeans tab. You should now find that the DequeueCount has increased to 1.

### Unsubscribe from the queue

Unsubscribe from the `FOO.BAR` queue by entering the following Stomp frame in the consumer’s `telnet` window:

    UNSUBSCRIBE
    destination:/queue/FOO.BAR
    receipt:

    ^@

### Disconnect the clients

To shut down both the producer and consumer gracefully, enter the following `DISCONNECT` frame in each of their respective `telnet` windows:

    DISCONNECT

    ^@