Fix javadoc

pom.xml

@@ -86,6 +86,7 @@
         <configuration>
           <charset>UTF-8</charset>
           <locale>en_US</locale>
+          <show>public</show>
         </configuration>
         <executions>
           <execution>

src/main/java/org/xerial/snappy/Snappy.java

@@ -27,6 +27,7 @@ package org.xerial.snappy;
 import java.io.IOException;
 import java.io.UnsupportedEncodingException;
 import java.nio.ByteBuffer;
+import java.nio.charset.Charset;
 
 /**
  * Snappy API for data compression/decompression
@@ -138,30 +139,73 @@ public class Snappy
         return compressedSize;
     }
 
+    /**
+     * Compress the input char array
+     * 
+     * @param input
+     * @return the compressed data
+     */
     public static byte[] compress(char[] input) {
         return rawCompress(input, input.length * 2); // char uses 2 bytes
     }
 
+    /**
+     * Compress the input double array
+     * 
+     * @param input
+     * @return the compressed data
+     */
     public static byte[] compress(double[] input) {
         return rawCompress(input, input.length * 8); // double uses 8 bytes
     }
 
+    /**
+     * Compress the input float array
+     * 
+     * @param input
+     * @return the compressed data
+     */
     public static byte[] compress(float[] input) {
         return rawCompress(input, input.length * 4); // float uses 4 bytes
     }
 
+    /**
+     * Compress the input int array
+     * 
+     * @param input
+     * @return the compressed data
+     */
     public static byte[] compress(int[] input) {
         return rawCompress(input, input.length * 4); // int uses 4 bytes
     }
 
+    /**
+     * Compress the input long array
+     * 
+     * @param input
+     * @return the compressed data
+     */
     public static byte[] compress(long[] input) {
         return rawCompress(input, input.length * 8); // long uses 8 bytes
     }
 
+    /**
+     * Compress the input short array
+     * 
+     * @param input
+     * @return the compressed data
+     */
     public static byte[] compress(short[] input) {
         return rawCompress(input, input.length * 2); // short uses 2 bytes
     }
 
+    /**
+     * Compress the input String
+     * 
+     * @param s
+     * @return the compressed data
+     * @throws IOException
+     */
     public static byte[] compress(String s) throws IOException {
         try {
             return compress(s, "UTF-8");
@@ -171,11 +215,34 @@ public class Snappy
         }
     }
 
+    /**
+     * Compress the input string using the given encoding
+     * 
+     * @param s
+     * @param encoding
+     * @return the compressed data
+     * @throws UnsupportedEncodingException
+     * @throws IOException
+     */
     public static byte[] compress(String s, String encoding) throws UnsupportedEncodingException, IOException {
         byte[] data = s.getBytes(encoding);
         return compress(data);
     }
 
+    /**
+     * Compress the input string using the given encoding
+     * 
+     * @param s
+     * @param encoding
+     * @return the compressed data
+     * @throws UnsupportedEncodingException
+     * @throws IOException
+     */
+    public static byte[] compress(String s, Charset encoding) throws IOException {
+        byte[] data = s.getBytes(encoding);
+        return compress(data);
+    }
+
     /**
      * Get the native library version of the snappy
      * 
@@ -252,13 +319,13 @@ public class Snappy
      * write the compressed data to the output buffer[offset, ...)
      * 
      * @param input
-     *            input array. This MUST be primitive array type
+     *            input array. This MUST be a primitive array type
      * @param inputOffset
      *            byte offset at the output array
      * @param inputLength
      *            byte length of the input data
      * @param output
-     *            output array. This MUST be primitive array type
+     *            output array. This MUST be a primitive array type
      * @param outputOffset
      *            byte offset at the output array
      * @return byte size of the compressed data
@@ -380,10 +447,26 @@ public class Snappy
         return decompressedSize;
     }
 
+    /**
+     * Uncompress the input data as char array
+     * 
+     * @param input
+     * @return the umcompressed data
+     * @throws IOException
+     */
     public static char[] uncompressCharArray(byte[] input) throws IOException {
         return uncompressCharArray(input, 0, input.length);
     }
 
+    /**
+     * Uncompress the input[offset, .., offset+length) as a char array
+     * 
+     * @param input
+     * @param offset
+     * @param length
+     * @return the uncompressed data
+     * @throws IOException
+     */
     public static char[] uncompressCharArray(byte[] input, int offset, int length) throws IOException {
         int uncompressedLength = Snappy.uncompressedLength(input, offset, length);
         char[] result = new char[uncompressedLength / 2];
@@ -391,6 +474,13 @@ public class Snappy
         return result;
     }
 
+    /**
+     * Uncompress the input as a double array
+     * 
+     * @param input
+     * @return the uncompressed data
+     * @throws IOException
+     */
     public static double[] uncompressDoubleArray(byte[] input) throws IOException {
         int uncompressedLength = Snappy.uncompressedLength(input, 0, input.length);
         double[] result = new double[uncompressedLength / 8];
@@ -451,10 +541,26 @@ public class Snappy
         return ((SnappyNativeAPI) impl).uncompressedLength(compressed, compressed.position(), compressed.remaining());
     }
 
+    /**
+     * Uncompress the input as a float array
+     * 
+     * @param input
+     * @return the uncompressed data
+     * @throws IOException
+     */
     public static float[] uncompressFloatArray(byte[] input) throws IOException {
         return uncompressFloatArray(input, 0, input.length);
     }
 
+    /**
+     * Uncompress the input[offset, offset+length) as a float array
+     * 
+     * @param input
+     * @param offset
+     * @param length
+     * @return the uncompressed data
+     * @throws IOException
+     */
     public static float[] uncompressFloatArray(byte[] input, int offset, int length) throws IOException {
         int uncompressedLength = Snappy.uncompressedLength(input, offset, length);
         float[] result = new float[uncompressedLength / 4];
@@ -462,10 +568,26 @@ public class Snappy
         return result;
     }
 
+    /**
+     * Uncompress the input data as an int array
+     * 
+     * @param input
+     * @return the uncompressed data
+     * @throws IOException
+     */
     public static int[] uncompressIntArray(byte[] input) throws IOException {
         return uncompressIntArray(input, 0, input.length);
     }
 
+    /**
+     * Uncompress the input[offset, offset+length) as an int array
+     * 
+     * @param input
+     * @param offset
+     * @param length
+     * @return the uncompressed data
+     * @throws IOException
+     */
     public static int[] uncompressIntArray(byte[] input, int offset, int length) throws IOException {
         int uncompressedLength = Snappy.uncompressedLength(input, offset, length);
         int[] result = new int[uncompressedLength / 4];
@@ -473,10 +595,26 @@ public class Snappy
         return result;
     }
 
+    /**
+     * Uncompress the input data as a long array
+     * 
+     * @param input
+     * @return the uncompressed data
+     * @throws IOException
+     */
     public static long[] uncompressLongArray(byte[] input) throws IOException {
         return uncompressLongArray(input, 0, input.length);
     }
 
+    /**
+     * Uncompress the input[offset, offset+length) as a long array
+     * 
+     * @param input
+     * @param offset
+     * @param length
+     * @return the uncompressed data
+     * @throws IOException
+     */
     public static long[] uncompressLongArray(byte[] input, int offset, int length) throws IOException {
         int uncompressedLength = Snappy.uncompressedLength(input, offset, length);
         long[] result = new long[uncompressedLength / 8];
@@ -484,10 +622,26 @@ public class Snappy
         return result;
     }
 
+    /**
+     * Uncompress the input as a short array
+     * 
+     * @param input
+     * @return the uncompressed data
+     * @throws IOException
+     */
     public static short[] uncompressShortArray(byte[] input) throws IOException {
         return uncompressShortArray(input, 0, input.length);
     }
 
+    /**
+     * Uncompress the input[offset, offset+length) as a short array
+     * 
+     * @param input
+     * @param offset
+     * @param length
+     * @return the uncompressed data
+     * @throws IOException
+     */
     public static short[] uncompressShortArray(byte[] input, int offset, int length) throws IOException {
         int uncompressedLength = Snappy.uncompressedLength(input, offset, length);
         short[] result = new short[uncompressedLength / 2];
@@ -495,6 +649,13 @@ public class Snappy
         return result;
     }
 
+    /**
+     * Uncompress the input as a String
+     * 
+     * @param input
+     * @return the uncompressed dasta
+     * @throws IOException
+     */
     public static String uncompressString(byte[] input) throws IOException {
         try {
             return uncompressString(input, "UTF-8");
@@ -504,6 +665,15 @@ public class Snappy
         }
     }
 
+    /**
+     * Uncompress the input[offset, offset+length) as a String
+     * 
+     * @param input
+     * @param offset
+     * @param length
+     * @return the uncompressed data
+     * @throws IOException
+     */
     public static String uncompressString(byte[] input, int offset, int length) throws IOException {
         try {
             return uncompressString(input, offset, length, "UTF-8");
@@ -513,6 +683,17 @@ public class Snappy
         }
     }
 
+    /**
+     * Uncompress the input[offset, offset+length) as a String of the given
+     * encoding
+     * 
+     * @param input
+     * @param offset
+     * @param length
+     * @param encoding
+     * @return the uncompressed data
+     * @throws IOException
+     */
     public static String uncompressString(byte[] input, int offset, int length, String encoding) throws IOException,
             UnsupportedEncodingException {
         byte[] uncompressed = new byte[uncompressedLength(input, offset, length)];
@@ -520,10 +701,50 @@ public class Snappy
         return new String(uncompressed, encoding);
     }
 
+    /**
+     * Uncompress the input[offset, offset+length) as a String of the given
+     * encoding
+     * 
+     * @param input
+     * @param offset
+     * @param length
+     * @param encoding
+     * @return the uncompressed data
+     * @throws IOException
+     */
+    public static String uncompressString(byte[] input, int offset, int length, Charset encoding) throws IOException,
+            UnsupportedEncodingException {
+        byte[] uncompressed = new byte[uncompressedLength(input, offset, length)];
+        int compressedSize = uncompress(input, offset, length, uncompressed, 0);
+        return new String(uncompressed, encoding);
+    }
+
+    /**
+     * Uncompress the input as a String of the given encoding
+     * 
+     * @param input
+     * @param encoding
+     * @return the uncompressed data
+     * @throws IOException
+     * @throws UnsupportedEncodingException
+     */
     public static String uncompressString(byte[] input, String encoding) throws IOException,
             UnsupportedEncodingException {
         byte[] uncompressed = uncompress(input);
         return new String(uncompressed, encoding);
     }
 
+    /**
+     * Uncompress the input as a String of the given encoding
+     * 
+     * @param input
+     * @param encoding
+     * @return the uncompressed data
+     * @throws IOException
+     */
+    public static String uncompressString(byte[] input, Charset encoding) throws IOException,
+            UnsupportedEncodingException {
+        byte[] uncompressed = uncompress(input);
+        return new String(uncompressed, encoding);
+    }
 }

src/main/java/org/xerial/snappy/SnappyInputStream.java

@@ -31,6 +31,7 @@ import java.io.InputStream;
 /**
  * A stream filter for reading data compressed by {@link SnappyOutputStream}.
  * 
+ * 
  * @author leo
  * 
  */
@@ -46,11 +47,23 @@ public class SnappyInputStream extends InputStream
 
     private byte[]              chunkSizeBuf       = new byte[4];
 
+    /**
+     * Create a filter for reading compressed data as a uncompressed stream
+     * 
+     * @param input
+     * @throws IOException
+     */
     public SnappyInputStream(InputStream input) throws IOException {
         this.in = input;
         readHeader();
     }
 
+    /**
+     * Close the stream
+     */
+    /* (non-Javadoc)
+     * @see java.io.InputStream#close()
+     */
     @Override
     public void close() throws IOException {
         compressed = null;
@@ -117,6 +130,13 @@ public class SnappyInputStream extends InputStream
 
     }
 
+    /**
+     * Reads up to len bytes of data from the input stream into an array of
+     * bytes.
+     */
+    /* (non-Javadoc)
+     * @see java.io.InputStream#read(byte[], int, int)
+     */
     @Override
     public int read(byte[] b, int off, int len) throws IOException {
         return rawRead(b, off, len);
@@ -159,7 +179,8 @@ public class SnappyInputStream extends InputStream
      *            offset
      * @param len
      *            the number of long elements to read
-     * @return the number of read bytes
+     * @return the total number of bytes read into the buffer, or -1 if there is
+     *         no more data because the end of the stream has been reached.
      * @throws IOException
      */
     public int read(long[] d, int off, int len) throws IOException {
@@ -170,7 +191,8 @@ public class SnappyInputStream extends InputStream
      * Read long array from the stream
      * 
      * @param d
-     * @return the number of read bytes
+     * @return the total number of bytes read into the buffer, or -1 if there is
+     *         no more data because the end of the stream has been reached.
      * @throws IOException
      */
     public int read(long[] d) throws IOException {
@@ -186,7 +208,8 @@ public class SnappyInputStream extends InputStream
      *            offset
      * @param len
      *            the number of double elements to read
-     * @return the number of read bytes
+     * @return the total number of bytes read into the buffer, or -1 if there is
+     *         no more data because the end of the stream has been reached.
      * @throws IOException
      */
     public int read(double[] d, int off, int len) throws IOException {
@@ -197,7 +220,8 @@ public class SnappyInputStream extends InputStream
      * Read double array from the stream
      * 
      * @param d
-     * @return read bytes
+     * @return the total number of bytes read into the buffer, or -1 if there is
+     *         no more data because the end of the stream has been reached.
      * @throws IOException
      */
     public int read(double[] d) throws IOException {
@@ -208,7 +232,8 @@ public class SnappyInputStream extends InputStream
      * Read int array from the stream
      * 
      * @param d
-     * @return read bytes
+     * @return the total number of bytes read into the buffer, or -1 if there is
+     *         no more data because the end of the stream has been reached.
      * @throws IOException
      */
     public int read(int[] d) throws IOException {
@@ -224,7 +249,8 @@ public class SnappyInputStream extends InputStream
      *            offset
      * @param len
      *            the number of int elements to read
-     * @return the number of read bytes
+     * @return the total number of bytes read into the buffer, or -1 if there is
+     *         no more data because the end of the stream has been reached.
      * @throws IOException
      */
     public int read(int[] d, int off, int len) throws IOException {
@@ -240,7 +266,8 @@ public class SnappyInputStream extends InputStream
      *            offset
      * @param len
      *            the number of float elements to read
-     * @return the number of read bytes
+     * @return the total number of bytes read into the buffer, or -1 if there is
+     *         no more data because the end of the stream has been reached.
      * @throws IOException
      */
     public int read(float[] d, int off, int len) throws IOException {
@@ -251,7 +278,8 @@ public class SnappyInputStream extends InputStream
      * Read float array from the stream
      * 
      * @param d
-     * @return the number of read bytes
+     * @return the total number of bytes read into the buffer, or -1 if there is
+     *         no more data because the end of the stream has been reached.
      * @throws IOException
      */
     public int read(float[] d) throws IOException {
@@ -267,7 +295,8 @@ public class SnappyInputStream extends InputStream
      *            offset
      * @param len
      *            the number of short elements to read
-     * @return the number of read bytes
+     * @return the total number of bytes read into the buffer, or -1 if there is
+     *         no more data because the end of the stream has been reached.
      * @throws IOException
      */
     public int read(short[] d, int off, int len) throws IOException {
@@ -278,7 +307,8 @@ public class SnappyInputStream extends InputStream
      * Read short array from the stream
      * 
      * @param d
-     * @return the number of read bytes
+     * @return the total number of bytes read into the buffer, or -1 if there is
+     *         no more data because the end of the stream has been reached.
      * @throws IOException
      */
     public int read(short[] d) throws IOException {
@@ -330,6 +360,16 @@ public class SnappyInputStream extends InputStream
         return true;
     }
 
+    /**
+     * Reads the next byte of uncompressed data from the input stream. The value
+     * byte is returned as an int in the range 0 to 255. If no byte is available
+     * because the end of the stream has been reached, the value -1 is returned.
+     * This method blocks until input data is available, the end of the stream
+     * is detected, or an exception is thrown.
+     */
+    /* (non-Javadoc)
+     * @see java.io.InputStream#read()
+     */
     @Override
     public int read() throws IOException {
         if (uncompressedCursor < uncompressedLimit) {

src/main/java/org/xerial/snappy/SnappyOutputStream.java

@@ -36,8 +36,9 @@ import java.io.OutputStream;
  * 
  * The output data format is:
  * <ol>
- * <li>snappy codec header defined in {@link SnappyCodec}
+ * <li>snappy codec header defined in {@link SnappyCodec} (8 bytes)
- * <li>a pair of (compressed data size, compressed data...)
+ * <li>a pair of (compressed data size [4 byte integer. Big-endian], compressed
+ * data...)
  * <li>...
  * </ol>
  *