Package org.jclouds.openstack.marconi.v1.features

Interface ClaimApi

@Consumes("application/json")
@Path("/claims")
public interface ClaimApi

Provides access to Messages via their REST API.

Method Summary

Modifier and Type	Method	Description
List<Message>	claim(int ttl, int grace, int limit)	This operation claims a set of messages (up to the value of the limit parameter) from oldest to newest and skips any messages that are already claimed.
Claim	get(String claimId)	Gets a specific claim and the associated messages.
boolean	release(String claimId)	This operation immediately releases a claim, making any remaining, undeleted messages that are associated with the claim available to other workers.
void	update(String claimId, int ttl)	Clients should periodically renew claims during long-running batches of work to avoid losing a claim while processing a message.

Method Detail

claim

@Named("claim:claim")
@POST
List<Message> claim(int ttl,
                    int grace,
                    @QueryParam("limit")
                    int limit)

This operation claims a set of messages (up to the value of the limit parameter) from oldest to newest and skips any messages that are already claimed. If no unclaimed messages are available, an empty List is returned.

When a client (worker) finishes processing a message, it should delete the message before the claim expires to ensure that the message is processed only once. As part of the delete operation, workers should specify the claim ID. If workers perform these actions and a claim simply expires, the server can return an error and notify the worker of the race condition. This action gives the worker a chance to roll back its own processing of the given message because another worker can claim the message and process it.

The age given for a claim is relative to the server's clock. The claim's age is useful for determining how quickly messages are getting processed and whether a given message's claim is about to expire.

When a claim expires, it is released. If the original worker failed to process the message, another client worker can then claim the message.

Note that claim creation is best-effort, meaning the worker may claim and return less than the requested number of messages.

To deal with workers that have stopped responding (for up to 1209600 seconds or 14 days, including claim lifetime), the server extends the lifetime of claimed messages to be at least as long as the lifetime of the claim itself, plus the specified grace period. If a claimed message would normally live longer than the grace period, its expiration is not adjusted.

Parameters:

ttl - The TTL attribute specifies how long the server waits before releasing the claim. The ttl value must be between 60 and 43200 seconds (12 hours). You must include a value for this attribute in your request.

grace - The grace value specifies the message grace period in seconds. The value of grace value must be between 60 and 43200 seconds (12 hours). You must include a value for this attribute in your request.

limit - Specifies the number of messages to return, up to 20 messages.

get

@Named("claim:get")
@GET
@Path("/{claim_id}")
@Nullable
Claim get(@PathParam("claim_id")
          String claimId)

Gets a specific claim and the associated messages.

Parameters:

claimId - Specific claim ID of the message to get.

update

@Named("claim:update")
@Path("/{claim_id}")
@Produces("application/json")
void update(@PathParam("claim_id")
            String claimId,
            int ttl)

Clients should periodically renew claims during long-running batches of work to avoid losing a claim while processing a message. The client can renew a claim by including a new TTL for the claim (which can be different from the original TTL). The server resets the age of the claim and applies the new TTL.

Parameters:

claimId - Specific claim ID of the message to get.

ttl - The ttl attribute specifies how long the server waits before releasing the claim. The ttl value must be between 60 and 43200 seconds (12 hours). You must include a value for this attribute in your request.

release

@Named("claim:delete")
@DELETE
@Path("/{claim_id}")
boolean release(@PathParam("claim_id")
                String claimId)

This operation immediately releases a claim, making any remaining, undeleted messages that are associated with the claim available to other workers. This operation is useful when a worker is performing a graceful shutdown, fails to process one or more messages, or is taking longer than expected to process messages, and wants to make the remainder of the messages available to other workers.

Parameters:

claimId - Specific claim ID of the message to get.