org.apache.qpid.proton.reactor

Interface Reactor

All Known Implementing Classes:

ReactorImpl

public interface Reactor

The proton reactor provides a general purpose event processing library for writing reactive programs. A reactive program is defined by a set of event handlers. An event handler is just any class or object that extends the Handler interface. For convenience, a class can extend BaseHandler and only handle the events that it cares to implement methods for.

This class is not thread safe (with the exception of the wakeup() method) and should only be used by a single thread at any given time.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Reactor.Factory

Method Summary

Modifier and Type	Method and Description
Acceptor	acceptor(java.lang.String host, int port) Creates a new acceptor.
Acceptor	acceptor(java.lang.String host, int port, Handler handler) Creates a new acceptor.
Record	attachments()
java.util.Set<ReactorChild>	children()
Collector	collector()
Connection	connection(Handler handler) Deprecated. Use connectionToHost(String, int, Handler) instead.
Connection	connectionToHost(java.lang.String host, int port, Handler handler) Creates a new out-bound connection to the given host and port.
void	free() Frees any resources (such as sockets and selectors) held by the reactor or its children.
java.lang.String	getConnectionAddress(Connection c) Get the address used by the connection
Handler	getGlobalHandler()
Handler	getHandler()
ReactorOptions	getOptions() Gets the reactor options.
long	getTimeout()
long	mark() Updates the last time that the reactor's state has changed, potentially resulting in events being generated.
long	now()
boolean	process() Process any events pending for this reactor.
boolean	quiesced()
void	run() Simplifies the use of the reactor by wrapping the use of start, run, and stop method calls.
Task	schedule(int delay, Handler handler) Schedules execution of a task to take place at some point in the future.
Selectable	selectable() Creates a new Selectable as a child of this reactor.
void	setConnectionHost(Connection c, java.lang.String host, int port) Set the host address used by the connection
void	setGlobalHandler(Handler handler) Sets a new global handler.
void	setHandler(Handler handler) Sets a new handler, that will receive any events not handled by a child of the reactor.
void	setTimeout(long timeout) The value the reactor will use for Selector.select(long) that is called as part of process().
void	start() Starts the reactor.
void	stop() Stops the reactor.
void	update(Selectable selectable) Updates the specified Selectable either emitting a Event.Type.SELECTABLE_UPDATED event if the selectable is not terminal, or Event.Type.SELECTABLE_FINAL if the selectable is terminal and has not already emitted a Event.Type.SELECTABLE_FINAL event.
void	wakeup() Wakes up the thread (if any) blocked in the process() method.
void	yield() Yields, causing the next call to process() to return successfully - without processing any events.

Method Detail

mark

long mark()

Updates the last time that the reactor's state has changed, potentially resulting in events being generated.

Returns:

the current time in milliseconds System.currentTimeMillis().

now

long now()

Returns:

the last time that mark() was called.

attachments

Record attachments()

Returns:

an instance of Record that can be used to associate other objects (attachments) with this instance of the Reactor class.

setTimeout

void setTimeout(long timeout)

The value the reactor will use for Selector.select(long) that is called as part of process().

Parameters:

timeout - a timeout value in milliseconds, to associate with this instance of the reactor. This can be retrieved using the getTimeout() method

getTimeout

long getTimeout()

Returns:

the value previously set using setTimeout(long) or 0 if no previous value has been set.

getGlobalHandler

Handler getGlobalHandler()

Returns:

the global handler for this reactor. Every event the reactor sees is dispatched to the global handler. To receive every event generated by the reactor, associate a child handler with the global handler. For example:

            getGlobalHandler().add(yourHandler);
         

setGlobalHandler

void setGlobalHandler(Handler handler)

Sets a new global handler. You probably don't want to do this and would be better adding a handler to the value returned by the {getGlobalHandler() method.

Parameters:

handler - the new global handler.

getHandler

Handler getHandler()

Returns:

the handler for this reactor. Every event the reactor sees, which is not handled by a child of the reactor (such as a timer, connection, acceptor, or selector) is passed to this handler. To receive these events, it is recommend that you associate a child handler with the handler returned by this method. For example:

           getHandler().add(yourHandler);
         

setHandler

void setHandler(Handler handler)

Sets a new handler, that will receive any events not handled by a child of the reactor. Note that setting a handler via this method replaces the previous handler, and will result in no further events being dispatched to the child handlers associated with the previous handler. For this reason it is recommended that you do not use this method and instead add child handlers to the value returned by the getHandler() method.

Parameters:

handler - the new handler for this reactor.

children

java.util.Set<ReactorChild> children()

Returns:

a set containing the child objects associated with this reactor. This will contain any active instances of: Task - created using the schedule(int, Handler) method, Connection - created using the connectionToHost(String, int, Handler) method, Acceptor - created using the acceptor(String, int) method, acceptor(String, int, Handler) method, or Selectable - created using the selectable() method.

collector

Collector collector()

Returns:

the Collector used to gather events generated by this reactor.

selectable

Selectable selectable()

Creates a new Selectable as a child of this reactor.

Returns:

the newly created Selectable.

update

void update(Selectable selectable)

Updates the specified Selectable either emitting a Event.Type.SELECTABLE_UPDATED event if the selectable is not terminal, or Event.Type.SELECTABLE_FINAL if the selectable is terminal and has not already emitted a Event.Type.SELECTABLE_FINAL event.

Parameters:

selectable -

yield

void yield()

Yields, causing the next call to process() to return successfully - without processing any events. If multiple calls can be made to yield and only the next invocation of process() will be affected.

quiesced

boolean quiesced()

Returns:

true if the reactor is in quiesced state (e.g. has no events to process). false is returned otherwise.

process

boolean process()
         throws HandlerException

Process any events pending for this reactor. Events are dispatched to the handlers registered with the reactor, or child objects associated with the reactor. This method blocks until the reactor has no more work to do (and no more work pending, in terms of scheduled tasks or open selectors to process).

Returns:

true if the reactor may have more events in the future. For example: if there are scheduled tasks, or open selectors. false is returned if the reactor has (and will have) no more events to process.

Throws:

HandlerException - if an unchecked exception is thrown by one of the handlers - it will be re-thrown attached to an instance of HandlerException.

wakeup

void wakeup()

Wakes up the thread (if any) blocked in the process() method. This is the only method of this class that is thread safe, in that it can be used at the same time as another thread is using the reactor.

start

void start()

Starts the reactor. This method should be invoked before the first call to process().

stop

void stop()
   throws HandlerException

Stops the reactor. This method should be invoked after the last call to process().

Throws:

HandlerException

run

void run()
  throws HandlerException

Simplifies the use of the reactor by wrapping the use of start, run, and stop method calls.

Logically the implementation of this method is:

   start();
   while(process()) {}
   stop();
 

Throws:

HandlerException - if an unchecked exception is thrown by one of the handlers - it will be re-thrown attached to an instance of HandlerException.

schedule

Task schedule(int delay,
              Handler handler)

Schedules execution of a task to take place at some point in the future.

Parameters:

delay - the number of milliseconds, in the future, to schedule the task for.

handler - a handler to associate with the task. This is notified when the deadline for the task is reached.

Returns:

an object representing the task that has been scheduled.

connection

@Deprecated
Connection connection(Handler handler)

Deprecated. Use connectionToHost(String, int, Handler) instead.

Creates a new out-bound connection.

Parameters:

handler - a handler that is notified when events occur for the connection. Typically the host and port to connect to would be supplied to the connection object inside the logic which handles the Event.Type.CONNECTION_INIT event via setConnectionHost(Connection, String, int)

Returns:

the newly created connection object.

connectionToHost

Connection connectionToHost(java.lang.String host,
                            int port,
                            Handler handler)

Creates a new out-bound connection to the given host and port.

This method will cause Reactor to set up a network connection to the host and create a Connection for it.

Parameters:

host - the host to connect to (e.g. "localhost")

port - the port used for the connection.

handler - a handler that is notified when events occur for the connection.

Returns:

the newly created connection object.

setConnectionHost

void setConnectionHost(Connection c,
                       java.lang.String host,
                       int port)

Set the host address used by the connection

This method will set/change the host address used by the Reactor to create an outbound network connection for the given Connection

Parameters:

c - the Connection to assign the address to

host - the address of the host to connect to (e.g. "localhost")

port - the port to use for the connection.

getOptions

ReactorOptions getOptions()

Gets the reactor options.

Returns:

the reactor options

getConnectionAddress

java.lang.String getConnectionAddress(Connection c)

Get the address used by the connection

This may be used to retrieve the remote peer address. Note that the returned address may be in numeric IP format.

Parameters:

c - the Connection

Returns:

a string containing the address in the following format:

   host[:port]
 

acceptor

Acceptor acceptor(java.lang.String host,
                  int port)
           throws java.io.IOException

Creates a new acceptor. This is equivalent to calling:

   acceptor(host, port, null);
 

Parameters:

host -

port -

Returns:

the newly created acceptor object.

Throws:

java.io.IOException

acceptor

Acceptor acceptor(java.lang.String host,
                  int port,
                  Handler handler)
           throws java.io.IOException

Creates a new acceptor. This acceptor listens for in-bound connections.

Parameters:

host - the host name or address of the NIC to listen on.

port - the port number to listen on.

handler - if non-null this handler is registered with each new connection accepted by the acceptor.

Returns:

the newly created acceptor object.

Throws:

java.io.IOException

free

void free()

Frees any resources (such as sockets and selectors) held by the reactor or its children.