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