# HG changeset patch
# User Tim Englich <tim.englich@intevation.de>
# Date 1258117261 0
# Node ID b198ca47f363febd79e124ddbfe89a849ebaae8d
# Parent  008709f796118484a5ee0b7a525f51018e5badad
Added Documentation of Configuration-Files

gnv-artifacts/trunk@334 c6561f87-3c4e-4783-a992-168aeb5c3f6f

diff -r 008709f79611 -r b198ca47f363 gnv-artifacts/ChangeLog
--- a/gnv-artifacts/ChangeLog	Fri Nov 13 09:57:25 2009 +0000
+++ b/gnv-artifacts/ChangeLog	Fri Nov 13 13:01:01 2009 +0000
@@ -1,5 +1,13 @@
 2009-11-13  Tim Englich  <tim.englich@intevation.de>
 
+	* doc/conf/log4j.properties,,
+	  doc/conf/conf.xml,
+	  doc/conf/arcsdeconnectionpool.properties,
+	  doc/conf/products/timeseries/conf_timeseriespoint.xml: 
+	  Added Documentation of Configuration-Files.
+
+2009-11-13  Tim Englich  <tim.englich@intevation.de>
+	
 	* doc/conf/products/verticalcrosssection/conf_mesh.xml,
 	  doc/conf/products/horizontalcrosssection/conf_mesh.xml:
 	  Removed statistics as possible out-Variant from Configuration
diff -r 008709f79611 -r b198ca47f363 gnv-artifacts/doc/conf/arcsdeconnectionpool.properties
--- a/gnv-artifacts/doc/conf/arcsdeconnectionpool.properties	Fri Nov 13 09:57:25 2009 +0000
+++ b/gnv-artifacts/doc/conf/arcsdeconnectionpool.properties	Fri Nov 13 13:01:01 2009 +0000
@@ -1,3 +1,24 @@
+###############################################################################
+###############################################################################
+# In this File it is possible to configure the Connectionpool to the the 
+# ArcSDE-DataBackend.
+# maxActive: Number of maximal Connection which can be used.
+# testOnBorrow: Should the Pool test the Connection which will be borrowed
+#               if it is Valid
+# testOnReturn: Should the Pool test the Connection which will be returned
+#               if it is Valid
+# testWhileIdle: Should the Pool test the Connection while it is Idl
+#                if it is Valid
+# timeBetweenEvictionRunsMillis : Time in Milliseconds which is allowed
+#                                 to reused a returned Connection.
+# server: The URL of the Server where the Database is reachable.
+# username: The Username which should be used to Connect to the Databackend.
+# credentials: The Credentials to the given username
+# port: The Communicationport which must be used to connect to the Databackend
+# database: The Name of the Instance which should be connected to.
+###############################################################################
+###############################################################################
+
 maxActive=2
 testOnBorrow=true
 testOnReturn=false
diff -r 008709f79611 -r b198ca47f363 gnv-artifacts/doc/conf/conf.xml
--- a/gnv-artifacts/doc/conf/conf.xml	Fri Nov 13 09:57:25 2009 +0000
+++ b/gnv-artifacts/doc/conf/conf.xml	Fri Nov 13 13:01:01 2009 +0000
@@ -36,6 +36,10 @@
                               ttl="300000" artifact="de.intevation.gnv.artifacts.fis.FISArtifact">de.intevation.artifactdatabase.DefaultArtifactFactory</artifact-factory>
         </artifact-factories>
     </factories>
+    
+    <!--  Artifacts which represent one FIS. Each FIS can have several Products 
+          which will be Access using separate Artifacts.
+          Those Artifacts are configured below these Section.-->
     <artifacts>
         <artifact name="fis_marnet">
             <products>
@@ -353,6 +357,11 @@
             </products>
         </artifact>
         
+        <!--  Product specific Artifacts which are referenced by the Artifacts
+              of the FIS above.
+              The product-Artifacts can be configured here or can be referenced
+              using an xlink:href-Attribute. -->
+              
         <artifact name="timeSeries" xlink:href="${artifacts.config.dir}/products/timeseries/conf_timeseriespoint.xml" />
         <artifact name="timeSeriesMesh" xlink:href="${artifacts.config.dir}/products/timeseries/conf_mesh.xml" />
         
@@ -368,13 +377,21 @@
         <artifact name="horizontalCrossSectionMesh" xlink:href="${artifacts.config.dir}/products/horizontalcrosssection/conf_mesh.xml" />
     </artifacts>
     <ehcache>
+        <!--  In this Section the Path to Configurationfile for the EHCache,
+              which is unsed to store the Results of the Artifacts ,
+              is given.-->
         <configuration>${artifacts.config.dir}/ehcache.xml</configuration>
     </ehcache>
     <geo-backend>
+        <!--  In this Section the required Configuration for the geo-backend is
+              given. It is possible to configue the Path of the  ConnectionPool-
+              Properties and the Query-Properties-File where all required 
+              Queries of the System are stored. -->
         <backend-configuration>${artifacts.config.dir}/arcsdeconnectionpool.properties</backend-configuration>
         <query-configuration>${artifacts.config.dir}/queries.properties</query-configuration>
     </geo-backend>
     <rest-server>
+        <!--  at this Point it is possible to Change the Port the ArtifactDatabase will bind to.-->
         <port>8181</port>
     </rest-server>
     <!-- garbage collection of outdated artifacts -->
diff -r 008709f79611 -r b198ca47f363 gnv-artifacts/doc/conf/log4j.properties
--- a/gnv-artifacts/doc/conf/log4j.properties	Fri Nov 13 09:57:25 2009 +0000
+++ b/gnv-artifacts/doc/conf/log4j.properties	Fri Nov 13 13:01:01 2009 +0000
@@ -1,3 +1,11 @@
+###############################################################################
+# Developmentconfiguration for the Loggingengine.
+# The Configuration will only log the Information to the Console.
+# For Test- and Productionenviroment it is necessary to create a
+# separate Configuration which will be log the Informations e.g. into
+# a File (RolingFileAppender).
+###############################################################################
+
 # Set root logger level to DEBUG and its only appender to A1.
 log4j.rootLogger=DEBUG, A1
 
diff -r 008709f79611 -r b198ca47f363 gnv-artifacts/doc/conf/products/timeseries/conf_timeseriespoint.xml
--- a/gnv-artifacts/doc/conf/products/timeseries/conf_timeseriespoint.xml	Fri Nov 13 09:57:25 2009 +0000
+++ b/gnv-artifacts/doc/conf/products/timeseries/conf_timeseriespoint.xml	Fri Nov 13 13:01:01 2009 +0000
@@ -1,19 +1,77 @@
 <?xml version="1.0" encoding="UTF-8"?>
+<!--  This is the Artifact which represents the required Businesslogic to
+      collect the required Data for rendering specified OutputFormats
+      for TimeSeries on TimeSeriesPoint-Data.
+      * Charts
+      * Statistics
+      * CSV
+      * ODV -->
 <artifact name="timeSeries">
     <transitions>
+        
+        <!--  The required Transitionsteps which must be done until rendering
+              the OutputFormats. Each Transition is represented one required 
+              Step. One Steps can consume specified InputParameters an after 
+              that it can calculate new Data which will be used as possible 
+              InputValues in the next Transition-Step from each Transition it 
+              is only possible to move to those Transitions which are Configured 
+              in the rechableTransitions-Tag  -->
+              
+         <!-- Description of the Transition-Attributes:
+              * id: The id of the Transition. This must be unique in one Artifact.
+                    It is used to reference the Transition eg. in 
+                    reachableTransitions.
+              * description: A short description which should describe the Transition
+              * transition: The Class which must be load to handle the required logic,
+                            This class will be load using reflection. -->
+              
         <transition id="timeseries_area" description="timeseries_area_one" transition="de.intevation.gnv.transition.DefaultTransition">
+            
+            <!-- The QueryID which identifies the Query which is configured in 
+                 the Queries-Properties-File.
+                 It is possible to define no Query. 
+                 In this case you have to remove this Element from the 
+                 Configuration.-->
             <queryID>area_filter</queryID>
+            
+            <!-- The ID of the Data which will be fetched using this Transition.
+                 The Name must be unique in one Artifact.
+                 The Name is used for the localization and must be set into the
+                 several PropertiesFiles for the localization.  -->
             <dataname>areaid</dataname>
+            
+            <!-- This Flag will be used to switch between single and
+                 multiselect possibility of the Data which will be fetched 
+                 using this transition.  -->
             <data-multiselect>false</data-multiselect>
-             <data-noselect>true</data-noselect>
+            
+            <!-- Optional Flag which can be used to set that is is possible 
+                 to select no entry in the Data which will be fetched using
+                 this transition. -->
+            <data-noselect>true</data-noselect>
+            
             <reachableTransitions>
+                   <!-- reachableTransitions are those Transition which can be
+                        reached as next Step. The Transition notifies in 
+                        describe-output which Transitions can be reached.
+                        The User / calling program can choose which Transition 
+                        he/it wants to use next  -->
                    <transition>timeseries_subarea</transition>
             </reachableTransitions>
+            
             <inputvalues>
+                <!-- At this place it is necessary to configure the Elements
+                     which must be feed and can be used in this transition.
+                     It is possible to set if the Values should be used in 
+                     the DatabaseQuery of this Transition and how often it
+                     must be used.
+                     The order of the Elements is also the Order of usage setting
+                     the Values into the SQL-Query. -->
                 <inputvalue name="sourceid" type="Integer" multiselect="false" usedinquery="0"/>
                 <inputvalue name="fisname" type="String" multiselect="false" usedinquery="0"/>
             </inputvalues>
         </transition>
+        
         <transition id="timeseries_subarea" description="timeseries_subaera" transition="de.intevation.gnv.transition.DefaultTransition">
             <queryID>subarea_filter</queryID>
             <dataname>subareaid</dataname>
@@ -22,6 +80,9 @@
                    <transition>timeseries_timeseriespoint</transition>
             </reachableTransitions>
             <alternativeTransition>
+                <!-- It is possible  to configure an alternative Transition which 
+                     will be used if the feed put the Information that no Data 
+                     was selected. -->
                 <transition id="timeseries_without_geom" description="timeseries_mesh_without_geom" transition="de.intevation.gnv.transition.DefaultTransition">
                     <queryID>timeseries_timeseriespoint</queryID>
                     <dataname>featureid</dataname>
@@ -96,6 +157,9 @@
             </inputvalues>
         </transition>
         
+        <!--  Last Transition is the Output-Transition. At this place the differen OutputModes are configured.
+              For each OutputMode it might be necessary to configure separat Databasequery which collect the
+              Data. -->
         <transition id="timeseries_calculate_results" description="timeseries_interval" transition="de.intevation.gnv.transition.timeseries.TimeSeriesOutputTransition">
             <queryID>timeseries_chart_data</queryID>
             <queryID-odv>timeseries_odv_data</queryID-odv>
@@ -117,6 +181,8 @@
                 <outputsMode name="odv" description="ODV-Export der Daten" mime-type="text/plain"/>
                 <outputsMode name="statistics" description="Statistik zu den Daten" mime-type="text/xml"/>
             </outputsModes>
+            <!--  Definition of the TimeGaps which are required to render the Charts properly.
+                  each Parameter in each FIS can have   -->
             <time-gap-definition xlink:href="${artifacts.config.dir}/products/timeseries/timegap_definition.xml" />
         </transition>