snappy-java/README

This document is a copy of http://code.google.com/p/snappy-java/

---------------------------------------

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:
{{{
<dependency>
  <groupId>org.xerial.snappy</groupId>
  <artifactId>snappy-java</artifactId>
  <version>(version)</version>
  <type>jar</type>
  <scope>compile</scope>
</dependency>
}}}

==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.

{{{
    <dependency>
      <groupId>org.xerial.snappy</groupId>
      <artifactId>snappy-java</artifactId>
      <version>(version)</version>
      <scope>provided</scope>
    </dependency>
}}}
----
Snappy-java is developed by [http://www.xerial.org/leo Taro L. Saito]. Twitter  [http://twitter.com/#!/taroleo @taroleo]


[usage]

* Add snappy-java-(version).jar to your classpath
* Use the compress/decompress methods defined in org.xerial.snappy.Snappy class.

== Contributors ==
  * Tatu Saloranta  
    * Providing benchmark suite
  * Alec Wysoker
    * Performance and memory usage improvement