
tim@906: \section{Model of transitions}
hans@911: \subsection{Overview of Subject-Specific Configuration: From FIS, Products, States,
hans@911: Transitions and SQL-statements}
tim@910: 
hans@911: The GNV-system provides several expert information systems (FIS). Within a FIS
hans@911: users can select products for analysing and visualising different
hans@911: subject-specific issues like timeseries diagrams and different types of
hans@911: profiles. In order to generate these products, different kind of data out of the
hans@911: dataware house is needed.
tim@910: 
hans@911: The configuration is mainly split up into two steps\footnote{Except for
hans@911: integrating the MapViewer. There is a third step necessary by configuring
hans@911: additional tables in the datawarehouse}:
hans@911: \begin{enumerate}
hans@911:     \item FIS and their according products (Metainformation)
hans@911:     \item products with their states, transitions, outputs and SQL-statements
hans@911:     (Implementation)
hans@911: \end{enumerate}
tim@910: 
tim@920: %% TODO: Add a Screenshot of the GNV WebClient marking GUI elements for FIS,
hans@911: %% product, states and transitions
tim@910: 
hans@911: Main entry point for the configuration is the file \verb+ conf/conf.xml +
hans@911: defining the list of FIS and the according products based on the different
hans@911: datamodels in the datawarehouse. The provided datamodels are:
tim@910: 
hans@911: \begin{enumerate}
hans@911:     \item ESRI ArcMarineBSH with following subtypes
hans@911:         \begin{enumerate}
hans@911:             \item TimeSeriesPoints
hans@911:             \item MeshFeatures
hans@911:             \item Measurements/InstantaneousPoints
tim@914:             \item Marine Features
hans@911:         \end{enumerate}
hans@911:     \item ESRI ArcS57,
hans@911:     \item CONTIS
hans@911: \end{enumerate}
tim@910: 
hans@911: Each product configuration consists of a datamodel specific configuration
hans@912: organized in a product specific folder in \verb+ conf/products+ \footnote{The
hans@911: special case of a "Horizontales Schnittprofil" is configured in
hans@912: conf/horizontalprofile/conf\_mesh\_cross.xml }. The directory layout looks
hans@911: like this:
hans@911: 
hans@911: \begin{verbatim}
hans@911: products/
hans@911: |-- horizontalcrosssection
hans@911: |   `-- conf_mesh.xml
hans@911: |-- horizontalprofile
hans@911: |   |-- conf_instantaneouspoint.xml
hans@911: |   |-- conf_mesh.xml
hans@911: |   `-- conf_mesh_cross.xml
hans@911: |-- layer
hans@911: |   `-- conf.xml
hans@911: |-- timeseries
hans@911: |   |-- conf_mesh.xml
hans@911: |   |-- conf_timeseriespoint.xml
hans@911: |   `-- timegap_definition.xml
hans@911: |-- verticalcrosssection
hans@911: |   `-- conf_mesh.xml
hans@911: `-- verticalprofile
hans@911:     |-- conf_instantaneouspoint.xml
hans@911:     |-- conf_mesh.xml
hans@911:     `-- conf_timeseriespoint.xml
hans@911: \end{verbatim}
hans@911: 
hans@911: The subtypes of the ArcMarineBSH based datamodel are configured in the files below:
tim@910: \begin{itemize}
tim@910:    \item TimeSeriesPoints: conf\_timeseriespoint.xml
tim@910:    \item Mesh: conf\_mesh.xml
tim@910:    \item InstantaneousPoints: conf\_instantaneouspoint.xml
tim@910: \end{itemize}
tim@910: 
hans@911: Within each of these files, the steps for gathering the values for the
hans@911: parameterisation are configured by defining states, transitions and outputs
tim@920: (c.f. \ref{ref:config-a-product}).  The definition of states, transitions and
hans@931: outputs reference the actual SQL-statements via an identifier. The SQL-statements
hans@931: are gathered in the file \verb+conf/queries.properties+.
hans@911: 
tim@910: 
hans@931: \subsection{Explaining the background of the XML configuration}
tim@907: 
tim@908: It is possible to configure the GNV in many ways.
tim@940: It is possible to add or remove FIS, add or remove products from a FIS or
tim@908: to manipulate the steps which must be gone until a product can be create
tim@940: a diagram or generate an CSV-export.
tim@908: 
tim@920: The configuration of the provided FIS are divided in three main parts.
tim@908: 
tim@908: \begin{itemize}
tim@940:     \item Configuration of the list of FIS via artifact-factories
tim@940:     \item Configuration of main artifacts which will be instantiated if an 
tim@940:   artifact-factory was called.
tim@940:     \item Configuration of the different artifacts which provides products which can be 
tim@907:   served by the FIS.
tim@908: \end{itemize}
tim@907: 
tim@910: \subsubsection{Configuration of a FIS}
tim@940: The point of entry into the system is to configure an artifact-factory.
tim@940: Each artifact-factory represents one FIS.
tim@940: It is possible to configure several artifact-factories.
tim@940: The artifact-factories will be configured in the section 
tim@940: /artifact-database/artifact-factories of the configurationfile.
tim@907: 
tim@907: \begin{lstlisting}
hans@931: <artifact-factory name='fis_NEWFISNAME' 
tim@907:                   description='Factory to create an artifact to be used with the FIS NEWFISNAME'  
tim@907:                   ttl='3600000' 
tim@907:                   artifact='de.intevation.artifactdatabase.ProxyArtifact'>
tim@907:                   de.intevation.gnv.artifacts.GNVProductArtifactFactory
tim@907: </artifact-factory>
tim@907: \end{lstlisting}
tim@907: 
tim@940: At this moment the following attributes of an artifact-factory are configurable.
tim@908: \begin{itemize}
tim@940:     \item name: The name of the artifact. Must be unique in one artifact-server
tim@940:     \item description: Short description which job the artifact-factory has to do.
tim@940:     \item  ttl: The time to live: The time using milliseconds an artifact, created using this 
tim@940:                 factory, can live without any user-interaction.
tim@940:     \item artifact: The name of the class of the artifact which should be created.
tim@908: \end{itemize}
tim@907: 
tim@940: The next listing shows the dependencies between the FIS and the name
tim@940: of the artifact-factory which belongs to it.
hans@911: 
hans@911: \begin{itemize}
hans@911:     \item Marnet: fis\_marnet
hans@911:     \item IMIS: fis\_imis
hans@911:     \item STAUN: fis\_staun
hans@911:     \item Modeldata fis\_modeldata
hans@911:     \item Iceclimatology: fis\_eisklimatologie
hans@911:     \item Ice Station Report: fis\_icestations
hans@911:     \item SST: fis\_sst
hans@911:     \item Delphin: fis\_delphin
hans@911:     \item Thermosalinograph: fis\_thermosalinograph
hans@911:     \item Chemusurvey: fis\_chemusurvey
hans@911:     \item GTS: fis\_gts
hans@911:     \item CTD: fis\_bsh\_ctd
hans@911:     \item XBT: fis\_bsh\_xbt
tim@940:     \item SeaCat: fis\_seacat
hans@911:     \item Sea State: fis\_seastate
hans@911:     \item Current Meter: fis\_currentmeter
hans@911:     \item Nauthis: fis\_nauthis
hans@911:     \item Contis: fis\_contis
hans@911:     \item Marine Features: fis\_marinefeatures
hans@911: \end{itemize}
hans@911: 
tim@907: \subsubsection{Configuration of main Artifact}
tim@940: For each artifact-factory it is necessary to configure one artifact which will be 
tim@940: created using the factory.
tim@940: This artifact is the representation of the specific FIS.
tim@940: It contains the configuration which products will be served for this FIS.
tim@907: 
tim@940: The artifacts are configured in the section /artifact-database/artifacts of 
tim@940: the configurationfile.
tim@907: 
tim@907: \begin{lstlisting}
hans@931: <artifact name='fis_NEWFISNAME'>
tim@907:     <products>
tim@907:      ...
tim@907:     </products>
tim@907: </artifact>
tim@907: \end{lstlisting}
tim@907: 
tim@940: The key is to use the same name for the artifact as used for the artifact-factory.
tim@940: The name has to be unique.
tim@940: In the section /artifact/products it is possible to define several products as 
tim@940: explained in the next section.
tim@907: 
tim@910: \paragraph{Products to an FIS}
tim@940: One FIS can provide several products.
tim@940: To do this it is required to configure them as shown below in the section 
tim@907: /artifact/products
tim@907: 
tim@907: \begin{lstlisting}
tim@907: <product name= "timeSeries">
tim@907:       <artifact-factory name="timeSeries" 
tim@907:                         description="Artiefactfactory for Instantiating the Artifact for TimeSeries on TimeSeriesPoints"  
tim@907:                         ttl="300000" 
tim@907:                         artifact="de.intevation.gnv.timeseries.TimeSeriesArtifact">
tim@907:            de.intevation.gnv.artifacts.GNVArtifactFactory
tim@907:       </artifact-factory>
tim@907:       <parameters>
tim@907:           <parameter name="sourceid" 
tim@907:                      value="4"/>
tim@907:           <parameter name="fisname" 
tim@907:                      value="fis\_marnet"/>
tim@907:       </parameters>
tim@907:  </product>
tim@907:  \end{lstlisting}
tim@907: 
tim@940: Each product is also represented by an artifact. To create this artifact we have to 
tim@940: use an artifact-factory which is configured in each product 
tim@907: (/product/artifact-factory).
tim@907: 
tim@940: Each product can have several parameters /product/parameters/parameters.
tim@940: The parameter named sourceid and fisname are required parameters.
tim@907: 
tim@940: The parameter fisname contains the key to the name of the FIS. The key must be 
tim@907: unique.
tim@940: The parameter sourceid contains the key to identify the FIS in the 
tim@940: datawarehouse. (MEDIAN.SOURCEINFO)
tim@907: 
tim@907: 
tim@910: \subsubsection{Configuration of an Product}
hans@911: \label{ref:config-a-product}
tim@940: The products of the different FIS are also modeled as artifact-objects.
tim@940: The different products which are currently available are stored in separate
tim@940: files in the folder project.
tim@908: 
tim@940: In those files the workflow of each product is configured.  Each step which is
tim@920: required to model a new diagram is represented using a state in the
tim@940: configurationfile.
tim@908: 
tim@940: To move between those states it is required to model transitions which define
tim@940: between which states it is possible to move and which conditions must be
tim@908: fulfilled.
tim@908: 
tim@940: The last step is called output-state. This state is responsible to generate the
tim@940: output for the different formats which can be served from the product (Diagram,
tim@908: CSV, ODV, WMS,...).
tim@908: 
tim@907: \paragraph{States}
tim@940: A state is one step which is required to fetch the data for generating e.g. an
tim@940: diagram.
tim@908: 
tim@940: For example in each product it is possible to choose one or more parameters.
tim@908: 
tim@940: To configure a state you have to use a XML-fragment as shown below:
tim@908: 
tim@908: \begin{lstlisting}
tim@908: <state id="timeseries_parameter" description="timeseries_parameter" state="de.intevation.gnv.state.DefaultState">
tim@908:    <queryID>timeseries_parameter</queryID>
tim@908:    <dataname>parameterid</dataname>
tim@908:    <data-multiselect>true</data-multiselect>
tim@908:    <inputvalues>
tim@913:       ...
tim@908:    </inputvalues>
tim@908: </state>
tim@908: \end{lstlisting}
tim@908: 
tim@940: At this moment the following attributes of an state are configurable.
tim@908: \begin{itemize}
tim@940:     \item id: The name of the artifact. Must be unique in one artifact-server
tim@940:     \item description: Short description which job the artifact-factory has to do.
tim@940:     \item queryID: The id of the query which should be used to fetch the data 
tim@940:                    displayed in this state. All queries are defined in the file
tim@920:                    conf/queries.properties
tim@940:     \item dataname: The id of the data which will be displayed in this state.
tim@940:                     The id will be use to localize the description of the data.
tim@940:                     The localization is located in module gnv-artifacts in folder
tim@934:                     src/main/resources.
tim@940:     \item data-multiselect: true it is possible to select 1 or more items.
tim@940:                             false it is possible to select only one item.
tim@940:     \item inputvalues: The values which can be "feed" to this state and which 
tim@940:                        will be used as values in SQL-statements.
tim@909: \end{itemize}
tim@908: 
tim@913: \paragraph{Input Values of a State}
tim@940: At section /state/inputvalues it is possible to add definitions for inputvalues.
tim@940: Those values have two meanings for the state.
tim@913: 
tim@913: \begin{itemize}
tim@940:      \item They were used to fill the SQL-statements to fetch the data.
tim@913:            (Each entry replace one ore more "?" )
tim@940:      \item They were used to validate the inputdata which is "feed" to
tim@940:            the FIS in the current state.
tim@913: \end{itemize}
tim@913: 
tim@940: WARNING: The order of the inputvalues is significant at which position the value will
tim@940: be put into the SQL-statement.
tim@913: 
tim@940: It is possible to add one inputvalue twice or more often to put its value at
tim@920: different positions of the SQL-statement.
tim@913: 
tim@913: \begin{lstlisting}
tim@913: <inputvalues>
tim@913:     <inputvalue name="featureid" type="Integer" multiselect="false" usedinquery="1"/>
tim@913:     <inputvalue name="fisname" type="String" multiselect="false" usedinquery="0"/>
tim@913:     <inputvalue name="parameterid" type="Integer" multiselect="true" usedinquery="0"/>
tim@913: </inputvalues>
tim@913: \end{lstlisting}
tim@913: 
tim@913: \begin{itemize}
tim@940:     \item name: Name of the value that could be feed or should be used in SQL-statment.
tim@940:                 The name must fit to one dataname configured in this state or one other
tim@940:                 state which was visited before.
tim@940:     \item type: The type of the value. This is required for the validation 
tim@940:                 of the value.
tim@913:                 This might be String, Integer, Double, Date, Point, LineString, 
tim@913:                 Polygon, Coordinate, Geometry and AttributeName.
tim@940:                 Coordinate is a format which accepts geographical coordinates in 
tim@934:                 the following Syntax: 56n30 6e20
tim@940:                 AttributeName marks a stringvalue which will be used in 
tim@940:                 SQL-statement without surrounding with "'" in the statement.
tim@940:                 Usage is e.g. for determining the Axis (i or j) in the workflow
tim@940:                 of Horizontalprofiles.
tim@940:     \item multiselect: true if more than on value can be feed or put into the SQL-statement.
tim@940:                        false if one on value will be accepted.
tim@940:     \item usedinquery: Number how often the value should be put into the SQL-statement:
tim@940:                        0: Value will not out into the statement.
tim@940:                        1: Value will put once into the statement,
tim@913:                        2 or more: Value will be put as often as configured 
tim@940:                                   into the SQL-statement (this is useful if 
tim@940:                                   inner-selects are used)
tim@913: \end{itemize}
tim@913: 
tim@913: The next part will explain the usage of inputvalues.
tim@913: 
tim@940: This SQL-statement is configured to use in the state above, which will fetch
tim@940: all parameter-ids with the according german name which are reffered to the given
tim@934: TimeSeriesPoint (e.g.Arkona Basin Buoy FeatureID = 100011 )
tim@913: 
tim@934:  
tim@913: \begin{lstlisting}
tim@913: SELECT DISTINCT 
tim@913:        p.PARAMETERID KEY, 
tim@913:        p.GERMANNAME || '  ['|| p.UNIT ||']' VALUE, 
tim@913:        p.GERMANNAME 
tim@913: FROM MEDIAN.PARAMETER P, 
tim@913:      MEDIAN.TIMESERIES TS, 
tim@913:      MEDIAN.TIMESERIESVALUE TSV, 
tim@913:      MEDIAN.MEASUREMENT M, 
tim@913:      MEDIAN.TIMESERIESPOINT TSP 
tim@913: WHERE M.FEATUREID = TSP.FEATUREID AND 
tim@913:       M.MEASUREMENTID = TSV.MEASUREMENTID AND 
tim@913:       TS.TIMESERIESID = TSV.TIMESERIESID AND 
tim@913:       P.PARAMETERID = TS.PARAMETERID AND 
tim@913:       TSP.FEATUREID = ? 
tim@913: ORDER BY P.GERMANNAME
tim@913: \end{lstlisting}
tim@913: 
tim@940: If there are put the inputvalues in it it will look like this
tim@934: if we assume that the inputvalues has got the following values
tim@934: which where feed by choosing this FIS (fisname) and the Station
tim@934: (featureid: Arkona Basin Buoy ):
tim@913: \begin{itemize}
tim@934:     \item featureid: 100011 (Marnet ==> Arkona Basin Buoy)
tim@913:     \item fisname: fis\_marnet
tim@913:     \item parameterid: not set because it's the value that should be 
tim@913:                        chosen in this state. 
tim@913: \end{itemize}
tim@913: 
tim@913: \begin{lstlisting}
tim@913: SELECT DISTINCT 
tim@913:        p.PARAMETERID KEY, 
tim@913:        p.GERMANNAME || '  ['|| p.UNIT ||']' VALUE, 
tim@913:        p.GERMANNAME 
tim@913: FROM MEDIAN.PARAMETER P,  
tim@913:        MEDIAN.TIMESERIES TS, 
tim@913:        MEDIAN.TIMESERIESVALUE TSV, 
tim@913:        MEDIAN.MEASUREMENT M, 
tim@913:        MEDIAN.TIMESERIESPOINT TSP  
tim@913: WHERE M.FEATUREID = TSP.FEATUREID AND 
tim@913:       M.MEASUREMENTID = TSV.MEASUREMENTID AND 
tim@913:       TS.TIMESERIESID = TSV.TIMESERIESID AND 
tim@913:       P.PARAMETERID = TS.PARAMETERID AND 
tim@934:       TSP.FEATUREID = 100011
tim@913: ORDER BY P.GERMANNAME
tim@913: \end{lstlisting}
tim@913: 
tim@940: The value of featureid will be inserted into the query because
tim@940: the attribute usedinquery is set to "1".
tim@913: 
tim@913: The values of the inputvalues fisname and parameterid will be
tim@940: excluded because the attribute usedinquery is set to "0"
tim@913: 
tim@913: 
tim@940: If the attribute usedinquery of the inputvalue featureid is set to "2"
tim@913: this might happen.
tim@913: 
tim@913: \begin{lstlisting}
tim@913: <inputvalues>
tim@913:     <inputvalue name="featureid" type="Integer" multiselect="false" usedinquery="2"/>
tim@913:     <inputvalue name="fisname" type="String" multiselect="false" usedinquery="0"/>
tim@913:     <inputvalue name="parameterid" type="Integer" multiselect="true" usedinquery="0"/>
tim@913: </inputvalues>
tim@913: \end{lstlisting}
tim@913: 
tim@913: \begin{lstlisting}
tim@913: SELECT DISTINCT 
tim@913:     ...
tim@913:     TSP.FEATUREID = ? AND
tim@913:     TSP.FEATUREID = ? 
tim@913:  ORDER BY P.GERMANNAME
tim@913: \end{lstlisting}
tim@913: 
tim@913: This SQL-statement will be modified to
tim@913: 
tim@913: \begin{lstlisting}
tim@913: SELECT DISTINCT 
tim@913:     ...
tim@934:     TSP.FEATUREID = 100011 AND
tim@934:     TSP.FEATUREID = 100011 
tim@913: ORDER BY P.GERMANNAME
tim@913: \end{lstlisting}
tim@913: 
tim@913: 
tim@940: At the next step of the workflow it is nessesary to determine all depths where
tim@940: the choosen parameters are measured.
tim@940: To do this we might have the following inputvalues:
tim@913: 
tim@913: \begin{lstlisting}
tim@913: <inputvalues>
tim@913:     <inputvalue name="featureid" type="Integer" multiselect="false" usedinquery="2"/>
tim@934:     <inputvalue name="fisname" type="String" multiselect="false" usedinquery="0"/>
tim@934:     <inputvalue name="parameterid" type="Integer" multiselect="true" usedinquery="1"/>
tim@934:     <inputvalue name="measurementid" type="Integer" multiselect="true" usedinquery="0"/>
tim@913: </inputvalues>
tim@913: \end{lstlisting}
tim@913: 
tim@934: \begin{itemize}
tim@934:    \item featureid: 100011 (Marnet ==> Arkona Basin Buoy)
tim@934:    \item fisname: fis\_marnet
tim@934:    \item parameterid: 2 (Salzgehalt [pSal])
tim@934:    \item measurementid: not set because it's the value that should be
tim@934:                         chosen in this state.
tim@934: \end{itemize}
tim@913: 
tim@913: \begin{lstlisting}
tim@934: SELECT DISTINCT 
tim@934:        M.MEASUREMENTID KEY, 
tim@934:        M.ZLOCATION VALUE, 
tim@934:        P.PARAMETERID PARAMETERID 
tim@934: FROM MEDIAN.MEASUREMENT M, 
tim@934:      MEDIAN.TIMESERIESVALUE TSV, 
tim@934:      MEDIAN.TIMESERIES T, 
tim@934:      MEDIAN.PARAMETER P 
tim@934: WHERE M.MEASUREMENTID = TSV.MEASUREMENTID AND 
tim@934:       TSV.TIMESERIESID = T.TIMESERIESID AND 
tim@934:       T.PARAMETERID = P.PARAMETERID AND 
tim@934:       M.FEATUREID = ? AND 
tim@934:       M.FEATUREID = ? AND 
tim@934:       P.PARAMETERID IN (?)
tim@934: ORDER BY m.ZLOCATION DESC
tim@913: \end{lstlisting}
tim@913: 
tim@913: This SQL-statement will be modified to
tim@913: 
tim@913: \begin{lstlisting}
tim@913: SELECT DISTINCT 
tim@934:        M.MEASUREMENTID KEY, 
tim@934:        M.ZLOCATION VALUE, 
tim@934:        P.PARAMETERID PARAMETERID 
tim@934: FROM MEDIAN.MEASUREMENT M, 
tim@934:      MEDIAN.TIMESERIESVALUE TSV, 
tim@934:      MEDIAN.TIMESERIES T, 
tim@934:      MEDIAN.PARAMETER P 
tim@934: WHERE M.MEASUREMENTID = TSV.MEASUREMENTID AND 
tim@934:       TSV.TIMESERIESID = T.TIMESERIESID AND 
tim@934:       T.PARAMETERID = P.PARAMETERID AND 
tim@934:       M.FEATUREID = 100011 AND 
tim@934:       M.FEATUREID = 100011 AND 
tim@934:       P.PARAMETERID IN (2)
tim@934: ORDER BY m.ZLOCATION DESC
tim@913: \end{lstlisting}
tim@913: 
tim@908: 
tim@907: \paragraph{Transitions}
tim@908: 
tim@940: To move between two states it is necessary to configure dependencies between
tim@940: the different states.
tim@940: This dependencies are called transitions.
tim@908: 
tim@940: There are different kinds of transitions which can be used.
tim@908: \begin{itemize}
tim@940:   \item Transitions which only link two states
tim@940:   \item Transition which link two states with a additional condition. 
tim@908:         (e.g. If a region was selected in the Regionfilter or not )
tim@908: \end{itemize}
tim@908: 
tim@940: The listing below shows a transition with an additional condition.
tim@908: \begin{lstlisting}
tim@908: <transition transition="de.intevation.gnv.transition.ValueCompareTransition">
tim@908:     <from state="timeseries_area"/>
tim@908:     <to state="timeseries_without_geom"/>
tim@908:     <condition inputvalue="areaid" value="n/n" operator="equal"/>
tim@908: </transition>
tim@908: \end{lstlisting}
tim@908: 
tim@908: \begin{itemize}
tim@940:   \item from: The id of the state which you have to come from
tim@940:   \item to:   The id of the state which can be reached.
tim@940:   \item condition: The condition which have to be fulfilled.
tim@908: \end{itemize}
tim@934: 
tim@940: At this moment only EQUAL and NOTEQUAL are supported as condition for an
tim@934: ValueCompareTransition.
tim@908: 
tim@907: \paragraph{Outputstate}
tim@907: 
tim@940: The outputstate is an special state which was created to define
tim@940: the different possibilities of outputs for each product.
tim@940: An outputstate is handled as an state which is described above.
tim@909: Additionally you are able to configure which kind of outputs should
tim@909: be provided.
tim@909: 
tim@940: There are several outputstates. Each one is designed to create 
tim@940: the output for one special product.
tim@909: 
tim@915: \begin{itemize}
tim@915:   \item TimeSeries: TimeSeriesOutputState
tim@915:   \item Horizontalprofile: HorizontalProfileOutputState
tim@915:   \item Horizontalprofile on Meshes: HorizontalProfileMeshOutputState
tim@915:   \item Verticalcrosssection:VerticalCrossSectionOutputState
tim@915:   \item Verticalprofiles: VerticalProfileOutputState
tim@915:   \item Horizontalcrosssections: HorizontalCrossSectionMeshOutputState
tim@915:   \item Layer: LayerOutputState
tim@915: \end{itemize}
tim@915: 
tim@940: All these outputstates are implemented in package de.intevation.gnv.state
tim@915: and its subpackages. 
tim@915: 
tim@940: You have to put the fullqualified name of the outputstate to the attribute state
tim@915: as shown below.
tim@909: 
tim@940: You can configure an outputstate as shown below:
tim@909: 
tim@909: \begin{lstlisting}
tim@909: <state id="timeseries_calculate_results" description="timeseries_interval" state="de.intevation.gnv.state.timeseries.TimeSeriesOutputState">
tim@909:     <queryID>timeseries_chart_data</queryID>
tim@909:      ...
tim@909:     <outputsModes>
tim@909:         <outputsMode name="chart" description="Chartrepresentation of the Values" mime-type="image/png">
tim@909:         ...
tim@909:         </outputsMode>
tim@909:     </outputsModes>
tim@909:  </state>
tim@909: \end{lstlisting}
tim@909: 
tim@940: At section /state/outputsModes it is possible to add one ore more outputmodes
tim@940: to one state as shown in the next paragraph.
tim@909: 
tim@909: \paragraph{OutputModes}
tim@909: 
tim@940: It is possible to configure several outputmodes in one outputstate.
tim@940: Inserting or deleting the configuration of an special
tim@940: outputmode will cause that the pending item will be shown or hidden 
tim@909: in the GUI.
tim@909: 
tim@909: WARNING: IT MIGHT BE POSSIBLE THAT ONE OR MORE OUTPUTMODES ARE NOT
tim@909:          SUPPORTED BY AN PRODUCT. IN THAT CASE IT IS NECESSARY TO
tim@909:          IMPLEMENT THE REQUIRED FUNCTIONALITY BEFORE IT IS POSSIBLE
tim@909:          TO OFFER THIS OUTPUTMODE.
tim@909: 
tim@940: Currently the following outputmodes are supported:
tim@909: 
tim@909: \begin{itemize}
tim@909:    \item chart
tim@909:    \item histogram
tim@909:    \item csv
tim@909:    \item odv
tim@909:    \item statistics
tim@909:    \item wms
tim@909:    \item shapefile
tim@909: \end{itemize}
tim@909: 
tim@940: The following example shows how to configure an outputmode chart:
tim@909: 
tim@909: \begin{lstlisting}
tim@909: <outputsMode name="chart" description="Chartrepresentation of the Values" mime-type="image/png">
tim@909:     <parameters>
tim@909:         <inputvalue name="width" type="Integer" value="600"/>
tim@909:         <inputvalue name="height" type="Integer" value="400"/>
tim@909:         <inputvalue name="points" type="Boolean" value="false"/>
tim@909:     </parameters>
tim@909:     <exportModes>
tim@909:         <export name="img" description="IMG-Export der Daten" mime-type="image/png" />
tim@909:         <export name="pdf" description="PDF-Export der Daten" mime-type="application/pdf" />
tim@909:         <export name="svg" description="SVG-Export der Daten" mime-type="image/svg+xml" />
tim@909:       </exportModes>
tim@909: </outputsMode>
tim@909: \end{lstlisting}
tim@909: 
tim@909: // TODO add simple OutputMode e.g. for CSV??
tim@909: 
tim@909: \begin{itemize}
tim@940:    \item name: The name of the mode. This must not be changed because it is used 
tim@940:                by the program.
tim@940:    \item description: a short description of this outputmode. 
tim@909:    \item parameters: one ore more parameters which will be shown in the GUI e.g. 
tim@940:                      for changing the size of an chart.
tim@909:    \item exportModes: one or more formats which can be served.
tim@909: \end{itemize}
tim@909: 
tim@907: 
tim@906: \subsection{Adding a new FIS}
tim@940: In this section it will be explained which steps has to be done to integrate a
tim@940: new FIS into the artifact-server.  This will be done using the configuration for
tim@940: an FIS which use data from MEDIAN.TIMESERIES section of the datawarehouse e.g.
tim@908: MARNET or STAUN
tim@906: 
tim@940: Pay attention that for publishing the changes to the artifact-server you will 
tim@906: have to restart it. 
tim@906: 
tim@940: \subsubsection{Adding a new Artifact-factory}
tim@940: First step is to add a new artifact-factory to the configuration conf/conf.xml
tim@940: To do this you have to add a new XML-fragment into the section 
tim@906: /factories/artifact-factories  which look like that:
tim@906: 
tim@906: \begin{lstlisting}
tim@906: <artifact-factory name='fis\_NEWFISNAME' 
tim@906:                   description='Factory to create an artifact to be used with the FIS NEWFISNAME'  
tim@906:                   ttl='3600000' 
tim@906:                   artifact='de.intevation.artifactdatabase.ProxyArtifact'>
tim@906:                   de.intevation.gnv.artifacts.GNVProductArtifactFactory
tim@906: </artifact-factory>
tim@906: \end{lstlisting}
tim@906:  
tim@940: In this XML-fragment you only have to replace the placeholder NEWFISNAME with a 
tim@940: unique short name for the new FIS.
tim@906: 
tim@916: \paragraph{Example}
tim@940: This example shows how to add an FIS and which effects it took to the 
tim@916: REST-Server.
tim@916: 
tim@940: At first we add the following artifact-factory into the file conf/conf.xml
tim@940: in section /artifact-database/artifact-factories which add a new 
tim@940: FIS called justanewfis to the server:
tim@916: 
tim@916: \begin{lstlisting}
tim@916: <artifact-factory name='fis\_justanewfis' 
tim@916:                   description='Factory to create an artifact to be used with the FIS NEWFISNAME'  
tim@916:                   ttl='3600000' 
tim@916:                   artifact='de.intevation.artifactdatabase.ProxyArtifact'>
tim@916:                   de.intevation.gnv.artifacts.GNVProductArtifactFactory
tim@916: </artifact-factory>
tim@916: \end{lstlisting}
tim@916: 
tim@940: Then we restart the artifact-database executing the following command:
tim@916: 
tim@920: \begin{lstlisting}
tim@916: /etc/init.d/artifactdb restart
tim@920: \end{lstlisting}
tim@916: 
tim@916: Then we check if the new FIS is served by the REST-Server
tim@916: calling the following command:
tim@916: 
tim@920: \begin{lstlisting}
tim@919: curl http://localhost:8181/factories | xmllint --format - | grep fis\_justanewfis
tim@920: \end{lstlisting}
tim@916: 
tim@940: If the FIS was added the new artifact-factory will be found in the generated 
tim@940: XML-output and it will be shown.
tim@940: Otherwise no XML-output will be shown.
tim@916: 
tim@940: \subsubsection{Adding a new Artifact for Artifact-factory}
tim@940: The next step is to define the artifact itself.
tim@940: For this it is necessary to add an XML-fragment into the section /artifacts of 
tim@940: the main configurationfile /conf/conf.xml
tim@906: \begin{lstlisting}
tim@906: <artifact name='fis\_NEWFISNAME'>
tim@906:     <products>
tim@906:      ...
tim@906:     </products>
tim@906: </artifact>
tim@906: \end{lstlisting}
tim@906: 
tim@940: In this XML-fragment it is also required to replace the placeholder NEWFISNAME 
tim@940: with the name which was used to configure the artifact-factory.
tim@906: 
tim@940: Now the artifact-server can handle an additional FIS without any products yet.
tim@906: 
tim@940: To prevent needless configuration-work it is useful way to clone an artifact 
tim@940: which handle the same kind of work as the new FIS.
tim@906: 
tim@917: 
tim@917: \paragraph{Example}
tim@940: Now we will configure an artifact to the FIS justanewfis.
tim@917: 
tim@940: For this we have to add the following XML-fragment to the file conf/conf.xml
tim@940: in section /artifact-database/artifacts:
tim@917: 
tim@917: \begin{lstlisting}
tim@917: <artifact name='fis\_justanewfis'>
tim@917:     <products>
tim@917:     </products>
tim@917: </artifact>
tim@917: \end{lstlisting}
tim@917: 
tim@940: Restart the artifact-database:
tim@917: 
tim@919: \begin{lstlisting}
tim@917: /etc/init.d/artifactdb restart
tim@919: \end{lstlisting}
tim@917: 
tim@940: Now we should be able to choose the artifact.
tim@919: 
tim@917: The Listbox with products will be empty.
tim@919: \begin{lstlisting}
tim@919: curl -d "@sample-documents/create-artifact.xml"  http://localhost:8181/create | xmllint --format -
tim@919: \end{lstlisting}
tim@917: 
tim@906: \subsubsection{Adding removing Products to the specific Artifact}
tim@940: Now it is time to configure the different products which the FIS should be able 
tim@906: to provide.
tim@940: To do this it is necessary to copy the XML-fragments of the products into the
tim@940: XML-element <products> of the previously integrated artifact.
tim@906: \begin{lstlisting}
tim@906: <artifact name='fis\_NEWFISNAME'>
tim@906:      <products>
tim@906:          <product name= "timeSeries">
tim@906:               <artifact-factory name="timeSeries" 
tim@940:                                 description="Artifactfactory for instantiating the artifact for TimeSeries on TimeSeriesPoints"  
tim@906:                                 ttl="300000" 
tim@906:                                 artifact="de.intevation.gnv.timeseries.TimeSeriesArtifact">
tim@906:                   de.intevation.gnv.artifacts.GNVArtifactFactory
tim@906:               </artifact-factory>
tim@906:               <parameters>
tim@906:                   <parameter name="sourceid" 
tim@906:                              value="VALUEOFSOURCEID"/>
tim@906:                   <parameter name="fisname" 
tim@906:                              value="fis\_NEWFISNAME"/>
tim@906:               </parameters>
tim@906:           </product>
tim@906:           <product name= "verticalProfile">
tim@906:               <artifact-factory name="verticalProfile" 
tim@940:                                 description="Artifactfactory for instantiating the artifact for Verticalprofiles on TimeSeriesPoints"  
tim@906:                                 ttl="300000" 
tim@906:                                 artifact="de.intevation.gnv.profile.vertical.VerticalProfileArtifact">
tim@906:                   de.intevation.gnv.artifacts.GNVArtifactFactory
tim@906:               </artifact-factory>
tim@906:               <parameters>
tim@906:                   <parameter name="sourceid" 
tim@906:                              value="VALUEOFSOURCEID"/>
tim@906:                   <parameter name="fisname" 
tim@906:                              value="fis\_NEWFISNAME"/>
tim@906:               </parameters>
tim@906:           </product>
tim@906:      </products>
tim@906: </artifact>
tim@906: \end{lstlisting}
tim@906: 
tim@940: In this XML-fragment you have to replace the placeholders NEWFISNAME as before 
tim@940: and VALUEOFSOURCEID with the value for the new FIS as defined in the table 
tim@906: MEDIAN.SOURCEINFO.
tim@906: 
tim@918: \paragraph{Example}
tim@940: Now we will add a product to the new FIS.
tim@940: To let the products work we will choose a product which
tim@918: will contain the sourceid of an existing FIS (e.g 4 Marnet).
tim@918: 
tim@940: At first add the following XML-fragment to the new artifact.
tim@918: \begin{lstlisting}
tim@918: <product name= "timeSeries">
tim@918:     <artifact-factory name="timeSeries" 
tim@940:                       description="Artifactfactory for instantiating the artifact for TimeSeries on TimeSeriesPoints"  
tim@918:                       ttl="300000" 
tim@918:                       artifact="de.intevation.gnv.timeseries.TimeSeriesArtifact">
tim@918:                       de.intevation.gnv.artifacts.GNVArtifactFactory
tim@918:     </artifact-factory>
tim@918:     <parameters>
tim@918:         <parameter name="sourceid" 
tim@918:                  value="4"/>
tim@918:         <parameter name="fisname" 
tim@918:                  value="fis\_justanewfis"/>
tim@918:     </parameters>
tim@919: </product>
tim@918: \end{lstlisting}
tim@918: 
tim@940: Restart the artifact-database:
tim@918: 
tim@919: \begin{lstlisting}
tim@918: /etc/init.d/artifactdb restart
tim@919: \end{lstlisting}
tim@919: 
tim@919: If we call 
tim@919: \begin{lstlisting}
tim@919: curl -d "@sample-documents/create-artifact.xml"  http://localhost:8181/create | xmllint --format -
tim@919: \end{lstlisting}
tim@919: 
tim@940: the product timeSeries should be available for the FIS justanewfis.
tim@918:  
tim@940: Now we should be able to choose the product.
tim@940: This product should work and you should be able to generate even the defined
tim@940: outputformats.
tim@918: 
tim@906: \subsection{Adding a new Product}
tim@940: To add a new product to the system it is necessary that the required 
tim@940: artifact representation is implemented in the sourcecode.
tim@940: Without doing that step it is not possible to create a new product.
tim@906: 
tim@940: All products are configured in separate files that will be included into the 
tim@940: main configuration using Xlink-references.
tim@906: 
tim@940: First step is to create a new file in the folder products and there in the 
tim@940: sub-folder where the product belongs to (timeseries,verticalprofile,
tim@906: horizontalprofile,horizontalcrosssection,layer,...)
tim@906: 
tim@940: Then you have tor reference this file in the file /conf/conf.xml in the section 
tim@940: /artifacts using the following XML-fragment.
tim@906: 
tim@906: \begin{lstlisting}
tim@906: <artifact name="timeSeries" 
tim@906:           xmlns:xlink="http://www.w3.org/1999/xlink" 
tim@906:           xlink:href="${artifacts.config.dir}/products/PATHTOFILE" /> 
tim@906: \end{lstlisting}
tim@906: 
tim@940: The placeholder PATHTOFILE has to be replaced with the relative path and the 
tim@940: name of the file starting in the folder products.  
tim@906: 
tim@906: Then it is possible to add the product to a FIS as explained in the next section.
tim@940: Please note that the defined name of the artifact-factory has to match to the 
tim@940: name of the added products which is also designed as an artifact.
tim@906: 
tim@906: \subsection{Adding a additional Product to a FIS}
tim@940: To add a additional product to a FIS you only have to add the XML-fragment which 
tim@940: represents the product to the artifact-configuration of the FIS in section
tim@906: /artifacts/artifact/products.
tim@906: 
tim@906: \begin{lstlisting}
tim@906:  <product name= "timeSeries">
tim@906:      <artifact-factory name="timeSeries" 
tim@940:                        description="Artifactfactory for instantiating the artifact for TimeSeries on TimeSeriesPoints"  
tim@906:                        ttl="300000" 
tim@906:                        artifact="de.intevation.gnv.timeseries.TimeSeriesArtifact">
tim@906:           de.intevation.gnv.artifacts.GNVArtifactFactory
tim@906:      </artifact-factory>
tim@906:      <parameters>
tim@906:          <parameter name="sourceid" 
tim@906:                     value="VALUEOFSOURCEID"/>
tim@906:          <parameter name="fisname" 
tim@906:                     value="fis\_NEWFISNAME"/>
tim@906:      </parameters>
tim@906:  </product>
tim@906:  \end{lstlisting}
tim@906: 
tim@906: Please note that you have to replace the Placeholders as explained above.
tim@906: 




