Package generic.concurrent

# Class ConcurrentQBuilder<I,R>

java.lang.Object
generic.concurrent.ConcurrentQBuilder<I,R>

Type Parameters:
  `I` - The type of the items to be processed.
  `R` - The type of objects resulting from processing an item

public class ConcurrentQBuilder<I,R> extends Object
A helper class to build up the potentially complicated `ConcurrentQ`.

Note: you must supply either a `GThreadPool` instance or a thread pool name. Further, if you supply the name of a thread pool, then a private, non-shared pool will be used. If you wish to make use of a shared pool, then you need to create that thread pool yourself. See `GThreadPool.getSharedThreadPool(String)`.

Examples:

     QCallback<I, R> callback = new AbstractQCallback<I, R>() {
         public R process(I item, TaskMonitor monitor) {
             // do work here...
         }
     };

     ConcurrentQBuilder<I, R> builder = new ConcurrentQBuilder<I, R>();
     builder.setThreadPoolName("Thread Pool Name");
     builder.setQueue(new PriorityBlockingQueue());
     concurrentQ = builder.build(callback);

     // OR, you can chain the builder calls:
     ConcurrentQBuilder<I, R> builder = new ConcurrentQBuilder<I, R>();
     queue = builder.setThreadPoolName("Thread Pool Name").
     				setQueue(new PriorityBlockingQueue()).
     				setMaxInProgress(1).
     				build(callback);

Note: if you wish to take advantage of blocking when adding items to the `ConcurrentQ`, see `setQueue(Queue)`.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ConcurrentQBuilder()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `ConcurrentQ<I,R>`
  `build(QCallback<I,R> callback)`
  Builds the final `ConcurrentQ`.
  `ConcurrentQBuilder<I,R>`
  `setCancelClearsAllJobs(boolean clearAllJobs)`
  Sets whether a cancel will clear all jobs (current and pending) or just the current jobs being processed.
  `ConcurrentQBuilder<I,R>`
  `setCollectResults(boolean collectResults)`
  Specifies if the concurrent queue should collect the results as items are processed so they can be returned in a `ConcurrentQ.waitForResults()` or `ConcurrentQ.waitForNextResult()` call.
  `ConcurrentQBuilder<I,R>`
  `setJobsReportProgress(boolean reportsProgress)`
  True signals that the jobs run by the client wish to report progress.
  `ConcurrentQBuilder<I,R>`
  `setListener(QItemListener<I,R> listener)`
  `ConcurrentQBuilder<I,R>`
  `setMaxInProgress(int max)`
  Specifies the maximum number of items that can be process at a time.
  `ConcurrentQBuilder<I,R>`
  `setMonitor(TaskMonitor monitor)`
  `ConcurrentQBuilder<I,R>`
  `setQueue(Queue<I> queue)`
  Sets the queue to be used by the `ConcurrentQ`.
  `ConcurrentQBuilder<I,R>`
  `setThreadPool(GThreadPool threadPool)`
  Use the given thread pool for processing the work items.
  `ConcurrentQBuilder<I,R>`
  `setThreadPoolName(String name)`
  Sets the name to be used when creating a private thread pool.

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### ConcurrentQBuilder

    public ConcurrentQBuilder()

- ## Method Details

  - ### setQueue

    public ConcurrentQBuilder<I,R> setQueue(Queue<I> queue)
    Sets the queue to be used by the `ConcurrentQ`. If you would like advanced features, like a queue that blocks when too many items have been placed in it, then use an advanced queue here, such as a `LinkedBlockingQueue`.

    Note: if you wish to take advantage of blocking when adding items to the `ConcurrentQ`, then be sure to call the appropriate method, such as `ConcurrentQ.offer(java.util.Iterator)`.

    Parameters:
      `queue` - the queue to be used by the `ConcurrentQ`
    Returns:
      this builder

  - ### setMaxInProgress

    public ConcurrentQBuilder<I,R> setMaxInProgress(int max)
    Specifies the maximum number of items that can be process at a time. If this is set to 0, then the concurrent queue will attempt to execute as many items at a time as there are threads in the given threadPool. Setting this parameter to 1 will have the effect of guaranteeing that all times are processed one at a time in the order they were submitted. Any other positive value will run that many items concurrently, up to the number of available threads.
    Parameters:
      `max` - the max number of items to execute at one time; defaults to 0
    Returns:
      this builder instance

  - ### setThreadPoolName

    public ConcurrentQBuilder<I,R> setThreadPoolName(String name)
    Sets the name to be used when creating a private thread pool. If you wish to use a shared thread pool, then you need to create that thread pool yourself and call `setThreadPool(GThreadPool)`.
    Parameters:
      `name` - the name of the thread pool.
    Returns:
      this builder instance
    See Also:
      - `GThreadPool.getSharedThreadPool(String)`

  - ### setThreadPool

    public ConcurrentQBuilder<I,R> setThreadPool(GThreadPool threadPool)
    Use the given thread pool for processing the work items. If you do not care to configure the thread pool used and you do not wish to make use of shared thread pools, then you can call `setThreadPoolName(String)` instead of this method.
    Parameters:
      `threadPool` - the thread pool to use
    Returns:
      this builder instance
    See Also:
      - `GThreadPool.getSharedThreadPool(String)`

  - ### setCollectResults

    public ConcurrentQBuilder<I,R> setCollectResults(boolean collectResults)
    Specifies if the concurrent queue should collect the results as items are processed so they can be returned in a `ConcurrentQ.waitForResults()` or `ConcurrentQ.waitForNextResult()` call.
    Parameters:
      `collectResults` - true signals to collect the generated results; defaults to false
    Returns:
      this builder instance

  - ### setJobsReportProgress

    public ConcurrentQBuilder<I,R> setJobsReportProgress(boolean reportsProgress)
    True signals that the jobs run by the client wish to report progress. The default value is false.

    The default of false is good for clients that have a known amount of work to be processed. In this case, a total count of work jobs is maintained by the queue. As items are completed, the queue will update the monitor provided to it at construction time to reflect the number of jobs completed as work is done. On the other hand, some clients have no known number of jobs to complete, but simply add work to the queue as it arrives. In that case, the client should update its monitor for progress, as the queue cannot do so in a meaningful way.

    Parameters:
      `reportsProgress` - true signals that the client will update progress; false signals that the queue should do so
    Returns:
      this builder instance

  - ### setListener

    public ConcurrentQBuilder<I,R> setListener(QItemListener<I,R> listener)

  - ### setMonitor

    public ConcurrentQBuilder<I,R> setMonitor(TaskMonitor monitor)

  - ### setCancelClearsAllJobs

    public ConcurrentQBuilder<I,R> setCancelClearsAllJobs(boolean clearAllJobs)
    Sets whether a cancel will clear all jobs (current and pending) or just the current jobs being processed. The default value is `true`.
    Parameters:
      `clearAllJobs` - if true, cancelling the monitor will cancel all items currently being processed by a thread and clear the scheduled items that haven't yet run. If false, only the items currently being processed will be cancelled.
    Returns:
      this builder
    See Also:
      - `ConcurrentQ.setMonitor(TaskMonitor, boolean)`

  - ### build

    public ConcurrentQ<I,R> build(QCallback<I,R> callback)
    Builds the final `ConcurrentQ`.
    Parameters:
      `callback` - the callback for processing each job
    Returns:
      the new queue