
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: 
hans@911: %% TODO: Add a screenshoot 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
hans@911: (c.f. \ref{ref:config-a-product}).  The defintion of states, transitions and
hans@911: outputs reference the actual SQL-statements via identifier. The SQL-statements
hans@911: are gathered in the file \verb+conf/queries.txt+.
hans@911: 
tim@910: 
tim@906: \subsection{General principle of model of transitions}
tim@907: 
tim@908: It is possible to configure the GNV in many ways.
tim@908: 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@908: a diagramm or generate an CSV-Export.
tim@908: 
tim@908: The configuration of the provided FIS are devided in three main parts.
tim@908: 
tim@908: \begin{itemize}
hans@911:     \item Configuration of the list of FIS via Artifactfactories
tim@908:     \item Configuration of main Artifacts which will be instantiated if an 
tim@907:   Artifactfactory was called.
tim@908:     \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@907: The Point of Enty into the system is to configure an Artifactfactory.
tim@907: Each Artifactfactory represents one FIS.
tim@907: It is possible to configure several Artifactfactories.
tim@908: The Artifactfactories will be configured in the Section 
tim@907: /artifact-database/artifact-factories of the Configurationfile.
tim@907: 
tim@907: \begin{lstlisting}
tim@907: <artifact-factory name='fis\_marnet' 
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@907: At this moment the following Attributes of an Artifact-Factory are configurabel.
tim@908: \begin{itemize}
tim@908:     \item name: The Name of the Artifact. Must be unique in one Artifact-Server
tim@908:     \item description: Short description which Job the Artifactfactory has to do.
tim@908:     \item  ttl: The Time to Live: The Time using Milliseconds an Artifact, created using this 
tim@908:                 factory, can live without any Userinteraction.
tim@908:     \item artifact: The Name of the Class of the Artifact which should be created.
tim@908: \end{itemize}
tim@907: 
hans@911: The next listing shows the dependencies between the FIS and the Name
hans@911: of the Artifactfactory 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
hans@911:     \item SeaCat: is\_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@908: For each Artifact-Factory it is necessary to configure one Artifact which will be 
tim@908: created using the Factory.
tim@907: This Artifact is the representation of the specific FIS.
tim@908: It contains the Configuration which products will be serverd for ths FIS.
tim@907: 
tim@907: The Artifacts are configured in the Section /artifact-database/artifacts of 
tim@907: the Configurationfile.
tim@907: 
tim@907: \begin{lstlisting}
tim@907: <artifact name='fis\_marnet'>
tim@907:     <products>
tim@907:      ...
tim@907:     </products>
tim@907: </artifact>
tim@907: \end{lstlisting}
tim@907: 
tim@907: The Key is to use the same Name for the Artifact as used for the Artifactfactory.
tim@907: The Name has to be unique.
tim@907: In the Section /artifact/products it is possible to define several Products as 
tim@907: explained in the next Section.
tim@907: 
tim@910: \paragraph{Products to an FIS}
tim@910: One FIS can provide several Products.
tim@907: 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@908: Each Product is also represented by an Artifact. To create this Artifact we have to 
tim@907: use an Artifact-Factory which is configured in each product 
tim@907: (/product/artifact-factory).
tim@907: 
tim@907: Each Product can have several parameters /product/parameters/parameters.
tim@907: The Parameter named sourceid and fisname are required Parameters.
tim@907: 
tim@907: The Parameter fisname contains the key to the Name of the FIS. The Key must be 
tim@907: unique.
tim@907: The Parameter sourceid contains the key to identify the FIS in the 
tim@907: DataWareHouse. (MEDIAN.SOURCEINFO)
tim@907: 
tim@907: 
tim@910: \subsubsection{Configuration of an Product}
hans@911: \label{ref:config-a-product}
tim@908: The Products of the different FIS are also modeled as Artifact-Objects.
tim@908: The different Products which are currently avaliable are stored in separate
tim@908: Files in the Folder project.
tim@908: 
tim@908: In those Files the Workflow of each product is configured.  Each step which is
tim@908: required to model a new Diagramm is represented using a state in the
tim@908: Configuration-File.
tim@908: 
tim@908: To move between those States it is required to model Transitions which define
tim@908: between which States it is possible to move and which conditions must be
tim@908: fulfilled.
tim@908: 
tim@908: The Last step is called OutputState. This State is responsible to generate the
tim@908: output for the different Formats which can be served from the Product (Diagramm,
tim@908: CSV, ODV, WMS,...).
tim@908: 
tim@907: \paragraph{States}
tim@908: A state is one Step which is required to fetch the Data for generating e.g. an
tim@908: Diagramm.
tim@908: 
tim@908: For example in each Product it is Possible to choose one or more Parameters.
tim@908: 
tim@908: 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@908: At this moment the following Attributes of an Artifact-Factory are configurabel.
tim@908: \begin{itemize}
tim@908:     \item id: The Name of the Artifact. Must be unique in one Artifact-Server
tim@908:     \item description: Short description which Job the Artifactfactory has to do.
tim@908:     \item queryID: The ID of the Query which should be used to fetch the Data 
tim@908:                    displayed in this state. //TODO: Reference to queries.properties
tim@908:     \item dataname: The ID of the Data which will be displaied in this State.
tim@908:                     The ID will be use to localize the description of the Data.
tim@908:     \item data-multiselect: true it is possible to select 1 or more Items.
tim@908:                             false ist is possible to select only one Item.
tim@913:     \item inputvalues: The Values which can be "feed" to this State and which 
tim@913:                        will be used as Values in SQL-statements.
tim@909: \end{itemize}
tim@908: 
tim@913: \paragraph{Input Values of a State}
tim@913: At Section /state/inputvalues it is possible to add Definitions for InputValues.
tim@913: Those values have two meanings for the State.
tim@913: 
tim@913: \begin{itemize}
tim@913:      \item They were used to fill the SQL-Statements to fetch the Data
tim@913:            (Each entry replace one ore more "?" )
tim@913:      \item They were used to validate the Inputdata which is "feed" to
tim@913:            the FIS in the current State
tim@913: \end{itemize}
tim@913: 
tim@913: WARNING: The Order of the InputValues is significant at which position the Value will
tim@913: be put into the SQL-Statement.
tim@913: 
tim@913: It is possible to add one InputValue twice or more often to put its value at
tim@913: 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@913:     \item name: Name of the Value that could be feed or should be used in SQl-statment.
tim@913:                 The name must fit to one dataname configured in this State or one other
tim@913:                 State which was visited before.
tim@913:     \item type: The type of the Value. This is required for the Validation 
tim@913:                 of the Value.
tim@913:                 This might be String, Integer, Double, Date, Point, LineString, 
tim@913:                 Polygon, Coordinate, Geometry and AttributeName.
tim@913:     \item multiselect: true if more than on Value can be feed or put into the SQl-statement.
tim@913:                        false if one on Value will be accepted.
tim@913:     \item usedinquery: Number how often the value should be put into the SQL-Statement:
tim@913:                        0: Value will not out into the Statement.
tim@913:                        1: Value will put once into the Staement,
tim@913:                        2 or more: Value will be put as often as configured 
tim@913:                                   into the SQL-Statement (this is useful if 
tim@913:                                   Inner-Selects are used)
tim@913: \end{itemize}
tim@913: 
tim@913: The next part will explain the usage of inputvalues.
tim@913: 
tim@913: This SQL-statment is configured to use in the State above.
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@913:       TSP.FEATUREID = ? 
tim@913: ORDER BY P.GERMANNAME
tim@913: \end{lstlisting}
tim@913: 
tim@913: If there are put the Inputvalues in it it will look like this
tim@913: if we assume that the inputvalues has got the following values:
tim@913: \begin{itemize}
tim@913:     \item featureid: 4 (Marnet)
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@913:       TSP.FEATUREID = 4 
tim@913: ORDER BY P.GERMANNAME
tim@913: \end{lstlisting}
tim@913: 
tim@913: The value of featureid will be inserted into the Query because
tim@913: the Attribute usedinquery is set to "1".
tim@913: 
tim@913: The values of the inputvalues fisname and parameterid will be
tim@913: excluded because the Attribute usedinquery is set to "0"
tim@913: 
tim@913: 
tim@913: 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: 
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@913:     TSP.FEATUREID = 4 AND
tim@913:     TSP.FEATUREID = 4 
tim@913: ORDER BY P.GERMANNAME
tim@913: \end{lstlisting}
tim@913: 
tim@913: 
tim@913: If the Attribute usedinquery of the inputvalue fisname additionally is set to "1"
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="1"/>
tim@913:     <inputvalue name="parameterid" type="Integer" multiselect="true" usedinquery="0"/>
tim@913: </inputvalues>
tim@913: \end{lstlisting}
tim@913: 
tim@913: 
tim@913: \begin{lstlisting}
tim@913:  SELECT DISTINCT 
tim@913:     ...
tim@913:     TSP.FEATUREID = ? AND
tim@913:     TSP.FEATUREID = ? AND
tim@913:     NOCOLUMNINDB  = ?
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@913:     TSP.FEATUREID = 4 AND
tim@913:     TSP.FEATUREID = 4 AND
tim@913:     NOCOLUMNINDB  = 'fis\_marnet' 
tim@913: ORDER BY P.GERMANNAME
tim@913: \end{lstlisting}
tim@913: 
tim@908: 
tim@907: \paragraph{Transitions}
tim@908: 
tim@908: To move between two States it is necessary to configure dependencies between
tim@908: the different States.
tim@908: This dependencies are called. Transitions.
tim@908: 
tim@908: There are different Kind of Transitions which can be used.
tim@908: \begin{itemize}
tim@908:   \item Transitions which only link two States
tim@908:   \item Transition which link two States with a aditional Condition. 
tim@908:         (e.g. If a region was selected in the Regionfilter or not )
tim@908: \end{itemize}
tim@908: 
tim@908: 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@908:   \item from: The ID of the State which you have to come from
tim@908:   \item to:   The ID of the State which can be reached.
tim@908:   \item condition: The Condition which have to be fulfilled.
tim@908: \end{itemize}
tim@908: 
tim@907: \paragraph{Outputstate}
tim@907: 
tim@909: The OutputState is an special State which was created to define
tim@909: the different possibilities of Outputs for each Product.
tim@909: 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@909: There are several OutputStates. Each one is designed to create 
tim@915: 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@915: All these Outputstates are Implemented in package de.intevation.gnv.state
tim@915: and its subpackages. 
tim@915: 
tim@915: You have to put the fullqulified name of the Outputstate to the Attribute State
tim@915: as shown below.
tim@909: 
tim@909: 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@909: At Section /state/outputsModes it is possible to add one ore more OutputModes
tim@909: to one State as shown in the next Paragraph.
tim@909: 
tim@909: \paragraph{OutputModes}
tim@909: 
tim@909: It is possible to configure several OutputModes in one OutputState.
tim@909: Inserting or deleting the Configuration of an special
tim@909: 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@909: 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@909: The following Example shows the Configuration for the 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@909:    \item name: The name of the Mode. This must not be changed because it is used 
tim@909:                by the Programm.
tim@909:    \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@909:                      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@908: In this Section it will be explained which steps has to be done to integrate a
tim@908: new FIS into the Artifact-Server.  This will be done using the Configuration for
tim@908: an FIS which use data from MEDIAN.TIMESERIES Section of the DataWareHouse e.g.
tim@908: MARNET or STAUN
tim@906: 
tim@906: Pay attention that for publishing the Changes to the Artifact-Server you will 
tim@906: have to restart it. 
tim@906: 
tim@906: \subsubsection{Adding a new Artifactfactory}
tim@906: First step is to add a new Artifactfactory to the Configuration conf/conf.xml
tim@906: 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@906: In this XML-Fragment you only have to replace the placeholder NEWFISNAME with a 
tim@906: unique short Name for the new FIS.
tim@906: 
tim@916: \paragraph{Example}
tim@916: This Example shows how to add an FIS and which effects it took to the 
tim@916: REST-Server.
tim@916: 
tim@916: At first we add the follwing Artifactfactory into the file conf/conf.xml
tim@916: in Section /artifact-database/artifact-factories which add a new 
tim@916: 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@916: Then we restart the Artifact-database executing the followinig command:
tim@916: 
tim@916: /etc/init.d/artifactdb restart
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@916: curl http://localhost:8181/factories |grep fis\_justanewfis
tim@916: 
tim@916: If the FIS was added the new Artifactfactory will be found in the generated 
tim@916: XML-Output and it will be shown.
tim@916: Otherwise no XML-Output will be shown.
tim@916: 
tim@906: \subsubsection{Adding a new Artifact for Artifactfactory}
tim@906: The next Step is to define the Artifact itself.
tim@906: For this it is necessary to add an XML-Fragment into the Section /artifacts of 
tim@906: the main Configuration-File /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@906: In this XML- Fragment it is also required to replave the placeholder NEWFISNAME 
tim@906: with the name which was used to configure the Artifact-Factory.
tim@906: 
tim@906: Now the ArtifactServer can serv an additional FIS without any Products yet.
tim@906: 
tim@906: To prevent needless Configuration-Work it is useful way to clone an Artifact 
tim@906: which handle the same Kind of work as the new FIS.
tim@906: 
tim@917: 
tim@917: \paragraph{Example}
tim@917: Now we will configure an Artifact to the FIS justanewfis.
tim@917: 
tim@917: For this we have to add the following XML-Fragment to the File conf/conf.xml
tim@917: 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@917: Restart the Artifact-Database:
tim@917: 
tim@917: /etc/init.d/artifactdb restart
tim@917: 
tim@917: Now we should be able to choose the Artifact.
tim@917: The Listbox with products will be empty.
tim@917: //TODO: USE Screenshots the commandline is to complex?
tim@917: 
tim@906: \subsubsection{Adding removing Products to the specific Artifact}
tim@906: Now it is Time to configure the different Products which the FIS should be able 
tim@906: to provide.
tim@906: To do this it is necessary to Copy the XML-Fragments of the products into the
tim@906: 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@906:                                 description="Artiefactfactory 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@906:                                 description="Artiefactfactory 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@908: In this XML-Fragment you have to replace the placeholders NEWFISNAME as before 
tim@906: 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@918: Now we will add a Product to the new FIS.
tim@918: 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@918: 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@918:                       description="Artiefactfactory 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@918:  </product>
tim@918: \end{lstlisting}
tim@918: 
tim@918: Restart the Artifact-Database:
tim@918: 
tim@918: /etc/init.d/artifactdb restart
tim@918:  
tim@918: Now we should be able to choose the Product Timeseries for FIS justanewfis.
tim@918: This Product should work and you should be able to generate even the defined
tim@918: Outputformats.
tim@918: 
tim@906: \subsubsection{Putting SourceID to specific Artifact}
tim@906: \subsection{Adding a new Product}
tim@906: To add a new Product to the System it is necessary that the required 
tim@906: Artifactrepresentation is Implemented in the SourceCode.
tim@906: Without doing that step it is not possible to create a new Product.
tim@906: 
tim@906: All Products are configured in separate Files that will be included into the 
tim@908: Mainconfiguration using Xlink-References.
tim@906: 
tim@906: First Step is to create a new File in the Folder products and there in the 
tim@906: subfolder where the Product belongs to (timeseries,verticalprofile,
tim@906: horizontalprofile,horizontalcrosssection,layer,...)
tim@906: 
tim@906: Then you have tor reference this File in the File /conf/conf.xml in the Section 
tim@906: /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@906: The placeholder PATHTOFILE has to be replaced with the relative Path and the 
tim@906: 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@906: Please note that the defined Name of the ArtifactFactory has to match to the 
tim@906: 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@906: To add a additional Product to a FIS you only have to add the XML-Fragment which 
tim@906: 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@906:                        description="Artiefactfactory 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: 




