change: improve structure and documentation of properties

SVN: 7411

datamover/dist/etc/service.properties

 #
-# Mandatory
+# Incoming target
 #
 
-# The directory where the data producer writes to.
-# incoming-target = [<host-name>:]<dir-path>
+# The directory where the data producer writes data items to.
+# Syntax: incoming-target = [<host-name>:[<rsync-module>:]]<dir-path>
+# * If you set a <host-name> and a <dir-path> it will be assumed that the target is a directory on a 
+#   remote host that has an accessible ssh server and that this host is allowed to connect to.
+# * If you set a <host-name>, an <rsync-module> and a <dir-path>, it will be assumed that that the 
+#   target is a directory on a remote host that has an accessible ssh server and an accessible rsync 
+#   server that this host is allowed to connect to.     
+# Note that setting the <rsync-module> still required an ssh connections for some operations, so
+# setting this parameter just means that the bulk transfer is using the rsync server.   
 incoming-target = data/incoming
 
+# The string prepended to incoming data sets. '%t' will be replaced with the current time. 
+prefix-for-incoming = %t_
+
+# When set to <true>, then the incoming directory will be treated as a mounted remote directory.
+# This is only relevant when the incoming-target does not contain a <host-name> (which makes it 
+# explicit that the incoming target is remote).
+#treat-incoming-as-remote = <true or false> 
+
+#
+# Buffer
+#
+
 # The local directory to store the paths to be transfered temporarily
 buffer-dir = data/buffer
 
 # If free disk space goes below value defined here, a notification email will be sent.
-# Value must be specified in kilobytes (1048576 = 1024 * 1024 = 1GB). If no high water mark is
-# specified or if value is negative, the system will not be watching.
+# Value must be specified in kilobytes (1048576 = 1024 * 1024 = 1GB).
+# Comment this out or set it to a negative value in order to disable the high-water mark feature 
+# for the buffer.
 buffer-dir-highwater-mark = 1048576
 
+#
+# Outgoing target
+#
+
 # The remote target to move the data to.
 # Syntax: outgoing-target = [<host-name>:[<rsync-module>:]]<dir-path>
-# remote filesystem.
-# If you set a <host-name> and a <dir-path> it will be assumed that the target is a directory on a 
-# remote host that has an accessible ssh server and that this host is allowed to connect to.
-# If you set a <host-name>, an <rsync-module> and a <dir-path>, it will be assumed that that the 
-# target is a directory on a remote host that has an accessible ssh server and an accessible rsync 
-# server that this host is allowed to connect to.     
-# Not that setting the <rsync-module> still required an ssh connections for some operations, so
+# * If you set a <host-name> and a <dir-path> it will be assumed that the target is a directory on a 
+#   remote host that has an accessible ssh server and that this host is allowed to connect to.
+# * If you set a <host-name>, an <rsync-module> and a <dir-path>, it will be assumed that that the 
+#   target is a directory on a remote host that has an accessible ssh server and an accessible rsync 
+#   server that this host is allowed to connect to.     
+# Note that setting the <rsync-module> still required an ssh connections for some operations, so
 # setting this parameter just means that the bulk transfer is using the rsync server.   
 outgoing-target = data/outgoing
 
-# outgoing-target-highwater-mark = 1048576
+# If free disk space goes below value defined here, a notification email will be sent.
+# Value must be specified in kilobytes (1048576 = 1024 * 1024 = 1GB). 
+# Comment this out or set it to a negative value in order to disable the high-water mark feature
+# for the outgoing directory.
+outgoing-target-highwater-mark = 1048576
 
-# The local directory to store paths that need manual intervention
+#
+# Optional feature: handshake on incoming data 
+#
+
+# Path to the script file that will be executed to check whether an incoming data item is already 
+# complete or not.
+#data-completed-script = <path to script> 
+
+# Timeout (in seconds) for the data-completed-script. If the script exceeds this timeout, it will 
+# be killed and an error is reported. 
+#data-completed-script-timeout = <timeout in seconds> 
+
+#
+# Optional feature: manual intervention handling
+#
+
+# The local directory to store paths that need manual intervention (mandatory, but only used when 
+# manual-intervention-regex is set 
 manual-intervention-dir = data/manual_intervention
 
-prefix-for-incoming = %t_
+# Regular expression of paths that need manual intervention, default prefix-for-incoming 
+# corresponds to regex '[0-9]{14}_'
+# Set this to enable manual intervention checking.
+#manual-intervention-regex = <regex of paths that need manual intervention, default prefix-for-incoming corresponds to '[0-9]{14}_'>
 
 #
-# Optional (remove comments when changing the values)
-#
-
-# rsync-executable = <path to rsync>
-# hard-link-executable = <path to ln for creating hard links> (only matters if use-rsync-for-extra-copies is set to false)
-# Specify only when using an ssh tunnel:
-#   incoming-host-find-executable = <path on the remote incoming host to the GDU find executable>
-#   outgoing-host-find-executable = <path on the remote outgoing host to the GDU find executable>
-# check-interval = <time interval between two checks in seconds>
-# check-interval-internal = <time interval between two checks for the internal queues in seconds>
-# inactivity-period = <time period before a copy process is considered stalled in seconds>
-# quiet-period = <time period that a path (file or directory)  in incoming is required to be "quiet" before it is copied in seconds>
-# failure-interval = <time interval to wait after a failure before the operation is re-tried in seconds>
-# max-retries = <maximal number of retries when an operation fails>
-# cleansing-regex = <regex of paths that should be removed before moving a path to outgoing>
-# manual-intervention-regex = <regex of paths that need manual intervention, default prefix-for-incoming corresponds to '[0-9]{14}_'>
-# treat-incoming-as-remote = <true or false, when switched on, than incoming directory is treated as remote> 
-# extra-copy-dir = <path to a directory. If specified, a copy of incoming data will be made there>
-# use-rsync-for-extra-copies = false, if ln should be called on each file individually to create an extra copy
-# prefix-for-incoming = prefix that is put in front of every incoming data directory, %t will be replaced with time stamp
-# data-completed-script = script executed to check whether incoming data are complete or not
-# data-completed-script-timeout = timeout in seconds for data completed script if it doesn't stop 
+# Optional feature: data cleansing
+#
+
+# The regular expression of paths that should be removed before moving an item to outgoing
+#cleansing-regex = <regex>
+
+#
+# Optional feature: creation of an extra (immutable) copy on the Datamover server for processing
+#
+
+# The (local) directory in which an extra copy of each incoming data item will be created.
+# The copy needs to be treated immutable, i.e. it may be read and deleted, but not changed!
+#extra-copy-dir = <path>
+
+#
+# Timing parameters
+#
+
+# The time period (in seconds) that an incoming data item needs to be 'quiet' (i.e. no write 
+# access is sensed on it) before moving it to the buffer will start.
+#quiet-period = <time period in seconds>
+
+# Time interval (in seconds) between two checks for incoming data.
+#check-interval = <time interval in seconds>
+
+# Time interval (in seconds) between two checks on the buffer directory.
+# (You will probably not want to change this.)
+#check-interval-internal = <time interval in seconds>
+
+# Time period (in seconds) without any write activity on the target before a copy process is 
+# considered stalled.
+#inactivity-period = <time period before a copy process is considered stalled in seconds>
+
+# Time period (in seconds) to wait after a failure has occurred before the operation is re-tried.
+#failure-interval = <time period in seconds>
+
+# Maximal number of re-tries of a failed operation before giving up on it.
+#max-retries = <maximal number of retries>
+
+#
+# Explicitly set executables (leave blank to let Datamover find them itself)
+#
+
+# The path to the rsync executable. Only required if the first occurrence of rsync in the PATH is 
+# not what you want to use for the Datamover.
+#rsync-executable = <path to rsync>
+
+# Path to the GNU find executable on the remote incoming host.
+# Specify only when using an ssh tunnel or an rsync server for copying the incoming data. 
+#incoming-host-find-executable = <'find' path on the remote incoming host>
+
+# Path to the GNU find executable on the remote outgoing host.
+# Specify only when using an ssh tunnel or an rsync server for copying the outgoing data. 
+#outgoing-host-find-executable = <'find' path on the remote outgoing host>