Skip to content

Latest commit

 

History

History
406 lines (275 loc) · 9.42 KB

README.md

File metadata and controls

406 lines (275 loc) · 9.42 KB
Raw

IronMQ Java Client

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>0.0.19</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": "0000000000000000JhRJ",
  "project_id": "54000000000000000000000d",
  "scheme": "http",
  "host": "mq-aws-us-east-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");
Client client = new Client("my project", "my token", Cloud.ironAWSUSEast);

IronMQ supports multiple clouds/regions:

  • Cloud.ironAWSEUWest
  • Cloud.ironRackspaceORD
  • Cloud.ironRackspaceLON
  • and more...

For full list, view /src/main/java/io/iron/ironmq/Cloud.java

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 timeout = 30;
int delay = 0;
int expiresIn = 0;
String messageId = queue.push(body, timeout, delay, expiresIn);

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.get();

When you pop/get 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:

Message msg = queue.get(2);

--

Delete a Message from the Queue

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

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

Delete multiple messages in one API call:

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

Delete multiple messages specified by messages id array.

--

Queues

List Queues

Queues queues = new Queues(client);
ArrayList<QueueModel> allQueues = queues.getAllQueues();

--

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):

  • timeout: After timeout (in seconds), item will be placed back onto queue. You must delete the message from the queue to ensure it does not go back onto the queue. Default is 60 seconds. Minimum is 30 seconds. Maximum is 86,400 seconds (24 hours).

  • 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).

  • expires_in: How long in seconds to keep the item on the queue before it is deleted. Default is 604,800 seconds (7 days). Maximum is 2,592,000 seconds (30 days).

--

Get Messages from a Queue

Single message:

Message msg = queue.get();

Multiple messages:

int count = 5;
Message msg = queue.get(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.

String messageId = "xxxxxxxxxxxxxx";
queue.touchMessage(messageId);

--

Release Message

int delay = 1;
queue.releaseMessage(id, 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 msg = queue.get();
queue.deleteMessage(msg);

--

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.

queue.addAlertsToQueue(alertsArrayList);

Replace current queue alerts with a given list of alerts. This is for Pull Queue only.

queue.updateAlertsToQueue(alertsArrayList);

Remove alerts from a queue. This is for Pull Queue only.

queue.deleteAlertsFromQueue(alertsArrayList);

Remove alert from a queue by its ID. This is for Pull Queue only.

queue.deleteAlertFromQueueById(alertid);

--

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

String subscriberUrl1 = "http://mysterious-brook-1807.herokuapp.com/ironmq_push_1";
Subscriber subscriber = new Subscriber();
subscriber.url = subscriberUrl1;
subscriberArrayList.add(subscriber);

int retries = 3;
int retriesDelay = 3;
queue.updateQueue(subscriberArrayList, "multicast", retries, retriesDelay);

The following parameters are all related to Push Queues:

  • subscribers: An array of subscriber hashes containing a “url” field. This set of subscribers will replace the existing subscribers. To add or remove subscribers, see the add subscribers endpoint or the remove subscribers endpoint. See below for example json.
  • push_type: Either multicast to push to all subscribers or unicast to push to one and only one subscriber. Default is multicast.
  • 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.

--

Add/Remove Subscribers on a Queue

Add subscriber to Push Queue:

String subscriberUrl1 = "http://mysterious-brook-1807.herokuapp.com/ironmq_push_1";
Subscriber subscriber = new Subscriber();
subscriber.url = subscriberUrl1;
subscriberArrayList.add(subscriber);

queue.addSubscribersToQueue(subscriberArrayList);

queue.removeSubscribersFromQueue(subscribersToRemove);

--

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.pushMssages(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.