Add missing javadoc and review new code

10 files changed, 205 insertions, 7 deletions

diff --git a/src/main/java/de/measite/minidns/DNSCache.java b/src/main/java/de/measite/minidns/DNSCache.java
index 78e6c041..14a3a776 100644
--- a/src/main/java/de/measite/minidns/DNSCache.java
+++ b/src/main/java/de/measite/minidns/DNSCache.java
@@ -5,8 +5,19 @@ package de.measite.minidns;
  */
 public interface DNSCache {
 
+    /**
+     * Add an an dns answer/response for a given dns question. Implementations
+     * should honor the ttl / receive timestamp.
+     * @param q The question.
+     * @param message The dns message.
+     */
     void put(Question q, DNSMessage message);
 
+    /**
+     * Request a cached dns response.
+     * @param q The dns question.
+     * @return The dns message.
+     */
     DNSMessage get(Question q);
 
 }
diff --git a/src/main/java/de/measite/minidns/Question.java b/src/main/java/de/measite/minidns/Question.java
index 8efe19f1..62862251 100644
--- a/src/main/java/de/measite/minidns/Question.java
+++ b/src/main/java/de/measite/minidns/Question.java
@@ -4,39 +4,89 @@ import java.io.ByteArrayOutputStream;
 import java.io.DataInputStream;
 import java.io.DataOutputStream;
 import java.io.IOException;
+import java.util.Arrays;
 
 import de.measite.minidns.Record.CLASS;
 import de.measite.minidns.Record.TYPE;
 import de.measite.minidns.util.NameUtil;
 
+/**
+ * A DNS question (request).
+ */
 public class Question {
 
+    /**
+     * The question string (e.g. "measite.de").
+     */
     private final String name;
 
+    /**
+     * The question type (e.g. A).
+     */
     private final TYPE type;
 
+    /**
+     * The question class (usually IN / internet).
+     */
     private final CLASS clazz;
 
+    /**
+     * Cache for the serialized object.
+     */
     private byte[] byteArray;
 
+    /**
+     * Create a dns question for the given name/type/class.
+     * @param name The name e.g. "measite.de".
+     * @param type The type, e.g. A.
+     * @param clazz The class, usually IN (internet).
+     */
     public Question(String name, TYPE type, CLASS clazz) {
         this.name = name;
         this.type = type;
         this.clazz = clazz;
     }
 
+    /**
+     * Create a dns question for the given name/type/IN (internet class).
+     * @param name The name e.g. "measite.de".
+     * @param type The type, e.g. A.
+     */
+    public Question(String name, TYPE type) {
+        this(name, type, CLASS.IN);
+    }
+
+    /**
+     * Retrieve the type of this question.
+     * @return The type.
+     */
     public TYPE getType() {
         return type;
     }
 
+    /**
+     * Retrieve the class of this dns question (usually internet).
+     * @return The class of this dns question.
+     */
     public CLASS getClazz() {
         return clazz;
     }
 
+    /**
+     * Retrieve the name of this dns question (e.g. "measite.de").
+     * @return The name of this dns question.
+     */
     public String getName() {
         return name;
     }
 
+    /**
+     * Parse a byte array and rebuild the dns question from it.
+     * @param dis The input stream.
+     * @param data The plain data (for dns name references).
+     * @return The parsed dns question.
+     * @throws IOException On errors (read outside of packet).
+     */
     public static Question parse(DataInputStream dis, byte[] data) throws IOException {
         String name = NameUtil.parse(dis, data);
         TYPE type = TYPE.getType(dis.readUnsignedShort());
@@ -44,6 +94,10 @@ public class Question {
         return new Question (name, type, clazz);
     }
 
+    /**
+     * Generate a binary paket for this dns question.
+     * @return The dns question.
+     */
     public byte[] toByteArray() {
         if (byteArray == null) {
             ByteArrayOutputStream baos = new ByteArrayOutputStream(512);
@@ -65,7 +119,7 @@ public class Question {
 
     @Override
     public int hashCode() {
-        return toByteArray().hashCode();
+        return Arrays.hashCode(toByteArray());
     }
 
     @Override
@@ -76,6 +130,8 @@ public class Question {
         if (!(other instanceof Question)) {
             return false;
         }
-        return this.hashCode() == other.hashCode();
+        byte t[] = toByteArray();
+        byte o[] = ((Question)other).toByteArray();
+        return Arrays.equals(t, o);
     }
 }
diff --git a/src/main/java/de/measite/minidns/Record.java b/src/main/java/de/measite/minidns/Record.java
index fb0b5d5f..36d3db1a 100644
--- a/src/main/java/de/measite/minidns/Record.java
+++ b/src/main/java/de/measite/minidns/Record.java
@@ -286,10 +286,18 @@ public class Record {
                (q.getName().equals(name));
     }
 
+    /**
+     * The generic record name, e.g. "measite.de".
+     * @return The record name.
+     */
     public String getName() {
         return name;
     }
 
+    /**
+     * The payload data, usually a subclass of data (A, AAAA, CNAME, ...).
+     * @return The payload data.
+     */
     public Data getPayload() {
         return payloadData;
     }
diff --git a/src/main/java/de/measite/minidns/record/A.java b/src/main/java/de/measite/minidns/record/A.java
index a85a7af0..4311c651 100644
--- a/src/main/java/de/measite/minidns/record/A.java
+++ b/src/main/java/de/measite/minidns/record/A.java
@@ -5,8 +5,14 @@ import java.io.IOException;
 
 import de.measite.minidns.Record.TYPE;
 
+/**
+ * A record payload (ip pointer).
+ */
 public class A implements Data {
 
+    /**
+     * Target IP.
+     */
     private byte[] ip;
 
     @Override
diff --git a/src/main/java/de/measite/minidns/record/AAAA.java b/src/main/java/de/measite/minidns/record/AAAA.java
index d89147b2..e4fd5ecf 100644
--- a/src/main/java/de/measite/minidns/record/AAAA.java
+++ b/src/main/java/de/measite/minidns/record/AAAA.java
@@ -5,8 +5,14 @@ import java.io.IOException;
 
 import de.measite.minidns.Record.TYPE;
 
+/**
+ * AAAA payload (an ipv6 pointer).
+ */
 public class AAAA implements Data {
 
+    /**
+     * The ipv6 address.
+     */
     private byte[] ip;
 
     @Override
diff --git a/src/main/java/de/measite/minidns/record/CNAME.java b/src/main/java/de/measite/minidns/record/CNAME.java
index 4657b4a5..1ac27814 100644
--- a/src/main/java/de/measite/minidns/record/CNAME.java
+++ b/src/main/java/de/measite/minidns/record/CNAME.java
@@ -6,6 +6,9 @@ import java.io.IOException;
 import de.measite.minidns.Record.TYPE;
 import de.measite.minidns.util.NameUtil;
 
+/**
+ * CNAME payload (pointer to another domain / address).
+ */
 public class CNAME implements Data {
 
     protected String name;
@@ -20,8 +23,7 @@ public class CNAME implements Data {
 
     @Override
     public byte[] toByteArray() {
-        // TODO Auto-generated method stub
-        return null;
+        throw new UnsupportedOperationException("Not implemented yet");
     }
 
     @Override
diff --git a/src/main/java/de/measite/minidns/record/Data.java b/src/main/java/de/measite/minidns/record/Data.java
index 9cb80374..7f2db03a 100644
--- a/src/main/java/de/measite/minidns/record/Data.java
+++ b/src/main/java/de/measite/minidns/record/Data.java
@@ -5,12 +5,30 @@ import java.io.IOException;
 
 import de.measite.minidns.Record.TYPE;
 
+/**
+ * Generic payload class.
+ */
 public interface Data {
 
+    /**
+     * The payload type.
+     * @return The payload type.
+     */
     TYPE getType();
 
+    /**
+     * Binary representation of this payload.
+     * @return The binary representation of this payload.
+     */
     byte[] toByteArray();
 
+    /**
+     * Parse this payload.
+     * @param dis The input stream.
+     * @param data The plain data (needed for name cross references).
+     * @param length The payload length.
+     * @throws IOException on io error (read past paket boundary).
+     */
     void parse(DataInputStream dis, byte data[], int length) throws IOException;
 
 }
diff --git a/src/main/java/de/measite/minidns/record/NS.java b/src/main/java/de/measite/minidns/record/NS.java
index bf07e8c4..8ac2d4c3 100644
--- a/src/main/java/de/measite/minidns/record/NS.java
+++ b/src/main/java/de/measite/minidns/record/NS.java
@@ -2,6 +2,9 @@ package de.measite.minidns.record;
 
 import de.measite.minidns.Record.TYPE;
 
+/**
+ * Nameserver record.
+ */
 public class NS extends CNAME {
 
     @Override
diff --git a/src/main/java/de/measite/minidns/record/SRV.java b/src/main/java/de/measite/minidns/record/SRV.java
index 32b70c4d..707bf3f5 100644
--- a/src/main/java/de/measite/minidns/record/SRV.java
+++ b/src/main/java/de/measite/minidns/record/SRV.java
@@ -6,49 +6,99 @@ import java.io.IOException;
 import de.measite.minidns.Record.TYPE;
 import de.measite.minidns.util.NameUtil;
 
+/**
+ * SRV record payload (service pointer).
+ */
 public class SRV implements Data {
 
+    /**
+     * The priority of this service.
+     */
     protected int priority;
+
+    /**
+     * The weight of this service.
+     */
     protected int weight;
+
+    /**
+     * The target port.
+     */
     protected int port;
+
+    /**
+     * The target server.
+     */
     protected String name;
 
+    /**
+     * The priority of this service. Lower values mean higher priority.
+     * @return The priority.
+     */
     public int getPriority() {
         return priority;
     }
 
+    /**
+     * Set the priority of this service entry. Lower values have higher priority.
+     * @param priority The new priority.
+     */
     public void setPriority(int priority) {
         this.priority = priority;
     }
 
+    /**
+     * The weight of this service. Services with the same priority should be
+     * balanced based on weight.
+     * @return The weight of this service.
+     */
     public int getWeight() {
         return weight;
     }
 
+    /**
+     * Set the weight of this service.
+     * @param weight The new weight of this service.
+     */
     public void setWeight(int weight) {
         this.weight = weight;
     }
 
+    /**
+     * The target port of this service.
+     * @return The target port of this service.
+     */
     public int getPort() {
         return port;
     }
 
+    /**
+     * Set the target port of this service.
+     * @param port The new target port.
+     */
     public void setPort(int port) {
         this.port = port;
     }
 
+    /**
+     * The name of the target server.
+     * @return The target servers name.
+     */
     public String getName() {
         return name;
     }
 
+    /**
+     * Set the name of the target server.
+     * @param name The new target servers name. 
+     */
     public void setName(String name) {
         this.name = name;
     }
 
     @Override
     public byte[] toByteArray() {
-        // TODO Auto-generated method stub
-        return null;
+        throw new UnsupportedOperationException("Not implemented yet");
     }
 
     @Override
diff --git a/src/main/java/de/measite/minidns/util/NameUtil.java b/src/main/java/de/measite/minidns/util/NameUtil.java
index 91a6649d..7ae373bc 100644
--- a/src/main/java/de/measite/minidns/util/NameUtil.java
+++ b/src/main/java/de/measite/minidns/util/NameUtil.java
@@ -8,12 +8,28 @@ import java.net.IDN;
 import java.util.HashSet;
 import java.util.Arrays;
 
+/**
+ * Utilities related to internationalized domain names and dns name handling.
+ */
 public class NameUtil {
 
+    /**
+     * Retrieve the rough binary length of a string
+     * (length + 2 bytes length prefix).
+     * @param name The name string.
+     * @return The binary size of the string (length + 2).
+     */
     public static int size(String name) {
         return name.length() + 2;
     }
 
+    /**
+     * Check if two internationalized domain names are equal, possibly causing
+     * a serialization of both domain names.
+     * @param name1 The first domain name.
+     * @param name2 The second domain name.
+     * @return True if both domain names are the same.
+     */
     public static boolean idnEquals(String name1, String name2) {
         if (name1 == name2) return true; // catches null, null
         if (name1 == null) return false;
@@ -27,6 +43,12 @@ public class NameUtil {
         }
     }
 
+    /**
+     * Serialize a domain name under IDN rules.
+     * @param name The domain name.
+     * @return The binary domain name representation.
+     * @throws IOException Should never happen.
+     */
     public static byte[] toByteArray(String name) throws IOException {
         ByteArrayOutputStream baos = new ByteArrayOutputStream(64);
         DataOutputStream dos = new DataOutputStream(baos);
@@ -38,8 +60,16 @@ public class NameUtil {
         dos.writeByte(0);
         dos.flush();
         return baos.toByteArray();
-    }   
+    }
 
+    /**
+     * Parse a domain name starting at the current offset and moving the input
+     * stream pointer past this domain name (even if cross references occure).
+     * @param dis The input stream.
+     * @param data The raw data (for cross references).
+     * @return The domain name string.
+     * @throws IOException Should never happen.
+     */
     public static String parse(DataInputStream dis, byte data[]) 
         throws IOException
     {
@@ -63,6 +93,14 @@ public class NameUtil {
         return s;
     }
 
+    /**
+     * Parse a domain name starting at the given offset. 
+     * @param data The raw data.
+     * @param offset The offset.
+     * @param jumps The list of jumps (by now).
+     * @return The parsed domain name.
+     * @throws IllegalStateException on cycles.
+     */
     public static String parse(
         byte data[],
         int offset,