Author: mes
Date: 2010-10-08 11:32:21 -0700 (Fri, 08 Oct 2010)
New Revision: 22190
Modified:
core3/io-api/trunk/src/main/java/org/cytoscape/io/CyFileFilter.java
core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CyNetworkViewReader.java
core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CyNetworkViewReaderManager.java
core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CyPropertyReader.java
core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CyPropertyReaderManager.java
core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CySessionReader.java
core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CySessionReaderManager.java
core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CyTableReader.java
core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CyTableReaderManager.java
core3/io-api/trunk/src/main/java/org/cytoscape/io/util/StreamUtil.java
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/AbstractCyWriter.java
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyNetworkViewWriter.java
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyNetworkViewWriterFactory.java
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyNetworkViewWriterManager.java
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyTableWriter.java
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyTableWriterFactory.java
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyTableWriterManager.java
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyWriter.java
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyWriterFactory.java
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyWriterManager.java
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/PropertyWriterFactory.java
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/PropertyWriterManager.java
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/SessionWriter.java
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/SessionWriterFactory.java
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/SessionWriterManager.java
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/ViewWriter.java
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/ViewWriterFactory.java
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/ViewWriterManager.java
Log:
added a ton of javadoc
Modified: core3/io-api/trunk/src/main/java/org/cytoscape/io/CyFileFilter.java
===================================================================
--- core3/io-api/trunk/src/main/java/org/cytoscape/io/CyFileFilter.java
2010-10-08 15:06:00 UTC (rev 22189)
+++ core3/io-api/trunk/src/main/java/org/cytoscape/io/CyFileFilter.java
2010-10-08 18:32:21 UTC (rev 22190)
@@ -24,7 +24,7 @@
/**
* A method that attempts to determine whether the specified
InputStream can be read
* by the Reader using this filter.
- * @param uri The input steam to be checked.
+ * @param stream The input steam to be checked.
* @param category The data category of the input steam.
* @return True if we believe the stream can be read, false otherwise.
*/
Modified:
core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CyNetworkViewReader.java
===================================================================
---
core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CyNetworkViewReader.java
2010-10-08 15:06:00 UTC (rev 22189)
+++
core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CyNetworkViewReader.java
2010-10-08 18:32:21 UTC (rev 22190)
@@ -7,16 +7,26 @@
import org.cytoscape.work.Task;
/**
- * The basic input interface that specifies what is to be read and when it is
to
- * be read. This interface should be extended by other interfaces to provide
- * access to the data that gets read. One class can then implement multiple
- * CyReader interfaces to support reading files that contain multiple types of
- * data (like networks that contain both attribute and view model information).
- *
+ * An extension of the Task interface that returns an array of
+ * {...@link CyNetworkView} objects as well as optional
+ * {...@link VisualStyle} objects that are read as part of the Task.
+ * Instances of this interface are created by InputStreamTaskFactory
+ * objects registered as OSGi services, which are in turn processed
+ * by associated reader manager objects that distinguish
+ * InputStreamTaskFactories based on the DataCategory associated with
+ * the CyFileFilter.
*/
public interface CyNetworkViewReader extends Task {
+ /**
+ * @return An array of CyNetworkView objects.
+ */
CyNetworkView[] getNetworkViews();
+ /**
+ * @return An array of VisualStyle objects. The list may be
+ * empty if no VisualStyle is defined by the input being
+ * read.
+ */
VisualStyle[] getVisualStyles();
}
Modified:
core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CyNetworkViewReaderManager.java
===================================================================
---
core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CyNetworkViewReaderManager.java
2010-10-08 15:06:00 UTC (rev 22189)
+++
core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CyNetworkViewReaderManager.java
2010-10-08 18:32:21 UTC (rev 22190)
@@ -36,11 +36,14 @@
/**
- * Central registry for all Cytoscape import classes.
+ * An object that registers all InputStreamReaderFactory singletons,
+ * processes specified input to determine the appropriate factory to
+ * use and then returns an instance of the correct CyNetworkViewReader
+ * for the input.
*/
public interface CyNetworkViewReaderManager {
/**
- * Given a URI this method will attempt to find a
CyNetworkViewReaderFactory
+ * Given a URI this method will attempt to find a
InputStreamReaderFactory
* that can read the URI, will set the InputStream for the factory and
* will return the reader task.
* @param uri The URI we're attempting to read.
@@ -50,7 +53,7 @@
CyNetworkViewReader getReader(URI uri);
/**
- * Given an InputStream this method will attempt to find a
CyNetworkViewReaderFactory
+ * Given an InputStream this method will attempt to find a
InputStreamReaderFactory
* that can read the stream, will set the InputStream for the factory
and
* will return the reader task.
* @param stream The input stream we're attempting to read.
Modified:
core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CyPropertyReader.java
===================================================================
---
core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CyPropertyReader.java
2010-10-08 15:06:00 UTC (rev 22189)
+++
core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CyPropertyReader.java
2010-10-08 18:32:21 UTC (rev 22190)
@@ -3,13 +3,26 @@
import org.cytoscape.work.Task;
/**
- *
+ * An extension of the Task interface that returns a property
+ * object. The type of the object returned can be be anything,
+ * but will in practice be
+ * {...@link java.util.Properties},
+ * {...@link org.cytoscape.property.bookmark.Bookmarks},
+ * {...@link org.cytoscape.property.session.Cysession}. The system
+ * determines the specific object type based on the CyFileFilter
+ * associated with the InputStreamTaskFactory service that
+ * produces this reader.
+ * Instances of this interface are created by InputStreamTaskFactory
+ * objects registered as OSGi services, which are in turn processed
+ * by associated reader manager objects that distinguish
+ * InputStreamTaskFactories based on the DataCategory associated with
+ * the CyFileFilter.
*/
public interface CyPropertyReader extends Task {
/**
- * @return A property object of type T. Type T can be
- * be generally be any object, but in practice will be
+ * @return A property object. The type can be
+ * be anything, but in practice will be
* {...@link java.util.Properties},
* {...@link org.cytoscape.property.bookmark.Bookmarks}, and
* {...@link org.cytoscape.property.session.Cysession}.
Modified:
core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CyPropertyReaderManager.java
===================================================================
---
core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CyPropertyReaderManager.java
2010-10-08 15:06:00 UTC (rev 22189)
+++
core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CyPropertyReaderManager.java
2010-10-08 18:32:21 UTC (rev 22190)
@@ -4,11 +4,14 @@
import java.net.URI;
/**
- *
+ * An object that registers all InputStreamReaderFactory singletons,
+ * processes specified input to determine the appropriate factory to
+ * use and then returns an instance of the correct CyPropertyReader
+ * for the input.
*/
public interface CyPropertyReaderManager {
/**
- * Given a URI this method will attempt to find a CyPropertyReaderFactory
+ * Given a URI this method will attempt to find a InputStreamReaderFactory
* that can read the URI, will set the InputStream for the factory and
* will return the reader task.
* @param uri The URI we're attempting to read.
@@ -18,7 +21,7 @@
CyPropertyReader getReader(URI uri);
/**
- * Given an InputStream this method will attempt to find a
CyPropertyReaderFactory
+ * Given an InputStream this method will attempt to find a
InputStreamReaderFactory
* that can read the stream, will set the InputStream for the factory and
* will return the reader task.
* @param stream The input stream we're attempting to read.
Modified:
core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CySessionReader.java
===================================================================
--- core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CySessionReader.java
2010-10-08 15:06:00 UTC (rev 22189)
+++ core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CySessionReader.java
2010-10-08 18:32:21 UTC (rev 22190)
@@ -4,10 +4,22 @@
import org.cytoscape.work.Task;
/**
+ * An extension of the Task interface that returns a
+ * {...@link CySession} object. The reader does nothing
+ * beyond create the CySession object and does NOT do
+ * use the CySession object to define the state of
+ * Cytoscape - that is managed by the CySessionManager.
+ * Instances of this interface are created by InputStreamTaskFactory
+ * objects registered as OSGi services, which are in turn processed
+ * by associated reader manager objects that distinguish
+ * InputStreamTaskFactories based on the DataCategory associated with
+ * the CyFileFilter.
*/
public interface CySessionReader extends Task {
+ /**
+ * @return A {...@link CySession} object.
+ */
CySession getCySession();
-
}
Modified:
core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CySessionReaderManager.java
===================================================================
---
core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CySessionReaderManager.java
2010-10-08 15:06:00 UTC (rev 22189)
+++
core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CySessionReaderManager.java
2010-10-08 18:32:21 UTC (rev 22190)
@@ -4,11 +4,14 @@
import java.net.URI;
/**
- *
+ * An object that registers all InputStreamReaderFactory singletons,
+ * processes specified input to determine the appropriate factory to
+ * use and then returns an instance of the correct CySessionReader
+ * for the input.
*/
public interface CySessionReaderManager {
/**
- * Given a URI this method will attempt to find a CySessionReaderFactory
+ * Given a URI this method will attempt to find a InputStreamReaderFactory
* that can read the URI, will set the InputStream for the factory and
* will return the reader task.
* @param uri The URI we're attempting to read.
@@ -18,7 +21,7 @@
CySessionReader getReader(URI uri);
/**
- * Given an InputStream this method will attempt to find a
CySessionReaderFactory
+ * Given an InputStream this method will attempt to find a
InputStreamReaderFactory
* that can read the stream, will set the InputStream for the factory and
* will return the reader task.
* @param stream The input stream we're attempting to read.
Modified:
core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CyTableReader.java
===================================================================
--- core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CyTableReader.java
2010-10-08 15:06:00 UTC (rev 22189)
+++ core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CyTableReader.java
2010-10-08 18:32:21 UTC (rev 22190)
@@ -3,7 +3,19 @@
import org.cytoscape.model.CyTable;
import org.cytoscape.work.Task;
+/**
+ * An extension of the Task interface that returns an array of
+ * {...@link CyTable} objects.
+ * Instances of this interface are created by InputStreamTaskFactory
+ * objects registered as OSGi services, which are in turn processed
+ * by associated reader manager objects that distinguish
+ * InputStreamTaskFactories based on the DataCategory associated with
+ * the CyFileFilter.
+ */
public interface CyTableReader extends Task{
+ /**
+ * @return An array of CyTable objects.
+ */
public CyTable[] getCyDataTables();
}
Modified:
core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CyTableReaderManager.java
===================================================================
---
core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CyTableReaderManager.java
2010-10-08 15:06:00 UTC (rev 22189)
+++
core3/io-api/trunk/src/main/java/org/cytoscape/io/read/CyTableReaderManager.java
2010-10-08 18:32:21 UTC (rev 22190)
@@ -34,12 +34,15 @@
/**
- * Central registry for all Cytoscape import classes.
+ * An object that registers all InputStreamReaderFactory singletons,
+ * processes specified input to determine the appropriate factory to
+ * use and then returns an instance of the correct CyTableReader
+ * for the input.
*/
public interface CyTableReaderManager {
/**
- * Given a URI this method will attempt to find a
CyDataTableReaderFactory
+ * Given a URI this method will attempt to find a
InputStreamReaderFactory
* that can read the URI, will set the InputStream for the factory and
* will return the reader task.
* @param uri The URI we're attempting to read.
@@ -49,7 +52,7 @@
CyTableReader getReader(URI uri);
/**
- * Given an InputStream this method will attempt to find a
CyDataTableReaderFactory
+ * Given an InputStream this method will attempt to find a
InputStreamReaderFactory
* that can read the stream, will set the InputStream for the factory
and
* will return the reader task.
* @param stream The input stream we're attempting to read.
Modified: core3/io-api/trunk/src/main/java/org/cytoscape/io/util/StreamUtil.java
===================================================================
--- core3/io-api/trunk/src/main/java/org/cytoscape/io/util/StreamUtil.java
2010-10-08 15:06:00 UTC (rev 22189)
+++ core3/io-api/trunk/src/main/java/org/cytoscape/io/util/StreamUtil.java
2010-10-08 18:32:21 UTC (rev 22190)
@@ -5,12 +5,29 @@
import java.net.URL;
import java.net.URLConnection;
+/**
+ * A stateless utility class that provides special handling to support
+ * InputStreams and URLConnections over the network.
+ */
public interface StreamUtil {
+ // TODO what's the difference between these two methods?
+ /**
+ * @param source The URL from which to generate the InputStream.
+ * @return An input stream from the specified URL.
+ */
public InputStream getInputStream(URL source) throws IOException;
+ /**
+ * @param source The URL from which to generate the InputStream.
+ * @return An input stream from the specified URL.
+ */
public InputStream getBasicInputStream(URL source) throws IOException;
+ /**
+ * @param source The URL from which to generate the URLConnection.
+ * @return An URLConnection from the specified URL.
+ */
public URLConnection getURLConnection(URL source) throws IOException;
}
Modified:
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/AbstractCyWriter.java
===================================================================
---
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/AbstractCyWriter.java
2010-10-08 15:06:00 UTC (rev 22189)
+++
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/AbstractCyWriter.java
2010-10-08 18:32:21 UTC (rev 22190)
@@ -13,29 +13,60 @@
import java.util.ArrayList;
/**
+ * An abstract utility implementation of a Task that writes a user defined
+ * file to a file type determined by a provided writer manager. This class
+ * is meant to be extended for specific file types such that the appropriate
+ * CyWriter can be identified.
*/
public abstract class AbstractCyWriter<T extends CyWriterManager> extends
AbstractTask
implements CyWriter {
private File outputFile;
+ /**
+ * The method sets the file to be written. This field should not
+ * be called directly, but rather handled by the {...@link Tunable}
+ * processing. This method is the "setter" portion of a
+ * getter/setter tunable method pair.
+ * @param f The file to be written.
+ */
public final void setOutputFile(File f) {
if ( f != null )
outputFile = f;
}
+ /**
+ * This method gets the file to be written. This method should not
+ * be called directly, but rather handled by the {...@link Tunable}
+ * processing. This method is the "getter" portion of a
+ * getter/setter tunable method pair.
+ * @return The file to be written.
+ */
@Tunable(description="Select the output file name")
public final File getOutputFile() {
return outputFile;
}
+ /**
+ * The list of file type options generated by the file types
+ * available from the CyWriterManager. This field should not
+ * be set directly, but rather handled by the {...@link Tunable}
+ * processing.
+ */
@Tunable(description = "Select the export file format")
public final ListSingleSelection<String> options;
private final Map<String,CyFileFilter> descriptionFilterMap;
+ /**
+ * The CyWriterManager specified in the constructor.
+ */
protected final T writerManager;
+ /**
+ * @param writerManager The CyWriterManager to be used to determine
which
+ * CyWriter to be used to write the file chosen by the user.
+ */
public AbstractCyWriter(T writerManager) {
if ( writerManager == null )
throw new NullPointerException("CyWriterManager is
null");
@@ -48,6 +79,11 @@
options = new ListSingleSelection<String>( new
ArrayList<String>( descriptionFilterMap.keySet() ) );
}
+ /**
+ * This method processes the chosesn input file and output type and
attempts
+ * to write the file.
+ * @param tm The TaskMonitor provided by the TaskManager execution
environment.
+ */
public final void run(TaskMonitor tm) throws Exception {
if ( outputFile == null )
throw new NullPointerException("Output file has not be
specified!");
@@ -67,6 +103,11 @@
insertTasksAfterCurrentTask( writer );
}
+ /**
+ * Should return a CyWriter object for writing the specified file of
the specified type.
+ * @param filter The specific type of file to be written.
+ * @param out The file that will be written.
+ */
protected abstract CyWriter getWriter(CyFileFilter filter, File out)
throws Exception;
}
Modified:
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyNetworkViewWriter.java
===================================================================
---
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyNetworkViewWriter.java
2010-10-08 15:06:00 UTC (rev 22189)
+++
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyNetworkViewWriter.java
2010-10-08 18:32:21 UTC (rev 22190)
@@ -6,11 +6,18 @@
import java.io.File;
/**
+ * A utility Task implementation specifically for writing a CyNetworkView.
*/
public final class CyNetworkViewWriter extends
AbstractCyWriter<CyNetworkViewWriterManager> {
+ // the view to be written
private final CyNetworkView view;
+ /**
+ * @param writerManager The CyNetworkViewWriterManager used to
determine which
+ * CyNetworkViewWriterFactory to use to write the file.
+ * @param view The CyNetworkView to be written out.
+ */
public CyNetworkViewWriter(CyNetworkViewWriterManager writerManager,
CyNetworkView view ) {
super(writerManager);
if ( view == null )
@@ -18,6 +25,9 @@
this.view = view;
}
+ /**
+ * {...@inheritdoc}
+ */
protected CyWriter getWriter(CyFileFilter filter, File file) throws
Exception{
return writerManager.getWriter(view,filter,file);
}
Modified:
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyNetworkViewWriterFactory.java
===================================================================
---
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyNetworkViewWriterFactory.java
2010-10-08 15:06:00 UTC (rev 22189)
+++
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyNetworkViewWriterFactory.java
2010-10-08 18:32:21 UTC (rev 22190)
@@ -6,8 +6,16 @@
import org.cytoscape.view.model.CyNetworkView;
/**
- *
+ * A specialization of CyWriterFactory that allows a CyNetworkView to
+ * be specified and written.
*/
public interface CyNetworkViewWriterFactory extends CyWriterFactory {
+
+ /**
+ * Specifies the CyNetworkView to be written by the CyWriter Task
+ * generated by this factory. This method must be called
+ * prior to calling the getWriter() method.
+ * @param view The CyNetworkView to be written.
+ */
void setNetworkView(CyNetworkView view);
}
Modified:
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyNetworkViewWriterManager.java
===================================================================
---
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyNetworkViewWriterManager.java
2010-10-08 15:06:00 UTC (rev 22189)
+++
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyNetworkViewWriterManager.java
2010-10-08 18:32:21 UTC (rev 22190)
@@ -40,10 +40,25 @@
import java.io.OutputStream;
/**
- * Central registry for all Cytoscape export classes.
+ * A CyWriterManager specific to writing CyNetworkView objects.
*/
public interface CyNetworkViewWriterManager extends CyWriterManager {
+ /**
+ * @param view The CyNetworkView to be written.
+ * @param filter The CyFileFilter that defines the type of file to be
written.
+ * @param file The file to be written.
+ * @return The CyWriter Task that will attempt to write the specified
view to the
+ * specified file of the specified file type.
+ */
CyWriter getWriter(CyNetworkView view, CyFileFilter filter, File file)
throws Exception;
+
+ /**
+ * @param view The CyNetworkView to be written.
+ * @param filter The CyFileFilter that defines the type of file to be
written.
+ * @param os The output steam to be written.
+ * @return The CyWriter Task that will attempt to write the specified
view to the
+ * specified output steam of the specified file type.
+ */
CyWriter getWriter(CyNetworkView view, CyFileFilter filter,
OutputStream os) throws Exception;
}
Modified:
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyTableWriter.java
===================================================================
--- core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyTableWriter.java
2010-10-08 15:06:00 UTC (rev 22189)
+++ core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyTableWriter.java
2010-10-08 18:32:21 UTC (rev 22190)
@@ -6,11 +6,17 @@
import java.io.File;
/**
+ * A utility Task implementation specifically for writing CyTable objects.
*/
public final class CyTableWriter extends
AbstractCyWriter<CyTableWriterManager> {
private final CyTable table;
+ /**
+ * @param writerManager The CyTableWriterManager used to determine
which
+ * CyTableWriterFactory to use to write the file.
+ * @param table The CyTable to be written out.
+ */
public CyTableWriter(CyTableWriterManager writerManager, CyTable table ) {
super(writerManager);
if ( table == null )
@@ -18,6 +24,9 @@
this.table = table;
}
+ /**
+ * {...@inheritdoc}
+ */
protected CyWriter getWriter(CyFileFilter filter, File file) throws
Exception{
return writerManager.getWriter(table,filter,file);
}
Modified:
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyTableWriterFactory.java
===================================================================
---
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyTableWriterFactory.java
2010-10-08 15:06:00 UTC (rev 22189)
+++
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyTableWriterFactory.java
2010-10-08 18:32:21 UTC (rev 22190)
@@ -6,9 +6,16 @@
import org.cytoscape.model.CyTable;
/**
- * Returns a Task that will write
+ * A specialization of CyWriterFactory that allows a CyTable to
+ * be specified and written.
*/
public interface CyTableWriterFactory extends CyWriterFactory {
+ /**
+ * Specifies the CyTable to be written by the CyWriter Task
+ * generated by this factory. This method must be called
+ * prior to calling the getWriter() method.
+ * @param table The CyTable to be written.
+ */
void setTable(CyTable table);
}
Modified:
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyTableWriterManager.java
===================================================================
---
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyTableWriterManager.java
2010-10-08 15:06:00 UTC (rev 22189)
+++
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyTableWriterManager.java
2010-10-08 18:32:21 UTC (rev 22190)
@@ -39,8 +39,27 @@
import java.io.File;
import java.io.OutputStream;
+/**
+ * A CyWriterManager specific to writing CyTable objects.
+ */
public interface CyTableWriterManager extends CyWriterManager {
+
+ /**
+ * @param table The CyTable to be written.
+ * @param filter The CyFileFilter that defines the type of file to be
written.
+ * @param file The file to be written.
+ * @return The CyWriter Task that will attempt to write the specified
table to the
+ * specified file of the specified file type.
+ */
CyWriter getWriter(CyTable table, CyFileFilter filter, File file)
throws Exception;
+
+ /**
+ * @param table The CyTable to be written.
+ * @param filter The CyFileFilter that defines the type of file to be
written.
+ * @param os The output stream to be written.
+ * @return The CyWriter Task that will attempt to write the specified
table to the
+ * specified output stream of the specified file type.
+ */
CyWriter getWriter(CyTable table, CyFileFilter filter, OutputStream os)
throws Exception;
}
Modified: core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyWriter.java
===================================================================
--- core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyWriter.java
2010-10-08 15:06:00 UTC (rev 22189)
+++ core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyWriter.java
2010-10-08 18:32:21 UTC (rev 22190)
@@ -5,6 +5,8 @@
import org.cytoscape.work.Task;
/**
+ * A marker interface used to indicate that data will be written
+ * to a specified output stream.
*/
public interface CyWriter extends Task {
}
Modified:
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyWriterFactory.java
===================================================================
---
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyWriterFactory.java
2010-10-08 15:06:00 UTC (rev 22189)
+++
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyWriterFactory.java
2010-10-08 18:32:21 UTC (rev 22190)
@@ -6,9 +6,24 @@
import org.cytoscape.io.FileIOFactory;
/**
- *
+ * CyWriterFactory defines the base methods for specifying output and
+ * for generating a Task to write the actual output. Instantiations
+ * of CyWriterFactories are meant to be singleton objects registered
+ * as OSGi services.
*/
public interface CyWriterFactory extends FileIOFactory {
+
+ /**
+ * This method defines where the generated CyWriter Task should
+ * write its data to. This method is meant to be called prior
+ * to calling getWriter().
+ * @param os The OutputStream to be written to.
+ */
void setOutputStream(OutputStream os);
+
+ /**
+ * @return A CyWriter Task suitable for writing to the specified
+ * output stream.
+ */
CyWriter getWriter();
}
Modified:
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyWriterManager.java
===================================================================
---
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyWriterManager.java
2010-10-08 15:06:00 UTC (rev 22189)
+++
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/CyWriterManager.java
2010-10-08 18:32:21 UTC (rev 22190)
@@ -40,19 +40,24 @@
import org.cytoscape.io.CyFileFilter;
/**
- *
+ * A CyWriterManager aggregates CyWriterFactory services for specific
DataCategories
+ * and provides a mechanism for choosing the CyWriterFactory given a particular
+ * file type.
*/
public interface CyWriterManager {
/**
- * Will return the available CyFileFilters that define the available
+ * @return A list of the available CyFileFilters that define the
available
* output types.
*/
List<CyFileFilter> getAvailableWriters();
/**
- * Returns a CyWriterFactory for the appropriate filter.
+ * @param filter The filter used to determine the type of file written.
+ * @param os The OutputStream that will be written to by the CyWriter
+ * generated by the CyWriterFactory.
+ * @return A CyWriterFactory for the appropriate filter.
*/
public CyWriterFactory getMatchingFactory(CyFileFilter filter,
OutputStream os);
}
Modified:
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/PropertyWriterFactory.java
===================================================================
---
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/PropertyWriterFactory.java
2010-10-08 15:06:00 UTC (rev 22189)
+++
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/PropertyWriterFactory.java
2010-10-08 18:32:21 UTC (rev 22190)
@@ -2,9 +2,18 @@
/**
- * Returns a Task that will write
+ * A specialization of CyWriterFactory that allows a property Object to
+ * be specified and written. See {...@link org.cytoscape.property.CyProperty}
+ * for details on the type of Object.
*/
public interface PropertyWriterFactory extends CyWriterFactory {
+ /**
+ * Specifies the property object to be written by the CyWriter Task
+ * generated by this factory. This method must be called
+ * prior to calling the getWriter() method.
+ * @param property The property object to be written. In general
+ * this object should be of types described in {...@link
org.cytoscape.property.CyProperty}.
+ */
void setProperty(Object property);
}
Modified:
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/PropertyWriterManager.java
===================================================================
---
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/PropertyWriterManager.java
2010-10-08 15:06:00 UTC (rev 22189)
+++
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/PropertyWriterManager.java
2010-10-08 18:32:21 UTC (rev 22190)
@@ -38,11 +38,28 @@
import java.io.File;
import java.io.OutputStream;
+/**
+ * A CyWriterManager specific to writing property objects. See
+ * {...@link org.cytoscape.property.CyProperty} for information on
+ * types of object expected.
+ */
public interface PropertyWriterManager extends CyWriterManager {
/**
- * The filter is important here because it will
+ * @param property The property object to be written.
+ * @param filter The CyFileFilter that defines the type of file to be
written.
+ * @param file The file to be written.
+ * @return The CyWriter Task that will attempt to write the specified
property
+ * object to the specified file of the specified file type.
*/
CyWriter getWriter(Object property, CyFileFilter filter, File file)
throws Exception;
+
+ /**
+ * @param property The property object to be written.
+ * @param filter The CyFileFilter that defines the type of file to be
written.
+ * @param os The output stream to be written.
+ * @return The CyWriter Task that will attempt to write the specified
property
+ * object to the specified output stream of the specified file type.
+ */
CyWriter getWriter(Object property, CyFileFilter filter, OutputStream
os) throws Exception;
}
Modified:
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/SessionWriter.java
===================================================================
--- core3/io-api/trunk/src/main/java/org/cytoscape/io/write/SessionWriter.java
2010-10-08 15:06:00 UTC (rev 22189)
+++ core3/io-api/trunk/src/main/java/org/cytoscape/io/write/SessionWriter.java
2010-10-08 18:32:21 UTC (rev 22190)
@@ -9,6 +9,7 @@
import java.util.List;
/**
+ * A utility Task implementation that writes a CySession to a file.
*/
public final class SessionWriter extends AbstractTask implements CyWriter {
@@ -16,6 +17,12 @@
private final SessionWriterManager writerMgr;
private final File outputFile;
+ /**
+ * @param writerMgr The SessionWriterManager contains single expected
+ * SessionWriterFactory to use to write the file.
+ * @param session The CySession to be written out.
+ * @param outputFile The file the CySession should be written to.
+ */
public SessionWriter(SessionWriterManager writerMgr, CySession session,
File outputFile) {
if ( writerMgr == null )
@@ -31,6 +38,11 @@
this.outputFile = outputFile;
}
+ /**
+ * The method that will actually write the specified session to the
specified
+ * file.
+ * @param tm The TaskMonitor provided by the TaskManager execution
environment.
+ */
public final void run(TaskMonitor tm) throws Exception {
List<CyFileFilter> filters = writerMgr.getAvailableWriters();
@@ -45,5 +57,4 @@
insertTasksAfterCurrentTask( writer );
}
-
}
Modified:
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/SessionWriterFactory.java
===================================================================
---
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/SessionWriterFactory.java
2010-10-08 15:06:00 UTC (rev 22189)
+++
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/SessionWriterFactory.java
2010-10-08 18:32:21 UTC (rev 22190)
@@ -4,9 +4,16 @@
import org.cytoscape.session.CySession;
/**
- * Returns a Task that will write
+ * A specialization of CyWriterFactory that allows a CySession to
+ * be specified and written.
*/
public interface SessionWriterFactory extends CyWriterFactory {
+ /**
+ * Specifies the CySession to be written by the CyWriter Task
+ * generated by this factory. This method must be called
+ * prior to calling the getWriter() method.
+ * @param session The CySession to be written.
+ */
void setSession(CySession session);
}
Modified:
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/SessionWriterManager.java
===================================================================
---
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/SessionWriterManager.java
2010-10-08 15:06:00 UTC (rev 22189)
+++
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/SessionWriterManager.java
2010-10-08 18:32:21 UTC (rev 22190)
@@ -39,8 +39,26 @@
import java.io.File;
import java.io.OutputStream;
+/**
+ * A CyWriterManager specific to writing CySession objects.
+ */
public interface SessionWriterManager extends CyWriterManager {
+ /**
+ * @param session The CySession to be written.
+ * @param filter The CyFileFilter that defines the type of file to be
written.
+ * @param file The file to be written.
+ * @return The CyWriter Task that will attempt to write the specified
session to the
+ * specified file of the specified file type.
+ */
CyWriter getWriter(CySession session, CyFileFilter filter, File file)
throws Exception;
+
+ /**
+ * @param session The CySession to be written.
+ * @param filter The CyFileFilter that defines the type of file to be
written.
+ * @param os The output stream to be written.
+ * @return The CyWriter Task that will attempt to write the specified
session to the
+ * specified output stream of the specified file type.
+ */
CyWriter getWriter(CySession session, CyFileFilter filter, OutputStream
os) throws Exception;
}
Modified:
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/ViewWriter.java
===================================================================
--- core3/io-api/trunk/src/main/java/org/cytoscape/io/write/ViewWriter.java
2010-10-08 15:06:00 UTC (rev 22189)
+++ core3/io-api/trunk/src/main/java/org/cytoscape/io/write/ViewWriter.java
2010-10-08 18:32:21 UTC (rev 22190)
@@ -7,12 +7,20 @@
import java.io.File;
/**
+ * A utility Task implementation that will write the specified View to the
+ * the specified image file using the specified RenderingEngine.
*/
public final class ViewWriter extends AbstractCyWriter<ViewWriterManager> {
private final View<?> view;
private final RenderingEngine re;
+ /**
+ * @param writerManager The ViewWriterManager used to determine which
type of
+ * file should be written.
+ * @param view The View object to be written to the specified file.
+ * @param re The RenderingEngine used to generate the image to be
written to the file.
+ */
public ViewWriter(ViewWriterManager writerManager, View<?> view,
RenderingEngine re ) {
super(writerManager);
@@ -25,6 +33,9 @@
this.re = re;
}
+ /**
+ * {...@inheritdoc}
+ */
protected CyWriter getWriter(CyFileFilter filter, File file) throws
Exception {
return writerManager.getWriter(view,re,filter,file);
}
Modified:
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/ViewWriterFactory.java
===================================================================
---
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/ViewWriterFactory.java
2010-10-08 15:06:00 UTC (rev 22189)
+++
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/ViewWriterFactory.java
2010-10-08 18:32:21 UTC (rev 22190)
@@ -5,9 +5,18 @@
import org.cytoscape.view.model.View;
/**
- * Returns a Task that will write
+ * A specialization of CyWriterFactory that allows a View to
+ * be specified and written.
*/
public interface ViewWriterFactory extends CyWriterFactory {
+ /**
+ * Specifies the View to be written by the CyWriter Task
+ * generated by this factory. This method must be called
+ * prior to calling the getWriter() method.
+ * @param view The View to be written.
+ * @param re The RenderingEngine used to generate the image of the
+ * specified View.
+ */
void setViewRenderer(View<?> view, RenderingEngine re);
}
Modified:
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/ViewWriterManager.java
===================================================================
---
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/ViewWriterManager.java
2010-10-08 15:06:00 UTC (rev 22189)
+++
core3/io-api/trunk/src/main/java/org/cytoscape/io/write/ViewWriterManager.java
2010-10-08 18:32:21 UTC (rev 22190)
@@ -40,8 +40,28 @@
import java.io.File;
import java.io.OutputStream;
+/**
+ * A CyWriterManager specific to writing View objects.
+ */
public interface ViewWriterManager extends CyWriterManager {
+ /**
+ * @param view The View to be written.
+ * @param re The RenderingEngine used to generate the image to be
written.
+ * @param filter The CyFileFilter that defines the type of file to be
written.
+ * @param file The file to be written.
+ * @return The CyWriter Task that will attempt to write the specified
view to the
+ * specified file of the specified file type.
+ */
CyWriter getWriter(View<?> view, RenderingEngine re, CyFileFilter
filter, File file) throws Exception;
+
+ /**
+ * @param view The View to be written.
+ * @param re The RenderingEngine used to generate the image to be
written.
+ * @param filter The CyFileFilter that defines the type of file to be
written.
+ * @param os The output stream to be written.
+ * @return The CyWriter Task that will attempt to write the specified
view to the
+ * specified output stream of the specified file type.
+ */
CyWriter getWriter(View<?> view, RenderingEngine re, CyFileFilter
filter, OutputStream os) throws Exception;
}
--
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.
