[CIShell-SVN] SF.net SVN: cishell: [611] trunk/core/org.cishell.docs/src/specification

[<bh...@us...>]

Revision: 611
          http://cishell.svn.sourceforge.net/cishell/?rev=611&view=rev
Author:   bh2
Date:     2008-01-30 14:32:46 -0800 (Wed, 30 Jan 2008)

Log Message:
-----------
* Fleshed out algorithm constraints for each type of algorithm
* Added algorithm metadata element definitions
* Added a reference to constructing mime types documentation

Modified Paths:
--------------
    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/data.tex
    trunk/core/org.cishell.docs/src/specification/tex/dataconversionservice.tex
    trunk/core/org.cishell.docs/src/specification/tex/guibuilderservice.tex

Added Paths:
-----------
    trunk/core/org.cishell.docs/src/specification/tex/algorithmtypes.tex

Modified: trunk/core/org.cishell.docs/src/specification/main.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/main.tex	2008-01-30 19:13:58 UTC (rev 610)
+++ trunk/core/org.cishell.docs/src/specification/main.tex	2008-01-30 22:32:46 UTC (rev 611)
@@ -37,6 +37,7 @@
 \input{./tex/introduction.tex}
 \input{./tex/framework.tex}
 \input{./tex/algorithms.tex}
+\input{./tex/algorithmtypes.tex}
 \input{./tex/data.tex}
 \input{./tex/guidefinition.tex}
 \orgcishellframework{}

Modified: trunk/core/org.cishell.docs/src/specification/tex/algorithms.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/algorithms.tex	2008-01-30 19:13:58 UTC (rev 610)
+++ trunk/core/org.cishell.docs/src/specification/tex/algorithms.tex	2008-01-30 22:32:46 UTC (rev 611)
@@ -48,21 +48,116 @@
 control of an \class{Algorithm}'s progress while executing. See each interface's
 documentation for more details.
 
-\subsection{Algorithm Service Metadata}
+\subsection{Algorithm Service Metadata Definition}
 \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 inputted and outputted is provided. In addition to the
-mechanics of the algorithms, interesting data such as the authors, label, urls,
-and description are provided. This metadata can be searched by anyone using
+of each \class{Data} item to be inputted and outputted is provided. In addition
+to the mechanics of the algorithms, interesting data such as the authors, label,
+urls, and description are provided. This metadata can be searched by anyone using
 OSGi's service registry to find relevant algorithms for use.
 
-\comments{Lots more to do here. Need to define what is/isn't mandatory for each
-algorithm type. Perhaps some figures\ldots}
+Each standard metadata element required by the CIShell specification is defined
+below and in the interface \class{AlgorithmProperty}. It defines each key string
+and the valid value strings to set in the metadata \class{Dictionary} when
+registering an algorithm as a service.
 
-\subsubsection{Standard Algorithm Constraints}
-\label{algConstraints}
+\subsection*{service.pid}
+A string that uniquely identifies the algorithm. The service.pid should not
+change between sessions and only one algorithm with a given service.pid should
+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. 
 
+\subsection*{in\_data}
+Specifies the type and number of \class{Data} inputs the
+algorithm accepts. The string is a comma separated list of data formats. Valid strings
+for each data format are: a full Java class if a Java \class{Object} is
+expected, a string with the format ``file:\textit{mime/type}'' if a
+\class{java.io.File} is expected, or a string with the format
+``file-ext:\textit{file-extension}'' if a \class{java.io.File} known only by
+extension is expected (only applicable for validator algorithms), see 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.
 
+\subsection*{out\_data}
+Specifies the type and number of \class{Data} outputs
+the algorithm will produce when successfully run. This metadata key has the same string format
+as defined in the in\_data specification. If no \class{Data} outputs are
+produced then the string ``null'' or not specifying the out\_data attribute at
+all is valid.
+
+\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.
+
+\subsection*{type}
+Specifies the type of the algorithm. If no type is set, then
+it is assumed to be of ``Standard Algorithm'' type. Which metadata keys to use and
+their exact meaning varies depending on the type of algorithm. The different
+algorithm types and their constraints are defined in section
+\ref{algConstraints}.
+
+\subsection*{remotable}
+Specifies if the algorithm can be run remotely. An algorithm can be run
+remotely if it only uses the services provided by the \class{CIShellContext}
+and does not create its own non-\class{GUIBuilderService}-built GUI. Valid
+strings are ``true'' or ``false''. If this metadata element is not set, then
+it is assumed that it cannot be run remotely.
+
+\subsection*{label}
+Specifies a human-readable short name for the algorithm. What label is
+acceptable varies depending on the type of the algorithm. 
+
+\subsection*{description}
+Provides more details on the workings of the algorithm. What
+description is acceptable varies depending on the type of the algorithm.
+
+\subsection*{menu\_path}
+Specifies where on the menu an algorithm is to be
+placed if a menu bar is used. Otherwise, it can act as a primitive hierarchical
+classification of the algorithm. The string is a ``/'' separated list with
+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
+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
+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.
+
+\subsection*{authors}
+A comma separated list of the authors of the abstract algorithm.
+
+\subsection*{implementers}
+A comma separated list of the developers who implemented the algorithm in code.
+
+\subsection*{integrators}
+A comma separated list of the developers who integrated the algorithm code as
+a compliant cishell algorithm.
+
+\subsection*{documentation\_url}
+A URL to relevant documentation for the algorithm.
+
+\subsection*{reference}
+A formal reference to a paper explaining the abstract algorithm.
+
+\subsection*{reference\_url}
+A URL to a paper explaining the abstract algorithm.
+
+\subsection*{written\_in}
+A comma separated list of the programming languages used to implement and
+integrate the algorithm code.

Added: trunk/core/org.cishell.docs/src/specification/tex/algorithmtypes.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/algorithmtypes.tex	                        (rev 0)
+++ trunk/core/org.cishell.docs/src/specification/tex/algorithmtypes.tex	2008-01-30 22:32:46 UTC (rev 611)
@@ -0,0 +1,137 @@
+\section{Algorithm Type Specifications}
+
+\subsection*{\textit{Version 1.0}}
+
+\label{algConstraints}
+
+\subsection{Base Algorithm Constraints}
+
+All conformant algorithms regardless of type, must adhere to the following
+constraints:
+
+\subsubsection*{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 legal ``service.pid''.
+\end{itemize}
+
+\subsubsection*{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
+  short human-readable name for the algorithm.
+  \item The algorithm's service metadata should have a ``description''
+  describing what the algorithm does in more detail.
+  \item As much of the informational metadata as possible should be
+  provided. This includes ``authors'', ``implementors'', ``integrators'',
+  ``documentation\_url'', ``reference'', ``reference\_url'', and ``written\_in''.
+\end{itemize}
+
+\subsection{Standard Algorithms}
+
+Standard CIShell algorithms are the algorithms that most end-users will
+encounter. A standard algorithm has the following constraints:
+
+\subsubsection*{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 legal ``service.pid''.
+  \item The algorithm's service metadata must have a ``label'' which is a
+  short human-readable name for the algorithm. This is typically used to label
+  an algorithm for an end-user to see.
+  \item The algorithm's service metadata must have a ``description''
+  describing what the algorithm does in more detail.
+  \item The algorithm's service metadata must have a ``menu\_path'' which is
+  simultaneously a classification and a location on a GUI's menubar to place
+  the algorithm in. See section \ref{algMetaData} for how to format a
+  ``menu\_path''.
+  \item The algorithm's service metadata must not have a ``type'' set.
+\end{itemize}
+
+\subsubsection*{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 ``parentage=default'' if
+  it wishes to use the default \class{Data} parenting scheme described in
+  section \ref{algMetaData}.
+  \item As much of the informational metadata as possible should be
+  provided. This includes ``authors'', ``implementors'', ``integrators'',
+  ``documentation\_url'', ``reference'', ``reference\_url'', and ``written\_in''.
+\end{itemize}
+
+
+\subsection{Converter Algorithms}
+\label{converterAlg}
+
+A converter algorithm is a custom type of CIShell algorithm for converting data
+of one type to another. Converters are typically leveraged by the
+\class{DataConversionService} and are not used directly by end-users. A converter
+algorithm has the following constraints:
+
+\subsubsection*{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 convert 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''.
+  \item The algorithm's service metadata must have ``type=converter''.
+  \item The algorithm's service metadata must have ``conversion=lossy'' if
+  data is lossed during conversion or ``conversion=lossless'' if not.
+\end{itemize}
+
+\subsubsection*{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
+  short human-readable name for the converter, usually with the common name of
+  the input data format and output data format.
+  \item The algorithm's service metadata should have a ``description''
+  describing the conversion in more detail, especially what data may be lossed
+  if ``conversion=lossy''.
+  \item The algorithm's service metadata should have ``implementers'' filled
+  in accordingly.  
+\end{itemize}
+
+\subsection{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
+necessary due to the fact that one cannot simply assume based on the file
+extension what type of file format the data is in. Checking the contents of the
+file is necessary, especially in the case of multiple file formats for the same
+file extension (e.g., XML). A validator algorithm has the following constraints:
+
+\subsubsection*{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
+  type. This must be reflected in the algorithm's service metadata where
+  ``in\_data'' and ``out\_data'' have only one format each with one containing
+  a ``file:'' format and the other a ``file-ext:'' depending on the direction
+  of validation.
+  \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 legal ``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.
+\end{itemize}
+
+\subsubsection*{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 ``implementers'' filled
+  in accordingly.
+\end{itemize}

Modified: trunk/core/org.cishell.docs/src/specification/tex/data.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/data.tex	2008-01-30 19:13:58 UTC (rev 610)
+++ trunk/core/org.cishell.docs/src/specification/tex/data.tex	2008-01-30 22:32:46 UTC (rev 611)
@@ -1,16 +1,17 @@
 \section{Data Specification}
+\label{dataSpec}
 \subsection*{\textit{Version 1.0}}
 \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 data can be any
 Java \class{Object}. The format is a string which is either a full Java class or
-a mime type if it is a \class{java.lang.File}. The mime type corresponds to the
-file's data type and has the following form - ``file:mime/type''. Note that if no
-official mime type is available for a file format, a made up one can be used, but
-must still conform to how mime types are constructed, see \comments{reference to
-mime-type construction}. 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 the \class{DataProperty} interface definition for specific properties to use.
-
+a mime type if it is a \class{java.io.File}. The mime type corresponds to the
+file's data type and has the following form - ``file:\textit{mime/type}''. Note
+that if no official mime type is available for a file format, a made up one can
+be used, but must still conform to how mime types are constructed. See RFCs 3023
+and 4288 for more information on how to construct MIME types. 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 the \class{DataProperty}
+interface definition for specific properties to use.

Modified: trunk/core/org.cishell.docs/src/specification/tex/dataconversionservice.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/dataconversionservice.tex	2008-01-30 19:13:58 UTC (rev 610)
+++ trunk/core/org.cishell.docs/src/specification/tex/dataconversionservice.tex	2008-01-30 22:32:46 UTC (rev 611)
@@ -14,13 +14,12 @@
 \begin{itemize}
   \item \textit{DataConversionService} - The service interface for converting
   data to different formats.
-  \item \textit{Converter Algorithm} - A special type of algorithm which
-  converts data from one format to another.
+  \item \textit{Converter Algorithm} - A special type of algorithm, defined
+  on page \pageref{converterAlg}, which converts data from one format to
+  another.
   \item \textit{Converter} - The interface for a wrapped set of converter
   algorithms returned by the \class{DataConversionService} that will convert
   data from one format to another.
-  \item \textit{Validator} - A special type of converter algorithm which checks
-  a specified file to see if it is a particular file format. 
 \end{itemize}
 
 \section{Data Conversion Service}
@@ -43,71 +42,4 @@
 \label{fig:conversionGraph}
 \end{figure}
 
-\subsection{Converter Algorithms}
-
-A converter algorithm is a standard CIShell algorithm with the following
-constraints: 
-
-\subsubsection*{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 convert 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''.
-  \item The algorithm's service metadata must have ``type=converter''.
-  \item The algorithm's service metadata must have ``conversion=lossy'' if
-  data is lossed during conversion or ``conversion=lossless'' if not.
-\end{itemize}
-
-\subsubsection*{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
-  short human-readable name for the converter, usually with a readable name of
-  the input data format and output data format.
-  \item The algorithm's service metadata should have a ``description''
-  describing the conversion in more detail, perhaps going into what data may be
-  lossed if ``conversion=lossy''.
-\end{itemize}
-
-\subsection{Validator Algorithms}
-
-A validator algorithm is a standard CIShell algorithm which checks either an
-incoming or outgoing file to be sure it is of the type specified. These algorithms
-have the following constraints:
-
-\subsubsection*{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
-  type. This must be reflected in the algorithm's service metadata where
-  ``in\_data'' and ``out\_data'' have only one format each with one containing
-  a ``file:'' format and the other a ``file-ext:'' depending on the direction
-  of validation.
-  \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 legal ``service.pid''.
-  \item The algorithm's service metadata must have ``type=validator''.
-\end{itemize}
-
-\subsubsection*{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
-  short human-readable name for the converter, usually with a readable name of
-  the input data format and output data format.
-  \item The algorithm's service metadata should have a ``description''
-  describing the conversion in more detail, perhaps going into what data may be
-  lossed if ``conversion=lossy''.
-\end{itemize}
-
-\orgcishellserviceconversion{}
+\orgcishellserviceconversion{}
\ No newline at end of file

Modified: trunk/core/org.cishell.docs/src/specification/tex/guibuilderservice.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/guibuilderservice.tex	2008-01-30 19:13:58 UTC (rev 610)
+++ trunk/core/org.cishell.docs/src/specification/tex/guibuilderservice.tex	2008-01-30 22:32:46 UTC (rev 611)
@@ -10,7 +10,7 @@
 addition to this, simple methods for creating warnings, pop-ups, and
 simple yes/no dialog boxes are provided by the GUI Builder Service.
 
-\subseciton{Entities}
+\subsection{Entities}
 
 \begin{itemize}
   \item \textit{GUIBuilderService} - The Service interface for creating
@@ -26,5 +26,6 @@
 \section{GUI Builder Service}
 
 \comments{Needs expanded. Should probably talk about remote GUIs\ldots}
+\comments{Insert a figure of the interaction between the entities\ldots}
 
 \orgcishellserviceguibuilder{}


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.