Author: mes
Date: 2010-12-07 17:20:34 -0800 (Tue, 07 Dec 2010)
New Revision: 23125
Added:
core3/work-api/trunk/src/main/java/org/cytoscape/work/ValuedTask.java
core3/work-api/trunk/src/main/java/org/cytoscape/work/ValuedTaskExecutor.java
Log:
added ValuedTask back
Added: core3/work-api/trunk/src/main/java/org/cytoscape/work/ValuedTask.java
===================================================================
--- core3/work-api/trunk/src/main/java/org/cytoscape/work/ValuedTask.java
(rev 0)
+++ core3/work-api/trunk/src/main/java/org/cytoscape/work/ValuedTask.java
2010-12-08 01:20:34 UTC (rev 23125)
@@ -0,0 +1,54 @@
+package org.cytoscape.work;
+
+/**
+ * Describes a unit of work that produces a result asynchronously.
+ * This interface is identical to <code>Task</code>, except it allows
+ * <code>run</code> to return a result. This interface is analogous to
+ * <code>java.util.concurrency.Future</code>.
+ *
+ * Because a <code>ValuedTask</code> cannot be executed by a
+ * <code>TaskManager</code>, an instance of this interface is typically wrapped
+ * by an instance of <code>ValuedTaskExecutor</code> in order to be
+ * executed by a <code>TaskManager</code>.
+ *
+ * @author Pasteur
+ */
+public interface ValuedTask<V>
+{
+ /**
+ * This method contains the action of the <code>ValuedTask</code>.
+ *
+ * This method should not be called by the programmer,
+ * since it will be called by the <code>TaskManager</code>.
+ *
+ * @return a useful result to be retrieved by another thread
+ * after the execution of this <code>ValuedTask</code> has completed.
+ *
+ * @param taskMonitor This is provided by <code>TaskManager</code>
+ * to allow the <code>ValuedTask</code> to modify its user interface.
+ *
+ * @throws Exception The <code>ValuedTask</code> is at liberty to
+ * throw an exception. The exception is
+ * caught by <code>TaskManager</code> and the information contained
+ * by the exception is displayed in the interface.
+ */
+ V run(TaskMonitor taskMonitor) throws Exception;
+
+ /**
+ * This method is called when the user chooses to cancel the
+ * <code>Task</code>.
+ *
+ * This method should not be called by the programmer,
+ * since it will be called by the <code>TaskManager</code>.
+ *
+ * <p>This method should inform the <code>run</code> method that it must
+ * terminate execution cleanly and do any necessary cleanup
+ * work required.</p>
+ *
+ * <p><i>WARNING:</i> this method is called by a different
+ * thread than the thread executing <code>run</code>.
+ * The programmer <i>must</i> be aware of
+ * concurrency issues.</p>
+ */
+ void cancel();
+}
Added:
core3/work-api/trunk/src/main/java/org/cytoscape/work/ValuedTaskExecutor.java
===================================================================
---
core3/work-api/trunk/src/main/java/org/cytoscape/work/ValuedTaskExecutor.java
(rev 0)
+++
core3/work-api/trunk/src/main/java/org/cytoscape/work/ValuedTaskExecutor.java
2010-12-08 01:20:34 UTC (rev 23125)
@@ -0,0 +1,208 @@
+package org.cytoscape.work;
+
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.CancellationException;
+import java.util.concurrent.TimeoutException;
+
+/**
+ * A class for wrapping <code>ValuedTask</code>s so they can be executed
+ * by a <code>TaskManager</code>.
+ * This class is analogous to <code>java.util.concurrency.FutureTask</code>.
+ *
+ * <p>Here is an example of how this class can be used:
+ * <br>
+ * <code>
+ * ValuedTask<Integer> myValuedTask = ...;<br>
+ * TaskManager taskManager = ...;<br>
+ * ValuedTaskExecutor<Integer> myValuedTaskExecutor = new
ValuedTaskExecutor<Integer>(myValuedTask);<br>
+ * taskManager.execute(myValuedTaskExecutor);<br>
+ * ...<br>
+ * Integer result = myValuedTaskExecutor.get();<br>
+ * </code></p>
+ *
+ * @author Pasteur
+ */
+public class ValuedTaskExecutor<V> implements Task
+{
+ /**
+ * Describes the state the <code>ValuedTask</code> is in.
+ */
+ public static enum State
+ {
+ /**
+ * The <code>ValuedTask</code> has been created
+ * and is ready to be executed, but the
+ * <code>run</code> method has not yet been called.
+ *
+ * This is the default state of the
+ * <code>ValuedTaskExecutor</code> when it is created.
+ */
+ READY,
+
+ /**
+ * The <code>ValuedTask</code>'s
+ * <code>run</code> method is currently
+ * being executed.
+ */
+ RUNNING,
+
+ /**
+ * The <code>ValuedTask</code> has finished execution,
+ * where the <code>run</code> method has finished and
+ * returned a result.
+ */
+ COMPLETED,
+
+ /**
+ * The <code>ValuedTask</code>'s <code>run</code> method
+ * did not complete because the user cancelled the
+ * <code>ValuedTask</code>.
+ */
+ CANCELLED,
+
+ /**
+ * The <code>ValuedTask</code>'s <code>run</code> method
+ * did not complete because it threw an exception.
+ */
+ EXCEPTION_THROWN;
+ }
+
+ final ValuedTask<V> valuedTask;
+
+ V result = null;
+ State state = State.READY;
+ Exception exception = null;
+
+ public ValuedTaskExecutor(ValuedTask<V> valuedTask)
+ {
+ this.valuedTask = valuedTask;
+ }
+
+ /**
+ * This method will be called by the <code>TaskManager</code> and
+ * should not be called by the programmer.
+ */
+ public void run(TaskMonitor taskMonitor) throws Exception
+ {
+ state = State.RUNNING;
+ try
+ {
+ result = valuedTask.run(taskMonitor);
+ if (state == State.RUNNING)
+ state = State.COMPLETED;
+ }
+ catch (Exception exception)
+ {
+ this.exception = exception;
+ state = State.EXCEPTION_THROWN;
+ throw exception;
+ }
+ finally
+ {
+ synchronized(this)
+ {
+ this.notifyAll();
+ }
+ }
+ }
+
+ /**
+ * This method might be called by the <code>TaskManager</code> and
+ * should not be called by the programmer.
+ */
+ public void cancel()
+ {
+ state = State.CANCELLED;
+ valuedTask.cancel();
+ }
+
+ /**
+ * Retrieves the result produced by the <code>ValuedTask</code> if it
+ * has finished execution, otherwise it waits until it
+ * finishes execution.
+ *
+ * This method will block until the <code>ValuedTask</code> has
+ * finished--that is, its state is no longer
+ * <code>READY</code> or <code>RUNNING</code>.
+ *
+ * @return The result of the <code>ValuedTask</code>.
+ *
+ * @throws InterruptedException if the current thread was interrupted
+ * while waiting for the result
+ * @throws ExecutionException if the <code>ValueTask</code> threw an
+ * exception
+ * @throws CancellationException if the user cancelled the
+ * <code>ValueTask</code>
+ */
+ public V get()
+ throws InterruptedException,
+ ExecutionException,
+ CancellationException
+ {
+ if (state == State.READY || state == State.RUNNING)
+ {
+ synchronized(this)
+ {
+ this.wait();
+ }
+ }
+
+ if (state == State.CANCELLED)
+ throw new CancellationException();
+ else if (state == State.EXCEPTION_THROWN)
+ throw new ExecutionException(exception);
+
+ return result;
+ }
+
+ /**
+ * Retrieves the result produced by the <code>ValuedTask</code> if it
+ * has finished execution, otherwise it waits a specified amount of
+ * time to finish execution.
+ *
+ * This method will block until the <code>ValuedTask</code> has
+ * finished--that is, its state is no longer
+ * <code>READY</code> or <code>RUNNING</code>--or the specified
+ * wait has timed out.
+ *
+ * @return The result of the <code>ValuedTask</code>.
+ *
+ * @throws InterruptedException if the current thread was interrupted
+ * while waiting
+ * @throws ExecutionException if the <code>ValueTask</code> threw an
+ * exception
+ * @throws CancellationException if the user cancelled the
+ * <code>ValueTask</code>
+ * @throws TimeoutException if the wait period specified timed out
+ */
+ public V get(long timeout, TimeUnit unit)
+ throws InterruptedException,
+ ExecutionException,
+ CancellationException,
+ TimeoutException
+ {
+ if (state == State.READY || state == State.RUNNING)
+ {
+ synchronized(this)
+ {
+ unit.timedWait(this, timeout);
+ }
+ }
+
+ if (state == State.CANCELLED)
+ throw new CancellationException();
+ else if (state == State.EXCEPTION_THROWN)
+ throw new ExecutionException(exception);
+
+ return result;
+ }
+
+ /**
+ * Retrieves the current state of the <code>ValuedTask</code>.
+ */
+ public State getState()
+ {
+ return state;
+ }
+}
--
You received this message because you are subscribed to the Google Groups
"cytoscape-cvs" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/cytoscape-cvs?hl=en.
