Merge pull request #90 from gmallard/dev
[stomp:mainline.git] / README.rdoc
1 ==README
2
3 * (https://github.com/stompgem/stomp/)
4
5 ===Overview
6
7 An implementation of the Stomp protocol for Ruby. See:
8
9 * [STOMP 1.0, 1.1, and 1.2] (http://stomp.github.com/index.html)
10
11 ===New
12
13 See _CHANGELOG.rdoc_ for details.
14
15 * Gem version 1.3.1. Bugfix for logging.
16 * Gem version 1.3.0. Added ERROR frame raising as exception, added anonymous connections, miscellaneous other fixes.
17 * Gem version 1.2.16. Fixed Stomp::Client to expose its connection's host parameters.
18 * Gem version 1.2.15. Timeout cleanup, added license info to gemspec.
19 * Gem version 1.2.14. Cleanup.
20 * Gem version 1.2.13. Stomp::Client#unreceive max_redeliveries fix.
21 * Gem version 1.2.12. Miscellaneous issue fixes and cleanup.
22 * Gem version 1.2.11. JRuby and AMQ support fixes.
23 * Gem version 1.2.10. Support failover from heartbeat threads.
24 * Gem version 1.2.9. Miscellaneous fixes and changes.
25 * Gem version 1.2.8. Stomp 1.1+ header codec inversion fix, test refactoring.
26 * Gem version 1.2.7. Stomp 1.2 support and miscellaneous fixes.
27 * Gem version 1.2.6. Miscellaneous fixes and changes.
28 * Gem version 1.2.5. Restructure. Forks with modifcations will be affected.
29 * Gem version 1.2.4. Stomp 1.1 heartbeat fix, autoflush capability, miscellaneous fixes.
30 * Gem version 1.2.3. Miscellaneous fixes, see changelog for details.
31 * Gem version 1.2.2. Performance and more SSL enhancements.
32 * Gem version 1.2.1. Full support of SSL certificates.
33 * Gem version 1.2.0. Support of Stomp protocol level 1.1.
34
35 ===Hash Login Example Usage (this is the recommended login technique)
36
37   hash = {
38       :hosts => [
39         # First connect is to remotehost1
40         {:login => "login1", :passcode => "passcode1", :host => "remotehost1", :port => 61612, :ssl => true},
41         # First failover connect is to remotehost2
42         {:login => "login2", :passcode => "passcode2", :host => "remotehost2", :port => 61613, :ssl => false},
43
44       ],
45       # These are the default parameters and do not need to be set
46       :reliable => true,                  # reliable (use failover)
47       :initial_reconnect_delay => 0.01,   # initial delay before reconnect (secs)
48       :max_reconnect_delay => 30.0,       # max delay before reconnect
49       :use_exponential_back_off => true,  # increase delay between reconnect attpempts
50       :back_off_multiplier => 2,          # next delay multiplier
51       :max_reconnect_attempts => 0,       # retry forever, use # for maximum attempts
52       :randomize => false,                # do not radomize hosts hash before reconnect
53       :connect_timeout => 0,              # Timeout for TCP/TLS connects, use # for max seconds
54       :connect_headers => {},             # user supplied CONNECT headers (req'd for Stomp 1.1+)
55       :parse_timeout => 5,                # receive / read timeout, secs
56       :logger => nil,                     # user suplied callback logger instance
57       :dmh => false,                      # do not support multihomed IPV4 / IPV6 hosts during failover
58       :closed_check => true,              # check first if closed in each protocol method
59       :hbser => false,                    # raise on heartbeat send exception
60       :stompconn => false,                # Use STOMP instead of CONNECT
61       :usecrlf => false,                  # Use CRLF command and header line ends (1.2+)
62       :max_hbread_fails => 0,             # Max HB read fails before retry.  0 => never retry
63       :max_hbrlck_fails => 0,             # Max HB read lock obtain fails before retry.  0 => never retry
64       :fast_hbs_adjust => 0.0,            # Fast heartbeat senders sleep adjustment, seconds, needed ...
65                                           # For fast heartbeat senders.  'fast' == YMMV.  If not
66                                           # correct for your environment, expect unnecessary fail overs
67       :connread_timeout => 0,             # Timeout during CONNECT for read of CONNECTED/ERROR, secs
68       :tcp_nodelay => true,               # Turns on the TCP_NODELAY socket option; disables Nagle's algorithm
69       :start_timeout => 10,               # Timeout around Stomp::Client initialization
70     }
71
72     # for client
73     client = Stomp::Client.new(hash)
74
75     # for connection
76     connection = Stomp::Connection.new(hash)
77
78 ===Positional Parameter Usage
79
80     client = Stomp::Client.new("user", "pass", "localhost", 61613)
81     client.publish("/queue/mine", "hello world!")
82     client.subscribe("/queue/mine") do |msg|
83       p msg
84     end
85
86 ===Stomp URL Usage
87
88     # Stomp URL :
89     A Stomp URL must begin with 'stomp://' and can be in one of the following forms:
90
91     stomp://host:port
92     stomp://host.domain.tld:port
93     stomp://login:passcode@host:port
94     stomp://login:passcode@host.domain.tld:port
95
96     e.g. c = Stomp::Client.new(urlstring)
97
98 ===Failover + SSL Example URL Usage
99
100     options = "initialReconnectDelay=5000&randomize=false&useExponentialBackOff=false"
101
102     # remotehost1 uses SSL, remotehost2 doesn't
103     client = Stomp::Client.new("failover:(stomp+ssl://login1:passcode1@remotehost1:61612,stomp://login2:passcode2@remotehost2:61613)?#{options}")
104
105     client.publish("/queue/mine", "hello world!")
106     client.subscribe("/queue/mine") do |msg|
107       p msg
108     end
109
110 ===Historical Information
111
112 Up until March 2009 the project was maintained and primarily developed by Brian McCallister.
113
114 ===Source Code and Project URLs
115
116   https://github.com/stompgem/stomp/
117
118 ===Stomp Protocol Information :
119
120   http://stomp.github.com/index.html
121
122 = Contributors
123
124 The following people have contributed to Stomp:
125
126 * Brian McCallister
127 * Glenn Rempe <glenn@rempe.us>
128 * jstrachan
129 * Marius Mathiesen <marius.mathiesen@gmail.com>
130 * Johan S√∏rensen <johan@johansorensen.com>
131 * Thiago Morello
132 * Guy M. Allard <stompgem@gmail.com>
133 * kookster
134 * Tony Garnock-Jones <tonyg@lshift.net>
135 * chirino
136 * Stefan Saasen
137 * Neil Wilson
138 * Dinesh Majrekar
139 * Kiall Mac Innes
140 * Rob Skaggs
141 * Tom May
142 * Lucas Hills
143 * Chris Needham
144 * R.I. Pienaar
145 * tworker
146 * James Pearson
147 * Craig
148 * Tommy Bishop
149 * Jeremy Gailor
150 * JP Hastings-Spital
151 * Glenn Roberts
152 * Ian Smith
153