org.jboss.dna.graph.request
Class CompositeRequestChannel

java.lang.Object
  extended by org.jboss.dna.graph.request.CompositeRequestChannel

public class CompositeRequestChannel
extends Object

A channel for Request objects that can be submitted to a consumer (typically a RequestProcessor or RepositoryConnection) while allowing the channel owner to continue adding more Request objects into the channel.

The owner of this channel is responsible for starting the processing using one of the two start(...) methods, adding Requests via add(...) methods, closing the channel when there are no more requests to be added, and finally awaiting until all of the submitted requests have been processed. Note that the owner can optionally pre-fill the channel with Request objects before calling start(...).

The consumer will be handed a CompositeRequest, and should use the CompositeRequest.iterator() method to obtain an Iterator<Request>. The Iterator.hasNext() method will block until there is another Request available in the channel, or until the channel is closed (at which point Iterator.hasNext() will return false. (Notice that the Iterator.next() method will also block if it is not preceeded by a Iterator.hasNext(), but will throw a NoSuchElementException when there are no more Request objects and the channel is closed.)

Because the CompositeRequest's iterator will block, the consumer will block while processing the request. Therefore, this channel submits the CompositeRequest to the consumer asynchronously, via an ExecutorService supplied in one of the two start methods.


Constructor Summary
CompositeRequestChannel(String sourceName)
          Create a new channel with the supplied channel name.
 
Method Summary
 void add(Request request)
          Add the request to this channel for asynchronous processing.
 CountDownLatch add(Request request, CountDownLatch latch)
          Add the request to this channel for asynchronous processing, and supply a count-down latch that should be decremented when this request is completed.
 void addAndAwait(Request request)
          Add the request to this channel for processing, but wait to return until the request has been processed.
 List<Request> allRequests()
          Get all the requests that were submitted to this queue.
 void await()
          Await until this channel has completed.
 void cancel(boolean mayInterruptIfRunning)
          Cancel this forked channel, stopping work as soon as possible.
 void close()
          Mark this source as having no more requests to process.
 boolean isClosed()
          Return whether this channel has been closed.
 boolean isComplete()
          Return whether this channel has completed all of its work.
 boolean isStarted()
          Return whether this channel has been started .
 String sourceName()
          Get the name of the source that this channel uses.
 void start(ExecutorService executor, ExecutionContext context, RepositoryConnectionFactory connectionFactory)
          Begins processing any requests that have been added to this channel.
 void start(ExecutorService executor, RequestProcessor processor, boolean closeProcessorWhenCompleted)
          Begins processing any requests that have been added to this channel.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CompositeRequestChannel

public CompositeRequestChannel(String sourceName)
Create a new channel with the supplied channel name.

Parameters:
sourceName - the name of the repository source used to execute this channel's requests; may not be null or empty
Method Detail

start

public void start(ExecutorService executor,
                  ExecutionContext context,
                  RepositoryConnectionFactory connectionFactory)
Begins processing any requests that have been added to this channel. Processing is done by submitting the channel to the supplied executor.

Parameters:
executor - the executor that is to do the work; may not be null
context - the execution context in which the work is to be performed; may not be null
connectionFactory - the connection factory that should be used to create connections; may not be null
Throws:
IllegalStateException - if this channel has already been started

start

public void start(ExecutorService executor,
                  RequestProcessor processor,
                  boolean closeProcessorWhenCompleted)
Begins processing any requests that have been added to this channel. Processing is done by submitting the channel to the supplied executor.

Parameters:
executor - the executor that is to do the work; may not be null
processor - the request processor that will be used to execute the requests; may not be null
closeProcessorWhenCompleted - true if this method should call RequestProcessor.close() when the channel is completed, or false if the caller is responsible for doing this
Throws:
IllegalStateException - if this channel has already been started

add

public void add(Request request)
Add the request to this channel for asynchronous processing.

Parameters:
request - the request to be submitted; may not be null
Throws:
IllegalStateException - if this channel has already been closed

add

public CountDownLatch add(Request request,
                          CountDownLatch latch)
Add the request to this channel for asynchronous processing, and supply a count-down latch that should be decremented when this request is completed.

Parameters:
request - the request to be submitted; may not be null
latch - the count-down latch that should be decremented when request has been completed; may not be null
Returns:
the same latch that was supplied, for method chaining purposes; never null
Throws:
IllegalStateException - if this channel has already been closed

addAndAwait

public void addAndAwait(Request request)
                 throws InterruptedException
Add the request to this channel for processing, but wait to return until the request has been processed.

Parameters:
request - the request to be submitted; may not be null
Throws:
InterruptedException - if the current thread is interrupted while waiting

close

public void close()
Mark this source as having no more requests to process.


isClosed

public boolean isClosed()
Return whether this channel has been closed.

Returns:
true if the channel was marked as done, or false otherwise

cancel

public void cancel(boolean mayInterruptIfRunning)
Cancel this forked channel, stopping work as soon as possible. If the channel has not yet been started, this method

Parameters:
mayInterruptIfRunning - true if the channel is still being worked on, and the thread on which its being worked on may be interrupted, or false if the channel should be allowed to finish if it is already in work.

isStarted

public boolean isStarted()
Return whether this channel has been started .

Returns:
true if this channel was started, or false otherwise

isComplete

public boolean isComplete()
Return whether this channel has completed all of its work.

Returns:
true if the channel was started and is complete, or false otherwise

await

public void await()
           throws ExecutionException,
                  InterruptedException,
                  CancellationException
Await until this channel has completed.

Throws:
CancellationException - if the channel was cancelled
ExecutionException - if the channel execution threw an exception
InterruptedException - if the current thread is interrupted while waiting

allRequests

public List<Request> allRequests()
Get all the requests that were submitted to this queue. The resulting list is the actual list that is appended when requests are added, and may change until the channel is closed.

Returns:
all of the requests that were submitted to this channel; never null

sourceName

public String sourceName()
Get the name of the source that this channel uses.

Returns:
the source name; never null


Copyright © 2008-2010 JBoss, a division of Red Hat. All Rights Reserved.