--- a/gnv-artifacts/src/main/java/de/intevation/gnv/raster/Palette.java	Tue Apr 06 13:07:11 2010 +0000
+++ b/gnv-artifacts/src/main/java/de/intevation/gnv/raster/Palette.java	Tue Apr 06 16:53:43 2010 +0000
@@ -13,13 +13,18 @@
 import org.w3c.dom.NodeList;
 
 /**
+ * Lookup mechanism to map double values from a list of
+ * ranges onto a set of colors and vice versa.
  * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
  */
 public class Palette
 implements   ValueToIndex
 {
-	private static Logger log = Logger.getLogger(Palette.class);
+    private static Logger log = Logger.getLogger(Palette.class);
 
+    /**
+     * An entry in the lookup table.
+     */
     public static final class Entry
     implements                Comparable
     {
@@ -37,9 +42,16 @@
 
         private Color  color;
 
+        /**
+         * Default constructor
+         */
         public Entry() {
         }
 
+        /**
+         * Copy constructor
+         * @param other The entry to copy.
+         */
         public Entry(Entry other) {
             index         = other.index;
             externalIndex = other.externalIndex;
@@ -49,6 +61,16 @@
             color         = other.color;
         }
 
+        /**
+         * Constructor to set the palette index, the exteral index,
+         * the value range, the color and the description.
+         * @param index The pallette index
+         * @param externalIndex The external index
+         * @param from Start of the interval
+         * @param to End of the interval
+         * @param color The color belonging to this interval.
+         * @param description The description of this range.
+         */
         public Entry(
             int    index,
             int    externalIndex,
@@ -65,6 +87,12 @@
             this.description   = description;
         }
 
+        /**
+         * Compares two entries by the start point of the interval.
+         * @param other
+         * @return -1 if this start point is before other. +1 if this 
+         * start point is after, else 0.
+         */
         public int compareTo(Object other) {
             Entry e = (Entry)other;
             if (from < e.from) return -1;
@@ -72,22 +100,46 @@
             return 0;
         }
 
+        /**
+         * The starting point of the interval.
+         * @return The starting point.
+         */
         public double getFrom() {
             return from;
         }
 
+        /**
+         * The end point of the interval.
+         * @return The end point.
+         */
         public double getTo() {
             return to;
         }
 
+        /**
+         * The color of the entry.
+         * @return The color.
+         */
         public Color getColor() {
             return color;
         }
 
+        /**
+         * The external index of this entry. Useful to model
+         * external joins.
+         * @return The external index.
+         */
         public int getExternalIndex() {
             return externalIndex;
         }
 
+        /**
+         * Searches for an entry which has a range that contains
+         * the given value.
+         * @param value The value to be searched.
+         * @return The entry containing the value or null if no such
+         * entry exists.
+         */
         public Entry locateEntry(double value) {
             Entry current = this;
             while (current != null) {
@@ -102,6 +154,12 @@
             return null;
         }
 
+        /**
+         * Returns the palette index for a given value.
+         * @param value The value to search.
+         * @return The index of the palette entry or -1 if
+         * no such entry exists.
+         */
         public int locate(double value) {
             Entry entry = locateEntry(value);
             return entry != null
@@ -109,6 +167,12 @@
                 : -1;
         }
 
+        /**
+         * Searches for an interval with a given index.
+         * @param index The index to be searched.
+         * @return The entry with the given index or null if no
+         * such entry exists.
+         */
         public Entry findByIndex(int index) {
             Entry current = this;
             while (current != null) {
@@ -122,18 +186,39 @@
             return current;
         }
 
+        /**
+         * The description of this entry.
+         * @return The description.
+         */
         public String getDescription() {
             return description;
         }
 
+        /**
+         * Determines if the range of this entry has
+         * infinitive length.
+         * @return true if the range of this entry has infinitive
+         * length else false.
+         */
         public boolean isInfinity() {
             return from == -Double.MAX_VALUE
               ||   to   ==  Double.MAX_VALUE;
         }
     } // class Entry
 
+    /**
+     * Internal table of the entrys.
+     */
     protected Entry [] entries;
+    
+    /**
+     * Root of the entry tree used to map values to entries.
+     */
     protected Entry    lookup;
+
+    /**
+     * The list of colors used by this palette.
+     */
     protected Color [] rgbs;
 
     private Entry buildLookup(Entry [] entries, int lo, int hi) {
@@ -147,9 +232,16 @@
         return entry;
     }
 
+    /**
+     * Default constructor.
+     */
     public Palette() {
     }
 
+    /**
+     * Constructor to create the palette from an XML document.
+     * @param document The document with palette information.
+     */
     public Palette(Document document) {
 
         NodeList rangeNodes = document.getElementsByTagName("range");
@@ -172,6 +264,13 @@
         buildLookup();
     }
 
+    /**
+     * Constructor to split a given palette into a given number of
+     * equal sized sub entries. Ranges of infinitive length are not
+     * splitted.
+     * @param original The source palette.
+     * @param N The number of chunks to split single ranges into.
+     */
     public Palette(Palette original, int N) {
         if (N < 2)  {
             throw new IllegalArgumentException("N < 2");
@@ -253,35 +352,75 @@
     }
 
 
+    /**
+     * Internal method to build the lookup tree.
+     */
     protected void buildLookup() {
         Arrays.sort(entries);
         lookup = buildLookup(entries, 0, entries.length-1);
     }
 
+    /**
+     * Creates a new palette which has ranges that are subdivided
+     * into a given number of sub ranges each.
+     * @param N The number od sub divisions of each range.
+     * @return The new created palette.
+     */
     public Palette subdivide(int N) {
         return new Palette(this, N);
     }
 
+    /**
+     * Return the number of entries in this palette.
+     * @return The number of entries.
+     */
     public int getSize() {
         return rgbs.length;
     }
 
+    /**
+     * Return the color of an entry for a given index.
+     * @param index The index.
+     * @return The color.
+     */
     public Color getColor(int index) {
         return rgbs[index];
     }
 
+    /**
+     * Return the RGB value
+     * @param index of an entry for a given index.
+     * @return rgb value
+     */
     public int indexToRGB(int index) {
         return rgbs[index].getRGB();
     }
 
+    /**
+     * Searches for the index of an entry which contains the
+     * given value.
+     * @param value The value to be searched.
+     * @return The index of the entry or -1 if no entry is found.
+     */
     public int toIndex(double value) {
         return lookup.locate(value);
     }
 
+    /**
+     * Searches for the an entry which contains the given value.
+     * @param value The value to be searched.
+     * @return The entry which contains the value or null if
+     * no such entry is found.
+     */
     public Entry getEntry(double value) {
         return lookup.locateEntry(value);
     }
 
+    /**
+     * Searches the entry for a given index.
+     * @param index The index of the entry.
+     * @return The entry or null if no such entry is found.
+     */
     public Entry getEntryByIndex(int index) {
         return lookup.findByIndex(index);
     }