Skip to content

Using proJMS

Jump to bottom
Hauke Altmann edited this page Jul 10, 2013 · 1 revision

Jargon

proJMS allows to publish messages. Each message published can be received by one or more Consumer. To connect Publishers and Consumers, Topics are used. When you send a message, you'll have to specify the Topic that message belongs to. Every Consumer that subscribed to this Topic will then receive the message.

A message must be of a Type. When a Consumer receives a message it can decide based on the Type of the message what to do with it.

Publishing messages

First import the Publisher class from the pro JMS library and create a Publisher object.

import projms.publisher.Publisher;
import java.util.UUID;
Publisher messagePublisher;

In the setup function, initialize the Publisher:

messagePublisher = new Publisher("peer://group1/" + UUID.randomUUID().toString(), this);

The first parameter of the constructor of publisher is the URI of the messaging broker the Publisher connects to. When using the peer protocol as in the example above, the Publisher will start it's own broker which will connect with every other broker in the same network with the same group ("group1") specified. The function call UUID.randomUUID().toString() creates an random string for the id of the Consumer. This is a good way to go most of the time because there can't be two Consumers with the same id in a group and there might be the use case that you want to start several Consumers without having to configure the client id in a static way for every instance. But you can also choose your own id without using a random function. "peer://group2/consumer1" would be a valid URI as well.

If you want to connect to an existing broker, f.e. if the Consumers are on another network, you can specify a different URI here. Please refer to the transport configuration documentation on the ActiveMQ website.

The second parameter is your sketch.

Sending a message:

void mousePressed() {
    //sends a message of the type "EXAMPLE_TYPE" to all consumers 
    //that listen on the "EXAMPLE_TOPIC"
    messagePublisher.sendMessage(
        "Mouse has been pressed", "EXAMPLE_TYPE", "EXAMPLE_TOPIC"
    );
}

For sending a message you'll need to specify the text message you want to send (first param), the type of the message and the topic.

The type can be any string. You just need to make sure, that your consumers can deal with this type. If you are only sending messages of one type, your consumer can simply ignore this parameter.

The topic can be any string. Make sure that the consumers that should get the message are subscribed to this topic.

Please have a look at the example sketches in the "examples" folder of the proJMS zip file for the full example. Receiving messages

First import the Consumer class from the proJMS library and create a Consumer object:

import projms.consumer.Consumer;
import java.util.UUID;
Consumer messageConsumer;

In the setup function initialize the Consumer, specifying the broker to connect to and the topic to listen to.

messageConsumer = new Consumer(
    this, "peer://group1/" + UUID.randomUUID().toString(), "EXAMPLE_TOPIC"
);

To receive messages you need to implement the function onMessageArrival in your sketch. This method will be called every time a message arrives.

//Whenever a message arrives this method is called
void onMessageArrival(String messageText, String messageType){
    //different message types can be handled differently here
    if(messageType.equals("EXAMPLE_TYPE")){
        //do something
    }
}

You can check the type of the message to handle different message types in a different way. USING proJMS with applications in different networks

It is necessary for this scenario to connect to a standalone messaging broker. If you are not running one already, it is necessary to set one up. A standard AtiveMQ messaging broker can be set up pretty easy if you've got some basic knowledge of the unix shell. However, i've got to admit that this is a more advanced issue.

Out of the box proJMS will allow you to connect your processing applications that reside in the same network. To make this possible, every application starts it's own ActiveMQ messaging broker. The brokers then connect using the peer protocol. In most cases this will not work anymore if you want to connect applications that run in different networks connected through a router because the messages using the peer protocol won't pass the router firewall.

For this scenario you will need to use a different protocol. ActiveMQ offers a variety of protocols that can be used. To keep this documentation short we will only explain the usage of the TCP and the HTTP protocol. Please refer to the ActiveMQ transport configuration section if you want to use another protocol or if you want to know more details about it. Using the TCP Protocol

If you don't have an ActiveMQ messaging broker up and running (or know the URI of one someone else runs), read the ActiveMQ Getting started section first to install and run your own messaging broker.

The tcp protocol is the default protocol used by ActivMQ to connect Publishers and Consumers with the message broker. Initializing a Publisher or consumer is straightforward if you know the URI:

 messagePublisher = new Publisher("tcp://yourdomain.org:61616", this);

and:

messageConsumer = new Consumer(
    this, "tcp://yourdomain.org:61616", "EXAMPLE_TOPIC"
);

In the example above your Publisher object will connect to a messaging broker at yourdomain.org running on port 61616 (which is the default port of this protocol). If a messaging broker is running there and the router firewall of the network your running the sketch in is allowing connections to that port using that protocol, you're finished.

If your router firewall is configured more strict it could happen that connections to that port with that protocol are blocked. In that case you can try using the HTTP protocol, described in the next section. Using the HTTP Protocol

If you don't have an ActiveMQ messaging broker up and running (or know the URI of one someone else runs), read the ActiveMQ Getting started section first to install and run your own messaging broker.

If you want to use the HTTP protocol with proJMS you'll need to install some more Java libraries first. Please have a look at the [Installation] page and install the optional HTTP Client and XStream libraries there.

You also need to activated the HTTP transport connector on your ActiveMQ messaging broker. Refer to the ActiveMQ transport configuration section for that.

You will need to add a HTTP transportConnector to your activemq.conf file:

<broker>
  ...
  <transportConnectors>
    <transportConnector name="http" uri="http://0.0.0.0:8080"/>  
  </transportConnectors>
  ...
</broker>

If you got a broker with HTTP enabled running on yourdomain.org, you can initialize Publishers and Consumers like this:

messagePublisher = new Publisher("http://yourdomain.org:8080", this);

and:

messageConsumer = new Consumer(
    this, "http://yourdomain.org:8080", "EXAMPLE_TOPIC"
);
Clone this wiki locally