stomp 0.3.4

A full STOMP 1.2 client implementation. Allows programs to interact with message queueing services like ActiveMQ and RabbitMQ.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

stomp-rs ![Travis CI Build Status](https://api.travis-ci.org/zslayton/stomp-rs.png?branch=master)
=====
`stomp-rs` provides a full [STOMP](http://stomp.github.io/stomp-specification-1.2.html) 1.2 client implementation for the [Rust programming language](http://www.rust-lang.org/). This allows programs written in Rust to interact with message queueing services like [ActiveMQ](http://activemq.apache.org/) and [RabbitMQ](http://www.rabbitmq.com/).

- [x] Connect
- [x] Subscribe
- [x] Send
- [x] Acknowledge (Auto/Client/ClientIndividual)
- [x] Transactions
- [x] Receipts
- [x] Disconnect
- [x] Heartbeats

The APIs for `stomp-rs` are not yet stable and are likely to fluctuate before v1.0.

## Examples
### Connect / Subscribe / Send
```rust
extern crate stomp;
use stomp::frame::Frame;
use stomp::subscription::{Ack, AckOrNack, Client};

fn main() {
  let mut session = match stomp::connect("127.0.0.1", 61613) {
    Ok(session)  => session,
    Err(error) => panic!("Could not connect to the server: {}", error)
  };
  
  // The callback system will switch to unboxed closures when that language feature is available
  fn on_message(frame: &Frame) -> AckOrNack {
    println!("Received a message:\n{}", frame);
    Ack
  }
  
  let topic = "/topic/messages";
  session.subscribe(topic, Client, on_message); // 'client' acknowledgement mode
  
  // Send arbitrary bytes with a specified MIME type
  session.send_bytes(topic, "text/plain", "Animal".as_bytes());
  
  // Send UTF-8 text with an assumed MIME type of 'text/plain'
  session.send_text(topic, "Vegetable");
  session.send_text(topic, "Mineral");
  
  session.listen(); // Loops infinitely, awaiting messages
}
```

### Transactions
```rust
  let mut tx = match session.begin_transaction() {
    Ok(tx) => tx,
    Err(error) => panic!("Could not begin new transaction: {}", error)
  };

  tx.send_text(topic, "Animal");
  tx.send_text(topic, "Vegetable");
  tx.send_text(topic, "Mineral");

  tx.commit(); // Or tx.abort();
```

### Receipts
```rust
  session.send_text_with_receipt(topic, "Modern Major General");
  debug!("Oustanding Receipt IDs: {}", session.oustanding_receipts());
```

### Handling RECEIPT frames
```rust
  fn on_receipt(frame: &Frame) {
    debug!("RECEIPT frame received:\n{}", frame);
  }

  session.on_receipt(on_receipt);
  session.send_text_with_receipt(topic, "Modern Major General");
```

### Handling ERROR frames
```rust
  fn on_error(frame: &Frame) {
    panic!("ERROR frame received:\n{}", frame);
  }

  session.on_error(on_error);
```

### Cargo.toml
```toml
[package]

name = "stomp_test"
version = "0.0.1"
authors = ["your_name_here"]

[[bin]]

name = "stomp_test"

[dependencies.stomp]

git = "https://github.com/zslayton/stomp-rs.git"
```

keywords: `Stomp`, `Rust`, `rust-lang`, `rustlang`, `cargo`, `ActiveMQ`, `RabbitMQ`, `Message Queue`, `MQ`