dive4elements/gnv-client: doc/config-manual/model_of

comparison doc/config-manual/model_of_transitions.tex @ 949:11d8cc2deb92 1.0

merged doc/1.0

author	Thomas Arendsen Hein <thomas@intevation.de>
date	Fri, 28 Sep 2012 12:13:58 +0200
parents	975bb59bb136
children

comparison

equal deleted inserted replaced

-:3f9fc88aec2b
+:11d8cc2deb92
+\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.

Mercurial > dive4elements > gnv-client

comparison doc/config-manual/model_of_transitions.tex @ 949:11d8cc2deb92 1.0