diff --git a/README b/README index 394d4fa..6186102 100755 --- a/README +++ b/README @@ -1,5 +1,106 @@ +The snappy-java is a Java port of the snappy http://code.google.com/p/snappy/, a fast compresser/decompresser (written in C++ developed by Google). + +== Features == + * [http://www.apache.org/licenses/LICENSE-2.0 Apache Licence Version 2.0]. Free for both commercial and non-commercial use! + * Fast compression/decompression tailored to 64-bit CPU architecture. + * JNI-based implemenation to achieve comparable performance to the native C++ version. + * Portable across various operating systems; Snappy-java contains the native libraries built for Window/Mac/Linux (32/64-bit). At runtime, snappy-java loads one of these libraries according to your machine environment (It looks system properties, `os.name` and `os.arch`). + * Simple usage. Add the snappy-java-(version).jar file to your classpath. Then call compression/decompression methods in org.xerial.snappy.Snappy. + +== Performance == + * Here are some [https://github.com/ning/jvm-compressor-benchmark/wiki benchmark results], comparing snappy-java and the other compressors `LZF`/`QuickLZ`/`Gzip`/`Bzip2`. Thanks [http://twitter.com/#!/cowtowncoder Tatu Saloranta @cowtowncoder] for providing the benchmark suite. + * Snappy's main target is very high-speed compression/decompression with reasonable compression size. Although the compression ratio of snappy-java is modest and about the same as `LZF` (ranging 20%-100% according to the dataset), among the Java-based compressors in the benchmark snappy-java is as fast as the fastest for compression, and the decompression speed is 2x as fast to the others. + +== Download == +The current version 1.0.1-rc4 is available from here: + * Release version: http://maven.xerial.org/repository/artifact/org/xerial/snappy/snappy-java + * [Milestone] release plans + * Snapshot version (the latest beta version): http://maven.xerial.org/repository/snapshot/org/xerial/snappy/snappy-java/ + +If you are a Maven user, see [#Using_with_Maven] + +== Usage == +First, import `org.xerial.snapy.Snappy` in your Java code: +{{{ +import org.xerial.snappy.Snappy; +}}} + +Then use `Snappy.compress(byte[])` and `Snappy.uncompress(byte[])`: +{{{ +String input = "Hello snappy-java! Snappy-java is a JNI-based wrapper of " ++ "Snappy, a fast compresser/decompresser."; +byte[] compressed = Snappy.compress(input.getBytes("UTF-8")); +byte[] uncompressed = Snappy.uncompress(compressed); + +String result = new String(uncompressed, "UTF-8"); +System.out.println(result); +}}} + +In addition, high-level methods (Snappy.compress(String), Snappy.compress(float[] ..) etc. ) and low-level ones (e.g. Snappy.rawCompress(.. ), Snappy.rawUncompress(..), etc.), which minimize memory copies, can be used. See also +[http://code.google.com/p/snappy-java/source/browse/src/main/java/org/xerial/snappy/Snappy.java Snappy.java] + +===Stream-based API=== +Stream-based compressor/decompressor `SnappyOutputStream`/`SnappyInputStream` are also available for reading/writing large data sets. + +===Setting classpath== +If you have snappy-java-(VERSION).jar in the current directory, use `-classpath` option as follows: +{{{ +$ javac -classpath ".;snappy-java-(VERSION).jar" Sample.java # in Windows +or +$ javac -classpath ".:snappy-java-(VERSION).jar" Sample.java # in Mac or Linux +}}} + +===Using with Maven=== + * Snappy-java is available from Maven's central repository: http://repo1.maven.org/maven2/org/xerial/snappy/snappy-java + +Add the following dependency to your pom.xml: +{{{ + + org.xerial.snappy + snappy-java + 1.0.1-rc4 + jar + compile + +}}} + +==Public discussion group== +Post bug reports or feature request to the Issue Tracker: http://code.google.com/p/snappy-java/issues/list + +Public discussion forum is here: [http://groups.google.com/group/xerial?hl=en Xerial Public Discussion Group]. + + +== Building from the source code == +See the [http://code.google.com/p/snappy-java/source/browse/INSTALL installation instruction]. Building from the source code is an option when JNI-related error (e.g., Java VM crash) is observed in your machine environment. To build snappy-java, you need Mercurial(hg), JDK (1.6 or higher), Maven (3.x or higher is required), g++ compiler (mingw in Windows) etc. + +{{{ +$ hg clone https://snappy-java.googlecode.com/hg/ snappy-java +$ cd snappy-java +$ make +}}} + +A file `target/snappy-java-$(version).jar` is the product containing the native library built for your platform. + +==Miscellaneous Notes== +===Using snappy-java with Tomcat6 Web Server=== + +Do not include snappy-java-(version).jar in WEB-INF/lib folder of your web application package, since multiple web applications hosted by the same Tomcat server cannot load the snappy-java's native library multiple times due to the specification of JNI (See Section 11.2.4 A Type Safety Restriction http://java.sun.com/docs/books/jni/html/design.html#8628). If Snappy is loaded by different class loaders under the same JVM, you will see `UnsatisfiedLinkError` exception. + +A workaround of this problem is to put snappy-java-(version).jar file into `(TOMCAT_HOME)/lib` direcotry, in which multiple web applications can share the same native library file (.dll, .jnilib, .so) extracted from this snappy-java-(version).jar file. + +If you are using Maven for your web application, set the dependency scope as 'provided', and manually put the snappy-java jar file into (TOMCAT_HOME)/lib folder. + +{{{ + + org.xerial.snappy + snappy-java + 1.0.1-rc4 + provided + +}}} +---- +Snappy-java is developed by [http://www.xerial.org/leo Taro L. Saito]. Twitter [http://twitter.com/#!/taroleo @taroleo] -Snappy-java is a Java port of snappy http://code.google.com/p/snappy/, a fast compressor/decompressor. [usage] diff --git a/src/main/java/org/xerial/snappy/LoadSnappy.java b/src/main/java/org/xerial/snappy/LoadSnappy.java index 40ba313..a56adf4 100755 --- a/src/main/java/org/xerial/snappy/LoadSnappy.java +++ b/src/main/java/org/xerial/snappy/LoadSnappy.java @@ -38,7 +38,8 @@ import java.security.NoSuchAlgorithmException; import java.util.Properties; /** - * + * This class loads a native library of Snappy according to the platform of the + * user. * * @author leo * @@ -49,7 +50,6 @@ public class LoadSnappy public static boolean load() { if (!isLoaded) { - ClassLoader cl = Thread.currentThread().getContextClassLoader(); loadSnappyNativeLibrary(); } return isLoaded; @@ -169,7 +169,7 @@ public class LoadSnappy if (isLoaded) return; - // Try loading library from org.sqlite.lib.path library path */ + // Try loading the library from org.xerial.snappy.lib.path library path */ String snappyNativeLibraryPath = System.getProperty("org.xerial.snappy.lib.path"); String snappyNativeLibraryName = System.getProperty("org.xerial.snappy.lib.name"); @@ -192,7 +192,7 @@ public class LoadSnappy return; } - // temporary library folder + // Temporary library folder. Use the value of java.io.tmpdir String tempFolder = new File(System.getProperty("java.io.tmpdir")).getAbsolutePath(); // Try extracting the library from jar if (extractAndLoadLibraryFile(snappyNativeLibraryPath, snappyNativeLibraryName, tempFolder)) { diff --git a/src/main/java/org/xerial/snappy/Snappy.java b/src/main/java/org/xerial/snappy/Snappy.java index 0694f19..ea6b41e 100755 --- a/src/main/java/org/xerial/snappy/Snappy.java +++ b/src/main/java/org/xerial/snappy/Snappy.java @@ -108,27 +108,27 @@ public class Snappy } public static byte[] compress(char[] input) { - return rawCompress(input, input.length * 2); // short use 2 bytes + return rawCompress(input, input.length * 2); // short uses 2 bytes } public static byte[] compress(double[] input) { - return rawCompress(input, input.length * 8); // double use 8 bytes + return rawCompress(input, input.length * 8); // double uses 8 bytes } public static byte[] compress(float[] input) { - return rawCompress(input, input.length * 4); // float use 4 bytes + return rawCompress(input, input.length * 4); // float uses 4 bytes } public static byte[] compress(int[] input) { - return rawCompress(input, input.length * 4); // int use 4 bytes + return rawCompress(input, input.length * 4); // int uses 4 bytes } public static byte[] compress(long[] input) { - return rawCompress(input, input.length * 8); // long use 8 bytes + return rawCompress(input, input.length * 8); // long uses 8 bytes } public static byte[] compress(short[] input) { - return rawCompress(input, input.length * 2); // short use 2 bytes + return rawCompress(input, input.length * 2); // short uses 2 bytes } public static byte[] compress(String s) throws SnappyException { @@ -177,7 +177,7 @@ public class Snappy } /** - * Get the maximum byte size needed for compressing a data of the given byte + * Get the maximum byte size needed for compressing data of the given byte * size. * * @param byteSize @@ -189,7 +189,7 @@ public class Snappy } /** - * Compress the input data and produce an output array + * Compress the input data and produce a byte array of the uncompressed data * * @param data * input array. The input MUST be an array type