Package one.world.io

This package defines support for structured I/O.

See:
Description

Interface Summary

PendingRequest.Collection

The interface required for collections of pending requests.

Class Summary

BenchmarkDatagramIO	Benchmarks DatagramIO.
BenchmarkDatagramIOLatency	Helper class for DatagramIO latency benchmark.
BenchmarkDatagramIOReceiver	Receiver-side helper class for DatagramIO throughput benchmark.
BenchmarkDatagramIOSender	Sender-side helper class for DatagramIO throughput benchmark.
BenchmarkNetworkIO	Benchmarks NetworkIO.
BenchmarkNetworkIOLatency	Helper class for NetworkIO latency benchmark.
BenchmarkNetworkIOReceiver	Receiver-side helper class for NetworkIO throughput benchmark.
BenchmarkNetworkIOSender	Sender-side helper class for NetworkIO throughput benchmark.
BenchmarkTupleStore	Perform tests for TupleStore operations.
DatagramIO	A factory for datagram I/O clients and servers.
DatagramIO.Client	An unreliable network I/O client.
DeleteRequest	Implementation of a delete request.
FlushEvent	Implementation of a flush event.
InputByIdResponse	Implementation of an input by ID response.
InputRequest	Implementation of an input request.
InputResponse	Implementation of an input response.
ListenResponse	Implementation of a listen response.
NetworkIO	A factory for network I/O clients and servers.
NetworkIO.Server	Accepts connections at a local IP address and TCP port.
OptionEvent	Implementation of an option event.
OutputRequest	Implementation of an output request.
OutputResponse	Implementation of an output response.
PendingInputRequests	Manages input requests that are waiting for matching tuples.
PendingInputRequests.Wrapper	A component wrapper for the PendingInputRequests manager.
PendingRequest	Encapsulates a pending input request, allowing it to be leased and removed.
Query	Implementation of a query.
QueryResponse	Implementation of a query response.
RemovePendingRequest	Implementation of a request to remove a pending input request from a PendingInputRequests manager.
SimpleInputRequest	Implementation of a simple input request.
SimpleOutputRequest	Implementation of a simple output request.
SioResource	Implementation of a descriptor for a structured I/O resource.
SynchronousPendingInputRequests	Manages input requests that are waiting for matching tuples.
TestDatagramIO	Regression tests for DatagramIO.
TestNetworkIO	Regression tests for NetworkIO.
TestPendingInputRequests	Regression tests for PendingInputRequests.
TestSioResource	Implementation of regression tests for structured I/O resource descriptors.
TestTupleFilter	Test set for TupleFilter and SerializedTupleFilter.
TestTupleStore	Basic tests for TupleStore.
TupleFilter	Implementation of a tuple filter, used to process queries.
TupleStore	A implementation of persitant storage though structured IO.

Exception Summary

AlreadyExistsException	Implementation of an already exists exception.
NoSuchTupleException	Implementation of a no such tuple exception.

Package one.world.io Description

This package defines support for structured I/O. Structured I/O implements input and output over tuples. The individual operations are

• put to put or write a tuple,
• read to read a tuple,
• listen to listen for new tuples,
• query to query for all tuples,
• delete to delete a tuple.

There are two kinds of event handlers for structured I/O. The first kind is used for structured I/O across communication channels. Handlers of the first kind only support atomic put, read, and listen operations and accept requests of type SimpleOutputRequest and SimpleInputRequest. The second kind is used for structured I/O on storage. Handlers of the second kind support all operations and, in addition to simple input and output requests, accept requests of type OutputRequest, DeleteRequest, and InputRequest. Structured I/O operations on storage are atomic by default and can optionally be executed as part of a transaction (though this feature has not yet been implemented).

The put operation on a communications channel simply puts the specified tuple into the channel. The put operation for storage adds a new tuple to the tuple store, if no tuple with the ID of the specified tuple exists in the store, and overwrites a tuple in the tuple store, if a tuple with the ID of the specified tuple already exists in the store.

The duration for read requests is the time to wait for any result before aborting the operation. The duration for query and listen requests is the requested time for the lease on the result iterator and on the listener, respectively.

Read, listen, and query operations can either return the entire matching tuple(s) or only the tuple ID(s) in their responses. Returning only the ID(s) is useful for operations that only need to confirm the arrival or existence of a tuple or subsequently delete a set of tuples.

Structured I/O event handlers signal the completion of a put operation with a OutputResponse containing the ID of the tuple written.

If reading an entire tuple, read operations return a InputResponse containing a single matching tuple if found. If there was no matching tuple, the InputResponse.tuple field is set to null. If reading only a tuple ID, read operations return a InputByIdResponse containing the ID of a single matching tuple if found. If there was no matching tuple, the InputByIdResponse.ident field is set to null.

If a delete operation actually deletes a tuple, it returns a OutputResponse containing the ID of the deleted tuple. If the store contains no tuple matching the ID of the delete request, a NoSuchTupleException is returned.

listen requests immediately return a ListenResponse containing the lease for the ongoing listen. As tuples are matched, a InputResponse is returned for each matching tuple.

query requests result in a QueryResponse containing a handler QueryResponse.iter for a query iterator as well as a handler QueryResponse.lease for the lease on the iterator. To retrieve the next element found, send a IteratorRequest to the iterator handler. If a IteratorRequest is sent to an iterator for a query which returned no results, a IteratorEmpty is returned. If a IteratorRequest is sent to an iterator which has already returned all its elements, NoSuchElementException is returned.

If several read and listen operations are outstanding at the same time, a newly added tuple is first matched against any outstanding listen operations and then against any outstanding read operations. Listen operations do not consume a tuple.

Structured I/O operations may result in an exceptional event. In addition to the specific exceptions mentioned above, there are several more general exceptions returned by Structured I/O. A TransactionException signals an exceptional condition regarding a specified transaction, for example, that the transaction cannot be joined or that it is unrecognized. A LeaseException signals an exceptional condition regarding the lease for a requested listen or query operation, for example, that the requested lease has been denied. Finally, a IOException signals an exceptional condition when performing the actual I/O.

Note that IOUtilities provides several helper methods to perform structured I/O operations.