A little outside of the scope of this document, but the reactor is an event source for letting an application know about events in the Proton messaging system. With this set of APIs an application can be register handlers that are notified when a connection is created, a message received, or a session closes.
An application creates handlers, objects which provide methods through which the reactor notifies the application's components of events and allows them each to handle the ones in which they are interested (see the Chain Of Responsibility design pattern for more on this idea). There are some pre-defined handlers for responding to incoming message events, outgoing message events, data flow and managing the AMQP endpoints. Look in the Qpid::Proton::Handlers package for more details on these classes.
The reactor examples come with a sample broker which can be used by other examples and which also works as an example itself. For now we'll just start up the broker example and tell it to listen on port 8888:
$ ruby ../examples/ruby/reactor/broker.rb --address=0.0.0.0:8888 Listening on 0.0.0.0:8888
This example broker will receive messages, create queues as needed, and deliver messages to endpoints.
Our first example creates an endpoint that sends messages to a queue to which it is subscribed. So it both sends and receives its message in one pass.
To start it, simply run:
$ ruby ../examples/ruby/reactor/helloworld.rb --address=0.0.0.0:8888 --queue=examples Hello world!
As you can see, the classic message was output by the example. Now let‘s take a look at what’s going on under the covers.
The following events occur while helloworld.rb runs:
The next example we'll look at will send the classic “Hello world” message to itself directly. This example shows some very fundamental elements of the reactor APIs that you should understand.
To launch the example:
$ ruby helloworld_direct.rb --address=0.0.0.0:8888/examples Hello world!
Not very different from the example that uses the broker, which is what we‘d expect from the outside. But let’s take a look inside of the example and see how it's different at that level
The direct version takes on the responsibility for listening to incoming connections as well as making an outgoing connection. So we see the following additional events occurring:
Now that we‘ve covered the basics with the archetypical hello world app, let’s look at some more interesting examples.
There are four example applications that demonstrate how to send and receive messages both directly and through an intermediary, such as a broker:
Simple send and direct send may, at first, seem to be so similar that you wonder why they're not just the same applciation. And I know for me I was wonder as I wrote the list above why there were two examples. The reason is that simple_send.rb uses the intermediary transfer responses to the messages it sends, while direct_send.rb uses an Acceptor to listen for an process responses.
You can use the examples in the follow ways:
simple_send.rb -> broker <- simple_recv.rb simple_send.rb -> direct_recv.rb direct_send.rb -> simple_recv.rb
In this set of examples we see the following event occurring, in addition to what we've seen before:
The broker.rb example application is a nice demonstration of doing something more interesting in Ruby with Proton.
The way the broker works is to listen to incoming connections, examine the components of the address for that connection, attach that connection to an exchange managing that address and then it sends any messages destined for that address to them.
The components of the broker example include:
The Broker manages a map connecting a queue address to the instance of Exchange that holds references to the endpoints of interest.
The broker application demonstrates a new set of reactor events: