IronMQ Java Client

Note: There are some differences from the previous version of IronMQ. For more information please go to Iron.io Dev Center.

Getting Started

There are three ways to get this package.

1. Add it as a Maven dependency Your pom.xml will look something like:

    <dependencies>
        <!-- IronMQ message queue client -->
        <dependency>
            <groupId>io.iron.ironmq</groupId>
            <artifactId>ironmq</artifactId>
            <version>LATEST</version>
        </dependency>
    </dependencies>

2. Download the jar from Maven Repo.

Note: You also need to have several dependencies added to classpath: com.google.code.gson 2.1 or later and org.apache.commons 3.3.1 or later.

For example following commands could be used to run your simple test program:

src$ javac -cp ".:ironmq.jar:gson-2.2.4.jar:commons-lang3-3.1.jar" org/ironmq_test/Program.java
src$ java -cp  ".:ironmq.jar:gson-2.2.4.jar:commons-lang3-3.1.jar" org.ironmq_test.Program

3. Build from source with Apache Buildr:

buildr package

The .jar file will appear under the target directory.

Configure

Initialize a client and get a queue object:

Using iron.json file

Put all settings in iron.json file. At least token and project_id. But host, port, scheme are also supported.

{
  "token": "m6000000000000000000RJ",
  "project_id": "54000000000000000000000d",
  "scheme": "http",
  "host": "mq-aws-us-east-1-1.iron.io",
  "port": 80
}

Then you need to instantiate a Client:

Client client = new Client();

iron.json file could be placed in home directory, in current directory of executing program or in ./config/ directory. File also could be hidden, i.e. to start with . symbol.

In case of using Maven put your iron.json in the root of project (near the pom.xml file) or in home directory.

It's also possible to look for iron.json file in parent directories:

lookUpLimit = 3;
Client client = new Client(<projectId or null>, <token or null>, <cloud or null>, 1, lookUpLimit);

In example above IronMq library will try to find iron.json file in 3 levels of parent folders of executing file.

Specifying configuration in initializer

Client client = new Client("my project", "my token", Cloud.ironAWSUSEast);
Queue queue = client.queue("test-queue");

It's also possible to specify more parameters:

int apiVersion = 3;
Client client = new Client(projectId, token, new Cloud("http", "localhost", 8080), apiVersion);

Keystone 2.0 authorization

iron.json

Add keystone section to your iron.json file

{
  "project_id": "000000000000000000000005",
  "keystone": {
    "server": "http://your.keystone.server/somepath/",
    "tenant": "some_tenant",
    "username": "bob",
    "password": "secret123",
  }
}

Initialize Client with empty token:

client = new Client(projectId, "", new Cloud(scheme, host, port), 3);

Or:

Assumed that IronMQ On-Premise runs on localhost:8080

{
  "scheme":"http",
  "host":"localhost",
  "port":8080,
  "project_id": "000000000000000000000005",
  "keystone": {
    "server": "http://your.keystone.server/somepath/",
    "tenant": "some_tenant",
    "username": "bob",
    "password": "secret123",
  }
}

client = new Client();

In code

client = new Client(projectId, new KeystoneIdentity(server, tenant, username, password), new Cloud(scheme, host, port), 3);

Token in iron.json file will be ignored.

You can combine using of .json config file and initializer. In the example below Client will be initialized with token from config file and project_id specified in code:

Client client = new Client("my project", null);

The Basics

Client client = new Client("my project", "my token", Cloud.ironAWSUSEast);

Post a Message to the Queue

queue.push("Hello, IronMQ!");

More complex example:

String body = "Hello, IronMQ!";
int delay = 0;
String messageId = queue.push(body, delay);

Post multiple messages in one API call:

String[] messages = {"c", "d"};
Ids ids = queue.pushMessages(messages);

--

Get a Message off the Queue

Message msg = queue.reserve();

When you reserve a message from the queue, it will NOT be deleted. It will eventually go back onto the queue after a timeout if you don't delete it (default timeout is 60 seconds).

Get multiple messages in one API call:

Messages messages = queue.reserve(2);

--

Delete a Message from the Queue

Message msg = queue.reserve();
queue.deleteMessage(msg);

Delete a message from the queue when you're done with it.

Delete multiple messages

1. Deleting Messages collection

Messages messages = queue.reserve(4);
queue.deleteMessages(messages);

2. Deleting by Ids

String[] messages = {"hello", "world"};
Ids ids = queue.pushMessages(messages);
queue.deleteMessages();

--

Queues

List Queues

ArrayList<QueueModel> allQueues = Queues.getQueues(client);

Additional Parameters:

• per\_page - number of elements in response, default is 30.
• previous - this is the last queue on the previous page, it will start from the next one. If queue with specified name doesn’t exist result will contain first per_page queues that lexicographically greater than previous
• prefix - an optional queue prefix to search on. e.g., prefix=ca could return queues ["cars", "cats", etc.]

Request below will return 20 queues started with "na" but lexicographically greater than "name_of_previous_queue".

int perPage = 20;
String previous = "name_of_previous_queue";
String prefix = "na";
ArrayList<QueueModel> allQueues = Queues.getQueues(client, previous, perPage, prefix);

--

Retrieve Queue Information

QueueModel infoAboutQueue = queue.getInfoAboutQueue();

--

Delete a Message Queue

queue.destroy();

--

Post Messages to a Queue

Single message:

queue.pushMessage(body);

Multiple messages:

String[] messages = {"c", "d"};
Ids ids = queue.pushMessages(messages);

Optional parameters (3rd, array of key-value pairs):

• delay: The item will not be available on the queue until this many seconds have passed. Default is 0 seconds. Maximum is 604,800 seconds (7 days).

--

Get Messages from a Queue

Single message:

Message msg = queue.reserve();

Multiple messages:

int count = 5;
Messages messages = queue.reserve(count);

Optional parameters:

• count: The maximum number of messages to get. Default is 1. Maximum is 100.

--

Touch a Message on a Queue

Touching a reserved message extends its timeout by the duration specified when the message was created, which is 60 seconds by default.

Message message = queue.reserve();
queue.touchMessage(message);

--

Release Message

Message message = queue.reserve();
int delay = 1;
queue.releaseMessage(message, delay);

Optional parameters:

• delay: The item will not be available on the queue until this many seconds have passed. Default is 0 seconds. Maximum is 604,800 seconds (7 days).

--

Delete a Message from a Queue

Message message = queue.get();
queue.deleteMessage(message);

--

Peek Messages from a Queue

Peeking at a queue returns the next messages on the queue, but it does not reserve them.

Single message:

Messages msg = queue.peek();

Multiple messages:

int count = 2;
Messages msg = queue.peek(count);

--

Clear a Queue

queue.clear();

--

Add alerts to a queue. This is for Pull Queue only.

ArrayList<Alert> alerts = new ArrayList<Alert>();
alerts.add(new Alert(Alert.typeProgressive, Alert.directionAscending, 5, "some_q"));
QueueModel info = queue.updateAlerts(alerts);

--

Push Queues

IronMQ push queues allow you to setup a queue that will push to an endpoint, rather than having to poll the endpoint. Here's the announcement for an overview.

Update a Message Queue

ArrayList<Subscriber> subscribers = new ArrayList<Subscriber>() {{ add(new Subscriber(url)); }};
QueueModel payload = new QueueModel(new QueuePushModel(subscribers, "multicast", 4, 7, "test_err"));
queue.update(payload);

The following parameters are all related to Push Queues:

• subscribers: An array of subscriber hashes containing url field. This set of subscribers will replace the existing subscribers.
• retries: How many times to retry on failure. Default is 3. Maximum is 100.
• retries_delay: Delay between each retry in seconds. Default is 60.

--

Update Queue Subscribers

ArrayList<Subscriber> subscribers = new ArrayList<Subscriber>();
subscribers.add(new Subscriber("http://localhost:3000"));
subscribers.add(new Subscriber("http://localhost:3030"));
queue.updateSubscribers(subscribers);

--

Get Message Push Status

String[] messages = {"test1", "test2"};
Ids ids = queue.pushMessages(messages);
SubscribersInfo subscribersInfo = queue.getPushStatusForMessage(ids.getId(0));

Returns an array of subscribers with status.

--

Acknowledge / Delete Message Push Status

String[] messages = {"test1", "test2"};
Ids ids = queue.pushMessages(messages);
SubscribersInfo subscribersInfo = queue.getPushStatusForMessage(ids.getId(0));
queue.deletePushMessageForSubscriber(ids.getId(0), subscribersInfo.getSubscribers().get(0).id);

--

Further Links

• IronMQ Overview
• IronMQ v3 REST/HTTP API
• Other Client Libraries

---

В© 2011 - 2014 Iron.io Inc. All Rights Reserved.