diff --git a/pom.xml b/pom.xml index fed3aa2..29b4c7e 100755 --- a/pom.xml +++ b/pom.xml @@ -86,6 +86,7 @@ UTF-8 en_US + public diff --git a/src/main/java/org/xerial/snappy/Snappy.java b/src/main/java/org/xerial/snappy/Snappy.java index fff81f6..3d41e31 100755 --- a/src/main/java/org/xerial/snappy/Snappy.java +++ b/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); + } } diff --git a/src/main/java/org/xerial/snappy/SnappyInputStream.java b/src/main/java/org/xerial/snappy/SnappyInputStream.java index 51c5d4e..a9d1023 100755 --- a/src/main/java/org/xerial/snappy/SnappyInputStream.java +++ b/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) { diff --git a/src/main/java/org/xerial/snappy/SnappyOutputStream.java b/src/main/java/org/xerial/snappy/SnappyOutputStream.java index 786606a..5ae645f 100755 --- a/src/main/java/org/xerial/snappy/SnappyOutputStream.java +++ b/src/main/java/org/xerial/snappy/SnappyOutputStream.java @@ -36,8 +36,9 @@ import java.io.OutputStream; * * The output data format is: *
    - *
  1. snappy codec header defined in {@link SnappyCodec} - *
  2. a pair of (compressed data size, compressed data...) + *
  3. snappy codec header defined in {@link SnappyCodec} (8 bytes) + *
  4. a pair of (compressed data size [4 byte integer. Big-endian], compressed + * data...) *
  5. ... *
*