Menu
▾
▴
[CIShell-SVN] SF.net SVN: cishell: [618]
|
From: <bh...@us...> - 2008-02-07 00:16:26
|
Revision: 618
http://cishell.svn.sourceforge.net/cishell/?rev=618&view=rev
Author: bh2
Date: 2008-02-06 16:15:28 -0800 (Wed, 06 Feb 2008)
Log Message:
-----------
* Added section listing versions of each specified package
* Removed typos, clarified, etc
* Updated/Cleaned API text
* Added some addition AlgorithmProperty properties
* Removed DataProperty.GRACE_TYPE and replaced it with GRAPH_TYPE. GRACE_TYPE is
WAY too specific to be in the specification.
* Removed public Converter[] findConverters(String inFormat, String outFormat,
int maxHops, String maxComplexity); from DataConversionService since it is not used
and is not worth specifying at this time.
Modified Paths:
--------------
branches/spec_update/org.cishell.framework/javadoc.xml
branches/spec_update/org.cishell.framework/src/org/cishell/app/service/datamanager/DataManagerService.java
branches/spec_update/org.cishell.framework/src/org/cishell/app/service/datamanager/package.html
branches/spec_update/org.cishell.framework/src/org/cishell/app/service/scheduler/SchedulerService.java
branches/spec_update/org.cishell.framework/src/org/cishell/app/service/scheduler/package.html
branches/spec_update/org.cishell.framework/src/org/cishell/framework/CIShellContext.java
branches/spec_update/org.cishell.framework/src/org/cishell/framework/LocalCIShellContext.java
branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/Algorithm.java
branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/AlgorithmFactory.java
branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/AlgorithmProperty.java
branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/DataValidator.java
branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/ProgressMonitor.java
branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/package.html
branches/spec_update/org.cishell.framework/src/org/cishell/framework/data/BasicData.java
branches/spec_update/org.cishell.framework/src/org/cishell/framework/data/Data.java
branches/spec_update/org.cishell.framework/src/org/cishell/framework/data/DataProperty.java
branches/spec_update/org.cishell.framework/src/org/cishell/framework/data/package.html
branches/spec_update/org.cishell.framework/src/org/cishell/framework/package.html
branches/spec_update/org.cishell.framework/src/org/cishell/overview.html
branches/spec_update/org.cishell.framework/src/org/cishell/service/conversion/Converter.java
branches/spec_update/org.cishell.framework/src/org/cishell/service/conversion/DataConversionService.java
branches/spec_update/org.cishell.framework/src/org/cishell/service/conversion/package.html
branches/spec_update/org.cishell.framework/src/org/cishell/service/guibuilder/GUIBuilderService.java
branches/spec_update/org.cishell.framework/src/org/cishell/service/guibuilder/package.html
trunk/core/org.cishell.docs/src/specification/tex/algorithms.tex
trunk/core/org.cishell.docs/src/specification/tex/algorithmtypes.tex
trunk/core/org.cishell.docs/src/specification/tex/introduction.tex
trunk/core/org.cishell.docs/src/specification/tex/osgidependencies.tex
Modified: branches/spec_update/org.cishell.framework/javadoc.xml
===================================================================
--- branches/spec_update/org.cishell.framework/javadoc.xml 2008-02-05 17:32:44 UTC (rev 617)
+++ branches/spec_update/org.cishell.framework/javadoc.xml 2008-02-07 00:15:28 UTC (rev 618)
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<project default="javadoc">
- <property name="version" value="0.5.0" />
+ <property name="version" value="1.0" />
<target name="javadoc">
<javadoc destdir="bin/doc"
access="public"
Modified: branches/spec_update/org.cishell.framework/src/org/cishell/app/service/datamanager/DataManagerService.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/app/service/datamanager/DataManagerService.java 2008-02-05 17:32:44 UTC (rev 617)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/app/service/datamanager/DataManagerService.java 2008-02-07 00:15:28 UTC (rev 618)
@@ -16,14 +16,14 @@
import org.cishell.framework.data.Data;
/**
- * A service for managing loaded {@link Data}s.
+ * A service for managing loaded {@link Data} objects.
* {@link DataManagerListener}s may be registered to be notified of changes
* in the model manager.
*
- * Clients are encouraged to use this service for managing the models they have
- * loaded into memory. Algorithm writers are encouraged not to use this service
- * as it is not guaranteed to be available like the standard CIShell services
- * are.
+ * Application developers are encouraged to use this service for managing the
+ * models they have loaded into memory. Algorithm developers are encouraged not
+ * to use this service as it is not guaranteed to be available like the standard
+ * CIShell services are.
*
* @author Bruce Herr (bh...@bh...)
*/
@@ -81,7 +81,6 @@
*/
public void removeDataManagerListener(DataManagerListener listener);
-
/**
* Returns the label for a stored Data object
*
Modified: branches/spec_update/org.cishell.framework/src/org/cishell/app/service/datamanager/package.html
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/app/service/datamanager/package.html 2008-02-05 17:32:44 UTC (rev 617)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/app/service/datamanager/package.html 2008-02-07 00:15:28 UTC (rev 618)
@@ -2,7 +2,7 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
- <title>org.cishell.framework.datamodel Package-level Javadoc</title>
+ <title>org.cishell.app.service.datamanager Package-level Javadoc</title>
<!--
/* ****************************************************************************
* CIShell: Cyberinfrastructure Shell, An Algorithm Integration Framework.
@@ -19,9 +19,12 @@
* ***************************************************************************/
-->
</head>
-<body>Provides the specification for the CIShell data manager service.
+<body>Provides interfaces for the CIShell Data Manager Service.
<h2>Package Specification</h2>
-This package specifies the API related to the data manager service.
+The API related to the Data Manager Service.
+@see <a href="http://cishell.org/dev/docs/spec/cishell-spec-1.0.pdf">
+CIShell Specification 1.0</a>
+
</body>
</html>
\ No newline at end of file
Modified: branches/spec_update/org.cishell.framework/src/org/cishell/app/service/scheduler/SchedulerService.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/app/service/scheduler/SchedulerService.java 2008-02-05 17:32:44 UTC (rev 617)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/app/service/scheduler/SchedulerService.java 2008-02-07 00:15:28 UTC (rev 618)
@@ -23,9 +23,10 @@
* A service for scheduling {@link Algorithm}s to be run.
* {@link SchedulerListener}s may be registered to be notified of events.
*
- * Clients are encouraged to use this service for scheduling Algorithms to be
- * run. Algorithm writers are encouraged not to use this service as it is not
- * guaranteed to be available like the standard CIShell services are.
+ * Application Developers are encouraged to use this service for scheduling
+ * Algorithms to be run. Algorithm developers are encouraged not to use this
+ * service as it is not guaranteed to be available like the standard CIShell
+ * services are.
*
* @author Bruce Herr (bh...@bh...)
*/
@@ -141,7 +142,6 @@
*/
public Calendar getScheduledTime(Algorithm algorithm);
-
/**
* Returns an Algorithm's associated ServiceReference if one was provided
* when the Algorithm was scheduled
Modified: branches/spec_update/org.cishell.framework/src/org/cishell/app/service/scheduler/package.html
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/app/service/scheduler/package.html 2008-02-05 17:32:44 UTC (rev 617)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/app/service/scheduler/package.html 2008-02-07 00:15:28 UTC (rev 618)
@@ -2,7 +2,7 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
- <title>org.cishell.framework.datamodel Package-level Javadoc</title>
+ <title>org.cishell.app.service.scheduler Package-level Javadoc</title>
<!--
/* ****************************************************************************
* CIShell: Cyberinfrastructure Shell, An Algorithm Integration Framework.
@@ -19,9 +19,12 @@
* ***************************************************************************/
-->
</head>
-<body>Provides the specification for the CIShell scheduler service.
+<body>Provides interfaces for the CIShell Scheduler Service.
<h2>Package Specification</h2>
-This package specifies the API related to the scheduler service.
+The API related to the Scheduler Service.
+@see <a href="http://cishell.org/dev/docs/spec/cishell-spec-1.0.pdf">
+CIShell Specification 1.0</a>
+
</body>
</html>
\ No newline at end of file
Modified: branches/spec_update/org.cishell.framework/src/org/cishell/framework/CIShellContext.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/framework/CIShellContext.java 2008-02-05 17:32:44 UTC (rev 617)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/CIShellContext.java 2008-02-07 00:15:28 UTC (rev 618)
@@ -21,7 +21,7 @@
/**
* The context by which algorithms in the framework can gain access to standard
* CIShell services. An instantiated CIShellContext must provide access to at
- * least the default services (as of this specification, the OSGi
+ * least the default services (as of the 1.0 specification, the OSGi
* {@link LogService}, the OSGi {@link PreferencesService}, the
* CIShell defined {@link DataConversionService}, and the CIShell defined
* {@link GUIBuilderService}). Other services may be made available through
@@ -32,7 +32,7 @@
public interface CIShellContext {
/**
- * Contains an array of the strings to access the default services
+ * Contains an array of the valid strings corresponding to the default services
*/
public static final String[] DEFAULT_SERVICES =
new String[] { LogService.class.getName(),
Modified: branches/spec_update/org.cishell.framework/src/org/cishell/framework/LocalCIShellContext.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/framework/LocalCIShellContext.java 2008-02-05 17:32:44 UTC (rev 617)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/LocalCIShellContext.java 2008-02-07 00:15:28 UTC (rev 618)
@@ -20,7 +20,7 @@
* A simple implementation of {@link CIShellContext} that pulls the
* CIShell services from the provided {@link BundleContext} that all OSGi
* bundles receive on activation. This was included in the standard API since
- * it will be used frequently by CIShell Client writers.
+ * it will be used frequently by CIShell Application writers.
*
* This implementation only returns standard services or the service strings
* given to it in its constructor.
@@ -44,13 +44,13 @@
/**
* Initializes the CIShell context with a custom set of standard services.
- * Only the standard services provided will be allowed to be gotten from
+ * Only the standard services provided will be allowed to be retrieved from
* this <code>CIShellContext</code>.
*
* @param bContext The <code>BundleContext</code> to use to find
* registered standard services.
* @param standardServices An array of strings specifying the services that
- * are allowed to be gotten from this class.
+ * are allowed to be retrieved from this class.
*/
public LocalCIShellContext(BundleContext bContext, String[] standardServices) {
this.bContext = bContext;
Modified: branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/Algorithm.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/Algorithm.java 2008-02-05 17:32:44 UTC (rev 617)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/Algorithm.java 2008-02-07 00:15:28 UTC (rev 618)
@@ -13,31 +13,22 @@
* ***************************************************************************/
package org.cishell.framework.algorithm;
-import org.cishell.framework.CIShellContext;
import org.cishell.framework.data.Data;
/**
- * In CIShell, an algorithm can be basically any arbitrary code
- * execution cycle. What happens when the execute method is run is entirely
- * up to the Algorithm writer. Some algorithms may be primed with a Data array
- * that it analyzes and returns a derivitive Data array or it may convert from
- * one Data array to another or not take in any Data array and based on some
- * given parameters create an entirely new Data array.
+ * A class which executes some arbitrary code and optionally returns any data
+ * produced. What happens when the execute method is run is entirely
+ * up to the Algorithm developer. Algorithms should be primed with whatever data
+ * is needed, usually by its associated {@link AlgorithmFactory}, before
+ * execution. This allows an Algorithm to be set up, then scheduled for later
+ * execution.
*
- * Algorithms are typically also given a {@link CIShellContext} by which they
- * can gain access to standard services like logging, preferences, and gui
- * creation. If an algorithm only uses these standard services and does not pop
- * up any graphical gui (aside from using the GUIBuilderService) then this
- * Algorithm may be safely run remotely.
- *
* @author Bruce Herr (bh...@bh...)
*/
public interface Algorithm {
/**
- * Executes and optionally returns a Data array. Algorithms are usually
- * primed ahead of time with all the necessary data needed. This allows
- * an Algorithm to be set up, then scheduled for later execution.
+ * Executes and optionally returns a Data array.
*
* @return A Data array that was created or <code>null</code>
*/
Modified: branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/AlgorithmFactory.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/AlgorithmFactory.java 2008-02-05 17:32:44 UTC (rev 617)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/AlgorithmFactory.java 2008-02-07 00:15:28 UTC (rev 618)
@@ -20,13 +20,13 @@
import org.osgi.service.metatype.MetaTypeProvider;
/**
- * A class for creating {@link Algorithm}s. This class provides the parameters
- * needed by an <code>Algorithm</code> on demand and when given correct data,
- * will create an <code>Algorithm</code> that can be executed. An algorithm
- * writer who wishes to be usable by CIShell clients must create an
- * implementation of this interface and register it (along with some standard
- * meta-data about the algorithm, defined in the {@link AlgorithmProperty}
- * class) in the OSGi service registry.
+ * A class for creating {@link Algorithm}s. This class provides the
+ * parameters needed by its associated <code>Algorithm</code> on demand and when
+ * given correct data, will create an <code>Algorithm</code> that can be executed.
+ * An algorithm developer who wishes to be usable by CIShell applications must
+ * create an implementation of this interface and register it (along with some
+ * standard metadata about the algorithm, defined in the
+ * {@link AlgorithmProperty} class) in the OSGi service registry.
*
* @author Bruce Herr (bh...@bh...)
*/
@@ -55,7 +55,7 @@
* service in OSGi.
* @param parameters A set of key-value pairs that were created based on
* the parameters given by the createParameters method.
- * @param context The context by which an Algorithm can gain access to
+ * @param context The context by which the Algorithm can gain access to
* standard CIShell services
* @return An <code>Algorithm</code> primed for execution
*/
Modified: branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/AlgorithmProperty.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/AlgorithmProperty.java 2008-02-05 17:32:44 UTC (rev 617)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/AlgorithmProperty.java 2008-02-07 00:15:28 UTC (rev 618)
@@ -15,29 +15,54 @@
/**
* A standard set of properties and values used for creating a service
- * Dictionary that is provided when registering an AlgorithmFactory with the
- * OSGi service registry.
+ * Dictionary that is provided when registering an {@link AlgorithmFactory}
+ * with the OSGi service registry.
*
+ * See the <a href="http://cishell.org/dev/docs/spec/cishell-spec-1.0.pdf">
+ * CIShell Specification 1.0</a> for documentation on each property.
+ *
* @author Bruce Herr (bh...@bh...)
*/
public interface AlgorithmProperty {
public static final String IN_DATA = "in_data";
public static final String OUT_DATA = "out_data";
public static final String NULL_DATA = "null";
- public static final String CONVERSION = "conversion";
- public static final String LOSSY = "lossy";
- public static final String LOSSLESS = "lossless";
- public static final String MENU_PATH = "menu_path";
+
+ public static final String PARENTAGE = "parentage";
+ public static final String DEFAULT_PARENTAGE="default";
+
+ public static final String ALGORITHM_TYPE = "type";
+ public static final String TYPE_CONVERTER = "converter";
+ public static final String TYPE_VALIDATOR = "validator";
+
+ public static final String REMOTEABLE = "remoteable";
+ public static final String REMOTE = "remote";
+
public static final String LABEL = "label";
public static final String DESCRIPTION = "description";
+
+ public static final String MENU_PATH = "menu_path";
public static final String ADDITIONS_GROUP = "additions";
public static final String START_GROUP = "start";
public static final String END_GROUP = "end";
- public static final String METATYPE_ID = "metatype-id";
- public static final String REMOTEABLE = "remoteable";
- public static final String REMOTE = "remote";
- public static final String ALGORITHM_TYPE = "type";
- public static final String TYPE_CONVERTER = "converter";
+
+ public static final String CONVERSION = "conversion";
+ public static final String LOSSY = "lossy";
+ public static final String LOSSLESS = "lossless";
+
+ public static final String AUTHORS = "authors";
+ public static final String IMPLEMENTERS = "implementers";
+ public static final String INTEGRATORS = "integrators";
+
+ public static final String DOCUMENTATION_URL = "documentation_url";
+ public static final String REFERENCE = "reference";
+ public static final String REFERENCE_URL = "reference_url";
+ public static final String WRITTEN_IN = "written_in";
+
+
+
+ //Undocumented/possibly-unnecessary properties
public static final String TYPE_ALGORITHM = "algorithm";
public static final String TYPE_DATASET = "dataset";
+ public static final String METATYPE_ID = "metatype-id";
}
Modified: branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/DataValidator.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/DataValidator.java 2008-02-05 17:32:44 UTC (rev 617)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/DataValidator.java 2008-02-07 00:15:28 UTC (rev 618)
@@ -25,8 +25,8 @@
* symmetric matrices, this interface would check the data ahead of time
* to ensure that the given matrix was in fact a symmetric matrix.
* <br />
- * In order for CIShell clients to fully recognize this additional validation
- * method, an algorithm writer must register this interface in addition to the
+ * In order for CIShell applications to fully recognize this additional validation
+ * method, an algorithm developer must register this interface in addition to the
* algorithm interface when registering their service.
*
* @author Bruce Herr (bh...@bh...)
Modified: branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/ProgressMonitor.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/ProgressMonitor.java 2008-02-05 17:32:44 UTC (rev 617)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/ProgressMonitor.java 2008-02-07 00:15:28 UTC (rev 618)
@@ -16,9 +16,9 @@
/**
* A class to monitor the progress of an algorithm. It allows for notification
* of progress, notification of cancellation, notification of pausing, and
- * description of current work during execution. These methods are generally
- * only called by the algorithm with the CIShell client providing the progress
- * monitor implementation.
+ * description of current work during execution. Except for the setter methods,
+ * the methods are generally only called by the algorithm with the CIShell
+ * application providing the progress monitor implementation.
*
* @author Bruce Herr (bh...@bh...)
*/
@@ -61,11 +61,11 @@
* Notifies the start of execution of the algorithm in addition to
* revealing how many work units will be used.
*
- * @param capabilities An ORed int that tells the monitor what the
+ * @param capabilities An OR'ed int that tells the monitor what the
* algorithm is capable of with respect to the
- * monitor. The ORed values are taken from the int
+ * monitor. The OR'ed values are taken from the int
* constants specified in this interface.
- * @param totalWorkUnits The number of work units, may be -1 if the
+ * @param totalWorkUnits The number of work units, -1 if the
* algorithm does not provide progress information.
*/
public void start(int capabilities, int totalWorkUnits);
@@ -85,7 +85,7 @@
/**
* Sets or clears a flag for cancellation of this algorithm's execution.
- * An algorithm writer can ignore or clear this flag if it cannot stop
+ * An algorithm developer can ignore or clear this flag if it cannot stop
* midstream. This is one of the methods that can be called by someone
* other than the algorithm.
*
@@ -104,7 +104,7 @@
/**
* Sets or clears a flag for pausing of this algorithm's execution. An
- * algorithm writer can ignore or clear this flag if it cannot pause
+ * algorithm developer can ignore or clear this flag if it cannot pause
* midstream. This is one of the methods that can be called by someone
* other than the algorithm.
*
Modified: branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/package.html
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/package.html 2008-02-05 17:32:44 UTC (rev 617)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/package.html 2008-02-07 00:15:28 UTC (rev 618)
@@ -19,12 +19,12 @@
* ***************************************************************************/
-->
</head>
-<body>Provides interfaces required for creating CIShell compatible algorithms.
+<body>Provides interfaces required for creating CIShell algorithms.
<h2>Package Specification</h2>
-This package specifies the API related to creation of CIShell compatible
-algorithms.
+The API related to creation of CIShell algorithms.
-TODO: Describe here how an algorithm is integrated into OSGi.
+@see <a href="http://cishell.org/dev/docs/spec/cishell-spec-1.0.pdf">
+CIShell Specification 1.0</a>
</body>
</html>
\ No newline at end of file
Modified: branches/spec_update/org.cishell.framework/src/org/cishell/framework/data/BasicData.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/framework/data/BasicData.java 2008-02-05 17:32:44 UTC (rev 617)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/data/BasicData.java 2008-02-07 00:15:28 UTC (rev 618)
@@ -29,7 +29,7 @@
private String format;
/**
- * Creates a Data object with the given data and an empty meta-data
+ * Creates a Data object with the given data and an empty metadata
* {@link Dictionary}
*
* @param data The data being wrapped
@@ -39,9 +39,9 @@
}
/**
- * Creates a Data object with the given data and meta-data {@link Dictionary}
+ * Creates a Data object with the given data and metadata {@link Dictionary}
*
- * @param properties The meta-data about the data
+ * @param properties The metadata about the data
* @param data The data being wrapped
*/
public BasicData(Dictionary properties, Object data, String format) {
Modified: branches/spec_update/org.cishell.framework/src/org/cishell/framework/data/Data.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/framework/data/Data.java 2008-02-05 17:32:44 UTC (rev 617)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/data/Data.java 2008-02-07 00:15:28 UTC (rev 618)
@@ -17,40 +17,36 @@
import java.util.Dictionary;
/**
- * A class that encapsulates data and its meta-data. This class is used to pass
+ * A class that encapsulates data and its metadata. This class is used to pass
* data between algorithms and is what algorithms optionally create when executed.
*
* @author Bruce Herr (bh...@bh...)
*/
public interface Data {
/**
- * Returns the meta-data associated with the data stored in this Data object.
+ * Returns the metadata associated with the data stored in this Data object.
* Some standard keys are in the {@link DataProperty} interface.
*
- * @return The data's meta-data
+ * @return The data's metadata
*/
public Dictionary getMetaData();
/**
* Returns the data stored in this Data object.
*
- * @return The data (a java object)
+ * @return The data (a Java object)
*/
public Object getData();
/**
- * Get the format of the encapsulated data. If the data is a {@link File},
+ * Returns the format of the encapsulated data. If the data is a {@link File},
* then this method returns what MIME type it is with "file:" prepended
- * (eg. file:text/plain). Otherwise, the string returned should be the java
+ * (eg. file:text/plain). Otherwise, the string returned should be the Java
* class it represents. For algorithms this format should be the same as
* their OUT_DATA property.
*
* @return The main format of the data
*/
public String getFormat();
-
- //TODO: Consider these methods for inclusion in Data
- //public String getUID(); //may be better for specifying parent datamodels
- //public Object getDataAsFormat(String format);
}
Modified: branches/spec_update/org.cishell.framework/src/org/cishell/framework/data/DataProperty.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/framework/data/DataProperty.java 2008-02-05 17:32:44 UTC (rev 617)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/data/DataProperty.java 2008-02-07 00:15:28 UTC (rev 618)
@@ -15,7 +15,7 @@
/**
- * Standard property keys to use when creating meta-data for a
+ * Standard property keys to use when creating metadata for a
* {@link Data} object.
*
* @author Bruce Herr (bh...@bh...)
@@ -30,14 +30,13 @@
/**
* The parent Data object of the Data object. This is used when a Data object
* is derived from another Data object to show the hierarchical relationship
- * between them. This property can be null, signifying that the Data object
+ * between them. This property can be null, signifying that the Data object
* was not derived from any other Data object, such as when loading a new Data
* object from a file. The type associated with this property is of type
* {@link Data}
*/
public static final String PARENT = "Parent";
- //TODO: should we consider removing this/changing it?
/**
* The general type of the Data object. Various standard types are created as
* constants with name *_TYPE from this class. These can be used, or new
@@ -66,9 +65,9 @@
/** Says this data model is abstractly an unknown type */
public static String OTHER_TYPE = "Unknown";
- /** a plain text file */
+ /** Says this data model is abstractly a plain text file */
public static String TEXT_TYPE = "Text";
- /** a file can be fed to xmgrace */
- public static String GRACE_TYPE = "Grace";
+ /** Says this data model is abstractly an informational graph. */
+ public static String GRAPH_TYPE = "Graph";
}
Modified: branches/spec_update/org.cishell.framework/src/org/cishell/framework/data/package.html
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/framework/data/package.html 2008-02-05 17:32:44 UTC (rev 617)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/data/package.html 2008-02-07 00:15:28 UTC (rev 618)
@@ -2,7 +2,7 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
- <title>org.cishell.framework.datamodel Package-level Javadoc</title>
+ <title>org.cishell.framework.data Package-level Javadoc</title>
<!--
/* ****************************************************************************
* CIShell: Cyberinfrastructure Shell, An Algorithm Integration Framework.
@@ -21,9 +21,10 @@
</head>
<body>Provides interfaces required for creating Data objects.
<h2>Package Specification</h2>
-This package specifies the API related to creation of Data objects.
+The API related to creation of Data objects.
-TODO: Describe here what a Data object is, how it is used, and why it is used.
+@see <a href="http://cishell.org/dev/docs/spec/cishell-spec-1.0.pdf">
+CIShell Specification 1.0</a>
</body>
</html>
\ No newline at end of file
Modified: branches/spec_update/org.cishell.framework/src/org/cishell/framework/package.html
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/framework/package.html 2008-02-05 17:32:44 UTC (rev 617)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/package.html 2008-02-07 00:15:28 UTC (rev 618)
@@ -2,7 +2,7 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
- <title>org.cishell.framework.algorithm Package-level Javadoc</title>
+ <title>org.cishell.framework Package-level Javadoc</title>
<!--
/* ****************************************************************************
* CIShell: Cyberinfrastructure Shell, An Algorithm Integration Framework.
@@ -19,11 +19,12 @@
* ***************************************************************************/
-->
</head>
-<body>The base package of the CIShell framework specification.
+<body>The core package for the CIShell platform API.
<h2>Package Specification</h2>
-This package is the root package for the CIShell framework specification
+The core package for the CIShell platform API
-TODO: Talk about the framework and give links.
+@see <a href="http://cishell.org/dev/docs/spec/cishell-spec-1.0.pdf">
+CIShell Specification 1.0</a>
</body>
</html>
\ No newline at end of file
Modified: branches/spec_update/org.cishell.framework/src/org/cishell/overview.html
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/overview.html 2008-02-05 17:32:44 UTC (rev 617)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/overview.html 2008-02-07 00:15:28 UTC (rev 618)
@@ -2,7 +2,7 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
- <title>org.cishell.framework.algorithm Package-level Javadoc</title>
+ <title>org.cishell Package-level Javadoc</title>
<!--
/* ****************************************************************************
* CIShell: Cyberinfrastructure Shell, An Algorithm Integration Framework.
@@ -20,13 +20,14 @@
-->
</head>
<body>
-This document is the API specification for the CIShell specification.
+API documentation for the Cyberinfrastructure Shell specification
@see <a href="http://www.osgi.org/osgi_technology/download_specs.asp">OSGi
-Service Platform Specification, Release 4</a>
-@see <a href="http://bundles.osgi.org/javadoc/r4/">OSGi Service Platform,
+Service Platform Specification, Release 4</a></li>
+@see <a href="http://bundles.osgi.org/javadoc/r4/">OSGi Service Platform
Release 4 API</a>
-@see "The CIShell Specification Paper"
+@see <a href="http://cishell.org/dev/docs/spec/cishell-spec-1.0.pdf">
+CIShell Specification 1.0</a>
</body>
</html>
\ No newline at end of file
Modified: branches/spec_update/org.cishell.framework/src/org/cishell/service/conversion/Converter.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/service/conversion/Converter.java 2008-02-05 17:32:44 UTC (rev 617)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/service/conversion/Converter.java 2008-02-07 00:15:28 UTC (rev 618)
@@ -28,24 +28,24 @@
public interface Converter {
/**
- * Returns an array of ServiceReferences to converters in the order that
- * they will be called when converting a Data
+ * Returns an array of ServiceReferences to converter algorithms in the order
+ * in which they will be called when converting a Data object.
*
- * @return An array ServiceReferences to converters to be used
+ * @return An array of ServiceReferences to converter algorithms to be used.
*/
public ServiceReference[] getConverterChain();
/**
* Returns the AlgorithmFactory that can be invoked to convert a given
- * Data of the correct in format (as specified in the Dictionary from
- * getProperties()) to a Data of the correct out format.
+ * Data object of the correct input format (as specified in the Dictionary
+ * from getProperties()) to a Data object of the correct output format.
*
* @return The AlgorithmFactory to do the converting
*/
public AlgorithmFactory getAlgorithmFactory();
/**
- * Get properties of the converter (same as algorithm service properties).
+ * Get properties of the Converter (same as algorithm service properties).
* It is a set of properties that correspond to the
* {@link AlgorithmProperty}s properties. The IN_DATA and OUT_DATA
* properties are guaranteed to be set in this Dictionary.
@@ -56,12 +56,12 @@
public Dictionary getProperties();
/**
- * Uses this converter to convert the given Data object to a new format.
- * This is a convenience method that uses this converter to convert a Data
- * object of the corrent format to a Data object of the defined out format
+ * Uses this Converter to convert the given Data object to a new format.
+ * This is a convenience method that uses this Converter to convert a Data
+ * object of the corrent format to a Data object of the defined output format
*
- * @param data The Data object with compatible in format
- * @return A Data object of correct out format, or <code>null</code> if the
+ * @param data The Data object with compatible format
+ * @return A Data object of correct output format, or <code>null</code> if the
* conversion fails
*/
public Data convert(Data data);
Modified: branches/spec_update/org.cishell.framework/src/org/cishell/service/conversion/DataConversionService.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/service/conversion/DataConversionService.java 2008-02-05 17:32:44 UTC (rev 617)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/service/conversion/DataConversionService.java 2008-02-07 00:15:28 UTC (rev 618)
@@ -23,7 +23,7 @@
* with the OSGi service registry and specified in its service dictionary that
* they are a converter. A converter will specify what data format it takes in
* ('in_data'), what it converts it to ('out_data'), and whether any information
- * will be lost in the conversion ('consersion'='lossless'|'lossy'). Using this
+ * will be lost in the conversion ('conversion'='lossless'|'lossy'). Using this
* and other standard algorithm properties, a DataConversionService will try and
* find the fastest, most efficient way to convert from one format to another.
*
@@ -32,7 +32,7 @@
public interface DataConversionService {
/**
- * Finds a converter from one format to another if at all possible. The
+ * Finds converters from one format to another if at all possible. The
* returned {@link Converter}s, which may be a composite of multiple
* algorithms, will take a {@link Data} object of the specified
* <code>inFormat</code> and convert it to a Data object of type
@@ -45,42 +45,13 @@
* @param outFormat The type of Data object that should be produced. This
* String should be formatted in the same way as an
* algorithm's {@link AlgorithmProperty#OUT_DATA}.
- * @return An AlgorithmFactory that will convert a Data object of the given
- * inFormat to the given outFormat, or <code>null</code> if there is
- * no way to convert.
+ * @return An array of {@link Converter}s that can convert a Data object of
+ * the given inFormat to the given outFormat, or <code>null</code>
+ * if there is no way to convert.
*/
public Converter[] findConverters(String inFormat, String outFormat);
/**
- * Finds a converter from one format to another falling within the given
- * parameters. The max number of converters to use (maxHops) and the
- * maximum allowed complexity for the converters to limit the impact a
- * conversion will make. The returned {@link Converter}s, which may
- * be a composite of multiple algorithms, will take a {@link Data} object of
- * the specified <code>inFormat</code> and convert it to a Data object of type
- * <code>outFormat</code>. If there is no way to convert the Data object
- * within the given parameters, <code>null</code> will be returned.
- *
- * @param inFormat The type of Data object to be converted. This String
- * should be formatted in the same way as an algorithm's
- * {@link AlgorithmProperty#IN_DATA}.
- * @param outFormat The type of Data object that should be produced. This
- * String should be formatted in the same way as an
- * algorithm's {@link AlgorithmProperty#OUT_DATA}.
- * @param maxHops The maximum number of converters to use for the
- * conversion.
- * @param maxComplexity The maximum complexity the conversion algorithm can
- * have in order to be considered for use in the
- * conversion. The format of the String is in big-O
- * notation. Examples are 'O(n)', 'O(n^2)', 'O(log(n))'.
- * @return An AlgorithmFactory that will convert a Data object of the given
- * inFormat to the given outFormat, or <code>null</code> if there is
- * no way to convert within the given parameters.
- */
- public Converter[] findConverters(String inFormat, String outFormat,
- int maxHops, String maxComplexity);
-
- /**
* Tries to find all the converters that can be used to transform the given
* Data object to the specified output format
*
@@ -102,6 +73,4 @@
* <code>null</code> if the conversion fails
*/
public Data convert(Data data, String outFormat);
-
- // TODO: More methods of conversion here?
}
Modified: branches/spec_update/org.cishell.framework/src/org/cishell/service/conversion/package.html
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/service/conversion/package.html 2008-02-05 17:32:44 UTC (rev 617)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/service/conversion/package.html 2008-02-07 00:15:28 UTC (rev 618)
@@ -2,7 +2,7 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
- <title>org.cishell.framework.datamodel Package-level Javadoc</title>
+ <title>org.cishell.service.conversion Package-level Javadoc</title>
<!--
/* ****************************************************************************
* CIShell: Cyberinfrastructure Shell, An Algorithm Integration Framework.
@@ -19,9 +19,12 @@
* ***************************************************************************/
-->
</head>
-<body>Provides the specification for the CIShell data conversion service.
+<body>Provides interfaces for the CIShell Data Conversion Service.
<h2>Package Specification</h2>
-This package specifies the API related to the data conversion service.
+The API related to the Data Conversion Service.
+@see <a href="http://cishell.org/dev/docs/spec/cishell-spec-1.0.pdf">
+CIShell Specification 1.0</a>
+
</body>
</html>
\ No newline at end of file
Modified: branches/spec_update/org.cishell.framework/src/org/cishell/service/guibuilder/GUIBuilderService.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/service/guibuilder/GUIBuilderService.java 2008-02-05 17:32:44 UTC (rev 617)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/service/guibuilder/GUIBuilderService.java 2008-02-07 00:15:28 UTC (rev 618)
@@ -28,11 +28,10 @@
* what input is needed (String, Integer, Float, etc...), a description of the
* input, and a way to validate input. There is also an XML format that OSGi
* provides a service ({@link MetaTypeService}) for that will parse the XML into
- * a MetaTypeProvider instance. More information about MetaTypeProvider and
- * MetaTypeService is available in the OSGi Service Platform Specification,
- * Release 4 Service Compendium, Section 105 (pg 129). You can download it at
- * <a href="http://www.osgi.org/osgi_technology/download_specs.asp">
- * http://www.osgi.org/osgi_technology/download_specs.asp</a>.
+ * a MetaTypeProvider instance. See the
+ * <a href="http://cishell.org/dev/docs/spec/cishell-spec-1.0.pdf">
+ * CIShell Specification 1.0</a> for documentation about creating GUIs with this
+ * service.
*
* Algorithm writers are encouraged to use this service if they need to get
* additional input from the user rather than creating their own GUI. This is
Modified: branches/spec_update/org.cishell.framework/src/org/cishell/service/guibuilder/package.html
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/service/guibuilder/package.html 2008-02-05 17:32:44 UTC (rev 617)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/service/guibuilder/package.html 2008-02-07 00:15:28 UTC (rev 618)
@@ -2,7 +2,7 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
- <title>org.cishell.framework.datamodel Package-level Javadoc</title>
+ <title>org.cishell.service.guibuilder Package-level Javadoc</title>
<!--
/* ****************************************************************************
* CIShell: Cyberinfrastructure Shell, An Algorithm Integration Framework.
@@ -19,9 +19,12 @@
* ***************************************************************************/
-->
</head>
-<body>Provides the specification for the CIShell GUI builder service.
+<body>Provides interfaces for the CIShell GUI Builder Service.
<h2>Package Specification</h2>
-This package specifies the API related to the GUI builder service.
+The API related to the GUI Builder Service.
+@see <a href="http://cishell.org/dev/docs/spec/cishell-spec-1.0.pdf">
+CIShell Specification 1.0</a>
+
</body>
</html>
\ No newline at end of file
Modified: trunk/core/org.cishell.docs/src/specification/tex/algorithms.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/algorithms.tex 2008-02-05 17:32:44 UTC (rev 617)
+++ trunk/core/org.cishell.docs/src/specification/tex/algorithms.tex 2008-02-07 00:15:28 UTC (rev 618)
@@ -92,13 +92,13 @@
\subsection*{parentage}
If this metadata element is used, it defines how the output \class{Data}
-produced by the algorithm should be arranged. \class{Data} items can be
-given a parent as part of their metadata (which usually means the \class{Data}
-was derived from the referenced \class{Data}). If parentage is set to
-``default'' then each of the algorithm's outputted \class{Data} items will have
-their parent \class{Data} item set as the first inputted \class{Data} item (if
-applicable). If parentage is set to something else or is not set at all, then
-it is up to the algorithm to set up these relationships.
+produced by the algorithm should be arranged. \class{Data} items can be given a parent as
+part of their metadata (which qsually means the \class{Data} was derived from the
+referenced \class{Data}). If parentage is set to ``default'' then each of the
+algorithm's outputted \class{Data} items will have their parent \class{Data} item
+set as the first inputted \class{Data} item (if applicable) by the
+CIShell-conforming application. If parentage is set to something else or is not
+set at all, then it is up to the algorithm to set up these relationships.
\subsection*{type}
Specifies the type of the algorithm. If no type is set, then
@@ -129,12 +129,12 @@
each element in the list getting more specific. The last element in the list
specifies a group for grouping algorithms in its final menu. Possible groups
include: ``additions'' for default placement, ``start'' for being placed at
-the start of the menu, ``end'' for being placed at the end of the menu. Some
+the start of the menu, or ``end'' for being placed at the end of the menu. Some
examples of valid menu\_path strings include: ``File/additions'',
``Analysis/Undirected Networks/start'', and ``Visualization/Networks/end''.
\subsection*{conversion}
-For converters algorithms, this metadata element specifies if any data is
+For converter algorithms, this metadata element specifies if any data is
lossed in the conversion. Possible values are ``lossy'' and ``lossless''. A
description of what type of information is lost should be explained in the
description.
Modified: trunk/core/org.cishell.docs/src/specification/tex/algorithmtypes.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/algorithmtypes.tex 2008-02-05 17:32:44 UTC (rev 617)
+++ trunk/core/org.cishell.docs/src/specification/tex/algorithmtypes.tex 2008-02-07 00:15:28 UTC (rev 618)
@@ -78,7 +78,7 @@
\item The algorithm must be a conformant \class{AlgorithmFactory}
implementation and properly registered as a service.
\item The algorithm must take in a single \class{Data} item and convert the
- item producing a single \class{Data} item. This must be reflected in the
+ item, producing a single \class{Data} item. This must be reflected in the
algorithm's service metadata where ``in\_data'' and ``out\_data'' have only
one format each.
\item The algorithm's service metadata must contain a legal ``service.pid''.
Modified: trunk/core/org.cishell.docs/src/specification/tex/introduction.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/introduction.tex 2008-02-05 17:32:44 UTC (rev 617)
+++ trunk/core/org.cishell.docs/src/specification/tex/introduction.tex 2008-02-07 00:15:28 UTC (rev 618)
@@ -52,3 +52,26 @@
This is the first release of the CIShell Platform Specification. All packages are
at 1.0 for this release. Subsequent releases may increase the version number of
specific packages, if changes have been made.
+
+\begin{table}[h!]
+\begin{tabular}{l l l}
+\textbf{Item} & \textbf{Package} & \textbf{Version} \\
+Framework Specification & org.cishell.framework & Version 1.0 \\
+Algorithm Specification & org.cishell.framework.algorithm & Version 1.0 \\
+Data Specification & org.cishell.framework.data & Version 1.0 \\
+Data Conversion Service Specification & org.cishell.service.conversion &
+Version 1.0 \\
+GUI Builder Service Specification & org.cishell.service.guibuilder & Version
+1.0 \\
+Log Service Specification & org.osgi.service.log & Version 1.3 \\
+Preferences Service Specification & org.osgi.service.prefs & Version 1.1 \\
+GUI Preferences Service Specification & org.cishell.service.\comments{TBD} &
+Version 1.0 \\
+Data Manager Application Service Specification & org.cishell.app.datamanager &
+Version 1.0 \\
+Scheduler Application Service Specification & org.cishell.app.scheduler &
+Version 1.0 \\
+\end{tabular}
+\caption{Packages and Versions}
+\label{table:packageVersions}
+\end{table}
\ No newline at end of file
Modified: trunk/core/org.cishell.docs/src/specification/tex/osgidependencies.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/osgidependencies.tex 2008-02-05 17:32:44 UTC (rev 617)
+++ trunk/core/org.cishell.docs/src/specification/tex/osgidependencies.tex 2008-02-07 00:15:28 UTC (rev 618)
@@ -6,13 +6,13 @@
implementation. Each additional required service is described in the OSGi
Service Platform Service Compendium R4.
-\subsection*{Required Service}
+\subsection*{Required Services}
\begin{description}
\item[Metatype Service] as described in OSGi section 105 ``Metatype Service
Specification'', this service defines the \class{MetaTypeProvider} class used
for specifying user interfaces in CIShell. In addition, it provides an XML
format for automatically generating \class{MetaTypeProvider}s and a service,
- \class{MetaTypeService} for harvesting them for use by bundles.
+ \class{MetaTypeService}, for harvesting them for use by bundles.
\item[Log Service] as described in OSGi section 101 ``Log Service
Specification'', this service is used as a universal logging system for
algorithms and services. See chapter \ref{logService} for more details.
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
