cishell-svn

[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.

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

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

Revision: 647
          http://cishell.svn.sourceforge.net/cishell/?rev=647&view=rev
Author:   bh2
Date:     2008-03-06 10:05:47 -0800 (Thu, 06 Mar 2008)

Log Message:
-----------
* added rgb: metatype extension
* first pass on "User-Adjustable Preferences Specification"
* first pass on in/out_data extensions

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/guidefinition.tex
    trunk/core/org.cishell.docs/src/specification/tex/osgidependencies.tex
    trunk/core/org.cishell.docs/src/specification/tex/preferencesservice.tex

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

Modified: trunk/core/org.cishell.docs/src/specification/main.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/main.tex	2008-03-06 16:46:25 UTC (rev 646)
+++ trunk/core/org.cishell.docs/src/specification/main.tex	2008-03-06 18:05:47 UTC (rev 647)
@@ -41,6 +41,7 @@
 \input{./tex/algorithmtypes.tex}
 \input{./tex/data.tex}
 \input{./tex/guidefinition.tex}
+\input{./tex/useradjustableprefs.tex}
 \orgcishellframework{}
 \orgcishellframeworkalgorithm{}
 \orgcishellframeworkdata{}

Modified: trunk/core/org.cishell.docs/src/specification/tex/algorithms.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/algorithms.tex	2008-03-06 16:46:25 UTC (rev 646)
+++ trunk/core/org.cishell.docs/src/specification/tex/algorithms.tex	2008-03-06 18:05:47 UTC (rev 647)
@@ -78,33 +78,42 @@
 \end{description}
 \end{quote}
 
-\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. There
-are several valid strings for each data format. If a Java \class{Object} is
-expected, use the expected full Java class as a string. If a \class{java.io.File}
-is expected, use a string with the format ``file:\textit{mime/type}''. If a
-\class{java.io.File} known only by file extension is expected (only applicable
-for validator algorithms), a string with the format
-``file-ext:\textit{file-extension}''. If no \class{Data} inputs are necessary
-then the string ``null'' or not specifying the in\_data attribute at all is
-valid. See section \ref{dataSpec} for more information on data format formatting.
 
+\subsection*{parameters_pid}
+\comments{Still need to define\ldots may play a bigger role than previously
+though\ldots}
+
+
+\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.
+
 \begin{quote}
 \begin{description}
   \item[Example 1:] in\_data = null
   \item[Example 2:] in\_data = java.lang.String
   \item[Example 3:] in\_data = java.lang.String, file:text/plain, file:text/xml
   \item[Example 4:] in\_data = file-ext:xml
+  \item[Example 5:] in\_data = +file:text/plain, *file:text/xml,
+  ?java.lang.String
+  \item[Example 6:] in\_data = ?my.package.SpecialClass
 \end{description}
 \end{quote}
 
 
 \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.
+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.
 
 \begin{quote}
 \begin{description}
@@ -112,9 +121,13 @@
   \item[Example 2:] out\_data = java.lang.String
   \item[Example 3:] out\_data = java.lang.String, file:text/plain, file:text/xml
   \item[Example 4:] out\_data = file-ext:csv
+  \item[Example 5:] out\_data = +file:text/plain, *file:text/xml,
+  ?java.lang.String
+  \item[Example 6:] out\_data = ?my.package.SpecialClass
 \end{description}
 \end{quote}
 
+
 \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

Modified: trunk/core/org.cishell.docs/src/specification/tex/data.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/data.tex	2008-03-06 16:46:25 UTC (rev 646)
+++ trunk/core/org.cishell.docs/src/specification/tex/data.tex	2008-03-06 18:05:47 UTC (rev 647)
@@ -4,14 +4,33 @@
 \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.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\footnote{http://tools.ietf.org/html/rfc3023} and
-4288\footnote{http://tools.ietf.org/html/rfc4288} 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.
+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
+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
+the \class{DataProperty} interface definition for specific properties to use.
+
+\subsection{Data Format Specification}
+
+Data formats are used by algorithms specifying what \class{Data} items are
+consumed/producted and \class{Data} objects must know what the format of its
+contained real data is. This format is simply a string that says what the
+format of the real data is. If the real data is a \class{java.io.File}, use a
+MIME type\footnote{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 (http://tools.ietf.org/html/rfc3023) and 4288
+(http://tools.ietf.org/html/rfc4288).} prefixed by ``file:'', i.e.,
+``file:\textit{mime/type}''. If the real data is a \class{java.io.File} known
+only by file extension (only applicable for validator algorithms), use the format
+``file-ext:\textit{file-extension}''. Otherwise, if the real data is a Java
+\class{Object}, use the full Java class as a string, i.e., ``java.lang.String''
+or ``my.package.SpecialClass''.
+
+To specify that a single \class{Data} object contains one or more
+sub-\class{Data} objects of a single format, prefix the type with a ``+''. For
+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.

Modified: trunk/core/org.cishell.docs/src/specification/tex/guidefinition.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/guidefinition.tex	2008-03-06 16:46:25 UTC (rev 646)
+++ trunk/core/org.cishell.docs/src/specification/tex/guidefinition.tex	2008-03-06 18:05:47 UTC (rev 647)
@@ -47,3 +47,9 @@
 An AD with type ``string'' and default value ``password:'' will receive a string
 corresponding to the entered password.
 
+\subsubsection*{rgb:} 
+An AD with type ``string'' and default value ``rgb:'' will
+receive a string which is a comma separated list that corresponds to the RGB
+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.

Modified: trunk/core/org.cishell.docs/src/specification/tex/osgidependencies.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/osgidependencies.tex	2008-03-06 16:46:25 UTC (rev 646)
+++ trunk/core/org.cishell.docs/src/specification/tex/osgidependencies.tex	2008-03-06 18:05:47 UTC (rev 647)
@@ -21,14 +21,16 @@
   Service Specification,'' this service is used as a universal preference
   storage system for algorithms and services. See chapter \ref{preferencesService} for
   more details.
-  \item[Configuration Admin Service] \comments{More details when the expanded
-  prefs spec is done\ldots}
+  \item[Configuration Admin Service] as described in OSGi section 104
+  ``Configuration Admin Service Specification,'' this service is used as a
+  manager/provider of configuration information for bundles and services. It is 
+  very useful for meeting the User Adjustable Preferences (section
+  \ref{userPrefsSpec}) requirements.
 \end{description}
 
 \subsection*{Recommended Services}
 \begin{description}
-  
   \item[Declarative Services] as described in OSGi section 112 ``Declarative
   Services Specification,'' this service can be used by CIShell algorithms to
-  simplify algorithm service registration and for finding necessary auxilary services.\item[]
+  simplify algorithm service registration and for finding necessary auxilary services.
 \end{description}

Modified: trunk/core/org.cishell.docs/src/specification/tex/preferencesservice.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/preferencesservice.tex	2008-03-06 16:46:25 UTC (rev 646)
+++ trunk/core/org.cishell.docs/src/specification/tex/preferencesservice.tex	2008-03-06 18:05:47 UTC (rev 647)
@@ -5,10 +5,12 @@
 
 CIShell requires OSGi's standard \class{PreferencesService} to be installed in a
 CIShell-compliant system. This gives both the algorithms and the applications
-built on CIShell a standard preferences storage sytem to use. This service has
-not been extended or modified. More information about the
-\class{PreferencesService} is available in the OSGi Service Platform Service
-Compendium Specification R4, section 106 under ``Preferences Service
-Specification.''
-
-\comments{Upcoming preferences w/ gui system spec goes here\ldots}
+built on CIShell a standard preferences storage system to use. It is used mainly
+as a storage mechanism for data that is not necessarily adjustable by end-users.
+Things like, last opened file, recently opened files, or any sort of data that
+may need to be saved between sessions. This service has not been modified or
+extended. More information about the \class{PreferencesService} is available in
+the OSGi Service Platform Service Compendium Specification R4, section 106 under
+``Preferences Service Specification.'' Algorithm developers wishing to expose
+user-adjustable preferences, should refer to section \ref{userPrefsSpec} for
+more information on this separate task.

Added: trunk/core/org.cishell.docs/src/specification/tex/useradjustableprefs.tex
===================================================================
--- trunk/core/org.cishell.docs/src/specification/tex/useradjustableprefs.tex	                        (rev 0)
+++ trunk/core/org.cishell.docs/src/specification/tex/useradjustableprefs.tex	2008-03-06 18:05:47 UTC (rev 647)
@@ -0,0 +1,60 @@
+\section{User Adjustable Preferences Specification}
+\label{userPrefsSpec}
+\subsection*{\textit{Version 1.0}}
+\subsection{Introduction}
+
+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 the algorithm parameters returned from
+\class{AlgorithmFactory.createParameters}. For storing data that is not directly
+end-user adjustable, see chapter \ref{preferencesService}.
+
+\subsection{Publishing User Adjustable Preferences}
+
+\subsubsection*{Create an ObjectClassDefinition (OCD)} To define parameters that
+can be adjusted by an end-user, an algorithm developer must first create an
+\class{ObjectClassDefinition} which details the parameters to be published. This
+OCD must be visible to the \class{MetaTypeService} either through the use of a
+METADATA.XML file or by the service implementing \class{MetaTypeProvider} and
+\class{ManagedService}. See section \ref{GUISpec} for more information.
+
+\subsubsection*{Designate a Persistent ID (PID) for the OCD} 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 wish.
+
+\subsubsection*{Designate 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
+``param-defaults'' for algorithm parameter defaults.
+
+\subsubsection*{Algorithm Parameter Defaults} 
+By publishing algorithm parameter defaults, algorithm developers allow
+end-users to adjust the default values they see when running their algorithm.
+This is typically accomplished by wrapping the created MetaTypeProvider
+returned from AlgorithmFactory.createParameters with overridden
+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
+\class{org.\-osgi.\-service.\-cm.\-ManagedService} and set in their service
+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
+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
+``Bundle-Version'' id analagous to local preference's) from their OCD's ADs
+prefixed by the PID of the published global preference. In this way, all global
+preferences published in the system will be available to anyone receiving
+preference data. Note that one does not have to publish any preferences to
+receive just global preference data.


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