\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 to improve: Add a Screenshot of the GNV WebClient marking GUI elements for FIS,
%% product, states and transitions

Main entry point for the configuration also is the file {\tt 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
            \item Marine Features
        \end{enumerate}
    \item ESRI ArcS57,
    \item CONTIS
\end{enumerate}

Each product configuration consists of a datamodel specific configuration
organized in a product specific folder in {\tt conf/products} \footnote{The
special case of a {\tt Horizontales Schnittprofil} is configured in
{\tt 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: {\tt conf\_timeseriespoint.xml}
   \item Mesh: {\tt conf\_mesh.xml}
   \item InstantaneousPoints: {\tt 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 definition of states, transitions and
outputs reference the actual SQL-statements via an identifier. The SQL-statements
are gathered in the file {\tt conf/queries.properties}.


\subsection{Background information of the XML configuration}

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 prepared until products like
a diagram or CSV-export can be generated.

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

\begin{itemize}
    \item Configuration of the list of FIS via {\tt artifact-factories}
    \item Configuration of main {\tt artifacts} which will be instantiated if an 
  {\tt artifact-factory} was called.
    \item Configuration of the different {\tt artifacts} which provides products which can be 
  served by the FIS.
\end{itemize}

\subsubsection{Configuration of a FIS}
The point of entry into the system is to configure an {\tt artifact-factory}.
Each artifact-factory represents one FIS.
It is possible to configure several {\tt artifact-factories}, which
represent the list of FIS in GUI.
The {\tt artifact-factories} will be configured in the section 
\texttt{/artifact-database/artifact-factories} of the configuration-file.

\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}

At this moment the following attributes of an {\tt artifact-factory} are
configurable:
\begin{itemize}
    \item {\tt name}: The name of the {\tt artifact}. Must be unique in one {\tt artifact-server}
    \item {\tt description}: Short description which job the {\tt artifact-factory} has to do.
    \item {\tt ttl}: The time to live: The time using milliseconds an
    {\tt artifact}, created using this factory, can live without any
    user-interaction.
    \item {\tt artifact}: The name of the class of the {\tt artifact} which should be created.
\end{itemize}

The next listing shows the dependencies between the FIS and the name
of the {\tt artifact-factory} which belongs to it.

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

\subsubsection{Configuration of main Artifact}
For each {\tt artifact-factory} it is necessary to configure one {\tt artifact} which will be 
created using the factory.
This {\tt artifact} is the representation of the specific FIS.
It contains the configuration which products will be served for this FIS.

The {\tt artifacts} are configured in the section {\tt /artifact-database/artifacts} of 
the configurationfile.

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

The key is to use the same name for the {\tt artifact} as used for the {\tt artifact-factory}.
The name has to be unique.
In the section {\tt /artifact/products} it is possible to define several products as 
explained in the next section.

\subsection{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 
{\tt /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 {\tt product} is also represented by an {\tt artifact}. In order to
create this {\tt artifact}, the {\tt artifact-factory} has to be used.
It is configured in each product 
({\tt /product/artifact-factory}).

Each product can have several parameters ({\tt
/product/parameters/parameters}).  The {\tt parameter} named {\tt
sourceid} and {\tt fisname} are required parameters.

The parameter {\tt fisname} contains the key to the name of the FIS. The
key must be unique.  The parameter {\tt sourceid} contains the key to
identify the FIS in the datawarehouse. ({\tt MEDIAN.SOURCEINFO})


\subsubsection{Configuration of an Product}
\label{ref:config-a-product}
The {\tt products} of the different FIS are also modeled as artifact-objects.
The different products which are currently available are stored in separate
files in the folder {\tt project}.

In those files the workflow of each product is configured.  Each step which is
required to model a new diagram is represented using a {\tt state} in the
configuration-file.

%% FIXME: fix wording
To move between those {\tt states} it is required to model {\tt transitions} which define
between which states it is possible to move and which conditions must be
fulfilled.

The last step is called {\tt output-state}. This state is responsible to generate the
output for the different formats which can be served from the product ({\tt Diagram,
CSV, ODV, WMS,..}.).

\paragraph{States}
A {\tt state} is one step which is required to fetch the data for generating e.g. an
diagram.

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 {\tt state} are configurable.
\begin{itemize}
    \item {\tt id}: The name of the artifact. Must be unique in one artifact-server
    \item {\tt description}: Short description which job the artifact-factory has to do.
    \item {\tt queryID}: The id of the query which should be used to fetch the data 
                   displayed in this state. All queries are defined in the file
                   conf/queries.properties
    \item {\tt dataname}: The id of the data which will be displayed in this state.
                    The id will be use to localize the description of the data.
                    The localization is located in module gnv-artifacts in folder
                    src/main/resources.
    \item {\tt data-multiselect}: {\tt true} it is possible to select 1 or more items.
                                 {\tt false} it is possible to select only one item.
    \item {\tt 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 {\tt /state/inputvalues} it is possible to add definitions for inputvalues.
Those values have two meanings for the {\tt 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}

{\bf WARNING: The order of the input-values 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 {\tt 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 {\tt 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. \\
                Coordinate is a format which accepts geographical coordinates in 
                the following Syntax: 56n30 6e20 \\
                AttributeName marks a stringvalue which will be used in 
                SQL-statement without surrounding with "'" in the statement.
                Usage is e.g. for determining the Axis (i or j) in the workflow
                of Horizontalprofiles.
    \item {\tt 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 {\tt 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 statement,
                       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-statement is configured to use in the state above, which will fetch
all parameter-ids with the according german name which are reffered to the given
TimeSeriesPoint (e.g.Arkona Basin Buoy FeatureID = 100011 )

 
\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}

Including inputvalues, the example for choosing the FIS ({\tt fisname})
and the Station 342 ({\tt featureid}: Arkona Basin Buoy) will look like
this: 
\begin{itemize}
    \item {\tt featureid}: 100011 (Marnet $\rightarrow$ Arkona Basin Buoy)
    \item {\tt fisname}: fis\_marnet
    \item {\tt 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 = 100011
ORDER BY P.GERMANNAME
\end{lstlisting}

The value of {\tt featureid} will be inserted into the query because
the attribute {\tt usedinquery} is set to "1".

The values of the inputvalues {\tt fisname} and {\tt parameterid} will be
excluded because the attribute {\tt usedinquery} is set to "0"


If the attribute {\tt usedinquery} of the inputvalue {\tt 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 = 100011 AND
    TSP.FEATUREID = 100011 
ORDER BY P.GERMANNAME
\end{lstlisting}


At the next step of the workflow it is nessesary to determine all depths where
the choosen parameters are measured.
To do this we might have the following inputvalues:

\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="1"/>
    <inputvalue name="measurementid" type="Integer" multiselect="true" usedinquery="0"/>
</inputvalues>
\end{lstlisting}

\begin{itemize}
   \item {\tt featureid}: 100011 (Marnet $\rightarrow$ Arkona Basin Buoy)
   \item {\tt fisname}: fis\_marnet
   \item {\tt parameterid}: 2 (Salzgehalt [pSal])
   \item {\tt measurementid}: not set because it's the value that should be
                        chosen in this state.
\end{itemize}

\begin{lstlisting}
SELECT DISTINCT 
       M.MEASUREMENTID KEY, 
       M.ZLOCATION VALUE, 
       P.PARAMETERID PARAMETERID 
FROM MEDIAN.MEASUREMENT M, 
     MEDIAN.TIMESERIESVALUE TSV, 
     MEDIAN.TIMESERIES T, 
     MEDIAN.PARAMETER P 
WHERE M.MEASUREMENTID = TSV.MEASUREMENTID AND 
      TSV.TIMESERIESID = T.TIMESERIESID AND 
      T.PARAMETERID = P.PARAMETERID AND 
      M.FEATUREID = ? AND 
      M.FEATUREID = ? AND 
      P.PARAMETERID IN (?)
ORDER BY m.ZLOCATION DESC
\end{lstlisting}

This SQL-statement will be modified to

\begin{lstlisting}
SELECT DISTINCT 
       M.MEASUREMENTID KEY, 
       M.ZLOCATION VALUE, 
       P.PARAMETERID PARAMETERID 
FROM MEDIAN.MEASUREMENT M, 
     MEDIAN.TIMESERIESVALUE TSV, 
     MEDIAN.TIMESERIES T, 
     MEDIAN.PARAMETER P 
WHERE M.MEASUREMENTID = TSV.MEASUREMENTID AND 
      TSV.TIMESERIESID = T.TIMESERIESID AND 
      T.PARAMETERID = P.PARAMETERID AND 
      M.FEATUREID = 100011 AND 
      M.FEATUREID = 100011 AND 
      P.PARAMETERID IN (2)
ORDER BY m.ZLOCATION DESC
\end{lstlisting}

The queries which are shown above are configurable.
Configuring takes place in the \\ file \texttt{queries.properties } which will
be explained in the next paragraph.

\paragraph{Query-configuration (queries.properties)}
\label{ref:queries.properties}

This file contains key-value-pairs to define SQL-statements.
All queries will be handle using the prepared-statement-syntax using "?"
to define a place where an dynamic value should be placed into the statement.
 
There is one special implementation to support spatial access to the 
{\tt ESRI ArcSDE}-database. This mechanism is used to realize the access to spatial-
objects.

All queries containing the following literals will be handled separatly
using the ESRI ArcSDE-API.

\begin{itemize}
    \item {\tt ST\_ASTEXT(SHAPE)}: Will return the geometry as an WellKnowText (WKT)
    \item {\tt ST\_ASTEXT(RASTER)}: Will return the raster in an readable way.
    \item {\tt INTERSECTS(SHAPE,"?")}: Will only return the elements which geometry
                                 intersects the given geometry ("?" will be
                                 replace with an WKT)
\end{itemize}


\paragraph{Transitions}

To move between two states it is necessary to configure dependencies
between the different states.  This dependencies are called {\tt
transitions}.

There are different kinds of {\tt transitions} which can be used.
\begin{itemize}
  \item Transitions which only link two states
  \item Transition which link two states with a additional 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 {\tt from}: The {\tt id} of the {\tt state} which you have to come from
  \item {\tt to}:   The {\tt id} of the {\tt state} which can be reached.
  \item {\tt condition}: The condition which have to be fulfilled.
\end{itemize}

At this moment only {\tt EQUAL} and {\tt NOTEQUAL} are supported as 
{\tt condition} for an {\tt ValueCompare\-Transition}.

\paragraph{Outputstate}

The {\tt outputstate} is a special {\tt state} which was created to define
the different possibilities of outputs for each product.
An {\tt outputstate} is handled as a {\tt state} which is described above.
Additionally you are able to configure which kind of outputs should
be provided.

There are several {\tt outputstates}. Each one is designed to create 
the output for one special product.

\begin{itemize}
  \item TimeSeries: {\tt TimeSeriesOutputState}
  \item Horizontalprofile: {\tt HorizontalProfileOutputState}
  \item Horizontalprofile on Meshes: {\tt HorizontalProfileMeshOutputState}
  \item Verticalcrosssection: {\tt VerticalCrossSectionOutputState}
  \item Verticalprofiles: {\tt VerticalProfileOutputState}
  \item Horizontalcrosssections: {\tt HorizontalCrossSectionMeshOutputState}
  \item Layer: {\tt LayerOutputState}
\end{itemize}

All these outputstates are implemented in {\tt package de.intevation.gnv.state}
and its {\tt sub\-packages}. 

The fullqualified name of the {\tt outputstate} to the attribute 
{\tt state} is shown below.

An example for an {\tt outputstate}:

\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 {\tt /state/outputsModes} it is possible to add one ore more 
{\tt outputmodes} to one state as shown in the next paragraph.

\paragraph{OutputModes}

It is possible to configure several {\tt outputmodes} in one {\tt outputstate}.
Inserting or deleting the configuration of a special
{\tt outputmode} will control if an item in the GUI will be displayed.

{\bf
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 {\tt outputmodes} are supported:

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

The following example shows how to configure an {\tt 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}


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


\section{Adding a new FIS}
In this section it will be explained which steps have to be done to integrate a
new FIS into the {\tt artifact-server}.  This will be done using the configuration for
a FIS which uses data from the table {\tt MEDIAN.TIMESERIES} section of
the datawarehouse (e.g. MARNET or STAUN).

For publishing the changes to the {\tt artifact-server}, it needs to be
restarted. 

\subsection{Adding a new Artifact-factory}
First step is to add a new {\tt artifact-factory} 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 {\tt NEWFISNAME}
with a unique short name for the new FIS.

\paragraph*{Example}
This example shows how to add a FIS and illustrates the effect on the
artifact-server's output.

First , the following {\tt artifact-factory} has to be added into the file 
{\tt conf/conf.xml} in section {\tt /artifact-database/artifact-factories} 
adding a new FIS called {\tt justanewfis} to the server:

\begin{lstlisting}
<artifact-factory name='fis_justanewfis' 
                  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}

Restart the {\tt artifact-database} executing:

\begin{lstlisting}
/etc/init.d/artifact-server restart
\end{lstlisting}

Checking if the new FIS is served by the REST-Server
calling the following command:

\begin{lstlisting}
curl http://localhost:8181/factories | xmllint --format - | grep fis_justanewfis
\end{lstlisting}

If the FIS was added, the new {\tt artifact-factory} will be found in the generated 
XML-output. Otherwise no XML-output will be shown.

\subsection{Adding a new Artifact for Artifact-factory}
The next step is to define the artifact itself.
For this it is necessary to add an XML-fragment into the section 
{\tt /artifacts} of the main configurationfile {\tt /conf/conf.xml}.

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

In this XML-fragment it is also required to replace the placeholder {\tt NEWFISNAME}
with the name which was used to configure the {\tt artifact-factory}.

Now the {\tt artifact-server} can handle an additional FIS without any products yet.

To prevent needless configuration-work, it is a useful way to clone an
existing artifact handling the same kind of work.


\paragraph*{Example}
Now will an artifact to the FIS {\tt fis\_justanewfis}, will be configured.

The following XML-fragment has to be added to the file 
{\tt conf/conf.xml} in section {\tt /artifact-database/artifacts}:

\begin{lstlisting}
<artifact name='fis_justanewfis'>
    <products>
    </products>
</artifact>
\end{lstlisting}

Restart the artifact-server

\begin{lstlisting}
/etc/init.d/artifact-server restart
\end{lstlisting}

Now it should be possible to choose the artifact.

The listbox in the GUI would be empty.
\begin{lstlisting}
curl -d "@sample-documents/create-artifact.xml"  http://localhost:8181/create | xmllint --format -
\end{lstlisting}

\subsection{Adding/Removing Products to the Specific Artifact}
Next step is, 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 {\tt products} of the
previously integrated artifact.

\begin{lstlisting}
<artifact name='fis_NEWFISNAME'>
     <products>
         <product name= "timeSeries">
              <artifact-factory name="timeSeries" 
                                description="Artifactfactory 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="Artifactfactory 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 the placeholders {\tt NEWFISNAME} have to be
replaced. The source-id \texttt{VALUEOFSOURCEID} with the value for the new
FIS as defined in the table {\tt MEDIAN.SOURCEINFO} needs to be added.

\paragraph*{Example}
Adding a product to the new FIS, choosing sourceid of an existing FIS
(e.g 4 $\rightarrow$ Marnet).

Add the following XML-fragment to the new artifact.
\begin{lstlisting}
<product name= "timeSeries">
    <artifact-factory name="timeSeries" 
                      description="Artifactfactory 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\_justanewfis"/>
    </parameters>
</product>
\end{lstlisting}

Restart the artifact-server

\begin{lstlisting}
/etc/init.d/artifact-server restart
\end{lstlisting}

If 
\begin{lstlisting}
curl -d "@sample-documents/create-artifact.xml"  http://localhost:8181/create | xmllint --format -
\end{lstlisting}

is called, the product {\tt timeSeries} should be available for the FIS {\tt justanewfis}.
 
Now, it should be able to choose the product.
This product including the definied outputformats should be available in
the GUI.

\subsection{Adding a new Product}
To add a new product to the system it is necessary that the required 
artifact representation is implemented in the {\tt sourcecode}.
Without doing that step it is not possible to create a new product.

All products are configured in separated files that will be included into the 
main configuration using Xlink-references.

First step is to create a new file in the folder {\tt products} and in the 
sub-folder where the product belongs to ({\tt timeseries,verticalprofile,
horizontalprofile,horizontal\-crosssection,layer,...})

Then the new product can be referenced in the file {\tt /conf/conf.xml} in the
section {\tt/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 {\tt 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 {\tt artifact-factory} has to match to the 
name of the added products which is also designed as an artifact.

\subsection{Adding an additional Product to a FIS}
To add an additional product to a FIS the XML-fragment which 
represents the product to the artifact-configuration of the FIS in section
{\tt /artifacts/artifact/products} needs to be added.

\begin{lstlisting}
 <product name= "timeSeries">
     <artifact-factory name="timeSeries" 
                       description="Artifactfactory 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 the placeholders have to be explained above.