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 firstper_page
queues that lexicographically greater thanprevious
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
В© 2011 - 2014 Iron.io Inc. All Rights Reserved.