\section{Model of transitions}
\subsection{Overview of Subject-Specific Configuration: From FIS, Products, States,
Transitions and SQL-statements}

The GNV-system provides several expert information systems (FIS). Within a FIS
users can select products for analysing and visualising different
subject-specific issues like timeseries diagrams and different types of
profiles. In order to generate these products, different kind of data out of the
dataware house is needed.

The configuration is mainly split up into two steps\footnote{Except for
integrating the MapViewer. There is a third step necessary by configuring
additional tables in the datawarehouse}:
\begin{enumerate}
    \item FIS and their according products (Metainformation)
    \item products with their states, transitions, outputs and SQL-statements
    (Implementation)
\end{enumerate}

%% TODO: Add a screenshoot of the GNV WebClient marking GUI elements for FIS,
%% product, states and transitions

Main entry point for the configuration is the file \verb+ conf/conf.xml +
defining the list of FIS and the according products based on the different
datamodels in the datawarehouse. The provided datamodels are:

\begin{enumerate}
    \item ESRI ArcMarineBSH with following subtypes
        \begin{enumerate}
            \item TimeSeriesPoints
            \item MeshFeatures
            \item Measurements/InstantaneousPoints
        \end{enumerate}
    \item ESRI ArcS57,
%% FIXME: Is Marine Feature a subtype of S57 or a model of its own?    
%%    \item Marine Features
    \item CONTIS
\end{enumerate}

Each product configuration consists of a datamodel specific configuration
organized in a product specific folder in \verb+ conf/products+ \footnote{The
special case of a "Horizontales Schnittprofil" is configured in
conf/horizontalprofile/conf\_mesh\_cross.xml }. The directory layout looks
like this:

\begin{verbatim}
products/
|-- horizontalcrosssection
|   `-- conf_mesh.xml
|-- horizontalprofile
|   |-- conf_instantaneouspoint.xml
|   |-- conf_mesh.xml
|   `-- conf_mesh_cross.xml
|-- layer
|   `-- conf.xml
|-- timeseries
|   |-- conf_mesh.xml
|   |-- conf_timeseriespoint.xml
|   `-- timegap_definition.xml
|-- verticalcrosssection
|   `-- conf_mesh.xml
`-- verticalprofile
    |-- conf_instantaneouspoint.xml
    |-- conf_mesh.xml
    `-- conf_timeseriespoint.xml
\end{verbatim}

The subtypes of the ArcMarineBSH based datamodel are configured in the files below:
\begin{itemize}
   \item TimeSeriesPoints: conf\_timeseriespoint.xml
   \item Mesh: conf\_mesh.xml
   \item InstantaneousPoints: conf\_instantaneouspoint.xml
\end{itemize}

Within each of these files, the steps for gathering the values for the
parameterisation are configured by defining states, transitions and outputs
(c.f. \ref{ref:config-a-product}).  The defintion of states, transitions and
outputs reference the actual SQL-statements via identifier. The SQL-statements
are gathered in the file \verb+conf/queries.txt+.


\subsection{General principle of model of transitions}

It is possible to configure the GNV in many ways.
It is possible to add or remove FIS, add or remove Products from a FIS or
to manipulate the steps which must be gone until a product can be create
a diagramm or generate an CSV-Export.

The configuration of the provided FIS are devided in three main parts.

\begin{itemize}
    \item Configuration of the list of FIS via Artifactfactories
    \item Configuration of main Artifacts which will be instantiated if an 
  Artifactfactory was called.
    \item Configuration of the different Artifacts which provides Products which can be 
  served by the FIS.
\end{itemize}

\subsubsection{Configuration of a FIS}
The Point of Enty into the system is to configure an Artifactfactory.
Each Artifactfactory represents one FIS.
It is possible to configure several Artifactfactories.
The Artifactfactories will be configured in the Section 
/artifact-database/artifact-factories of the Configurationfile.

\begin{lstlisting}
<artifact-factory name='fis\_marnet' 
                  description='Factory to create an artifact to be used with the FIS NEWFISNAME'  
                  ttl='3600000' 
                  artifact='de.intevation.artifactdatabase.ProxyArtifact'>
                  de.intevation.gnv.artifacts.GNVProductArtifactFactory
</artifact-factory>
\end{lstlisting}

At this moment the following Attributes of an Artifact-Factory are configurabel.
\begin{itemize}
    \item name: The Name of the Artifact. Must be unique in one Artifact-Server
    \item description: Short description which Job the Artifactfactory has to do.
    \item  ttl: The Time to Live: The Time using Milliseconds an Artifact, created using this 
                factory, can live without any Userinteraction.
    \item artifact: The Name of the Class of the Artifact which should be created.
\end{itemize}

The next listing shows the dependencies between the FIS and the Name
of the Artifactfactory which belongs to it.

\begin{itemize}
    \item Marnet: fis\_marnet
    \item IMIS: fis\_imis
    \item STAUN: fis\_staun
    \item Modeldata fis\_modeldata
    \item Iceclimatology: fis\_eisklimatologie
    \item Ice Station Report: fis\_icestations
    \item SST: fis\_sst
    \item Delphin: fis\_delphin
    \item Thermosalinograph: fis\_thermosalinograph
    \item Chemusurvey: fis\_chemusurvey
    \item GTS: fis\_gts
    \item CTD: fis\_bsh\_ctd
    \item XBT: fis\_bsh\_xbt
    \item SeaCat: is\_seacat
    \item Sea State: fis\_seastate
    \item Current Meter: fis\_currentmeter
    \item Nauthis: fis\_nauthis
    \item Contis: fis\_contis
    \item Marine Features: fis\_marinefeatures
\end{itemize}

\subsubsection{Configuration of main Artifact}
For each Artifact-Factory it is necessary to configure one Artifact which will be 
created using the Factory.
This Artifact is the representation of the specific FIS.
It contains the Configuration which products will be serverd for ths FIS.

The Artifacts are configured in the Section /artifact-database/artifacts of 
the Configurationfile.

\begin{lstlisting}
<artifact name='fis\_marnet'>
    <products>
     ...
    </products>
</artifact>
\end{lstlisting}

The Key is to use the same Name for the Artifact as used for the Artifactfactory.
The Name has to be unique.
In the Section /artifact/products it is possible to define several Products as 
explained in the next Section.

\paragraph{Products to an FIS}
One FIS can provide several Products.
To do this it is required to configure them as shown below in the Section 
/artifact/products

\begin{lstlisting}
<product name= "timeSeries">
      <artifact-factory name="timeSeries" 
                        description="Artiefactfactory for Instantiating the Artifact for TimeSeries on TimeSeriesPoints"  
                        ttl="300000" 
                        artifact="de.intevation.gnv.timeseries.TimeSeriesArtifact">
           de.intevation.gnv.artifacts.GNVArtifactFactory
      </artifact-factory>
      <parameters>
          <parameter name="sourceid" 
                     value="4"/>
          <parameter name="fisname" 
                     value="fis\_marnet"/>
      </parameters>
 </product>
 \end{lstlisting}

Each Product is also represented by an Artifact. To create this Artifact we have to 
use an Artifact-Factory which is configured in each product 
(/product/artifact-factory).

Each Product can have several parameters /product/parameters/parameters.
The Parameter named sourceid and fisname are required Parameters.

The Parameter fisname contains the key to the Name of the FIS. The Key must be 
unique.
The Parameter sourceid contains the key to identify the FIS in the 
DataWareHouse. (MEDIAN.SOURCEINFO)


\subsubsection{Configuration of an Product}
\label{ref:config-a-product}
The Products of the different FIS are also modeled as Artifact-Objects.
The different Products which are currently avaliable are stored in separate
Files in the Folder project.

In those Files the Workflow of each product is configured.  Each step which is
required to model a new Diagramm is represented using a state in the
Configuration-File.

To move between those States it is required to model Transitions which define
between which States it is possible to move and which conditions must be
fulfilled.

The Last step is called OutputState. This State is responsible to generate the
output for the different Formats which can be served from the Product (Diagramm,
CSV, ODV, WMS,...).

\paragraph{States}
A state is one Step which is required to fetch the Data for generating e.g. an
Diagramm.

For example in each Product it is Possible to choose one or more Parameters.

To configure a State you have to use a XML-Fragment as shown below:

\begin{lstlisting}
<state id="timeseries_parameter" description="timeseries_parameter" state="de.intevation.gnv.state.DefaultState">
   <queryID>timeseries_parameter</queryID>
   <dataname>parameterid</dataname>
   <data-multiselect>true</data-multiselect>
   <inputvalues>
      ...
   </inputvalues>
</state>
\end{lstlisting}

At this moment the following Attributes of an Artifact-Factory are configurabel.
\begin{itemize}
    \item id: The Name of the Artifact. Must be unique in one Artifact-Server
    \item description: Short description which Job the Artifactfactory has to do.
    \item queryID: The ID of the Query which should be used to fetch the Data 
                   displayed in this state. //TODO: Reference to queries.properties
    \item dataname: The ID of the Data which will be displaied in this State.
                    The ID will be use to localize the description of the Data.
    \item data-multiselect: true it is possible to select 1 or more Items.
                            false ist is possible to select only one Item.
    \item inputvalues: The Values which can be "feed" to this State and which 
                       will be used as Values in SQL-statements.
\end{itemize}

\paragraph{Input Values of a State}
At Section /state/inputvalues it is possible to add Definitions for InputValues.
Those values have two meanings for the State.

\begin{itemize}
     \item They were used to fill the SQL-Statements to fetch the Data
           (Each entry replace one ore more "?" )
     \item They were used to validate the Inputdata which is "feed" to
           the FIS in the current State
\end{itemize}

WARNING: The Order of the InputValues is significant at which position the Value will
be put into the SQL-Statement.

It is possible to add one InputValue twice or more often to put its value at
different positions of the SQl-Statement.

\begin{lstlisting}
<inputvalues>
    <inputvalue name="featureid" type="Integer" multiselect="false" usedinquery="1"/>
    <inputvalue name="fisname" type="String" multiselect="false" usedinquery="0"/>
    <inputvalue name="parameterid" type="Integer" multiselect="true" usedinquery="0"/>
</inputvalues>
\end{lstlisting}

\begin{itemize}
    \item name: Name of the Value that could be feed or should be used in SQl-statment.
                The name must fit to one dataname configured in this State or one other
                State which was visited before.
    \item type: The type of the Value. This is required for the Validation 
                of the Value.
                This might be String, Integer, Double, Date, Point, LineString, 
                Polygon, Coordinate, Geometry and AttributeName.
    \item multiselect: true if more than on Value can be feed or put into the SQl-statement.
                       false if one on Value will be accepted.
    \item usedinquery: Number how often the value should be put into the SQL-Statement:
                       0: Value will not out into the Statement.
                       1: Value will put once into the Staement,
                       2 or more: Value will be put as often as configured 
                                  into the SQL-Statement (this is useful if 
                                  Inner-Selects are used)
\end{itemize}

The next part will explain the usage of inputvalues.

This SQL-statment is configured to use in the State above.

\begin{lstlisting}
SELECT DISTINCT 
       p.PARAMETERID KEY, 
       p.GERMANNAME || '  ['|| p.UNIT ||']' VALUE, 
       p.GERMANNAME 
FROM MEDIAN.PARAMETER P, 
     MEDIAN.TIMESERIES TS, 
     MEDIAN.TIMESERIESVALUE TSV, 
     MEDIAN.MEASUREMENT M, 
     MEDIAN.TIMESERIESPOINT TSP 
WHERE M.FEATUREID = TSP.FEATUREID AND 
      M.MEASUREMENTID = TSV.MEASUREMENTID AND 
      TS.TIMESERIESID = TSV.TIMESERIESID AND 
      P.PARAMETERID = TS.PARAMETERID AND 
      TSP.FEATUREID = ? 
ORDER BY P.GERMANNAME
\end{lstlisting}

If there are put the Inputvalues in it it will look like this
if we assume that the inputvalues has got the following values:
\begin{itemize}
    \item featureid: 4 (Marnet)
    \item fisname: fis\_marnet
    \item parameterid: not set because it's the value that should be 
                       chosen in this state. 
\end{itemize}

\begin{lstlisting}
SELECT DISTINCT 
       p.PARAMETERID KEY, 
       p.GERMANNAME || '  ['|| p.UNIT ||']' VALUE, 
       p.GERMANNAME 
FROM MEDIAN.PARAMETER P,  
       MEDIAN.TIMESERIES TS, 
       MEDIAN.TIMESERIESVALUE TSV, 
       MEDIAN.MEASUREMENT M, 
       MEDIAN.TIMESERIESPOINT TSP  
WHERE M.FEATUREID = TSP.FEATUREID AND 
      M.MEASUREMENTID = TSV.MEASUREMENTID AND 
      TS.TIMESERIESID = TSV.TIMESERIESID AND 
      P.PARAMETERID = TS.PARAMETERID AND 
      TSP.FEATUREID = 4 
ORDER BY P.GERMANNAME
\end{lstlisting}

The value of featureid will be inserted into the Query because
the Attribute usedinquery is set to "1".

The values of the inputvalues fisname and parameterid will be
excluded because the Attribute usedinquery is set to "0"


If the Attribute usedinquery of the inputvalue featureid is set to "2"
this might happen.

\begin{lstlisting}
<inputvalues>
    <inputvalue name="featureid" type="Integer" multiselect="false" usedinquery="2"/>
    <inputvalue name="fisname" type="String" multiselect="false" usedinquery="0"/>
    <inputvalue name="parameterid" type="Integer" multiselect="true" usedinquery="0"/>
</inputvalues>
\end{lstlisting}


\begin{lstlisting}
SELECT DISTINCT 
    ...
    TSP.FEATUREID = ? AND
    TSP.FEATUREID = ? 
 ORDER BY P.GERMANNAME
\end{lstlisting}

This SQL-statement will be modified to

\begin{lstlisting}
SELECT DISTINCT 
    ...
    TSP.FEATUREID = 4 AND
    TSP.FEATUREID = 4 
ORDER BY P.GERMANNAME
\end{lstlisting}


If the Attribute usedinquery of the inputvalue fisname additionally is set to "1"
this might happen.

\begin{lstlisting}
<inputvalues>
    <inputvalue name="featureid" type="Integer" multiselect="false" usedinquery="2"/>
    <inputvalue name="fisname" type="String" multiselect="false" usedinquery="1"/>
    <inputvalue name="parameterid" type="Integer" multiselect="true" usedinquery="0"/>
</inputvalues>
\end{lstlisting}


\begin{lstlisting}
 SELECT DISTINCT 
    ...
    TSP.FEATUREID = ? AND
    TSP.FEATUREID = ? AND
    NOCOLUMNINDB  = ?
ORDER BY P.GERMANNAME
\end{lstlisting}

This SQL-statement will be modified to

\begin{lstlisting}
SELECT DISTINCT 
    ...
    TSP.FEATUREID = 4 AND
    TSP.FEATUREID = 4 AND
    NOCOLUMNINDB  = 'fis\_marnet' 
ORDER BY P.GERMANNAME
\end{lstlisting}


\paragraph{Transitions}

To move between two States it is necessary to configure dependencies between
the different States.
This dependencies are called. Transitions.

There are different Kind of Transitions which can be used.
\begin{itemize}
  \item Transitions which only link two States
  \item Transition which link two States with a aditional Condition. 
        (e.g. If a region was selected in the Regionfilter or not )
\end{itemize}

The listing below shows a Transition with an additional Condition.
\begin{lstlisting}
<transition transition="de.intevation.gnv.transition.ValueCompareTransition">
    <from state="timeseries_area"/>
    <to state="timeseries_without_geom"/>
    <condition inputvalue="areaid" value="n/n" operator="equal"/>
</transition>
\end{lstlisting}

\begin{itemize}
  \item from: The ID of the State which you have to come from
  \item to:   The ID of the State which can be reached.
  \item condition: The Condition which have to be fulfilled.
\end{itemize}

\paragraph{Outputstate}

The OutputState is an special State which was created to define
the different possibilities of Outputs for each Product.
An OutputState is handled as an State which is described above.
Additionally you are able to configure which kind of outputs should
be provided.

There are several OutputStates. Each one is designed to create 
the output for one special Product (Verticalprofile, TimeSeries,...)

//TODO: Listing of each OutputStates?

You can configure an OutputState as shown below:

\begin{lstlisting}
<state id="timeseries_calculate_results" description="timeseries_interval" state="de.intevation.gnv.state.timeseries.TimeSeriesOutputState">
    <queryID>timeseries_chart_data</queryID>
     ...
    <outputsModes>
        <outputsMode name="chart" description="Chartrepresentation of the Values" mime-type="image/png">
        ...
        </outputsMode>
    </outputsModes>
 </state>
\end{lstlisting}

At Section /state/outputsModes it is possible to add one ore more OutputModes
to one State as shown in the next Paragraph.

\paragraph{OutputModes}

It is possible to configure several OutputModes in one OutputState.
Inserting or deleting the Configuration of an special
OutputMode will cause that the pending Item will be shown or hidden 
in the GUI.

WARNING: IT MIGHT BE POSSIBLE THAT ONE OR MORE OUTPUTMODES ARE NOT
         SUPPORTED BY AN PRODUCT. IN THAT CASE IT IS NECESSARY TO
         IMPLEMENT THE REQUIRED FUNCTIONALITY BEFORE IT IS POSSIBLE
         TO OFFER THIS OUTPUTMODE.

Currently the following outputmodes are supported:

\begin{itemize}
   \item chart
   \item histogram
   \item csv
   \item odv
   \item statistics
   \item wms
   \item shapefile
\end{itemize}

The following Example shows the Configuration for the OutputMode Chart.

\begin{lstlisting}
<outputsMode name="chart" description="Chartrepresentation of the Values" mime-type="image/png">
    <parameters>
        <inputvalue name="width" type="Integer" value="600"/>
        <inputvalue name="height" type="Integer" value="400"/>
        <inputvalue name="points" type="Boolean" value="false"/>
    </parameters>
    <exportModes>
        <export name="img" description="IMG-Export der Daten" mime-type="image/png" />
        <export name="pdf" description="PDF-Export der Daten" mime-type="application/pdf" />
        <export name="svg" description="SVG-Export der Daten" mime-type="image/svg+xml" />
      </exportModes>
</outputsMode>
\end{lstlisting}

// TODO add simple OutputMode e.g. for CSV??

\begin{itemize}
   \item name: The name of the Mode. This must not be changed because it is used 
               by the Programm.
   \item description: a short description of this OutputMode. 
   \item parameters: one ore more parameters which will be shown in the GUI e.g. 
                     for changing the Size of an Chart.
   \item exportModes: one or more formats which can be served.
\end{itemize}


\subsection{Adding a new FIS}
In this Section it will be explained which steps has to be done to integrate a
new FIS into the Artifact-Server.  This will be done using the Configuration for
an FIS which use data from MEDIAN.TIMESERIES Section of the DataWareHouse e.g.
MARNET or STAUN

Pay attention that for publishing the Changes to the Artifact-Server you will 
have to restart it. 

\subsubsection{Adding a new Artifactfactory}
First step is to add a new Artifactfactory to the Configuration conf/conf.xml
To do this you have to add a new XML-Fragment into the Section 
/factories/artifact-factories  which look like that:

\begin{lstlisting}
<artifact-factory name='fis\_NEWFISNAME' 
                  description='Factory to create an artifact to be used with the FIS NEWFISNAME'  
                  ttl='3600000' 
                  artifact='de.intevation.artifactdatabase.ProxyArtifact'>
                  de.intevation.gnv.artifacts.GNVProductArtifactFactory
</artifact-factory>
\end{lstlisting}
 
In this XML-Fragment you only have to replace the placeholder NEWFISNAME with a 
unique short Name for the new FIS.

\subsubsection{Adding a new Artifact for Artifactfactory}
The next Step is to define the Artifact itself.
For this it is necessary to add an XML-Fragment into the Section /artifacts of 
the main Configuration-File /conf/conf.xml
\begin{lstlisting}
<artifact name='fis\_NEWFISNAME'>
    <products>
     ...
    </products>
</artifact>
\end{lstlisting}

In this XML- Fragment it is also required to replave the placeholder NEWFISNAME 
with the name which was used to configure the Artifact-Factory.

Now the ArtifactServer can serv an additional FIS without any Products yet.

To prevent needless Configuration-Work it is useful way to clone an Artifact 
which handle the same Kind of work as the new FIS.

\subsubsection{Adding removing Products to the specific Artifact}
Now it is Time to configure the different Products which the FIS should be able 
to provide.
To do this it is necessary to Copy the XML-Fragments of the products into the
XML-Element <products> of the previously integrated Artifact.
\begin{lstlisting}
<artifact name='fis\_NEWFISNAME'>
     <products>
         <product name= "timeSeries">
              <artifact-factory name="timeSeries" 
                                description="Artiefactfactory for Instantiating the Artifact for TimeSeries on TimeSeriesPoints"  
                                ttl="300000" 
                                artifact="de.intevation.gnv.timeseries.TimeSeriesArtifact">
                  de.intevation.gnv.artifacts.GNVArtifactFactory
              </artifact-factory>
              <parameters>
                  <parameter name="sourceid" 
                             value="VALUEOFSOURCEID"/>
                  <parameter name="fisname" 
                             value="fis\_NEWFISNAME"/>
              </parameters>
          </product>
          <product name= "verticalProfile">
              <artifact-factory name="verticalProfile" 
                                description="Artiefactfactory for Instantiating the Artifact for Verticalprofiles on TimeSeriesPoints"  
                                ttl="300000" 
                                artifact="de.intevation.gnv.profile.vertical.VerticalProfileArtifact">
                  de.intevation.gnv.artifacts.GNVArtifactFactory
              </artifact-factory>
              <parameters>
                  <parameter name="sourceid" 
                             value="VALUEOFSOURCEID"/>
                  <parameter name="fisname" 
                             value="fis\_NEWFISNAME"/>
              </parameters>
          </product>
     </products>
</artifact>
\end{lstlisting}

In this XML-Fragment you have to replace the placeholders NEWFISNAME as before 
and VALUEOFSOURCEID with the value for the new FIS as defined in the Table 
MEDIAN.SOURCEINFO.

\subsubsection{Putting SourceID to specific Artifact}
\subsection{Adding a new Product}
To add a new Product to the System it is necessary that the required 
Artifactrepresentation is Implemented in the SourceCode.
Without doing that step it is not possible to create a new Product.

All Products are configured in separate Files that will be included into the 
Mainconfiguration using Xlink-References.

First Step is to create a new File in the Folder products and there in the 
subfolder where the Product belongs to (timeseries,verticalprofile,
horizontalprofile,horizontalcrosssection,layer,...)

Then you have tor reference this File in the File /conf/conf.xml in the Section 
/artifacts using the following XML-Fragment.

\begin{lstlisting}
<artifact name="timeSeries" 
          xmlns:xlink="http://www.w3.org/1999/xlink" 
          xlink:href="${artifacts.config.dir}/products/PATHTOFILE" /> 
\end{lstlisting}

The placeholder PATHTOFILE has to be replaced with the relative Path and the 
Name of the File starting in the Folder products.  

Then it is possible to add the product to a FIS as explained in the next section.
Please note that the defined Name of the ArtifactFactory has to match to the 
Name of the added Products which is also designed as an Artifact.

\subsection{Adding a additional Product to a FIS}
To add a additional Product to a FIS you only have to add the XML-Fragment which 
represents the product to the Artifact-configuration of the FIS in Section 
/artifacts/artifact/products.

\begin{lstlisting}
 <product name= "timeSeries">
     <artifact-factory name="timeSeries" 
                       description="Artiefactfactory for Instantiating the Artifact for TimeSeries on TimeSeriesPoints"  
                       ttl="300000" 
                       artifact="de.intevation.gnv.timeseries.TimeSeriesArtifact">
          de.intevation.gnv.artifacts.GNVArtifactFactory
     </artifact-factory>
     <parameters>
         <parameter name="sourceid" 
                    value="VALUEOFSOURCEID"/>
         <parameter name="fisname" 
                    value="fis\_NEWFISNAME"/>
     </parameters>
 </product>
 \end{lstlisting}

Please note that you have to replace the Placeholders as explained above.