# HG changeset patch # User Hans Plum # Date 1273429193 0 # Node ID 2d84fc30ab583db9dbe2592c6781150d18d3f9fc # Parent 052b8bba4f41c6de3a1ed16ce9b4fb8357fdd649 Added more chapters in config-manual doc/trunk@1079 c6561f87-3c4e-4783-a992-168aeb5c3f6f diff -r 052b8bba4f41 -r 2d84fc30ab58 doc/ChangeLog --- 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 + + * 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 * general_settings.tex: diff -r 052b8bba4f41 -r 2d84fc30ab58 doc/config-manual/administering_artifact-server.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. diff -r 052b8bba4f41 -r 2d84fc30ab58 doc/config-manual/config-manual.tex --- 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} diff -r 052b8bba4f41 -r 2d84fc30ab58 doc/config-manual/general_settings.tex --- 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} diff -r 052b8bba4f41 -r 2d84fc30ab58 doc/config-manual/generating_charts.tex --- /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} diff -r 052b8bba4f41 -r 2d84fc30ab58 doc/config-manual/generating_maps.tex --- /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} diff -r 052b8bba4f41 -r 2d84fc30ab58 doc/config-manual/overview.tex --- /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}