--- a/doc/ChangeLog	Fri May 07 10:19:28 2010 +0000
+++ b/doc/ChangeLog	Sun May 09 18:19:53 2010 +0000
@@ -1,3 +1,27 @@
+2010-05-09  Hans Plum <hans@intevation.de>
+
+	* config-manual/config-manual.tex:
+	referenced new documents
+
+	* config-manual/overview.tex (added):
+	introduction/overview of the GNV-server consisting of
+	artifact- and mapserver
+
+	* config-manual/general_settings.tex:
+	overview of the entire configuration
+
+	* config-manual/generating_maps.tex (added),
+	config-manual/generating_charts.tex (added),
+	config-manual/administering_artifact-server.tex (added):
+	split up in typical tasks:
+	    - administration and installation
+	    - generating charts (TODO: Fill me)
+	    - generating maps (TODO: Fill me)
+	    - configuring fis, products, etc. (TODO: Integrate me)
+
+	* config-manual/config-manual.txt:
+	Added some hints
+
 2010-05-07  Tim Englich  <tim@intevation.de>
 
 	* general_settings.tex:

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/config-manual/administering_artifact-server.tex	Sun May 09 18:19:53 2010 +0000
@@ -0,0 +1,102 @@
+\subsection{Configuring and Running the Artifact-Server}
+
+This section describes the possibilities to configure the
+artifact-server. The following properties do affect mostly technical
+funtions of the server.
+
+This section describes the possibilities in a kind of a reference
+manual. Information for the process of installing and integration can be
+found in the Administration Manual of the GNV-System (FIXME reference).
+The following elements are covered here:
+
+\begin{lstlisting}
+artifact-database
+|-- geo-backend # pointing to database connection, SQL configuration
+|-- rest-server # port, listen addresses
+|-- database # internal database storing artifacts
+|-- ehcache # pointing to cache configuration
+|-- cleaner # time of cleanups FIXME
+`-- export-secret # signing project files
+\end{lstlisting}
+
+\paragraph*{geo-backend}
+{\em Function}: The geo-backend encapsulates the logic for accessing the database
+backend. At this time, the use of ESRI ArcSDE 9.3.1 is supported.
+
+At least, the following options for configuring the element {\tt
+geo-backend} are required:
+
+\begin{itemize}
+    \item {\tt backend-configuration}: path to the file defining the
+    connection properties to the database backend, preconfigured to {\tt
+    arcsdeconnection.properties}. Normally, just the
+    connection parameters have to de adapted. Further information can be
+    found in the file itself.
+
+    \item {\tt query-configuration}: path to the file listing a SQL
+    statements, preconfigured to {\tt queries.txt}. Further information can be
+    found at FIXME.
+\end{itemize}
+
+
+\paragraph*{rest-server}
+{\em Function}: The REST-Server needs a HTTP binding configured via:
+
+\begin{itemize}
+    \item {\tt port}: port the server should listen on. Preconfigured on
+    8181.
+    \item {\tt listen}: for security reason the accessibility can be
+    limited. The parameter needs an IP-address or a hostname.
+    Accessibility to the entire network can be done by
+    removing/commenting out of the element.
+\end{itemize}
+
+
+\paragraph*{database}
+{\em Function}: The internal database of the system for storing
+artifacts representing a parameterisation of a client session. So fare,
+the filebased database H2 is supported. Connecting to other backends can
+be provided.
+
+\begin{itemize}
+    \item {\tt user}: database user for connecting to the
+    artifact-database. In new installations "SA" is used.
+    \item {\tt password}: password of the database user for
+    authentification.
+    \item {\tt url}: Connection URL to the database-files.
+    In the preconfiguration, they are written to
+    \verb| ${artifacts.config.dir}/../artifactdb|
+\end{itemize}
+
+
+\paragraph*{ehcache}
+{\em Function}: The cache for storing result sets of the database. The
+configuration in {\tt ehcache.xml} should not been adapted. Changing has
+at least consequence to the system requirements.
+
+\begin{itemize}
+    \item {\tt configuration}: the path to the configuration file.
+    Preconfigured: \verb+${artifacts.config.dir}/ehcache.xml+
+\end{itemize}
+
+
+\paragraph*{cleaner}
+{\em Function}: Process for cleaning up the artifact-database. Artifacts
+have a time-to-life. Died artifacts need to be removed. Changing the
+interval has consequences to the size of the database.
+
+\begin{itemize}
+    \item {\tt sleep-time}: Time interval in milliseconds between 2
+    checks. Preconfigured: 60000 (1 minute)
+\end{itemize}
+
+
+\paragraph*{export-secret}
+{\em Function}: Signature for signing project files that were created by
+the artifact-server instance. Before reading a projectfile the server
+checks the file against that signature/check sum.
+
+{\bf Be aware, changing the signature of updating the source code of
+artifacts will prevent of using existing project-files.}
+
+For setting up the secret, c.f. the tips in the admin manual.

--- a/doc/config-manual/config-manual.tex	Fri May 07 10:19:28 2010 +0000
+++ b/doc/config-manual/config-manual.tex	Sun May 09 18:19:53 2010 +0000
@@ -194,7 +194,11 @@
 \include{title}
 \newpage
 \tableofcontents
+\include{overview}
 \include{general_settings}
+\include{administering_artifact-server}
+\include{generating_charts}
+\include{generating_maps}
 \include{model_of_transitions}
 
 \end{document}

--- a/doc/config-manual/general_settings.tex	Fri May 07 10:19:28 2010 +0000
+++ b/doc/config-manual/general_settings.tex	Sun May 09 18:19:53 2010 +0000
@@ -1,34 +1,100 @@
-\section{General Settings}
-\subsection{Structure of Configurationfile}
-The Configuration of the Artifact-Server will generally be done in one single
-File. This file is called conf.xml and is stored in the folder conf of the 
-Artifact-Server.
+\section{Configuring the GNV-Server}
+
+The configuration of the artifact- and mapserver is been done in the
+central configuration directory at {\tt artifact-server/conf/}. The
+central entry point is the file {\tt conf.xml}. All components of the
+configuration are linked from this document. 
+
+{\bf Within the configuration the key 
+{\verb+${artifacts.config.dir}+} can be used to reference the central
+configuration directory of the artifact-server instance, e.g. 
+{\tt /opt/artifact-server}.}
+
+The following structure gives an overview of the entire structure
+starting from {\tt conf/}:
+
+%% tree /opt/artifact-server/
+\begin{lstlisting}
+conf/
+|-- arcsdeconnectionpool.properties # database connection
+|-- charttemplate.xml # general properties for chart generation
+|-- conf.xml # central configuration
+|-- ehcache.xml # configuration of caching system
+|-- log4j.properties # logging of server
+|-- maptemplates # style defintions for rendering maps
+|   `-- *.vm
+|-- meshwidth.xml # buffer-size for querying different FIS on
+                  # meshes
+|-- palette # styling for 2D charts
+|   `-- *.xml
+|-- products # configuration of steps in workflows
+|   |-- horizontalcrosssection
+|   |   `-- *.xml
+|   |-- horizontalprofile
+|   |   `-- *.xml
+|   |-- layer
+|   |   `-- *.xml
+|   |-- timeseries
+|   |   |-- *.xml
+|   |   `-- timegap_definition.xml # definition of a gap depending FIXME
+|   |-- verticalcrosssection
+|   |   `-- *.xml
+|   `-- verticalprofile
+|       `-- *.xml
+`-- queries.properties # SQL configuration according to products
+\end{lstlisting}
+
+
+The central config-file {\tt conf/conf.xml} is XML-based and contains the
+following main elements:
+
+\begin{lstlisting}
+artifact-database
+|-- geo-backend # pointing to database connection, SQL configuration
+|-- rest-server # port, listen addresses
+|-- database # internal database storing artifacts
+|-- ehcache # pointing to cache configuration
+|-- cleaner # time of cleanups FIXME
+|-- export-secret # signing project files
+|-- factories # list of expert information systems
+|-- artifacts # list of products
+|-- gnv # charts, palettes, interpolation parameters
+|-- mapserver # integration of mapserver
+`-- velocity # templating language used in maptemplates
+\end{lstlisting}
+
+The documentation of the configuration will be split up in 4 sections
+addressing different tasks:
+\begin{enumerate}
+    \item "Configuring and Running Artifact-Server" covering the main elements {\tt
+geo-backend, rest-server, database, ehcache, cleaner, export-secret}
+    \item "Generating Charts -- Background and Configuration" covering
+    the main element {\tt gnv}
+    \item "Generating Maps -- Background and Configuration" covering the
+    main elements {\tt mapserver, velocity}
+    \item "Configuring FIS, Products, States, Transitions and
+    SQL-Statements" covering the main elements {\tt factories,
+    artifacts}
+\end{enumerate}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 Some additional Configurations will be done using Systemproperties. This 
 Properties will be listed in the last Section of this chapter.
 
-The Configuration is modelled using XML.
-The main Structure of the XML-Document now will be explained:
-
-\begin{verbatim}
-artifact-database
-|--artifact-factories
-|--artifacts
-|--gnv
-|  |--charttemplate
-|  |--palettes
-|  |--horizontal-cross-section-profile
-|  |--horizontal-cross-section
-|  |--vertical-cross-section
-|  |--shapefile-directory
-|  `--map-generator
-|--mapserver
-|--velocity
-|--ehcache
-|--geo-backend
-|--rest-server
-|--cleaner
-`--database
-\end{verbatim}
 
 \subsubsection{artifact-factories}
 
@@ -40,69 +106,7 @@
 These Section configures the Artifacts which could be reached using the Artifact-Server.
 The meaning of artifacts are explained in Section TODO: LINK to Model of Transition
 
-\subsubsection{gnv}
-
-This Section configures all GNV-specific settings of the Artifact-Server.
-//TODO add paragraphs and explain the child-elements.
-
-\subsubsection{mapserver}
-
-The Section Mapserver is introduced to be able to configure all Settings which 
-are required to setup the WMS-Export of the GNV-Artifacts.
-
-It is possible to Configure the following settings:
-
-\begin{itemize}
-    \item server: The URL the WMS of the GNV-Artifacts will be reached from
-                  Clients.
-\end{itemize}
-
-\subsubsection{velocity}
-
-Velocity is an Library which is used in this Project.
-Velocity has it's own Logging, so that it is necessary to configure
-this to get Loginformations.
-
-\begin{itemize}
-    \item logfile: The absolute Path to the Logfile of Velocity.
-\end{itemize}
-
-\subsubsection{ehcache}
 
-The Ehcache is used to implement an Cache storing the Thematic-Data of the
-different Sessions.
-
-It is possible to configure this Cache in many ways. To realize this it is
-possible to configure the following settings:
-
-\begin{itemize}
-    \item configuration: The absolute Path to the Configuration-File.
-                         It is possible to start with \$\{artifacts.config.dir\}
-                         to reference the file from the Directory which includes
-                         the Configuration
-\end{itemize}
-
-
-\subsubsection{geo-backend}
-
-The geo-backend is an separate Module of this Project. It encapsulate the logic
-which is required to provide the Access to the Databasebackend.
-At this Time only the Access to the ArcSDE is implemented.
-
-To setup the geo-backend the following settings are required:
-
-\begin{itemize}
-    \item backend-configuration: The absolute Path to the File which contains the
-                                 properties to establish the Connection to the 
-                                 Databasebackend.
-    \item query-configuration: The absolute Path to the File which contains all
-                               SQL-Statements which are required to fetch the
-                               Thematic-Data
-\end{itemize}
-
-Both Path can start with \$\{artifacts.config.dir\} to reference the file from 
-the Directory which includes the Configuration.
-\paragraph{Backend-Configuration (arcsdeconnectionpool.properties)}
 
 \paragraph{Query-configuration (queries.properties)}
 
@@ -127,12 +131,6 @@
                                  replace with an WKT) 
 \end{itemize}
 
-\subsubsection{rest-server}
-\subsubsection{cleaner}
-\subsubsection{database}
-
-
-\subsection{Set the Communicationport}
 \subsection{Logging}
 \subsection{Configure ArtifactServer using Systemproperties}
 \begin{itemize}

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/config-manual/generating_charts.tex	Sun May 09 18:19:53 2010 +0000
@@ -0,0 +1,51 @@
+\subsection{Generating Charts -- Background Information and Configuration}
+
+%% This section describes the possibilities to configure the
+%% artifact-server. The following properties do affect mostly technical
+%% funtions of the server.
+%% 
+%% This section describes the possibilities in a kind of a reference
+%% manual. Information for the process of installing and integration can be
+%% found in the Administration Manual of the GNV-System (FIXME reference).
+%% The following elements are covered here:
+
+\begin{lstlisting}
+artifact-database
+`-- gnv # charts, palettes, interpolation parameters
+    |-- charttemplate
+    |-- palettes
+    |-- horizontal-cross-section-profile
+    `-- vertical-cross-section
+\end{lstlisting}
+
+\paragraph*{charttemplate}
+{\em Function}: 
+
+\begin{itemize}
+    \item {\tt }:
+\end{itemize}
+
+
+\paragraph*{palettes}
+{\em Function}: 
+
+\begin{itemize}
+    \item {\tt }:
+\end{itemize}
+
+
+\paragraph*{horizontal-cross-section-profile}
+
+{\em Function}: 
+
+\begin{itemize}
+    \item {\tt }:
+\end{itemize}
+
+
+\paragraph*{vertical-cross-section}
+{\em Function}: 
+
+\begin{itemize}
+    \item {\tt }:
+\end{itemize}

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/config-manual/generating_maps.tex	Sun May 09 18:19:53 2010 +0000
@@ -0,0 +1,57 @@
+\subsection{Generating Maps-- Background Information and Configuration}
+
+%% TODO: principle of generating maps
+
+%% This section describes the possibilities to configure the
+%% artifact-server. The following properties do affect mostly technical
+%% funtions of the server.
+%% 
+%% This section describes the possibilities in a kind of a reference
+%% manual. Information for the process of installing and integration can be
+%% found in the Administration Manual of the GNV-System (FIXME reference).
+%% The following elements are covered here:
+
+\begin{lstlisting}
+artifact-database
+|-- gnv # charts, palettes, interpolation parameters
+|   |-- map-generator 
+|   |-- shapefile-directory
+|   `-- horizontal-cross-section
+|-- mapserver
+`-- velocity
+\end{lstlisting}
+
+\paragraph*{}
+{\em Function}: 
+
+\begin{itemize}
+    \item {\tt }:
+\end{itemize}
+
+\paragraph*{}
+{\em Function}: 
+
+\begin{itemize}
+    \item {\tt }:
+\end{itemize}
+
+\paragraph*{}
+{\em Function}: 
+
+\begin{itemize}
+    \item {\tt }:
+\end{itemize}
+
+\paragraph*{}
+{\em Function}: 
+
+\begin{itemize}
+    \item {\tt }:
+\end{itemize}
+
+\paragraph*{}
+{\em Function}: 
+
+\begin{itemize}
+    \item {\tt }:
+\end{itemize}

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/config-manual/overview.tex	Sun May 09 18:19:53 2010 +0000
@@ -0,0 +1,86 @@
+\section{Overview of the GNV-Server}
+
+\subsection{Tasks and Components of the GNV-Server}
+
+The GNV-server is a middleware-component and consists of two functional
+components:
+\begin{enumerate}
+    \item artifact-server -- providing access to the database and
+    managing the users' workflow to the GNV-WebClient
+    \item mapserver -- providing user-generated maps. Mapserver is
+    controlled by the artifact-server.
+\end{enumerate}
+
+The central concept of the artifact-server is to model the workflow of
+users by the following steps:
+\begin{enumerate}
+    \item selection of data (parameterization)
+    \item processing of result sets (interpolation, clipping)
+    \item exporting processed result sets (charts, statistics, raw data)
+\end{enumerate}
+
+Within the artifact-server, these steps are supported by the following
+core components for the entire GNV-system.  The naming refers to
+components used in the configuration. In order to simplify a first
+orientation in the configuration and this manual, the XML-tags/words in
+the central configuration file at {\tt conf/conf.xml} are used. They are
+marked in {\tt typewriter} style:
+
+\begin{itemize}
+   \item {\tt geo-backend} -- access to the database backend
+   \item {\tt rest-server} -- providing a RESTful-Interface with a
+   XML-based protocol to serve the expert information systems (FIS) with
+   their products to different clients, e.g. GNV WebClient
+   \item {\tt factories/*}, {\tt artifacts/*} --  managing the steps and
+   operations of users' workflow for all expert information
+   systems (FIS)
+   \item {\tt gnv} -- processing pipeline providing results of the
+   products with the following subtasks:
+     \begin{itemize}
+       \item processing of result sets like interpolation, clipping 
+       \item visualization of charts and maps
+       \item exporting selected raw data
+     \end{itemize}
+   \item {\tt mapserver} -- managing the Web Map Service for creating maps
+   dynamically
+\end{itemize}
+
+Each component has a specific configuration for its functionality and
+subsystems. 
+
+\subsection{Internal Structure of the GNV-Server}
+
+\subsubsection{Internal Structure of Artifact-Server}
+Per default the artifact-server can be found at {\tt
+/opt/artifact-server}\footnote{Information about installation and
+operation can be found in the admin-manual.}. The internal directory
+structure of the artifact-server looks like this:
+
+%% tree /opt -d -L1
+\begin{lstlisting}
+artifact-server
+|-- artifactdb # storing artifacts in a database
+|-- bin # binaries including all libraries
+|-- cache # storage for cached data (e.g. result sets)
+|-- conf # central configuration of artifact-server
+|-- install # files for system integration (just for setup)
+|-- mapfiles # generated configurations for map-server (done by
+             # map-generator)
+`-- shapefiles # raw data for map generating (done by map-generator)
+\end{lstlisting}
+
+
+\subsubsection{Internal Structure of Mapserver}
+Per default the mapserver can be found at {\tt
+/usr/lib/cgi-bin}.\footnote{Information about installation and
+operation can be found in the admin-manual.} The internal structure of
+the mapserver looks like this:
+
+%% tree /usr/lib/
+\begin{lstlisting}
+cgi-bin/
+|-- gnv-wms # wrapper pointing to the configuration (default:
+            # artifact-server/mapfiles/mapfile.map), invoked by
+            # webserver
+`-- mapserv-gp # binary of mapserver, invoked by wrapper
+\end{lstlisting}