one.world.util
Class IOUtilities

java.lang.Object
  |
  +--one.world.util.IOUtilities

public final class IOUtilities

extends Object

Implementation of I/O utilities. This class provides supporting functionality for binding resources, managing leases, and performing structured I/O. It includes several synchronous helper methods, which should be used with caution: They are intended for utilities, but should only see limited use in applications. All synchronous invocations performed by the methods in this class time out after Constants.SYNCHRONOUS_TIMEOUT.

Note that this class will be removed in a future release.

Warning: Synchronous invocations may result in deadlock. In particular, performing n concurrent synchronous invocations in an environment with n threads results in deadlock. As a result, components that are not thread-safe must not perform synchronous invocations.

Instead of using a synchronous invocation for a request/response interaction consider using an Operation. Operations do not capture the executing thread and are more flexible since they support retries for timed out request/response interactions. To use an operation, you need to write an additional event handler, called the continuation, that handles the result of the request/response interaction.

Version:

$Revision: 1.6 $

Method Summary

static BindingResponse	bind(EventHandler handler, Tuple descriptor) Bind the specified resource.
static BindingResponse	bind(EventHandler handler, Tuple descriptor, long duration) Bind the specified resource.
static void	delete(EventHandler handler, Guid id) Delete the tuple with the specified ID.
static IteratorElement	next(EventHandler iterator) Get the next element from the specified iterator.
static void	put(EventHandler handler, Tuple t, boolean simple) Put the specified tuple.
static QueryResponse	query(EventHandler handler, Query q) Query for all tuples matching the specified query.
static QueryResponse	query(EventHandler handler, Query q, long duration) Query for all tuples matching the specified query.
static QueryResponse	query(EventHandler handler, Query q, long duration, boolean idOnly) Query for all tuples matching the specified query.
static Tuple	read(EventHandler handler, Query q) Read a tuple matching the specified query.
static Tuple	read(EventHandler handler, Query q, long timeout, boolean simple) Read a tuple matching the specified query.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

bind

public static BindingResponse bind(EventHandler handler,
                                   Tuple descriptor)
                            throws UnknownResourceException,
                                   LeaseDeniedException

Bind the specified resource. This method synchronously binds the specified resource by issueing a binding request to the specified request handler. The requested lease duration is the lease default duration.

Parameters:

handler - The request handler.

descriptor - The resource descriptor.

Returns:

The corresponding binding response.

Throws:

IllegalArgumentException - Signals that descriptor is not a valid tuple, that handler does not accept binding requests, or that handler responds to binding requests with an unrecognized event.

TimeOutException - Signals that the synchronous invocation of handler has timed out.

UnknownResourceException - Signals that the specified resource is not recognized by the specified request handler.

LeaseDeniedException - Signals that the lease for the specified resource has been denied.

bind

public static BindingResponse bind(EventHandler handler,
                                   Tuple descriptor,
                                   long duration)
                            throws UnknownResourceException,
                                   LeaseDeniedException

Bind the specified resource. This method synchronously binds the specified resource by issueing a binding request to the specified request handler.

Parameters:

handler - The request handler.

descriptor - The resource descriptor.

duration - The initial lease duration.

Returns:

The corresponding binding response.

Throws:

IllegalArgumentException - Signals that descriptor is not a valid tuple, that duration is an invalid lease duration, that handler does not accept binding requests, or that handler responds to binding requests with an unrecognized event.

TimeOutException - Signals that the synchronous invocation of handler has timed out.

UnknownResourceException - Signals that the specified resource is not recognized by the specified request handler.

LeaseDeniedException - Signals that the lease for the specified resource has been denied.

put

public static void put(EventHandler handler,
                       Tuple t,
                       boolean simple)
                throws ResourceRevokedException

Put the specified tuple. This method synchronously writes the specified tuple to the specified structured I/O resource.

Parameters:

handler - The event handler for the structured I/O resource.

t - The tuple to put.

simple - true if a simple output request should be used.

Throws:

IllegalArgumentException - Signals that t is invalid, that handler does not accept (simple) output requests, or that handler responds with an unrecognized event.

TimeOutException - Signals that the synchronous invocation of handler has timed out.

ResourceRevokedException - Signals that the resource managed by the specified event handler has been revoked.

delete

public static void delete(EventHandler handler,
                          Guid id)
                   throws ResourceRevokedException,
                          NoSuchTupleException

Delete the tuple with the specified ID. This method synchronously deletes the tuple with the specified ID from the specified tuple store.

Parameters:

handler - The event handler for the tuple store.

id - The ID of the tuple to delete.

Throws:

IllegalArgumentException - Signals that handler does not accept delete requests or that handler responds with an unrecognized event.

TimeOutException - Signals that the synchronous invocation of handler has timed out.

ResourceRevokedException - Signals that the resource managed by the specified event handler has been revoked.

NoSuchTupleException - Signals that no tuple with the specified ID exists.

read

public static Tuple read(EventHandler handler,
                         Query q)
                  throws ResourceRevokedException

Read a tuple matching the specified query. This method synchronously reads a tuple matching the specified query from the specified tuple store. The read request times out immediately, thus only reading a tuple if that tuple already exists in the tuple store.

Parameters:

handler - The event handler for the structured I/O resource.

q - The query to match.

Returns:

The corresponding tuple or null if no tuple matches the query.

Throws:

IllegalArgumentException - Signals that q is invalid, that handler does not accept input requests, or that handler responds with an unrecognized event.

TimeOutException - Signals that the synchronous invocation of handler has timed out.

ResourceRevokedException - Signals that the resource managed by the specified event handler has been revoked.

read

public static Tuple read(EventHandler handler,
                         Query q,
                         long timeout,
                         boolean simple)
                  throws ResourceRevokedException

Read a tuple matching the specified query. This method synchronously reads a tuple matching the specified query from the specified structured I/O resource.

Note that the specified time-out is not the time-out of the synchronous invocation, but rather the time-out of the structured I/O read operation.

Parameters:

handler - The event handler for the structured I/O resource.

q - The query to match.

timeout - The time-out for the read operation.

simple - true if a simple input request should be used.

Returns:

The corresponding tuple or null if no tuple matches the query.

Throws:

IllegalArgumentException - Signals that q is invalid, that handler does not accept (simple) input requests, or that handler responds with an unrecognized event.

TimeOutException - Signals that the synchronous invocation of handler has timed out.

ResourceRevokedException - Signals that the resource managed by the specified event handler has been revoked.

query

public static QueryResponse query(EventHandler handler,
                                  Query q)
                           throws ResourceRevokedException,
                                  LeaseDeniedException

Query for all tuples matching the specified query. This method synchronously queries the specified tuple store.

Parameters:

handler - The event handler for the tuple store.

q - The query to match.

Returns:

The corresponding result.

Throws:

IllegalArgumentException - Signals that q is invalid, that handler does not accept input requests, or that handler responds with an unrecognized event.

TimeOutException - Signals that the synchronous invocation of handler has timed out.

ResourceRevokedException - Signals that the resource managed by the specified event handler has been revoked.

LeaseDeniedException - Signals that the lease for the iterator over the query's results has been denied.

query

public static QueryResponse query(EventHandler handler,
                                  Query q,
                                  long duration)
                           throws ResourceRevokedException,
                                  LeaseDeniedException

Query for all tuples matching the specified query. This method synchronously queries the specified tuple store.

Parameters:

handler - The event handler for the tuple store.

q - The query to match.

duration - The requested duration for the query iterator.

Returns:

The corresponding result.

Throws:

IllegalArgumentException - Signals that q is invalid, that duration is invalid, that handler does not accept input requests, or that handler responds with an unrecognized event.

TimeOutException - Signals that the synchronous invocation of handler has timed out.

ResourceRevokedException - Signals that the resource managed by the specified event handler has been revoked.

LeaseDeniedException - Signals that the lease for the iterator over the query's results has been denied.

query

public static QueryResponse query(EventHandler handler,
                                  Query q,
                                  long duration,
                                  boolean idOnly)
                           throws ResourceRevokedException,
                                  LeaseDeniedException

Query for all tuples matching the specified query. This method synchronously queries the specified tuple store.

Parameters:

handler - The event handler for the tuple store.

q - The query to match.

duration - The requested duration for the query iterator.

idOnly - The flag for whether to only query for the tuple IDs.

Returns:

The corresponding result.

Throws:

IllegalArgumentException - Signals that q is invalid, that duration is invalid, that handler does not accept input requests, or that handler responds with an unrecognized event.

TimeOutException - Signals that the synchronous invocation of handler has timed out.

ResourceRevokedException - Signals that the resource managed by the specified event handler has been revoked.

LeaseDeniedException - Signals that the lease for the iterator over the query's results has been denied.

next

public static IteratorElement next(EventHandler iterator)

Get the next element from the specified iterator. This method synchronously gets the next element from the specified iterator.

Parameters:

iterator - The event handler for the iterator.

Returns:

The next element.

Throws:

IllegalArgumentException - Signals that handler does not accept iterator requests, or that iterator responds to iterator requests with an unrecognized event.

TimeOutException - Signals that the synchronous invocation of iterator has timed out.

NoSuchElementException - Signals that the iterator has no elements left.