Menu
▾
▴
[CIShell-SVN] SF.net SVN: cishell: [649] trunk/core/org.cishell.docs/src/specification/ tex
|
From: <bh...@us...> - 2008-03-10 22:31:43
|
Revision: 649
http://cishell.svn.sourceforge.net/cishell/?rev=649&view=rev
Author: bh2
Date: 2008-03-10 15:31:38 -0700 (Mon, 10 Mar 2008)
Log Message:
-----------
Going over the spec with a fine toothed comb... The spec is nearly complete!
Modified Paths:
--------------
branches/spec_update/org.cishell.framework/src/org/cishell/app/service/datamanager/DataManagerService.java
branches/spec_update/org.cishell.framework/src/org/cishell/framework/LocalCIShellContext.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/ParameterMutator.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/service/conversion/DataConversionService.java
branches/spec_update/org.cishell.framework/src/org/cishell/service/guibuilder/GUIBuilderService.java
trunk/core/org.cishell.docs/src/specification/main.tex
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/data.tex
trunk/core/org.cishell.docs/src/specification/tex/datamanagerservice.tex
trunk/core/org.cishell.docs/src/specification/tex/framework.tex
trunk/core/org.cishell.docs/src/specification/tex/guidefinition.tex
trunk/core/org.cishell.docs/src/specification/tex/introduction.tex
trunk/core/org.cishell.docs/src/specification/tex/osgidependencies.tex
trunk/core/org.cishell.docs/src/specification/tex/useradjustableprefs.tex
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-03-07 21:56:18 UTC (rev 648)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/app/service/datamanager/DataManagerService.java 2008-03-10 22:31:38 UTC (rev 649)
@@ -18,7 +18,7 @@
/**
* A service for managing loaded {@link Data} objects.
* {@link DataManagerListener}s may be registered to be notified of changes
- * in the model manager.
+ * in the data manager.
*
* Application developers are encouraged to use this service for managing the
* models they have loaded into memory. Algorithm developers are encouraged not
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-03-07 21:56:18 UTC (rev 648)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/LocalCIShellContext.java 2008-03-10 22:31:38 UTC (rev 649)
@@ -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 Application writers.
+ * it will be used frequently by CIShell application developers.
*
* This implementation only returns standard services or the service strings
* given to it in its constructor.
@@ -44,7 +44,7 @@
/**
* Initializes the CIShell context with a custom set of standard services.
- * Only the standard services provided will be allowed to be retrieved from
+ * Only the service in the array will be allowed to be retrieved from
* this <code>CIShellContext</code>.
*
* @param bContext The <code>BundleContext</code> to use to find
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-03-07 21:56:18 UTC (rev 648)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/AlgorithmFactory.java 2008-03-10 22:31:38 UTC (rev 649)
@@ -21,15 +21,13 @@
/**
* A service interface for creating {@link Algorithm}s to be executed.
- * <br>
* An algorithm developer 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.
- * <br>
* If the algorithm requires input in addition to the raw data provided, a
* {@link MetaTypeProvider} must be published to OSGi's {@link MetaTypeService}
* (usually through a METADATA.XML file in the algorithm's bundle).
- * <br>
+ *
* See the <a href="http://cishell.org/dev/docs/spec/cishell-spec-1.0.pdf">
* CIShell Specification 1.0</a> for documentation on the full requirements for
* algorithm creation.
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-03-07 21:56:18 UTC (rev 648)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/AlgorithmProperty.java 2008-03-10 22:31:38 UTC (rev 649)
@@ -15,8 +15,8 @@
/**
* A standard set of properties and values used for creating a service
- * Dictionary that is provided when registering an {@link AlgorithmFactory}
- * with the OSGi service registry.
+ * metadata 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.
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-03-07 21:56:18 UTC (rev 648)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/DataValidator.java 2008-03-10 22:31:38 UTC (rev 649)
@@ -24,10 +24,6 @@
* make additional checks. For example, if an algorithm only worked on
* 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 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/ParameterMutator.java
===================================================================
--- branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/ParameterMutator.java 2008-03-07 21:56:18 UTC (rev 648)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/algorithm/ParameterMutator.java 2008-03-10 22:31:38 UTC (rev 649)
@@ -21,7 +21,7 @@
* An additional interface an {@link AlgorithmFactory} can implement that allows
* for adding, modifying, or removing input parameters before being shown to the
* end-user for input. This interface is often implemented by algorithms that
- * wish to customize the input UI based on the actual input data.
+ * wish to customize the user interface based on the actual input data.
*
* @author Bruce Herr (bh...@bh...)
*/
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-03-07 21:56:18 UTC (rev 648)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/data/Data.java 2008-03-10 22:31:38 UTC (rev 649)
@@ -17,15 +17,16 @@
import java.util.Dictionary;
/**
- * 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.
+ * A class that contains data, its format, 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 metadata associated with the data stored in this Data object.
- * Some standard keys are in the {@link DataProperty} interface.
+ * Standard keys and values are in the {@link DataProperty} interface.
*
* @return The data's metadata
*/
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-03-07 21:56:18 UTC (rev 648)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/framework/data/DataProperty.java 2008-03-10 22:31:38 UTC (rev 649)
@@ -15,7 +15,7 @@
/**
- * Standard property keys to use when creating metadata for a
+ * Standard property keys and values to use when creating metadata for a
* {@link Data} object
*
* @author Bruce Herr (bh...@bh...)
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-03-07 21:56:18 UTC (rev 648)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/service/conversion/DataConversionService.java 2008-03-10 22:31:38 UTC (rev 649)
@@ -36,8 +36,7 @@
* 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,
- * <code>null</code> will be returned.
+ * <code>outFormat</code>.
*
* @param inFormat The type of Data object to be converted. This String
* should be formatted in the same way as an algorithm's
@@ -46,8 +45,7 @@
* String should be formatted in the same way as an
* algorithm's {@link AlgorithmProperty#OUT_DATA}.
* @return An array of {@link Converter}s that can convert a Data object of
- * the given inFormat to the specified outFormat, or
- * <code>null</code> if there is no valid conversion sequence
+ * the given inFormat to the specified outFormat
*/
public Converter[] findConverters(String inFormat, String outFormat);
@@ -58,20 +56,16 @@
* @param data The Data object to convert
* @param outFormat The output format to convert to
* @return An array of {@link Converter}s that can convert the
- * given Data object to the specified output format, or
- * <code>null</code> if there is no valid conversion sequence
+ * given Data object to the specified output format
*/
public Converter[] findConverters(Data data, String outFormat);
/**
- * Tries to convert a given Data object to the specified output format. If
- * the conversion fails or there is no way to convert it, this method will
- * return a <code>null</code>.
+ * Tries to convert a given Data object to the specified output format
*
* @param data The Data to convert
* @param outFormat The format of the Data object to be returned
- * @return A Data object with the specified output format, or
- * <code>null</code> if there is no valid conversion sequence
+ * @return A Data object with the specified output format
* @throws ConversionException If the data conversion fails while converting
*/
public Data convert(Data data, String outFormat) throws ConversionException;
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-03-07 21:56:18 UTC (rev 648)
+++ branches/spec_update/org.cishell.framework/src/org/cishell/service/guibuilder/GUIBuilderService.java 2008-03-10 22:31:38 UTC (rev 649)
@@ -17,7 +17,6 @@
import org.osgi.service.log.LogService;
import org.osgi.service.metatype.MetaTypeProvider;
-import org.osgi.service.metatype.MetaTypeService;
import org.osgi.service.metatype.ObjectClassDefinition;
/**
@@ -26,11 +25,11 @@
* simple information and a more flexible way to create {@link GUI}s using a
* standard OSGi {@link MetaTypeProvider}. The MetaTypeProvider basically lists
* 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. See the
+ * input, and a way to validate input.
+ *
+ * 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
+ * CIShell Specification 1.0</a> for documentation on creating GUIs with this
* service.
*
* Algorithm writers are encouraged to use this service if they need to get
Modified: trunk/core/org.cishell.docs/src/specification/main.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/main.tex 2008-03-07 21:56:18 UTC (rev 648)
+++ trunk/core/org.cishell.docs/src/specification/main.tex 2008-03-10 22:31:38 UTC (rev 649)
@@ -1,4 +1,4 @@
-%% CIShell Specification
+%% Cyberinfrastructure Shell (CIShell) Core Specification
%%
%
@@ -54,10 +54,4 @@
\input{./tex/datamanagerservice.tex}
\input{./tex/schedulerservice.tex}
-%%% We have no references thus far, so this is commented out for now.
-% Bibliography:
-% \clearpage
-% \bibliographystyle{plain}
-% \bibliography{../bibliography}
-
\end{document}
Modified: trunk/core/org.cishell.docs/src/specification/tex/algorithms.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/algorithms.tex 2008-03-07 21:56:18 UTC (rev 648)
+++ trunk/core/org.cishell.docs/src/specification/tex/algorithms.tex 2008-03-10 22:31:38 UTC (rev 649)
@@ -7,22 +7,40 @@
The CIShell Platform has been specifically designed around the idea of the
algorithm. It is the central and most important concept. Algorithms are fully
defined and self-contained bits of execution. They can do many things from data
-conversion, data analysis, and can even spawn whole outside programs if needed.
+conversion, data analysis, and can even spawn whole external programs if needed.
Algorithms are very well defined black boxes in that what can come into and out
-of the algorithm is specified in each algorithm's metadata. Other than that,
-CIShell makes no attempt to understand the algorithm.
+of the algorithm is specified in each algorithm's service metadata and
+associated \class{MetaTypeProvider}. Other than that, CIShell makes no attempt
+to understand the algorithm.
+\subsubsection{Essentials}
+\begin{itemize}
+ \item \textit{Application Independence} - Algorithms must be usable in a wide
+ variety of contexts and should not be tied to any one CIShell environment or
+ front end where possible.
+ \item \textit{User Interface Independence} - Algorithms should not have to tie
+ themselves to a single UI where possible.
+ \item \textit{Black Box Algorithms} - Algorithms are black boxes whose
+ possible interactions are described in metadata.
+ \item \textit{Delayed Execution} - There may be a large delay between an
+ algorithm getting parameters for execution and its actual execution.
+ \item \textit{Remote Execution} - Algorithm interfaces should be designed to
+ facilitate remote execution of algorithms where possible.
+\end{itemize}
+
+\subsubsection{Operations}
+
To be recognized by CIShell, an \class{AlgorithmFactory} must be registered with
-OSGi's Service Registry. The service registry requires three things when
+OSGi's service registry. The service registry requires three things when
registering: an interface (\class{AlgorithmFactory}), an implementation, and a
\class{Dictionary} of metadata. The algorithm developer provides the
implementation and metadata. The metadata helps to differentiate and define the
algorithm for search and discovery, see section \ref{algMetaData}.
An algorithm defines its inputs in two ways. First, the input data is defined in
-the algorithm's service metadata. Second, the acceptable user-entered parameters
-are defined in a \class{MetaTypeProvider} and published to the
-\class{MetaTypeService}, see section \ref{GUISpec}.
+the algorithm's service metadata. Second, the acceptable user-entered
+input parameters are defined in a \class{MetaTypeProvider} and published to the
+\class{MetaTypeService}.
Figure \ref{fig:algExecWorkflow} shows the typical flow of information into and
out of an algorithm. First the input parameter specification is pulled from the
@@ -39,22 +57,21 @@
\label{fig:algExecWorkflow}
\end{figure}
+
\subsection{Optional Interfaces}
Algorithm developers may augment algorithms with additional interfaces to enhance
-parts of the execution workflow. See each interface's documentation for more
+parts of the execution workflow. See each interface's API documentation for more
details.
\begin{description}
\item[ParameterMutator] An \class{AlgorithmFactory} can implement the
\class{ParameterMutator} interface to add, remove, or modify an algorithm's
- parameters (\class{AttributeDefinition}s in an \class{ObjectClassDefinition}
- in a \class{MetaTypeProvider}) between the time when its
- \class{MetaTypeProvider} is pulled from the \class{MetaTypeService} and when
- the corresponding UI is shown to the user. This is typically done to
- customize the input parameters based on the data to be given to the
- algorithm. See section \ref{GUISpec} for information on constructing and
- publishing \class{MetaTypeProviders}.
+ input parameters between the time when its \class{MetaTypeProvider} is pulled
+ from the \class{MetaTypeService} and when the corresponding UI is shown to the
+ user. This is typically done to customize the input parameters based on the
+ data to be given to the algorithm. See section \ref{GUISpec} for information
+ on constructing and publishing \class{MetaTypeProviders}.
\item[DataValidator] An \class{AlgorithmFactory} can implement the
\class{DataValidator} interface to validate the data beyond the data format
@@ -65,16 +82,16 @@
of an \class{Algorithm}'s progress while executing.
\end{description}
-\subsection{Algorithm Service Metadata Definition}
+\subsection{Service Metadata}
\label{algMetaData}
-When an algorithm is registered with OSGi's service registry, a dictionary of
-metadata is provided. Since the algorithm itself is a black box, the metadata is
-used to provide information about the algorithm. Information such as the format
-of each \class{Data} item to be input and output is provided. In addition to the
-mechanics of the algorithms, data such as the authors, label, urls, citation
-references, and description are provided. This metadata can be searched by anyone
-using OSGi's service registry to find relevant algorithms.
+When an algorithm is registered with OSGi's service registry, a
+\class{Dictionary} of metadata is provided. Since the algorithm itself is a black
+box, the metadata is used to provide information about the algorithm. Information
+such as the format of each \class{Data} item to be input and output is provided.
+In addition to the mechanics of the algorithms, data such as the authors, label,
+urls, citation references, and description are provided. This metadata can be
+searched by anyone using OSGi's service registry to find relevant algorithms.
Each standard metadata element required by the CIShell specification is defined
below and in the interface \class{AlgorithmProperty}. It defines each key string
@@ -87,7 +104,7 @@
be available in the service registry at any given time. It is recommended to
use the Java naming scheme including path for this purpose, i.e.,
``org.cishell.my.algorithm.MyAlgorithm''. This metadata element is defined
-as part of the OSGi Service Platform Core Specification, section 6.1.12.58.
+as part of the OSGi Service Platform Core Specification, section 6.1.12.
\begin{quote}
\begin{description}
@@ -114,11 +131,12 @@
\subsection*{in\_data}
Specifies the formats and number of \class{Data} inputs the
algorithm accepts. The string is a comma separated list of data formats as
-defined in section \ref{dataSpec}. If any data is optional, prefix the associated
-format with a ``?''. When receiving the \class{Data} array, an optional
-\class{Data} element will be null if it is not provided. If no \class{Data}
-inputs are necessary then the string ``null'' or not specifying the in\_data attribute
-at all is valid.
+defined in section \ref{dataSpec}. If no \class{Data} inputs are necessary then
+the string ``null'' or not specifying the in\_data attribute at all is valid.
+If any data is optional, prefix the associated format with a ``?''. When the
+\class{AlgorithmFactory.createAlgorithm} method is called with a \class{Data}
+array, an optional \class{Data} element will be \class{null} if it is not
+provided.
By using the ``+'', ``*'', or ``?'' prefixes, ambiguities could arise from
specifying multiple input formats that could easily fit into two or more
@@ -140,12 +158,12 @@
\subsection*{out\_data}
Specifies the formats and number of \class{Data} inputs
-the algorithm produces when successfully run. The string is a comma separated
-list of data formats as defined in section \ref{dataSpec}. If any data is
-optional, prefix the associated format with a ``?''. When producing the
-\class{Data} array, an optional \class{Data} element must be null if it is not
-produced. If no \class{Data} is output then the string ``null'' or not specifying
-the out\_data attribute at all is valid.
+the algorithm produces when successfully executed. The string is a comma
+separated list of data formats as defined in section \ref{dataSpec}. If no
+\class{Data} is output then the string ``null'' or not specifying the out\_data
+attribute at all is valid. If any data is optional, prefix the associated
+format with a ``?''. When producing the \class{Data} array, an optional
+\class{Data} element must be \class{null} if it is not produced.
\begin{quote}
\begin{description}
@@ -161,12 +179,12 @@
\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) by the
+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 output \class{Data} items will have their parent \class{Data} item
+set as the first input \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.
Modified: trunk/core/org.cishell.docs/src/specification/tex/algorithmtypes.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/algorithmtypes.tex 2008-03-07 21:56:18 UTC (rev 648)
+++ trunk/core/org.cishell.docs/src/specification/tex/algorithmtypes.tex 2008-03-10 22:31:38 UTC (rev 649)
@@ -1,9 +1,6 @@
-\section{Algorithm Type Specifications}
-
-\subsection*{\textit{Version 1.0}}
-
+\subsection{Algorithm Types}
\label{algConstraints}
-\subsection{Introduction}
+\subsubsection{Introduction}
CIShell algorithms are a generic concept which have many uses. In the CIShell
Platform, they are used in 4 contexts: as general data-centric algorithms to be
@@ -11,21 +8,21 @@
Algorithms), as data validators (Validator Algorithms), and as providers of data
(Dataset Algorithms). In order to better separate these uses, a lightweight type
system has been introduced. The only way to tell the difference between them is
-by the constraints defined for each algorithm type.
+by the constraints defined for each algorithm type as defined below.
-\subsection{Base Algorithm Constraints}
+\subsubsection{Base Algorithm Constraints}
All conformant algorithms regardless of type, must adhere to the following
constraints:
-\subsubsection*{Required:}
+\paragraph*{Required:}
\begin{itemize}
\item The algorithm must be a conformant \class{AlgorithmFactory}
implementation and properly registered as a service.
\item The algorithm's service metadata must contain a valid ``service.pid''.
\end{itemize}
-\subsubsection*{Optional:}
+\paragraph*{Optional:}
\begin{itemize}
\item The algorithm's service metadata should have ``remoteable=true'' if it
meets the requirements of a remoteable algorithm.
@@ -38,12 +35,12 @@
``documentation\_url'', ``reference'', ``reference\_url'', and ``written\_in''.
\end{itemize}
-\subsection{Standard Algorithms}
+\subsubsection{Standard Algorithms}
Standard CIShell algorithms are the algorithms that most end-users will
encounter. A standard algorithm has the following constraints:
-\subsubsection*{Required:}
+\paragraph*{Required:}
\begin{itemize}
\item The algorithm must be a conformant \class{AlgorithmFactory}
implementation and properly registered as a service.
@@ -59,10 +56,10 @@
``menu\_path''.
\end{itemize}
-\subsubsection*{Optional:}
+\paragraph*{Optional:}
\begin{itemize}
- \item If additional user-entered parameters are needed, the algorithm should
- provide a \class{MetaTypeProvider} published by the \class{MetaTypeService}.
+ \item If additional user-entered input parameters are needed, the algorithm
+ should provide a \class{MetaTypeProvider} published to the \class{MetaTypeService}.
\item The algorithm's service metadata should have ``remoteable=true'' if it
meets the requirements of a remoteable algorithm.
\item The algorithm's service metadata should have ``parentage=default'' if
@@ -74,7 +71,7 @@
``documentation\_url'', ``reference'', ``reference\_url'', and ``written\_in''.
\end{itemize}
-\subsection{Dataset Algorithms}
+\subsubsection{Dataset Algorithms}
A dataset algorithm is a custom type of CIShell algorithm for providing
pre-generated data for use in the CIShell Platform. Dataset algorithms act just
@@ -82,7 +79,7 @@
Applications may not even treat them any differently than standard algorithms. A
dataset algorithm has the following constraints:
-\subsubsection*{Required:}
+\paragraph*{Required:}
\begin{itemize}
\item The algorithm must be a conformant \class{AlgorithmFactory}
implementation and properly registered as a service.
@@ -103,7 +100,7 @@
as its ``out\_data''.
\end{itemize}
-\subsubsection*{Optional:}
+\paragraph*{Optional:}
\begin{itemize}
\item The algorithm's service metadata should have ``remoteable=true'' if it
meets the requirements of a remoteable algorithm.
@@ -112,7 +109,7 @@
``documentation\_url'', ``reference'', and ``reference\_url''.
\end{itemize}
-\subsection{Converter Algorithms}
+\subsubsection{Converter Algorithms}
\label{converterAlg}
A converter algorithm is a custom type of CIShell algorithm for converting data
@@ -120,7 +117,7 @@
\class{DataConversionService} and are not used directly by end-users. A converter
algorithm has the following constraints:
-\subsubsection*{Required:}
+\paragraph*{Required:}
\begin{itemize}
\item The algorithm must be a conformant \class{AlgorithmFactory}
implementation and properly registered as a service.
@@ -132,12 +129,12 @@
\item The algorithm's service metadata must have ``type=converter''.
\item The algorithm's service metadata must have ``conversion=lossy'' if
data is lost during conversion or ``conversion=lossless'' if not.
- \item The algorithm must not require any parameters. The \class{Dictionary}
- passed to the createAlgorithm method will always be empty.
+ \item The algorithm must not require any input parameters. The
+ \class{Dictionary} passed to the createAlgorithm method will always be empty.
\end{itemize}
-\subsubsection*{Optional:}
-\begin{itemize}an
+\paragraph*{Optional:}
+\begin{itemize}
\item The algorithm's service metadata should have ``remoteable=true'' if it
meets the requirements of a remoteable algorithm.
\item The algorithm's service metadata should have a ``label'' which is a
@@ -150,7 +147,7 @@
in accordingly.
\end{itemize}
-\subsection{Validator Algorithms}
+\subsubsection{Validator Algorithms}
A validator algorithm is a custom type of CIShell algorithm which checks either
an incoming or outgoing file to be sure it is of the type specified. This is
@@ -161,28 +158,29 @@
bringing in outside data and saving out data from CIShell. A validator algorithm
has the following constraints:
-\subsubsection*{Required:}
+\paragraph*{Required:}
\begin{itemize}
\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 validate the
item producing a single \class{Data} item (with the same data, but changed
- format) or \class{null} if the file being validated is not of the right
+ format) or throw an exception if the file being validated is not of the right
type. This must be reflected in the algorithm's service metadata where
``in\_data'' and ``out\_data'' have only one data item each with one
- containing a ``file:'' format and the other a ``file-ext:'' depending on the
- direction of validation.
+ containing a ``file:\textit{mime/type}'' format and the other a
+ ``file-ext:\textit{file-extension}'' depending on the direction of validation.
+ See section \ref{dataSpec} for data format details.
\item The algorithm must not alter the data. Its only purpose is to validate
the proposed incoming or outgoing file.
\item The algorithm's service metadata must contain a valid ``service.pid''.
\item The algorithm's service metadata must have ``type=validator''.
\item The algorithm's service metadata must have a ``label'' which is the
common name of the data format being validated.
- \item The algorithm must not require any parameters. The \class{Dictionary}
- passed to the createAlgorithm method will always be empty.
+ \item The algorithm must not require any input parameters. The
+ \class{Dictionary} passed to the createAlgorithm method will always be empty.
\end{itemize}
-\subsubsection*{Optional:}
+\paragraph*{Optional:}
\begin{itemize}
\item The algorithm's service metadata should have ``remoteable=true'' if it
meets the requirements of a remoteable algorithm.
Modified: trunk/core/org.cishell.docs/src/specification/tex/data.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/data.tex 2008-03-07 21:56:18 UTC (rev 648)
+++ trunk/core/org.cishell.docs/src/specification/tex/data.tex 2008-03-10 22:31:38 UTC (rev 649)
@@ -4,8 +4,8 @@
\subsection{Introduction}
Data to be operated on is passed around in \class{Data} objects which hold the
-real data, the data's format, and its properties (metadata). The real data can be
-any Java \class{Object}. The format is a string describing the 'format' of the
+real data, the data's format, and the data's properties (metadata). The real
+data can be any Java \class{Object}. The format is a string describing the 'format' of the
data, see next section. Finally, the properties help describe the data. The label
to give the data, the parent \class{Data} object from which it was derived from,
and a coarse data type can all be defined in the \class{Data}'s properties. See
@@ -32,5 +32,5 @@
zero or more, prefix the type with a ``*''. This corresponds to a \class{Data}
object that is wrapping multiple (zero or one or more depending on the prefix)
other \class{Data} objects of the associated format in a Java array
-(\class{Data[]}) stored as its wrapped real data. This is useful for algorithms
-that can work on a variable number of \class{Data} items.
+(\class{Data[]}) stored as its contained real data. This is useful for
+algorithms that can work on a variable number of \class{Data} items.
Modified: trunk/core/org.cishell.docs/src/specification/tex/datamanagerservice.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/datamanagerservice.tex 2008-03-07 21:56:18 UTC (rev 648)
+++ trunk/core/org.cishell.docs/src/specification/tex/datamanagerservice.tex 2008-03-10 22:31:38 UTC (rev 649)
@@ -20,7 +20,7 @@
implementation of \class{DataManagerListener} with empty method
implementations.
\item \textit{Data} - The interface used to pass data (other than
- parameters) and its metadata between algorithms.
+ input parameters) and its metadata between algorithms.
\end{itemize}
\orgcishellappservicedatamanager{}
\ No newline at end of file
Modified: trunk/core/org.cishell.docs/src/specification/tex/framework.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/framework.tex 2008-03-07 21:56:18 UTC (rev 648)
+++ trunk/core/org.cishell.docs/src/specification/tex/framework.tex 2008-03-10 22:31:38 UTC (rev 649)
@@ -7,21 +7,6 @@
The \class{org.cishell.framework} package and subpackages define the core of
CIShell. The key components being algorithms, data, and CIShell service access.
-\subsection{Essentials}
-\begin{itemize}
- \item \textit{Application Independence} - Algorithms must be usable in a wide
- variety of contexts and should not be tied to any one CIShell environment or
- front end where possible.
- \item \textit{User Interface Independence} - Algorithms should not have to tie
- themselves to a single UI where possible.
- \item \textit{Black Box Algorithms} - Algorithms are black boxes whose
- possible interactions are described in metadata.
- \item \textit{Delayed Execution} - There may be a large delay between an
- algorithm getting parameters for execution and its actual execution.
- \item \textit{Remote Execution} - Algorithm interfaces should be designed to
- facilitate remote execution of algorithms where possible.
-\end{itemize}
-
\subsection{Entities}
\begin{itemize}
@@ -33,20 +18,20 @@
\item \textit{AlgorithmProperty} - The interface which provides string
constants for an algorithm's service metadata.
\item \textit{ParameterMutator} - The interface an \class{AlgorithmFactory}
- extends to provide the ability to add, remove, or modify user-entered
- parameters specifications (see section \ref{GUISpec}) before being shown to an
- end-user.
+ extends to provide the ability to add, remove, or modify its input
+ parameters specification (see section \ref{GUISpec}) before being transformed
+ into a form for user input.
\item \textit{DataValidator} - The interface an \class{AlgorithmFactory}
extends to provide additional data validation in addition to the data format validation
that an application should provide ahead of time.
\item \textit{ProgressTrackable} - The interface an \class{Algorithm} extends
- to allow for more detailed monitoring and control of an Algorithm's progress while
- executing.
+ to allow for more detailed monitoring and control of an \class{Algorithm}'s
+ progress while executing.
\item \textit{ProgressMonitor} - The interface for a class to be passed in to
a \class{ProgressTrackable} \class{Algorithm} so that the \class{Algorithm}
can be controlled and provide information on its progress while executing.
\item \textit{Data} - The interface used to pass data (other than
- parameters) and meta-data between algorithms.
+ input parameters) and its metadata between algorithms.
\item \textit{BasicData} - A simple implementation of the \class{Data}
interface.
\item \textit{DataProperty} - The interface which provides string constants
@@ -56,7 +41,7 @@
services.
\item \textit{LocalCIShellContext} - A simple implementation of the
\class{CIShellContext} interface which pulls CIShell services from the OSGi
- Service Registry.
+ service registry.
\end{itemize}
\begin{figure}[htb!]
@@ -68,8 +53,7 @@
\subsection{Operations}
-The algorithm developer should fully implement the \class{AlgorithmFactory}
-interface and make it available in OSGi's service registry. The system developer
-will provide the services required by CIShell in OSGi's service registry.
-Application developers will provide everything else, orchestrating the passing of
-information between algorithms.
+The algorithm developer should implement algorithms as described in this
+specification. The system developer will provide the services required by CIShell
+in OSGi's service registry. Application developers will provide everything else,
+orchestrating the passing of information between algorithms.
Modified: trunk/core/org.cishell.docs/src/specification/tex/guidefinition.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/guidefinition.tex 2008-03-07 21:56:18 UTC (rev 648)
+++ trunk/core/org.cishell.docs/src/specification/tex/guidefinition.tex 2008-03-10 22:31:38 UTC (rev 649)
@@ -4,21 +4,19 @@
\subsection{Introduction}
For many algorithms, just looking at the data given isn't enough. Additional
-parameters are often needed to know how to operate on a given piece of data. An
-algorithm can define what parameters are needed by providing a
+input parameters are often needed to know how to operate on a given piece of
+data. An algorithm can define what parameters are needed by providing a
\class{MetaTypeProvider}. It defines the types, value range, and textual
description of the parameters needed. From this information, a user interface
(UI) can be created that asks a user for the data. The \class{MetaTypeProvider}
is not tied to any specific UI, so it can be reused depending on the context
(desktop application, web application, command line, etc.).
-\class{MetaTypeProvider} is defined in the OSGi R4 Specification Service
-Compendium as part of the Meta Type Service. \class{MetaTypeProvider}s can be
-created in code or can be specified in an xml file (as defined in the
-specification) and pulled out of the \class{MetaTypeService} service. A
+\class{MetaTypeProvider} is an interface defined in the OSGi R4 Specification
+Service Compendium as part of the ``Metatype Service Specification''. A
\class{MetaTypeProvider} can be thought of as a collection of UIs. Each UI is
-called an \class{ObjectClassDefinition}, which provides a UI name and
-description and is a collection of parameters. Each parameter is an
+called an \class{ObjectClassDefinition}, which provides a UI name and description
+and is a collection of parameters. Each parameter is an
\class{AttributeDefinition} which includes the type, label, description, default
value, and range of valid values. Drop-down boxes can also be defined by using
option labels and values with the \class{AttributeDefinition}. OSGi's
@@ -31,7 +29,7 @@
strings, integers, booleans, etc, but several useful types are missing. To
support more types, an \class{AttributeDefinition} (AD) of type ``string'' has
its default value set to a certain string so that the UI builder recognizes this
-and selects an appropriate widget. When the algorithm receives the user entered
+and selects an appropriate widget. When the algorithm receives the user-entered
parameters, the associated value will be of type \class{java.lang.String}, but
should contain the correct value as defined below.
@@ -53,3 +51,26 @@
color values the user chose. Each item in the comma separated list would be
between 0 and 255. The first item would be the red value, second green value,
and third blue value.
+
+\subsection{Publishing MetaTypeProviders}
+
+For user-adjustable preferences and algorithm input parameters, a
+\class{MetaTypeProvider} is required to be published to the
+\class{MetaTypeService}. This can be done in two ways, through code or by a
+METADATA.XML file.
+
+To publish through code, a few steps must be followed. First, the service to be
+registered with the OSGi service registry must fully implement
+\class{org.\-osgi.\-service.\-cm.\-ManagedService} and
+\class{org.\-osgi.\-service.\-metatype.\-MetaTypeProvider}. Second, when
+registering the service, both \class{ManagedService} and \class{MetaTypeProvider}
+must be in the list of interfaces the service implements. If these two things are
+done, the \class{MetaTypeService} will notice it and add it to its registry of
+\class{MetaTypeProviders}.
+
+The recommended way to publish \class{MetaTypeProviders} is to publish through a
+METADATA.XML file. A METADATA.XML file must be included in the algorithm's OSGi
+bundle in a specific directory, ``OSGI-INF/metatype/''. The
+\class{MetaTypeService} will notice this in the bundle and add it to its registry
+of \class{MetaTypeProviders}. See the ``Metatype Service Specification'' in the
+OSGi specification for details on the XML format.
Modified: trunk/core/org.cishell.docs/src/specification/tex/introduction.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/introduction.tex 2008-03-07 21:56:18 UTC (rev 648)
+++ trunk/core/org.cishell.docs/src/specification/tex/introduction.tex 2008-03-10 22:31:38 UTC (rev 649)
@@ -7,12 +7,12 @@
while retaining their intellectual rights after distribution; (2) data holders to
easily disseminate their data for use by others; (3) application developers to
design applications from custom sets of algorithms and datasets that interoperate
-seamlessly; and ultimately (4) end-users to use existing datasets and algorithms
+seamlessly; and ultimately (4) end-users to use datasets and algorithms
effectively.
\section{CIShell Platform Overview}
-The CIShell Platform consists of Java interface definitions of algorithms, data,
+The CIShell Platform consists of Java interface definitions for algorithms, data,
services for algorithm developers, and services for application developers. Much
of the platform uses metadata and is fully defined.
@@ -35,8 +35,9 @@
The CIShell Specifications assume that the reader has at least one year of
practical experience in writing Java programs. CIShell is built to run on the
OSGi Service Platform Release 4\footnote{http://www.osgi.org/Release4/Download}
-and thus a working knowledge of OSGi is expected. OSGi (and thus CIShell) is highly dynamic and must be taken into consideration
-when developing anything on CIShell.
+and thus a working knowledge of OSGi is expected. OSGi (and thus CIShell) is
+highly dynamic and must be taken into consideration when developing anything on
+CIShell.
Non-Java algorithm developers may not need to know any Java and should be mainly
concerned with the metadata definitions for algorithms and data. They may also
Modified: trunk/core/org.cishell.docs/src/specification/tex/osgidependencies.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/osgidependencies.tex 2008-03-07 21:56:18 UTC (rev 648)
+++ trunk/core/org.cishell.docs/src/specification/tex/osgidependencies.tex 2008-03-10 22:31:38 UTC (rev 649)
@@ -10,10 +10,11 @@
\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.
+ Specification,'' this service is used by CIShell to find
+ \class{MetaTypeProviders} for user interface specification, user-adjustable
+ preferences, and input parameters. It also provides an XML format for
+ automatically generating \class{MetaTypeProvider}s which the
+ \class{MetaTypeService} harvests for use.
\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.
Modified: trunk/core/org.cishell.docs/src/specification/tex/useradjustableprefs.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/useradjustableprefs.tex 2008-03-07 21:56:18 UTC (rev 648)
+++ trunk/core/org.cishell.docs/src/specification/tex/useradjustableprefs.tex 2008-03-10 22:31:38 UTC (rev 649)
@@ -6,7 +6,7 @@
The user-adjustable preferences specification defines how any service can publish
user-adjustable preferences both globally and locally. In addition to global and
local preferences, algorithms can allow the system to allow end-users to adjust
-the default values for algorithms' user-entered parameters specification
+the default values for algorithms' user-entered input parameters specification
published to the \class{MetaTypeService}. For storing data that is not directly
end-user adjustable, see chapter \ref{preferencesService}.
@@ -20,14 +20,15 @@
\class{ManagedService}. See section \ref{GUISpec} for more information.
\subsubsection*{Designate an OCD a Persistent ID (PID)} Then they must designate
-the ObjectClassDefinition a persistent id (PID). The PID can be designated in two
-ways. The simplest way is by following the convention of creating a string with
-the associated service's ``service.pid'' and appending either ``.prefs.local'' or
-``.prefs.global''. The other way is to designate whatever PID the developer
-wishes and to provide a service property ``local\_pref\_pid'' or
-``global\_pref\_pid'' which is set to whatever PID they chose.
+the \class{ObjectClassDefinition} a persistent id (PID). The PID can be
+designated in two ways. The simplest way is by following the convention of
+creating a string with the associated service's ``service.pid'' and appending
+either ``.prefs.local'' or ``.prefs.global''. The other way is to designate
+whatever PID the developer wishes and to provide a service property
+``local\_pref\_pid'' or ``global\_pref\_pid'' which is set to whatever PID they
+chose.
-\subsubsection*{Designate What Preferences are to be Published} To let the system
+\subsubsection*{Declare What Preferences are to be Published} To let the system
know that you wish to publish preferences, the system properties must contain a
``prefs\_published'' key with zero or more of the following values (separated by
commas): ``local'' for publishing local prefs, ``global'' for global prefs, and
@@ -37,12 +38,11 @@
defaults, algorithm developers allow end-users to adjust the default values they
see when running their algorithm. This is typically accomplished by wrapping the
\class{MetaTypeProvider} published by the algorithm to the
-\class{MetaTypeService} (with PID designated to either the algorithm's
-``service.pid'' or whatever was specified by the algorithm's ``parameters\_pid'')
-with overridden \class{AttributeDefinitions} that change their default value.
-Many systems will have this on by default, but if the ``prefs\_published'' key is
-set in the algorithm's service metadata and ``param-defaults'' is not set, then
-this feature will be disabled for the algorithm.
+\class{MetaTypeService} with overridden \class{AttributeDefinitions} that
+change their default value. Many systems will have this on by default, but if
+the ``prefs\_published'' key is set in the algorithm's service metadata and
+``param-defaults'' is not set, then this feature will be disabled for the
+algorithm.
\subsubsection*{Receiving Preference Data} To be notified of changes to local or
global preferences, the service must implement
@@ -50,7 +50,7 @@
metadata ``receive\_prefs=true''. When either the local or global preferences are updated,
the updated method will be passed a \class{Dictionary} of all of the id/value
pairs, including the updated ones. Local preferences will have the same ids as
-the AttributeDefinitions (AD) defined in the associated OCD. The local
+the \class{AttributeDefinition}s (AD) defined in the associated OCD. The local
preferences will also have an additional id ``Bundle-Version", which contains the
version of the service's associated bundle that was used when the preference data
was last updated. Global preferences will have the same ids (plus a
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
