added Zero Bytes Copy page

Author: simotripo

src/site/apt/zero-bytes-copy.apt

@@ -0,0 +1,45 @@
+                                    ------
+                           Async Http Client - Zero Bytes Copy
+                                    ------
+                              Jeanfrancois Arcand
+                                    ------
+                                       2012
+
+Zero Bytes Copy
+
+  When uploading or downloading bytes, it is important to try to avoid buffering bytes in memory.
+
+* Upload
+
+  On the upload side, the mechanism is enabled by default when setting the <<<Request>>>'s body to a File:
+
++-----+
+AsyncHttpClient client = new AsyncHttpClient();
+File file = new File("file.avi");
+Future f = client.preparePut("http://localhost").setBody(file).execute();
++-----+
+
+  If you can't use a File, the recommended way is to use a <<<BodyGenerator>>>. It is strongly recommended to avoid
+  using <<<InputStream>>> as the library will unfortunately buffer the entire content in memory in order to set the
+  <<<content-lenght>>>, which can cause out of memory error.
+
+* Download
+
+  On the download side, you can use the <<<HttpResponseBodyPart.writeTo>>> to avoid loading bytes in memory and
+  unnecessary copy:
+
++-----+
+AsyncHttpClient client = new AsyncHttpClient();
+File tmp = new File("zeroCopy.txt");
+final FileOutputStream stream = new FileOutputStream(tmp);
+Future f = client.prepareGet("http://localhost/largefile.avi").execute(new AsyncHandler() {
+    public void onThrowable(Throwable t) { }
+
+    public STATE onBodyPartReceived(HttpResponseBodyPart bodyPart) throws Exception {
+        bodyPart.writeTo(stream);
+        return STATE.CONTINUE;
+    }
+
+{ .... } });
+Response resp = f.get();
++-----+