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

comparison doc/config-manual/model_of_transitions.tex @ 947:9a28846dfb9c

Final QS for V1.0 doc/trunk@1091 c6561f87-3c4e-4783-a992-168aeb5c3f6f

author	Hans Plum <hans.plum@intevation.de>
date	Wed, 12 May 2010 11:35:25 +0000
parents	491b8d6cd291
children	975bb59bb136

comparison

equal deleted inserted replaced

-:dd6102eae823
+:9a28846dfb9c
 \item FIS and their according products (Metainformation)
 \item Products with their states, transitions, outputs and SQL-statements
 (Implementation)
 \end{enumerate}
-%% TODO: Add a Screenshot of the GNV WebClient marking GUI elements for FIS,
+%% 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.
 (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{Explaining the background of the XML configuration}
+\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 gone until a product can be create
+to manipulate the steps which must be prepared until products like
-a diagram or generate an CSV-export.
+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}
 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 {\tt artifact-factory} represents one FIS.
+Each artifact-factory represents one FIS.
-It is possible to configure several {\tt artifact-factories}.
+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
-{\tt /artifact-database/artifact-factories} of the configurationfile.
+{\tt /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.
+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
+\item {\tt ttl}: The time to live: The time using milliseconds an
-factory, can live without any user-interaction.
+{\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.
 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.
-\paragraph{Products to an FIS}
+\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}
 value="fis\_marnet"/>
 </parameters>
 </product>
 \end{lstlisting}
-Each {\tt product} is also represented by an {\tt artifact}. To create this {\tt artifact} we have to
+Each {\tt product} is also represented by an {\tt artifact}. In order to
-use an {\tt artifact-factory} which is configured in each product
+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}).
+Each product can have several parameters ({\tt
-The {\tt parameter} named {\tt sourceid} and {\tt fisname} are required parameters.
+/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 fisname} contains the key to the name of the FIS. The
-The parameter {\tt sourceid} contains the key to identify the FIS in the
+key must be unique.  The parameter {\tt sourceid} contains the key to
-datawarehouse. ({\tt MEDIAN.SOURCEINFO})
+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
-configurationfile.
+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
 (Each entry replace one ore more "?" )
 \item They were used to validate the inputdata which is "feed" to
 the FIS in the current state.
 \end{itemize}
-WARNING: The order of the inputvalues is significant at which position the value will
+{\bf WARNING: The order of the input-values is significant at which position the value will
-be put into the SQL-statement.
+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}
 P.PARAMETERID = TS.PARAMETERID AND
 TSP.FEATUREID = ?
 ORDER BY P.GERMANNAME
 \end{lstlisting}
-If there are put the inputvalues in it it will look like this
+Including inputvalues, the example for choosing the FIS ({\tt fisname})
-if we assume that the inputvalues has got the following values
+and the Station 342 ({\tt featureid}: Arkona Basin Buoy) will look like
-which where feed by choosing this FIS ({\tt fisname}) and the Station
+this:
-({\tt featureid}: Arkona Basin Buoy ):
+\begin{itemize}
-\begin{itemize}
+\item {\tt featureid}: 100011 (Marnet $\rightarrow$ Arkona Basin Buoy)
-\item {\tt featureid}: 100011 (Marnet ==> 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}
 <inputvalue name="measurementid" type="Integer" multiselect="true" usedinquery="0"/>
 </inputvalues>
 \end{lstlisting}
 \begin{itemize}
-\item {\tt featureid}: 100011 (Marnet ==> Arkona Basin Buoy)
+\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}
 P.PARAMETERID IN (2)
 ORDER BY m.ZLOCATION DESC
 \end{lstlisting}
 The queries which are shown above are configurable.
-You can do this in the file {\tt queries.properties } which will
+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 ArcSDE}, because the {\tt ArcSDE} does not support the access to
+{\tt ESRI ArcSDE}-database. This mechanism is used to realize the access to spatial-
-spatial objects using the definition of the Simple Feature Specification for
-SQL of the OGC.
-It was necessary to implement this mechanism to realize the access to spatial-
 objects.
-All queries which contains the following literals will be handle separate
+All queries containing the following literals will be handled separatly
-using the {\tt ArcSDE-API}.
+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
 \end{itemize}
 \paragraph{Transitions}
-To move between two states it is necessary to configure dependencies between
+To move between two states it is necessary to configure dependencies
-the different states.
+between the different states.  This dependencies are called {\tt
-This dependencies are called {\tt transitions}.
+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.
 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 an special {\tt state} which was created to define
+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 an {\tt state} which is described above.
+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.
 \end{itemize}
 All these outputstates are implemented in {\tt package de.intevation.gnv.state}
 and its {\tt sub\-packages}.
-You have to put the fullqualified name of the {\tt outputstate} to the attribute
+The fullqualified name of the {\tt outputstate} to the attribute
-{\tt state} as shown below.
+{\tt state} is shown below.
-You can configure an {\tt outputstate} as 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>
 ...
 {\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 an special
+Inserting or deleting the configuration of a special
-{\tt outputmode} will cause that the pending item will be shown or hidden
+{\tt outputmode} will control if an item in the GUI will be displayed.
-in the {\tt GUI}.
+{\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}
 <export name="svg" description="SVG-Export der Daten" mime-type="image/svg+xml" />
 </exportModes>
 </outputsMode>
 \end{lstlisting}
-// TODO add simple OutputMode e.g. for CSV??
 \begin{itemize}
 \item {\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.
 GUI e.g. for changing the size of an chart.
 \item {\tt exportModes} : one or more formats which can be served.
 \end{itemize}
-\subsection{Adding a new FIS}
+\section{Adding a new FIS}
-In this section it will be explained which steps has to be done to integrate a
+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
-an FIS which use data from {\tt MEDIAN.TIMESERIES} section of the datawarehouse e.g.
+a FIS which uses data from the table {\tt MEDIAN.TIMESERIES} section of
-MARNET or STAUN
+the datawarehouse (e.g. MARNET or STAUN).
-Pay attention that for publishing the changes to the {\tt artifact-server} you will
+For publishing the changes to the {\tt artifact-server}, it needs to be
-have to restart it.
+restarted.
-\subsubsection{Adding a new Artifact-factory}
+\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'
+<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}
+\paragraph*{Example}
-This example shows how to add an FIS and which effects it took to the
+This example shows how to add a FIS and illustrates the effect on the
-REST-Server.
+artifact-server's output.
-At first we add the following {\tt artifact-factory} into the file
+First , the following {\tt artifact-factory} has to be added into the file
 {\tt conf/conf.xml} in section {\tt /artifact-database/artifact-factories}
-which add a new FIS called {\tt justanewfis} to the server:
+adding a new FIS called {\tt justanewfis} to the server:
 \begin{lstlisting}
-<artifact-factory name='fis\_justanewfis'
+<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}
-Then we restart the {\tt artifact-database} executing the following command:
+Restart the {\tt artifact-database} executing:
 \begin{lstlisting}
-/etc/init.d/artifactdb restart
+/etc/init.d/artifact-server restart
 \end{lstlisting}
-Then we check if the new FIS is served by the REST-Server
+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
+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
+If the FIS was added, the new {\tt artifact-factory} will be found in the generated
-XML-output and it will be shown.
+XML-output. Otherwise no XML-output will be shown.
-Otherwise no XML-output will be shown.
+\subsection{Adding a new Artifact for Artifact-factory}
-\subsubsection{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'>
+<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 useful way to clone an artifact
+To prevent needless configuration-work, it is a useful way to clone an
-which handle the same kind of work as the new FIS.
+existing artifact handling the same kind of work.
-\paragraph{Example}
+\paragraph*{Example}
-Now we will configure an artifact to the FIS justanewfis.
+Now will an artifact to the FIS {\tt fis\_justanewfis}, will be configured.
-For this we have to add the following XML-fragment to the file
+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'>
+<artifact name='fis_justanewfis'>
 <products>
 </products>
 </artifact>
 \end{lstlisting}
-Restart the artifact-database:
+Restart the artifact-server
 \begin{lstlisting}
-/etc/init.d/artifactdb restart
+/etc/init.d/artifact-server restart
 \end{lstlisting}
-Now we should be able to choose the artifact.
+Now it should be possible to choose the artifact.
-The Listbox with products will be empty.
+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}
-\subsubsection{Adding removing Products to the specific Artifact}
+\subsection{Adding/Removing Products to the Specific Artifact}
-Now it is time to configure the different products which the FIS should be able
+Next step is, to configure the different products which the FIS should
-to provide.
+be able to provide.  To do this it is necessary to copy the
-To do this it is necessary to copy the XML-fragments of the products into the
+XML-fragments of the products into the XML-element {\tt products} of the
-XML-element {\tt products} of the previously integrated artifact.
+previously integrated artifact.
-\begin{lstlisting}
-<artifact name='fis\_NEWFISNAME'>
+\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"
 </product>
 </products>
 </artifact>
 \end{lstlisting}
-In this XML-fragment you have to replace the placeholders {\tt NEWFISNAME}
+In this XML-fragment the placeholders {\tt NEWFISNAME} have to be
-as before and {\tt VALUEOFSOURCEID} with the value for the new FIS as defined
+replaced. The source-id {\tt VALUEOFSOURCEID} with the value for the new
-in the table {\tt MEDIAN.SOURCEINFO}.
+FIS as defined in the table {\tt MEDIAN.SOURCEINFO} needs to be added.
-\paragraph{Example}
+\paragraph*{Example}
-Now we will add a product to the new FIS.
+Adding a product to the new FIS, choosing sourceid of an existing FIS
-To let the products work we will choose a product which
+(e.g 4 $\rightarrow$ Marnet).
-will contain the sourceid of an existing FIS (e.g 4 Marnet).
+Add the following XML-fragment to the new artifact.
-At first 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"
 value="fis\_justanewfis"/>
 </parameters>
 </product>
 \end{lstlisting}
-Restart the artifact-database:
+Restart the artifact-server
 \begin{lstlisting}
-/etc/init.d/artifactdb restart
+/etc/init.d/artifact-server restart
 \end{lstlisting}
-If we call
+If
 \begin{lstlisting}
 curl -d "@sample-documents/create-artifact.xml"  http://localhost:8181/create | xmllint --format -
 \end{lstlisting}
-the product {\tt timeSeries} should be available for the FIS {\tt justanewfis}.
+is called, the product {\tt timeSeries} should be available for the FIS {\tt justanewfis}.
-Now we should be able to choose the product.
+Now, it should be able to choose the product.
-This product should work and you should be able to generate even the defined
+This product including the definied outputformats should be available in
-outputformats.
+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 separate files that will be included into the
+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 there in the
+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 you have tor reference this file in the file {\tt /conf/conf.xml} in the
+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"
 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 a additional Product to a FIS}
+\subsection{Adding an additional Product to a FIS}
-To add a additional product to a FIS you only have to add the XML-fragment which
+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}.
+{\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"
 value="fis\_NEWFISNAME"/>
 </parameters>
 </product>
 \end{lstlisting}
-Please note that you have to replace the Placeholders as explained above.
+Please note that the placeholders have to be explained above.

Mercurial > dive4elements > gnv-client

comparison doc/config-manual/model_of_transitions.tex @ 947:9a28846dfb9c