# HG changeset patch
# User Ingo Weinzierl <ingo.weinzierl@intevation.de>
# Date 1270732239 0
# Node ID 2cea76f1112e1e729df2069edfba09f3a2f6de0e
# Parent  bb7afd7833212bc8e73e1a3cf42abb820313e135
Added Javadoc in utils package.

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

diff -r bb7afd783321 -r 2cea76f1112e gnv-artifacts/ChangeLog
--- a/gnv-artifacts/ChangeLog	Thu Apr 08 11:31:44 2010 +0000
+++ b/gnv-artifacts/ChangeLog	Thu Apr 08 13:10:39 2010 +0000
@@ -1,3 +1,20 @@
+2010-04-08  Ingo Weinzierl <ingo.weinzierl@intevation.de>
+
+	* src/main/java/de/intevation/gnv/utils/FileUtils.java,
+	  src/main/java/de/intevation/gnv/utils/DistanceCalculator.java,
+	  src/main/java/de/intevation/gnv/utils/InputValidator.java,
+	  src/main/java/de/intevation/gnv/utils/ArtifactXMLUtilities.java,
+	  src/main/java/de/intevation/gnv/utils/ExclusiveExec.java,
+	  src/main/java/de/intevation/gnv/utils/MetaWriter.java,
+	  src/main/java/de/intevation/gnv/utils/MapfileGenerator.java,
+	  src/main/java/de/intevation/gnv/utils/WKTUtils.java,
+	  src/main/java/de/intevation/gnv/utils/StringUtils.java,
+	  src/main/java/de/intevation/gnv/utils/Pair.java,
+	  src/main/java/de/intevation/gnv/utils/ShapeFileWriter.java: Added Javadoc.
+
+	* src/main/java/de/intevation/gnv/utils/ArtifactFactoryUtilities.java:
+	  Removed.
+
 2010-04-08	Sascha L. Teichmann	<sascha.teichmann@intevation.de>
 
 	* src/main/java/de/intevation/gnv/state/profile/horizontalcrosssection/HorizontalCrossSectionMeshOutputState.java,
diff -r bb7afd783321 -r 2cea76f1112e gnv-artifacts/src/main/java/de/intevation/gnv/utils/ArtifactFactoryUtilities.java
--- a/gnv-artifacts/src/main/java/de/intevation/gnv/utils/ArtifactFactoryUtilities.java	Thu Apr 08 11:31:44 2010 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,53 +0,0 @@
-package de.intevation.gnv.utils;
-
-import de.intevation.artifacts.ArtifactFactory;
-
-import org.apache.log4j.Logger;
-
-import org.w3c.dom.Document;
-import org.w3c.dom.Node;
-
-/**
- * @author <a href="mailto:tim.englich@intevation.de">Tim Englich</a>
- *
- */
-public class ArtifactFactoryUtilities {
-    /**
-     * the logger, used to log exceptions and additonaly information
-     */
-    private static Logger log = Logger
-            .getLogger(ArtifactFactoryUtilities.class);
-
-    /**
-     * Constructor
-     */
-    public ArtifactFactoryUtilities() {
-    }
-
-    public ArtifactFactory createArtitfactFactor(Document config,
-                                                 Node artifactFactoryNode) {
-        String className = artifactFactoryNode.getTextContent();
-
-        ArtifactFactory factory = null;
-
-        try {
-            Class clazz = Class.forName(className);
-            factory = (ArtifactFactory) clazz.newInstance();
-        } catch (ClassNotFoundException cnfe) {
-            log.error(cnfe.getLocalizedMessage(), cnfe);
-        } catch (InstantiationException ie) {
-            log.error(ie.getLocalizedMessage(), ie);
-        } catch (ClassCastException cce) {
-            log.error(cce.getLocalizedMessage(), cce);
-        } catch (IllegalAccessException iae) {
-            log.error(iae.getLocalizedMessage(), iae);
-        }
-
-        if (factory != null) {
-            factory.setup(config, artifactFactoryNode);
-            log.info("Registering '" + factory.getName()
-                     + "' as artifact factory.");
-        }
-        return factory;
-    }
-}
diff -r bb7afd783321 -r 2cea76f1112e gnv-artifacts/src/main/java/de/intevation/gnv/utils/ArtifactXMLUtilities.java
--- a/gnv-artifacts/src/main/java/de/intevation/gnv/utils/ArtifactXMLUtilities.java	Thu Apr 08 11:31:44 2010 +0000
+++ b/gnv-artifacts/src/main/java/de/intevation/gnv/utils/ArtifactXMLUtilities.java	Thu Apr 08 13:10:39 2010 +0000
@@ -32,6 +32,8 @@
 import org.xml.sax.SAXException;
 
 /**
+ * This class provides some methods for creating and working with xml documents.
+ *
  * @author <a href="mailto:tim.englich@intevation.de">Tim Englich</a>
  *
  */
@@ -51,14 +53,19 @@
     public static final String XFORM_PREFIX = "xform";
 
     /**
-     * Constructor
+     * Constructor.<br>
+     * <b>Note:</b> It should not be necessary to create an object of this
+     * class - which is a helper class. Call static methods instead.
      */
     public ArtifactXMLUtilities() {
     }
 
     /**
-     * @param document
-     * @return
+     * Creates an <code>Element</code> and returns it.
+     * 
+     * @param document A document
+     * @param name Name of a node.
+     * @return an Element.
      */
     public static Element createArtifactElement(Document document, String name) {
         Element node = document.createElementNS(
@@ -67,6 +74,13 @@
         return node;
     }
 
+
+    /**
+     * Turns an xml document into a string.
+     *
+     * @param document An xml document.
+     * @return String representation of <i>document</i>.
+     */
     public static String writeDocument2String(Document document) {
         try {
             TransformerFactory transformerFactory = TransformerFactory
@@ -87,6 +101,12 @@
         return null;
     }
 
+    /**
+     * Read a document from input stream.
+     *
+     * @param inputStream The input stream.
+     * @return the document read from stream.
+     */
     public static Document readDocument(InputStream inputStream) {
         Document returnValue = null;
         try {
@@ -104,24 +124,43 @@
         return returnValue;
     }
 
+
+    @SuppressWarnings("static-access")
     public Document reInitDocument(Document document) {
         try {
-            byte[] barray = this.writeDocument2String(document).getBytes(
+            @SuppressWarnings("static-access")
+            byte[] barray = ArtifactXMLUtilities.writeDocument2String(document).getBytes(
                     "UTF-8");
             InputStream inputStream = new ByteArrayInputStream(barray);
-            return this.readDocument(inputStream);
+            return ArtifactXMLUtilities.readDocument(inputStream);
         } catch (UnsupportedEncodingException e) {
             log.error(e, e);
         }
         return document;
     }
 
+
+    /**
+     * Creates an <code>Element</code> with {@link #XFORM_PREFIX} and <i>name
+     * </i>.
+     *
+     * @param document A document.
+     * @param name The node name.
+     * @return the created element.
+     */
     public static Element createXFormElement(Document document, String name) {
         Element node = document.createElementNS(XFORM_URL, name);
         node.setPrefix(XFORM_PREFIX);
         return node;
     }
 
+    /**
+     * Creates an exception node.
+     *
+     * @param message The message in the node.
+     * @param document A document.
+     * @return the document containing the exception node.
+     */
     public static Document createExceptionReport(String message, Document document) {
         log.debug("ArtifactXMLUtilities.createExceptionReport");
         Element exceptionReportNode = createArtifactElement(document,
@@ -134,6 +173,13 @@
         return document;
     }
 
+    /**
+     * Creates an input exception node.
+     *
+     * @param msg The message in the node.
+     * @param doc A document.
+     * @return the document containing the exception node.
+     */
     public static Document createInputExceptionReport(String msg, Document doc) {
         Element exceptionReportNode = createArtifactElement(
             doc,"exceptionreport");
@@ -148,6 +194,13 @@
         return doc;
     }
 
+    /**
+     * Creates a success node.
+     *
+     * @param message The message.
+     * @param document A document.
+     * @return the document containing the success node.
+     */
     public static Document createSuccessReport(String message, Document document) {
         log.debug("ArtifactXMLUtilities.creatSuccessReport");
         Element reportNode = createArtifactElement(document, "result");
@@ -158,6 +211,12 @@
         return document;
     }
 
+    /**
+     * Read <i>fileName</i> and return the first child node.
+     * 
+     * @param fileName An xml document.
+     * @return the first child node in this document.
+     */
     public Node readConfiguration(String fileName){
         try {
             DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
@@ -174,5 +233,5 @@
             return null;
         }
     }
-
 }
+// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 :
\ No newline at end of file
diff -r bb7afd783321 -r 2cea76f1112e gnv-artifacts/src/main/java/de/intevation/gnv/utils/DistanceCalculator.java
--- a/gnv-artifacts/src/main/java/de/intevation/gnv/utils/DistanceCalculator.java	Thu Apr 08 11:31:44 2010 +0000
+++ b/gnv-artifacts/src/main/java/de/intevation/gnv/utils/DistanceCalculator.java	Thu Apr 08 13:10:39 2010 +0000
@@ -6,6 +6,8 @@
 import java.util.List;
 
 /**
+ * A helper class to calculate distances between points and coordinates.
+ * 
  * @author <a href="mailto:tim.englich@intevation.de">Tim Englich</a>
  *
  */
@@ -21,10 +23,26 @@
     public DistanceCalculator() {
     }
 
+
+    /**
+     * Calculates the distance between two points.
+     *
+     * @param p1 First point.
+     * @param p2 Second point.
+     * @return the distance.
+     */
     public static double calculateDistance(Point p1, Point p2){
         return calculateDistance(p1.getCoordinate(), p2.getCoordinate());
     }
 
+
+    /**
+     * Calculates the distance between two coordinates.
+     *
+     * @param p1 First coordinate.
+     * @param p2 Second coordinate.
+     * @return the distance.
+     */
     public static double calculateDistance(Coordinate p1, Coordinate p2){
         double resultValue = 0.0;
 
@@ -66,6 +84,12 @@
         return resultValue;
     }
 
+    /**
+     * Calculates the length of a path specified by coordinates in <i>path</i>.
+     *
+     * @param path A list of coordinates.
+     * @return the length of the given path.
+     */
     public static final double calculateDistance(List<Coordinate> path) {
         int N = path.size();
         if (N < 2) {
@@ -79,3 +103,4 @@
     }
 
 }
+// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 :
\ No newline at end of file
diff -r bb7afd783321 -r 2cea76f1112e gnv-artifacts/src/main/java/de/intevation/gnv/utils/ExclusiveExec.java
--- a/gnv-artifacts/src/main/java/de/intevation/gnv/utils/ExclusiveExec.java	Thu Apr 08 11:31:44 2010 +0000
+++ b/gnv-artifacts/src/main/java/de/intevation/gnv/utils/ExclusiveExec.java	Thu Apr 08 13:10:39 2010 +0000
@@ -16,13 +16,25 @@
  */
 public final class ExclusiveExec
 {
+    /**
+     * The only instance of this singleton.
+     */
     public static final ExclusiveExec INSTANCE = new ExclusiveExec();
 
     private HashMap tokens;
 
+    /**
+     * This class represents a unique key with a reference counter.
+     */
     public static class UniqueKey {
         Object key;
         int [] refs;
+
+        /**
+         * Constructs a new UniqueKey.
+         *
+         * @param key The key of this unique key.
+         */
         public UniqueKey(Object key) {
             this.key = key;
             refs = new int[1];
@@ -41,7 +53,6 @@
      * block.
      *
      * @param key The key used to identify same threads.
-     *
      * @return UniqueKey. Use this object to call {@link #release(UniqueKey)}
      * at the end of your code being synchronized.
      */
diff -r bb7afd783321 -r 2cea76f1112e gnv-artifacts/src/main/java/de/intevation/gnv/utils/FileUtils.java
--- a/gnv-artifacts/src/main/java/de/intevation/gnv/utils/FileUtils.java	Thu Apr 08 11:31:44 2010 +0000
+++ b/gnv-artifacts/src/main/java/de/intevation/gnv/utils/FileUtils.java	Thu Apr 08 13:10:39 2010 +0000
@@ -13,6 +13,9 @@
 import java.util.zip.ZipOutputStream;
 
 /**
+ * A helper class to provide some methods for working with files and
+ * directories.
+ * 
  * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
  * @author <a href="mailto:ingo.weinzierl@intevation.de">Ingo Weinzierl</a>
  */
@@ -21,6 +24,11 @@
     private FileUtils() {
     }
 
+    /**
+     * Deletes everything in a directory.
+     *
+     * @param dir The directory.
+     */
     public final static void deleteContent(File dir) {
         if (dir == null || !dir.isDirectory()) {
             return;
@@ -36,6 +44,12 @@
         return;
     }
 
+    /**
+     * Delete <i>file</i> and everything in <i>file</i> if it is a directory.
+     *
+     * @param file The file or directory.
+     * @return true, if deletion was successful - otherwise false.
+     */
     public final static boolean deleteRecursive(File file) {
 
         if (file == null) {
@@ -56,6 +70,14 @@
         return file.delete();
     }
 
+    /**
+     * Put the given file or directory into a zip archive.
+     *
+     * @param file The file or directory.
+     * @param outputStream The stream to write the archive to.
+     * @throws IOException if an error occured while zip creation or writing to
+     * output stream.
+     */
     public static void createZipArchive(
         File         file,
         OutputStream outputStream
@@ -98,6 +120,9 @@
         out.finish();
     }
 
+    /**
+     * A class representing a directory with a prefix.
+     */
     private static final class PrefixDir {
 
         String prefix;
@@ -110,6 +135,15 @@
 
     } // class PrefixDir
 
+    /**
+     * Write a file to zip archive.
+     *
+     * @param prefix A prefix.
+     * @param file The file.
+     * @param out The output stream.
+     * @throws IOException if an error occured while writing to zip output
+     * stream.
+     */
     private static void copyFileToZip(
         String          prefix,
         File            file,
diff -r bb7afd783321 -r 2cea76f1112e gnv-artifacts/src/main/java/de/intevation/gnv/utils/InputValidator.java
--- a/gnv-artifacts/src/main/java/de/intevation/gnv/utils/InputValidator.java	Thu Apr 08 11:31:44 2010 +0000
+++ b/gnv-artifacts/src/main/java/de/intevation/gnv/utils/InputValidator.java	Thu Apr 08 13:10:39 2010 +0000
@@ -38,6 +38,16 @@
         super();
     }
 
+    /**
+     * Validates the input of a range of double or date values. The input values
+     * need to be valid double or date values. <i>minInput</i> needs to be
+     * smaller or equal <i>maxInput</i>.
+     *
+     * @param minInput The lower bound.
+     * @param maxInput The upper bound.
+     * @param type One of 'Date' or 'Double'.
+     * @return true, if the input is valid, otherwise false.
+     */
     public static boolean isInputValid(String minInput, String maxInput, String type) {
         log.debug("InputValidator.isInputValid " + minInput + " " + maxInput + " " +type);
         boolean returnValue = false;
@@ -63,6 +73,13 @@
         return returnValue;
     }
 
+    /**
+     * Validates an input.
+     *
+     * @param input The input value.
+     * @param type The input value type.
+     * @return true if the input is valid, otherwise false.
+     */
     public static boolean isInputValid(String input, String type) {
         log.debug("InputValidator.isInputValid " + input + " " + type);
 
@@ -135,6 +152,13 @@
     }
 
 
+    /**
+     * Returns a point from wkt string.
+     *
+     * @param value The wkt string.
+     * @return a point.
+     * @throws ValidationException if <i>value</i> is not valid.
+     */
     public static Point getPointValue(String value) throws ValidationException{
         log.debug("InputValidator.getPointValue " + value);
 
@@ -184,6 +208,14 @@
     }
 
 
+    /**
+     * Makes sure that <i>tmp</i> is between <i>lo</i> and <i>up</i>.
+     *
+     * @param tmp The value to validate.
+     * @param lo The lower range bound.
+     * @param up The upper range bound.
+     * @return true, if tmp is valid, otherwise false.
+     */
     public static boolean isDateValid(Date tmp, Date lo, Date up) {
         // we need to transform the given dates into seconds, because
         // they differ in milliseconds -> that's why we cannot use the
@@ -202,3 +234,4 @@
         return true;
     }
 }
+// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 :
\ No newline at end of file
diff -r bb7afd783321 -r 2cea76f1112e gnv-artifacts/src/main/java/de/intevation/gnv/utils/MapfileGenerator.java
--- a/gnv-artifacts/src/main/java/de/intevation/gnv/utils/MapfileGenerator.java	Thu Apr 08 11:31:44 2010 +0000
+++ b/gnv-artifacts/src/main/java/de/intevation/gnv/utils/MapfileGenerator.java	Thu Apr 08 13:10:39 2010 +0000
@@ -32,29 +32,56 @@
 import org.w3c.dom.NodeList;
 
 /**
+ * This class iterates over a bunch of directories, searches for meta
+ * information coresponding to shapefiles and creates a mapfile which is used by
+ * a <i>MapServer</i>.
+ * 
  * @author <a href="mailto:ingo.weinzierl@intevation.de">Ingo Weinzierl</a>
  */
 public class MapfileGenerator
 extends Thread
 {
+    /**
+     * The configured template path.
+     */
     public static final String TEMPLATE_PATH =
         "/artifact-database/gnv/map-generator/templates/path/text()";
 
+    /**
+     * The configured template mapfile.
+     */
     public static final String TEMPLATE_MAPFILE =
         "/artifact-database/gnv/map-generator/templates/maptemplate/text()";
 
+    /**
+     * The configured mapfile path.
+     */
     public static final String MAPFILE_PATH =
         "/artifact-database/gnv/map-generator/mapfile/@path";
 
+    /**
+     * The configured shapefile base directory where the subdirectories for each
+     * artifact are stored.
+     */
     public static final String SHAPEFILE_BASE_DIR =
         "/artifact-database/gnv/shapefile-directory/@path";
 
+    /**
+     * The configured velocity logfile.
+     */
     public static final String VELOCITY_LOGFILE =
         "/artifact-database/velocity/logfile/@path";
 
+    /**
+     * The name of the file storing meta information coresponding to shapefiles.
+     */
     public static final String META_FILE_NAME = "meta.xml";
 
+    /**
+     * The XPath to layer nodes in the meta information xml file.
+     */
     public static final String XPATH_LAYER        = "/art:meta/art:layer";
+    
     public static final String XPATH_LAYER_NAME   = "art:name";
     public static final String XPATH_LAYER_TITLE  = "art:title";
     public static final String XPATH_LAYER_TYPE   = "art:type";
@@ -83,11 +110,23 @@
     }
 
 
+    /**
+     * A main method which can be used to create a mapfile without a running
+     * artifact server.<br>
+     * <b>NOTE:</b> This method is not implemented yet!
+     * 
+     * @param args Arguments.
+     */
     public static void main(String[] args) {
         // TODO IMPLEMENT ME
     }
 
 
+    /**
+     * Returns the instance of this generator.
+     *
+     * @return the instance.
+     */
     public static synchronized MapfileGenerator getInstance() {
         if (instance == null) {
             instance = new MapfileGenerator();
@@ -99,6 +138,9 @@
     }
 
 
+    /**
+     * Triggers the mapfile generation process.
+     */
     public void update() {
         synchronized (lock) {
             logger.debug("update");
@@ -108,6 +150,10 @@
     }
 
 
+    /**
+     * Thread to generate a mapfile.
+     */
+    @Override
     public void run() {
         logger.debug("Start MapfileGenerator thread...");
         try {
@@ -131,12 +177,22 @@
         }
     }
 
+    /**
+     * Method to check the existance of a template file.
+     *
+     * @param templateID The name of a template.
+     * @return true, of the template exists - otherwise false.
+     */
     public boolean templateExists(String templateID){
         Template template = getTemplateByName(templateID);
         return template != null;
     }
 
 
+    /**
+     * Method which starts searching for meta information file and mapfile
+     * generation.
+     */
     protected void generate() {
         File basedir       = new File(getShapefileBaseDir());
         List layers        = new ArrayList();
@@ -145,6 +201,11 @@
     }
 
 
+    /**
+     * Returns the VelocityEngine used for the template mechanism.
+     *
+     * @return the velocity engine.
+     */
     protected VelocityEngine getVelocityEngine() {
         if (velocityEngine == null) {
             velocityEngine = new VelocityEngine();
@@ -160,6 +221,12 @@
     }
 
 
+    /**
+     * Initialize velocity.
+     *
+     * @param engine Velocity engine.
+     * @throws Exception if an error occured while initializing velocity.
+     */
     protected void setupVelocity(VelocityEngine engine)
     throws Exception
     {
@@ -183,6 +250,11 @@
     }
 
 
+    /**
+     * Returns the path specifying the logfile for velocity.
+     *
+     * @return Velocity logfile path.
+     */
     protected String getVelocityLogfile() {
         if (velocityLogfile == null)
             velocityLogfile = Config.getStringXPath(VELOCITY_LOGFILE);
@@ -191,6 +263,11 @@
     }
 
 
+    /**
+     * Returns the base directory storing the templates.
+     *
+     * @return the template base directory.
+     */
     protected String getTemplateBaseDir() {
         if (templatePath == null) {
             templatePath = Config.getStringXPath(TEMPLATE_PATH);
@@ -201,6 +278,12 @@
     }
 
 
+    /**
+     * Returns a template specified by <i>model</i>.
+     *
+     * @param model The name of the template.
+     * @return a template.
+     */
     protected Template getTemplateByName(String model) {
         if (model.indexOf(".vm") < 0) {
             model = model.concat(".vm");
@@ -223,6 +306,12 @@
     }
 
 
+    /**
+     * Returns the mapfile  template.
+     *
+     * @return the mapfile template.
+     * @throws Exception if an error occured while reading the configuration.
+     */
     protected Template getMapfileTemplate()
     throws Exception
     {
@@ -231,6 +320,11 @@
     }
 
 
+    /**
+     * Returns the base directory storing the shapefiles.
+     *
+     * @return the shapefile base directory.
+     */
     protected String getShapefileBaseDir() {
         if (shapefileDirectory == null) {
             shapefileDirectory = Config.getStringXPath(SHAPEFILE_BASE_DIR);
@@ -241,6 +335,11 @@
     }
 
 
+    /**
+     * Returns the mapfile.
+     * 
+     * @return the mapfile.
+     */
     protected File getMapfile() {
         if (mapfile == null) {
             String tmp = Config.getStringXPath(MAPFILE_PATH);
@@ -252,6 +351,13 @@
     }
 
 
+    /**
+     * Search for meta information file in <i>file</i> and store the layer
+     * information in <i>store</i> if a meta file was found.
+     * 
+     * @param file The root directory to be searched for meta files.
+     * @param store A list storing <code>LayerInfo</code> objects.
+     */
     protected void searchMetaInformation(File file, List store) {
         if (file.isDirectory()) {
             File[] files = file.listFiles();
@@ -276,6 +382,13 @@
     }
 
 
+    /**
+     * Parses a meta information file and returns necessary information as
+     * <code>LayerInfo</code> array.
+     *
+     * @param file Meta information file.
+     * @return Array of LayerInfo objects.
+     */
     protected LayerInfo[] parseMeta(File file) {
         Document meta = XMLUtils.parseDocument(file);
         List layers   = new ArrayList();
@@ -302,6 +415,12 @@
     }
 
 
+    /**
+     * Parses a node storing layer information and returns them.
+     *
+     * @param layer Node storing information about a layer.
+     * @return a LayerInfo object.
+     */
     protected LayerInfo parseLayer(Node layer) {
         LayerInfo info  = new LayerInfo();
 
@@ -342,6 +461,13 @@
     }
 
 
+    /**
+     * Parses attributes in layer nodes.
+     *
+     * @param node A node containing layer information.
+     * @param xpath XPath specifying an attribute.
+     * @return Attribute as string.
+     */
     protected String parseLayerAttr(Node node, String xpath) {
         return (String) XMLUtils.xpath(
             node,
@@ -351,6 +477,11 @@
     }
 
 
+    /**
+     * Creates a mapfile with the layer information stored in <i>layers</i>.
+     * 
+     * @param layers Layer information.
+     */
     protected void writeMapfile(List layers) {
         String tmpMapName = "mapfile" + new Date().getTime();
 
diff -r bb7afd783321 -r 2cea76f1112e gnv-artifacts/src/main/java/de/intevation/gnv/utils/MetaWriter.java
--- a/gnv-artifacts/src/main/java/de/intevation/gnv/utils/MetaWriter.java	Thu Apr 08 11:31:44 2010 +0000
+++ b/gnv-artifacts/src/main/java/de/intevation/gnv/utils/MetaWriter.java	Thu Apr 08 13:10:39 2010 +0000
@@ -23,6 +23,9 @@
 import org.w3c.dom.Element;
 
 /**
+ * This class provides some methods to create files storing meta information
+ * about wms layers and a map service which serves these layers.
+ * 
  * @author <a href="mailto:ingo.weinzierl@intevation.de">Ingo Weinzierl</a>
  */
 public class MetaWriter {
@@ -41,9 +44,22 @@
 
     public static final String CONTEXT_LAYER_TITLE = "wms.title";
 
+    /**
+     * Constructor.
+     */
     private MetaWriter() {
     }
 
+    /**
+     * Writes a meta information file for product type 'Layer'.
+     * 
+     * @param context CallContext object.
+     * @param uuid The UUID of the current artifact.
+     * @param path The destination of the meta file.
+     * @param paramType The parameter type.
+     * @param layerType The layer type.
+     * @return the meta document.
+     */
     public static Document writeLayerMeta(CallContext context,
                                           String      uuid,
                                           String      path,
@@ -68,6 +84,16 @@
         }
     }
 
+
+    /**
+     * Writes a meta information file for product type 'Horizontalschnitt'.
+     *
+     * @param context The CallContext object.
+     * @param uuid The UUID of the current artifact.
+     * @param path The destination of the meta file.
+     * @param paramType The parameter type.
+     * @return the meta document.
+     */
     public static Document writeHorizontalcrosssectionMeta(
         CallContext context,
         String      uuid,
@@ -84,8 +110,8 @@
         meta.appendChild(root);
 
         writeAbstractMeta(context, meta, root);
-        writePolygonMeta(context, meta, root, uuid, path, paramType);
-        writeIsolineMeta(context, meta, root, uuid, path, paramType);
+        writePolygonMeta(context, meta, root, uuid, paramType);
+        writeIsolineMeta(context, meta, root, uuid, paramType);
 
         boolean success = writeMetaFile(path, meta);
 
@@ -97,8 +123,10 @@
     }
 
     /**
-     * @param path
-     * @param meta
+     * Method to write the <i>meta</i> document down to a file.
+     *
+     * @param path The destination of the file.
+     * @param meta The xml document storing the meta information.
      */
     private static boolean writeMetaFile(String path, Document meta) {
         try {
@@ -144,6 +172,13 @@
     }
 
 
+    /**
+     * Append meta information about the mapservice itself.
+     *
+     * @param callContext The CallContext object.
+     * @param document The meta information document.
+     * @param meta The element where the new information need to be appended to.
+     */
     public static void writeAbstractMeta(
         CallContext callContext,
         Document    document,
@@ -180,6 +215,16 @@
         meta.appendChild(mapserver);
     }
 
+    /**
+     * Append layer information to the meta document.
+     *
+     * @param callContext The CallContext object.
+     * @param document The meta document.
+     * @param meta The element where the new information need to be appended to.
+     * @param uuid The UUID of the current artifact.
+     * @param paramType The parameter type (e.g. salinity).
+     * @param layerType The layer type.
+     */
     protected static void writeLayerMeta(
         CallContext callContext,
         Document    document,
@@ -225,12 +270,20 @@
     }
 
 
+    /**
+     * Append polygon layer information to meta document.
+     *
+     * @param context
+     * @param document The meta document.
+     * @param meta The element where the new information need to be appended to.
+     * @param uuid The UUID of the current artifact.
+     * @param paramType The parameter type (e.g. salinity).
+     */
     public static void writePolygonMeta(
         CallContext context,
         Document    document,
         Element     meta,
         String      uuid,
-        String      path,
         String      paramType
     ) {
         XMLUtils.ElementCreator creator = new XMLUtils.ElementCreator(
@@ -274,12 +327,20 @@
     }
 
 
+    /**
+     * Append isoline layer information to meta document.
+     *
+     * @param context
+     * @param document The meta document.
+     * @param meta The element where the new information need to be appended to.
+     * @param uuid The UUID of the current artifact.
+     * @param paramType The parameter type (e.g. salinity).
+     */
     public static void writeIsolineMeta(
         CallContext context,
         Document    document,
         Element     meta,
         String      uuid,
-        String      path,
         String      paramType
     ) {
         XMLUtils.ElementCreator creator = new XMLUtils.ElementCreator(
diff -r bb7afd783321 -r 2cea76f1112e gnv-artifacts/src/main/java/de/intevation/gnv/utils/Pair.java
--- a/gnv-artifacts/src/main/java/de/intevation/gnv/utils/Pair.java	Thu Apr 08 11:31:44 2010 +0000
+++ b/gnv-artifacts/src/main/java/de/intevation/gnv/utils/Pair.java	Thu Apr 08 13:10:39 2010 +0000
@@ -3,6 +3,8 @@
 import java.io.Serializable;
 
 /**
+ * @param <A> 
+ * @param <B>
  * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
  */
 public final class Pair<A, B>
diff -r bb7afd783321 -r 2cea76f1112e gnv-artifacts/src/main/java/de/intevation/gnv/utils/ShapeFileWriter.java
--- a/gnv-artifacts/src/main/java/de/intevation/gnv/utils/ShapeFileWriter.java	Thu Apr 08 11:31:44 2010 +0000
+++ b/gnv-artifacts/src/main/java/de/intevation/gnv/utils/ShapeFileWriter.java	Thu Apr 08 13:10:39 2010 +0000
@@ -46,6 +46,9 @@
 
     private static NumberFormat format = NumberFormat.getInstance();
 
+    /**
+     * Precision used to format double values.
+     */
     public static final int DOUBLE_PRECISION = 3;
 
     static {
@@ -55,6 +58,17 @@
     private ShapeFileWriter() {
     }
 
+
+    /**
+     * Write multilinestrings to shapefile.
+     *
+     * @param shapeFile Shapefile.
+     * @param parameterId The parameter id.
+     * @param layer The layer.
+     * @param date The date.
+     * @param multiLineStrings The multilinestring.
+     * @return true, if shapefile writing was successful - otherwise false.
+     */
     public static boolean writeMultiLineStringsToFile(
         File                                shapeFile,
         Integer                             parameterId,
@@ -71,6 +85,18 @@
             "isolines");
     }
 
+
+    /**
+     * Write multilinestrings to shapefile.
+     *
+     * @param shapeFile Shapefile.
+     * @param parameterId The parameter id.
+     * @param layer The layer.
+     * @param date The date.
+     * @param multiLineStrings The multilinestring.
+     * @param name A name.
+     * @return true, if shapefile writing was successful - otherwise false.
+     */
     public static boolean writeMultiLineStringsToFile(
         File                                shapeFile,
         Integer                             parameterId,
@@ -173,6 +199,17 @@
         return success;
     }
 
+
+    /**
+     * Write multipolygon to file.
+     *
+     * @param shapeFile The shapefile.
+     * @param parameterId The parameter id.
+     * @param layer The layer.
+     * @param date The date.
+     * @param multiPolygons Multipolygons.
+     * @return true, if shapefile writing was successful - otherwise false.
+     */
     public static boolean writeMultiPolygonsToFile(
         File                       shapeFile,
         Integer                    parameterId,
@@ -190,6 +227,15 @@
     }
 
 
+    /**
+     * Write data to shapefile.
+     *
+     * @param shapeFile The shapefile.
+     * @param name The name.
+     * @param data The data.
+     * @param geometryType The geometry type.
+     * @return true, if shapefile writing was successful - otherwise false.
+     */
     public static boolean writeDataToFile(File shapeFile,
                                           String name,
                                           Collection<Result> data,
@@ -294,9 +340,20 @@
         }
 
         return true;
-
     }
 
+
+    /**
+     * Write multipolygons to file.
+     *
+     * @param shapeFile The shapefile.
+     * @param parameterId The parameter id.
+     * @param layer The layer.
+     * @param date The date.
+     * @param multiPolygons Multipolygons.
+     * @param name A name.
+     * @return true, if shapefile writing was successful - otherwise false.
+     */
     public static boolean writeMultiPolygonsToFile(
         File                       shapeFile,
         Integer                    parameterId,
@@ -399,6 +456,13 @@
         return success;
     }
 
+    /**
+     * Returns an object as Double.
+     *
+     * @param a An object.
+     * @return Object <i>a</i> as Double. If <i>a</i> is not a double and no
+     * number, 0d is returned.
+     */
     private static final Double asDouble(Object a) {
         if (a instanceof Double) {
             return (Double)a;
@@ -409,6 +473,13 @@
         return 0d;
     }
 
+    /**
+     * Turns a double value into a string representation taking account of the
+     * locale.
+     *
+     * @param value A double value.
+     * @return The double value formatted as string.
+     */
     private static final String value2description(Double value) {
         return format.format(value);
     }
diff -r bb7afd783321 -r 2cea76f1112e gnv-artifacts/src/main/java/de/intevation/gnv/utils/StringUtils.java
--- a/gnv-artifacts/src/main/java/de/intevation/gnv/utils/StringUtils.java	Thu Apr 08 11:31:44 2010 +0000
+++ b/gnv-artifacts/src/main/java/de/intevation/gnv/utils/StringUtils.java	Thu Apr 08 13:10:39 2010 +0000
@@ -1,6 +1,8 @@
 package de.intevation.gnv.utils;
 
 /**
+ * Helper class which supports some methods for working with strings.
+ *
  * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
  */
 public final class StringUtils
@@ -8,6 +10,13 @@
     private StringUtils() {
     }
 
+    /**
+     * Append a string to a string array.
+     *
+     * @param haystack String array.
+     * @param straw String to append.
+     * @return the new string array.
+     */
     public static final String [] append(String [] haystack, String straw) {
         if (haystack == null) {
             return new String [] { straw };
@@ -18,6 +27,13 @@
         return nhaystack;
     }
 
+    /**
+     * Checks the existence of a string in a given string array.
+     *
+     * @param haystack String array.
+     * @param needle String for being checked.
+     * @return true, if the string is contained in <i>haystack</i> - else false.
+     */
     public static final boolean contains(String [] haystack, String needle) {
         if (haystack == null) {
             return false;
diff -r bb7afd783321 -r 2cea76f1112e gnv-artifacts/src/main/java/de/intevation/gnv/utils/WKTUtils.java
--- a/gnv-artifacts/src/main/java/de/intevation/gnv/utils/WKTUtils.java	Thu Apr 08 11:31:44 2010 +0000
+++ b/gnv-artifacts/src/main/java/de/intevation/gnv/utils/WKTUtils.java	Thu Apr 08 13:10:39 2010 +0000
@@ -37,6 +37,11 @@
 
 import org.apache.log4j.Logger;
 
+/**
+ * A helper class which supports some useful methods to work with wkt strings.
+ *
+ * @author <a href="mailto:ingo.weinzierl@intevation.de">Ingo Weinzierl</a>
+ */
 public abstract class WKTUtils {
 
     private static Logger log = Logger.getLogger(WKTUtils.class);
@@ -59,6 +64,14 @@
     public static final String DEFAULT_COORDINATE_TEMPLATE =
         "{0}\u00b0N {1}'' {2}\u00b0E {3}''";
 
+    /**
+     * Checks the difference of two <code>Result</code>s.
+     *
+     * @param a A Result.
+     * @param b Another Result.
+     * @param indices Indices to be checked.
+     * @return true, if <i>a</i> and <i>b</i> are different - otherwise false.
+     */
     public static boolean different(Result a, Result b, int [] indices) {
         for (int i = 0; i < indices.length; ++i) {
             String oa = a.getString(indices[i]);
@@ -79,6 +92,12 @@
         return false;
     }
 
+    /**
+     * Turns a wkt string into a coordinate.
+     *
+     * @param shape A wkt string.
+     * @return wkt string as coordinate.
+     */
     public static Coordinate toCoordinate(String shape) {
         try {
             return shape != null
@@ -94,6 +113,12 @@
         return null;
     }
 
+    /**
+     * Turns a wkt string into a polygon.
+     *
+     * @param shape A wkt string.
+     * @return wkt string as polygon.
+     */
     public static Polygon toPolygon(String shape) {
         try {
             return (Polygon)new WKTReader().read(shape);
@@ -107,11 +132,23 @@
         return null;
     }
 
+    /**
+     * Returns a distance in km.
+     *
+     * @param distance A distance.
+     * @return distance in km.
+     */
     public static final double toKM(double distance) {
         return (distance * NAUTICAL_MILE) / KILOMETER;
     }
 
 
+    /**
+     * Turns a coordinate into a wkt string.
+     *
+     * @param coordinate A coordinate.
+     * @return the coordinate as wkt string.
+     */
     public static String toWKT(Coordinate coordinate) {
         StringBuilder sb = new StringBuilder("POINT(");
         sb.append(coordinate.x)
@@ -121,6 +158,7 @@
         return sb.toString();
     }
 
+
     public static final String indexBox(
         java.awt.Point a,
         java.awt.Point b,
@@ -360,18 +398,46 @@
 		return null;
 	}
 
+    /**
+     * Turns a wkt coordinate into a string format using the default locale of
+     * the virtual machine.
+     *
+     * @param wkt A wkt coordinate.
+     * @return A formatted coordinate.
+     */
     public static String toText(String wkt) {
         return toText(Locale.getDefault(), wkt);
     }
 
+    /**
+     * Turns a point into a string format using the default locale of the
+     * virtual machine.
+     *
+     * @param p A point.
+     * @return A point formatted as string.
+     */
     public static String toText(Point p) {
         return toText(Locale.getDefault(), toWKT(p.getCoordinate()));
     }
 
+    /**
+     * Turns a point into a string format using a given locale.
+     *
+     * @param locale A locale.
+     * @param p A point.
+     * @return a point formatted as string.
+     */
     public static String toText(Locale locale, Point p) {
         return toText(locale, toWKT(p.getCoordinate()));
     }
 
+    /**
+     * Turns a wkt coordiante into a formatted text using a given locale.
+     *
+     * @param locale A locale.
+     * @param wkt A wkt coordinate.
+     * @return a formatted coordinate.
+     */
     public static String toText(Locale locale, String wkt) {
         String formattedCoordinate = null;
         try {
@@ -428,3 +494,4 @@
         return null;
     }
 }
+// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 :
\ No newline at end of file