Author: ruschein
Date: 2010-10-18 14:37:46 -0700 (Mon, 18 Oct 2010)
New Revision: 22275
Modified:
core3/work-api/trunk/src/main/java/org/cytoscape/work/AbstractTask.java
core3/work-api/trunk/src/main/java/org/cytoscape/work/AbstractTaskManager.java
core3/work-api/trunk/src/main/java/org/cytoscape/work/AbstractTunableHandler.java
core3/work-api/trunk/src/main/java/org/cytoscape/work/AbstractTunableInterceptor.java
core3/work-api/trunk/src/main/java/org/cytoscape/work/ProvidesGUI.java
core3/work-api/trunk/src/main/java/org/cytoscape/work/Task.java
core3/work-api/trunk/src/main/java/org/cytoscape/work/TaskFactory.java
core3/work-api/trunk/src/main/java/org/cytoscape/work/TaskManager.java
core3/work-api/trunk/src/main/java/org/cytoscape/work/TaskMonitor.java
core3/work-api/trunk/src/main/java/org/cytoscape/work/TunableHandler.java
core3/work-api/trunk/src/main/java/org/cytoscape/work/TunableInterceptor.java
core3/work-api/trunk/src/main/java/org/cytoscape/work/undo/AbstractUndoableEdit.java
core3/work-api/trunk/src/main/java/org/cytoscape/work/undo/UndoSupport.java
Log:
Various Javadoc improvements.
Modified:
core3/work-api/trunk/src/main/java/org/cytoscape/work/AbstractTask.java
===================================================================
--- core3/work-api/trunk/src/main/java/org/cytoscape/work/AbstractTask.java
2010-10-18 20:37:00 UTC (rev 22274)
+++ core3/work-api/trunk/src/main/java/org/cytoscape/work/AbstractTask.java
2010-10-18 21:37:46 UTC (rev 22275)
@@ -5,6 +5,9 @@
* A base class for tasks that need to be able to access the TaskIterator
that contains them.
*/
public abstract class AbstractTask implements Task {
+ /**
+ * If this is true, we should abort whatever the <code>Task</code> is
currently doing in the run() method.
+ */
protected boolean cancelled = false;
private TaskIterator taskIterator;
@@ -27,9 +30,13 @@
taskIterator.insertTasksAfter(this, newTasks);
}
- /** Calling this attempts to abort the current task. How well this
works depends on the granularity of
- * a Task's checking whether "cancelled" is true or not and then
taking appropriate action.
+ /** {...@inheritdoc}
*/
+ abstract public void run(TaskMonitor taskMonitor) throws Exception;
+
+ /** Calling this attempts to abort the current <code>Task</code>. How
well this works depends on the granularity of
+ * a <code>Task</code>'s checking whether "cancelled" is true or not
and then taking appropriate action.
+ */
public void cancel() {
cancelled = true;
}
Modified:
core3/work-api/trunk/src/main/java/org/cytoscape/work/AbstractTaskManager.java
===================================================================
---
core3/work-api/trunk/src/main/java/org/cytoscape/work/AbstractTaskManager.java
2010-10-18 20:37:00 UTC (rev 22274)
+++
core3/work-api/trunk/src/main/java/org/cytoscape/work/AbstractTaskManager.java
2010-10-18 21:37:46 UTC (rev 22275)
@@ -1,14 +1,17 @@
package org.cytoscape.work;
-// TODO: Should we replace hasTunables() w/ a getTunableInterceptor() method?
-
/** Provides access to a TunableInterceptor to all derived classes and a
utility method to determine
* if an object has been annotated with Tunables.
*/
public abstract class AbstractTaskManager implements TaskManager {
protected final TunableInterceptor tunableInterceptor;
+ /**
+ * Initialises an <code>AbstractTaskManager</code> object by setting
its <code>TunableInterceptor</code>.
+ *
+ * @param tunableInterceptor The <code>TunableInterceptor</code> to be
used by this <code>TaskManager</code>.
+ */
public AbstractTaskManager(final TunableInterceptor tunableInterceptor)
{
this.tunableInterceptor = tunableInterceptor;
}
@@ -16,4 +19,6 @@
final public boolean hasTunables(final Object o) {
return tunableInterceptor.hasTunables(o);
}
+
+ abstract public void execute(TaskFactory factory);
}
Modified:
core3/work-api/trunk/src/main/java/org/cytoscape/work/AbstractTunableHandler.java
===================================================================
---
core3/work-api/trunk/src/main/java/org/cytoscape/work/AbstractTunableHandler.java
2010-10-18 20:37:00 UTC (rev 22274)
+++
core3/work-api/trunk/src/main/java/org/cytoscape/work/AbstractTunableHandler.java
2010-10-18 21:37:46 UTC (rev 22275)
@@ -23,7 +23,12 @@
final protected Object instance; // TODO: should this be private?
final protected Tunable tunable; // TODO: should this be private?
- /** Standard base class constructor for TunableHandlers that deal with
Tunables that annotate a field.
+ /** Standard base class constructor for <code>TunableHandler</code>s
that deal with
+ * <code>Tunable</code>s that annotate a field.
+ *
+ * @param field An instance of <code>Field</code> that represents a
field annotated with <code>@Tunable</code>
+ * @param instance An object instance that contains a field
corresponding to the <i>field</i> parameter
+ * @param tunable The <code>Tunable</code> that annotates <i>field</i>
*/
public AbstractTunableHandler(final Field field, final Object instance,
final Tunable tunable) {
this.field = field;
@@ -33,7 +38,13 @@
this.tunable = tunable;
}
- /** Standard base class constructor for TunableHandlers that deal with
Tunables that use getter and setter methods.
+ /** Standard base class constructor for <code>TunableHandler</code>s
that deal with
+ * <code>Tunable</code>s that use getter and setter methods.
+ *
+ * @param getter The getter method of the tunable object represented
by the <i>instance</i> parameter.
+ * @param setter The setter method complimentary to the getter.
+ * @param instance An instance of an object with a getter method that
has been determined to be annotated with <code>@Tunable</code>.
+ * @param tunable The <code>Tunable</code> that annotates the
<i>getter</i>.
*/
public AbstractTunableHandler(final Method getter, final Method setter,
final Object instance, final Tunable tunable) {
this.field = null;
@@ -51,6 +62,8 @@
}
/** Sets the value of the Tunable associated with this TunableHandler.
+ *
+ * @param newValue The new value that the associated tunable will be
set to.
*/
final public void setValue(final Object newValue) throws
IllegalAccessException, InvocationTargetException {
if (field != null)
Modified:
core3/work-api/trunk/src/main/java/org/cytoscape/work/AbstractTunableInterceptor.java
===================================================================
---
core3/work-api/trunk/src/main/java/org/cytoscape/work/AbstractTunableInterceptor.java
2010-10-18 20:37:00 UTC (rev 22274)
+++
core3/work-api/trunk/src/main/java/org/cytoscape/work/AbstractTunableInterceptor.java
2010-10-18 21:37:46 UTC (rev 22275)
@@ -62,15 +62,16 @@
* Here are the steps to get a list of handlers for each object annotated as
a<code> @Tunable </code>, in order to provide :
* <ul>
* <li>a Graphic User Interface for <code>Tunables</code> in the Cytoscape
Desktop(use of a <code>GuiTunableInterceptor</code>)</li>
- * <li>a CommandLine Interface in a terminal to execute the Tasks by just
typing the name of the class implementing the <code>TaskFactory</code>
interface (use of <code>CLTunableInterceptor</code>)</li>
- * <li>access to the properties of the <code>Tunables</code>(use of
<code>LoadPropsInterceptor</code> or <code>StorePropsInterceptor</code> NEED TO
BE DEVELOPPED !!!!!!!</li>
+ * <li>a Command-line interface to execute the Tasks by just typing the
name of the class implementing the <code>TaskFactory</code> interface (use of
<code>CLTunableInterceptor</code>)</li>
+ * <li>access to the properties of the <code>Tunables</code>(use of
<code>LoadPropsInterceptor</code> or <code>StorePropsInterceptor</code></li>
* </ul>
*
* <ol>
- * <li> First, detection of the Field annonated as <code> @Tunable </code>
in the class the <code>TunableInterceptor</code> is applied to</li>
- * <li> Then, the <code>Handlers</code> are created for each kind of
<code>Tunable</code> Object (In this example : creation of a
<code>AbstractBounded<Integer></code>, <code>AbstractBounded<Double></code> and
<code>Boolean</code> <code>Handlers<code>)</li>
- * <li> The <code>Handlers</code> are stored in a <i>handlerList</i>,
and are used by different <code>TunableInterceptor</code> types</li>
- * <li> Create a GUI, provide CommandLine Options, Store or Load
properties for those <code>Tunables</code> by using those
<code>Handlers</code></li>
+ * <li>Detection of a field or getter method annonated with <code>@Tunable
</code> in the class the <code>TunableInterceptor</code> is applied to</li>
+ * <li>The <code>Handlers</code> are created for each kind of
<code>Tunable</code> Object (In
+ * this example : creation of a
<code>AbstractBounded<Integer></code>,
<code>AbstractBounded<Double></code> and <code>Boolean</code>
<code>Handlers<code>)</li>
+ * <li>The <code>Handlers</code> are stored in a <i>handlerList</i>, and
are used by different <code>TunableInterceptor</code> types</li>
+ * <li>Create a GUI, provide command-line options, store or load
properties for those <code>Tunables</code> by using those
<code>TunableHandler</code>s</li>
* </ol>
* </pre></p>
*
Modified: core3/work-api/trunk/src/main/java/org/cytoscape/work/ProvidesGUI.java
===================================================================
--- core3/work-api/trunk/src/main/java/org/cytoscape/work/ProvidesGUI.java
2010-10-18 20:37:00 UTC (rev 22274)
+++ core3/work-api/trunk/src/main/java/org/cytoscape/work/ProvidesGUI.java
2010-10-18 21:37:46 UTC (rev 22275)
@@ -7,23 +7,20 @@
import java.lang.annotation.Target;
-...@retention(RetentionPolicy.RUNTIME)
-...@target({ElementType.METHOD})
-
-
/**
- * An annotation type that can be applied to a <i>method</i> in order to allow
<code>TunableInterceptor</code> to catch it,
- * and so to use its members to create a corresponding interface for a user.
+ * An annotation type that can be applied to a <i>method</i> in order to
allow a <code>TunableInterceptor</code>
+ * to catch it, and so to use its members to create a corresponding interface
for a user.
*
* Here is an example of how to use a <code>ProvidesGUI</code> annotation:
- * <p><pre>
- * <code>
- * @ProvidesGUI
+ *
+ * <pre>
+ * @ProvidesGUI
* public JPanel getGUI() { return mySetupPanel; }
- * </code>
- * </pre></p>
+ * </pre>
*
- * Please not that the method annotated with this needs to return a JPanel
and take no arguments.
+ * Please note that the method annotated with this needs to return a JPanel
and take no arguments.
*/
+...@retention(RetentionPolicy.RUNTIME)
+...@target({ElementType.METHOD})
public @interface ProvidesGUI {
}
Modified: core3/work-api/trunk/src/main/java/org/cytoscape/work/Task.java
===================================================================
--- core3/work-api/trunk/src/main/java/org/cytoscape/work/Task.java
2010-10-18 20:37:00 UTC (rev 22274)
+++ core3/work-api/trunk/src/main/java/org/cytoscape/work/Task.java
2010-10-18 21:37:46 UTC (rev 22275)
@@ -183,7 +183,7 @@
* <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>
+ * concurrency issues!</p>
*/
void cancel();
}
Modified: core3/work-api/trunk/src/main/java/org/cytoscape/work/TaskFactory.java
===================================================================
--- core3/work-api/trunk/src/main/java/org/cytoscape/work/TaskFactory.java
2010-10-18 20:37:00 UTC (rev 22274)
+++ core3/work-api/trunk/src/main/java/org/cytoscape/work/TaskFactory.java
2010-10-18 21:37:46 UTC (rev 22275)
@@ -2,9 +2,13 @@
/**
- * Returns an instance of a TaskIterator. Intended to be
- * used as an OSGi service, singleton, ebery task has one.
+ * Returns an instance of a TaskIterator. Intended to be
+ * used as an OSGi service, singleton, every type of <code>Task</code> has
one.
*/
public interface TaskFactory {
+ /** @return an iterator returning a sequence of <code>Task</code>s.
+ *
+ * N.B.: Most factory's returned iterator only yields a single
<code>Task</code>.
+ */
TaskIterator getTaskIterator();
}
Modified: core3/work-api/trunk/src/main/java/org/cytoscape/work/TaskManager.java
===================================================================
--- core3/work-api/trunk/src/main/java/org/cytoscape/work/TaskManager.java
2010-10-18 20:37:00 UTC (rev 22274)
+++ core3/work-api/trunk/src/main/java/org/cytoscape/work/TaskManager.java
2010-10-18 21:37:46 UTC (rev 22275)
@@ -17,8 +17,11 @@
* This method is called to execute a <code>Task</code>.
*
* This method returns once the <code>Task</code>s derived from the
<code>TaskIterator</code>
- * returned by the <code>TaskFactory>'s <code>getTaskIterator()</code>
method started execution.
+ * returned by the <code>TaskFactory</code>'s
<code>getTaskIterator()</code> method started execution.
* It does not wait for the <code>Task</code>s to finish.
+ *
+ * @param factory the <code>TaskFactory</code> whose tasks returned
by its getTaskIterator()
+ * method's iterator will be executed
*/
void execute(TaskFactory factory);
}
Modified: core3/work-api/trunk/src/main/java/org/cytoscape/work/TaskMonitor.java
===================================================================
--- core3/work-api/trunk/src/main/java/org/cytoscape/work/TaskMonitor.java
2010-10-18 20:37:00 UTC (rev 22274)
+++ core3/work-api/trunk/src/main/java/org/cytoscape/work/TaskMonitor.java
2010-10-18 21:37:46 UTC (rev 22275)
@@ -1,12 +1,12 @@
package org.cytoscape.work;
+
/**
* Used by <code>Task</code>s to modify its user interface.
*
* @author Pasteur
*/
-public interface TaskMonitor
-{
+public interface TaskMonitor {
/**
* Sets the title of the <code>Task</code>.
* The title is a succinct description of the <code>Task</code>'s
@@ -24,27 +24,8 @@
public void setProgress(double progress);
/**
- * Sets the status message that describes what <code>Task</code> is
currently doing.
+ * Sets the status message that describes what a <code>Task</code> is
currently doing.
* This method can be called throughout the course of the
<code>run</code> method.
*/
public void setStatusMessage(String statusMessage);
-
-
- /**
- * This method returns a TaskMonitor for use by embedded Tasks. The
parent ("this")
- * TaskMonitor will allocate the specified fraction of itself to the
sub TaskMonitor.
- * The sub TaskMonitor returned from this method will itself have a
full range of
- * of 0 to 1. This range will be mapped by the parent TaskMonitor to
match the specified
- * fraction. The effect of specifying a fraction is to increase the
progress of the
- * parent ("this") Task by the amount of the fraction. For example, if
the current
- * progress of the parent TaskMonitor is 0.1 and this method is called
with a fraction of
- * 0.5, then once the sub Task has been executed and the sub
TaskMonitor successfully
- * updated then the progress of the parent TaskMonitor will be set to
0.6. If the fractions
- * add up to more than 1, then the progress will be simply be set to 1.
- *
- * @param fraction A value between 0 and 1 exclusive. This represents
the fraction
- * of the parent TaskMonitor that will be allotted to the sub
TaskMonitor.
- * @return A TaskMonitor object suitable for monitoring the progress of
embedded Tasks.
- public TaskMonitor getSubTaskMonitor(double fraction);
- */
}
Modified:
core3/work-api/trunk/src/main/java/org/cytoscape/work/TunableHandler.java
===================================================================
--- core3/work-api/trunk/src/main/java/org/cytoscape/work/TunableHandler.java
2010-10-18 20:37:00 UTC (rev 22274)
+++ core3/work-api/trunk/src/main/java/org/cytoscape/work/TunableHandler.java
2010-10-18 21:37:46 UTC (rev 22275)
@@ -30,12 +30,13 @@
String[] getGroups();
/**
- * @return true if the associated <code>Tunable</code> controls nested
children, else false
+ * @return true if the associated <code>Tunable</code> allows
switching of mutually exclusive nested children, else false
*/
boolean controlsMutuallyExclusiveNestedChildren();
/**
- * @return returns the name of the key that determines the selection
of which controlled nested child is currently presented, or the empty string if
+ * @return returns the name of the key that determines the selection
of which controlled
+ * nested child is currently presented, or the empty string if
* controlsMutuallyExclusiveNestedChildren() returns false.
*/
String getChildKey();
Modified:
core3/work-api/trunk/src/main/java/org/cytoscape/work/TunableInterceptor.java
===================================================================
---
core3/work-api/trunk/src/main/java/org/cytoscape/work/TunableInterceptor.java
2010-10-18 20:37:00 UTC (rev 22274)
+++
core3/work-api/trunk/src/main/java/org/cytoscape/work/TunableInterceptor.java
2010-10-18 21:37:46 UTC (rev 22275)
@@ -53,7 +53,7 @@
* <code>Handlers</code>.<br>
* Important : the value of the <code>GUIHandler</code> will be set
only if its JPanel is valid.
*
- * @param obs Object[] which contains classes with
<code>Tunables</code> that need to be displayed to a user.
+ * @param objs Object[] which contains classes with
<code>Tunables</code> that need to be displayed to a user.
*
* @return boolean The success or failure of the validation of
<code>Tunables</code>' values depending on <code>validate</code> method from
<code>TunableValidator</code> interface.
* <p><pre>
Modified:
core3/work-api/trunk/src/main/java/org/cytoscape/work/undo/AbstractUndoableEdit.java
===================================================================
---
core3/work-api/trunk/src/main/java/org/cytoscape/work/undo/AbstractUndoableEdit.java
2010-10-18 20:37:00 UTC (rev 22274)
+++
core3/work-api/trunk/src/main/java/org/cytoscape/work/undo/AbstractUndoableEdit.java
2010-10-18 21:37:46 UTC (rev 22275)
@@ -42,6 +42,10 @@
public abstract class AbstractUndoableEdit extends
javax.swing.undo.AbstractUndoableEdit {
private final String presentationName;
+ /** Initialises an UndoableEdit.
+ *
+ * @param presentationName the name that will represent the undoable
action
+ */
public AbstractUndoableEdit(final String presentationName) {
if (presentationName == null)
throw new IllegalArgumentException("in call to
AbstractUndoableEdit(), presentationName must not be null!");
@@ -49,6 +53,8 @@
this.presentationName = presentationName;
}
+ /** @return a string representing the action that can be undone
+ */
@Override
public final String getPresentationName() {
return presentationName;
Modified:
core3/work-api/trunk/src/main/java/org/cytoscape/work/undo/UndoSupport.java
===================================================================
--- core3/work-api/trunk/src/main/java/org/cytoscape/work/undo/UndoSupport.java
2010-10-18 20:37:00 UTC (rev 22274)
+++ core3/work-api/trunk/src/main/java/org/cytoscape/work/undo/UndoSupport.java
2010-10-18 21:37:46 UTC (rev 22275)
@@ -36,7 +36,11 @@
* A simple interface that provides access to a Swing Undo Service.
*/
public interface UndoSupport {
+ /** @return the <code>UndoManager</code> associated with this
<code>UndoSupport</code> instance
+ */
UndoManager getUndoManager();
+ /** @return the <code>UndoableEditSupport</code> associated with this
<code>UndoSupport</code> instance
+ */
UndoableEditSupport getUndoableEditSupport();
}
--
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.
