Distributed Peer-to-Peer Web Search Engine and Intranet Search Appliance
Java decentralizedintranet-searchintranet-search-enginep2pp2p-networkprivacyprivacy-protectionsearch-enginesearchenginewebweb-search-enginewebsearchwebseearch-engine
FileUtils : added some JavaDocs and unit test cases
lucciomana0dfbaca6a06
diff --git a/source/net/yacy/kelondro/util/FileUtils.java b/source/net/yacy/kelondro/util/FileUtils.javaindex 7f1acfff5..e6fd6d670 100644--- a/source/net/yacy/kelondro/util/FileUtils.java+++ b/source/net/yacy/kelondro/util/FileUtils.java@@ -69,18 +69,29 @@ public final class FileUtils {private static final int DEFAULT_BUFFER_SIZE = 1024; // this is also the maximum chunk size+ /**+ * Copy a whole InputStream to an OutputStream. Important : it is the responsibility of the caller to close the input and output streams.+ *+ * @param source InputStream instance+ * @param dest OutputStream instance+ * @param count the total amount of bytes to copy (-1 for all, else must be greater than zero)+ * @return Total number of bytes copied.+ * @throws IOException when a read/write error occurred+ * @throws NullPointerException when a parameter is null+ */public static long copy(final InputStream source, final OutputStream dest) throws IOException {return copy(source, dest, -1);}/**- * Copies an InputStream to an OutputStream. Important : it is the responsibility of the caller to close the input and output streams.+ * Copies a specified amount of bytes from an InputStream to an OutputStream. Important : it is the responsibility of the caller to close the input and output streams.*- * @param source InputStream- * @param dest OutputStream+ * @param source InputStream instance+ * @param dest OutputStream instance* @param count the total amount of bytes to copy (-1 for all, else must be greater than zero)* @return Total number of bytes copied.- * @throws IOException+ * @throws IOException when a read/write error occurred+ * @throws NullPointerException when a parameter is null* @see #copy(InputStream source, File dest)* @see #copyRange(File source, OutputStream dest, int start)* @see #copy(File source, OutputStream dest)@@ -114,23 +125,63 @@ public final class FileUtils {return total;}+ /**+ * Copy a whole InputStream to a Writer, using the default platform charset to decode input stream bytes.+ * Important : it is the responsibility of the caller to close the input stream and output writer.+ *+ * @param source InputStream instance+ * @param dest Writer instance+ * @return the total number of characters copied.+ * @throws IOException when a read/write error occurred+ * @throws NullPointerException when a parameter is null+ */public static int copy(final InputStream source, final Writer dest) throws IOException {final InputStreamReader reader = new InputStreamReader(source);return copy(reader, dest);}+ /**+ * Copy a whole InputStream to a Writer, using the specified charset to decode input stream bytes.+ * Important : it is the responsibility of the caller to close the input stream and output writer.+ *+ * @param source InputStream instance+ * @param dest Writer instance+ * @return the total number of characters copied.+ * @throws IOException when a read/write error occurred+ * @throws NullPointerException when a parameter is null+ */public static int copy(final InputStream source, final Writer dest, final Charset inputCharset)throws IOException {final InputStreamReader reader = new InputStreamReader(source, inputCharset);return copy(reader, dest);}+ /**+ * Copy a String to Writer.+ * Important : it is the responsibility of the caller to close the output writer.+ *+ * @param source String instance+ * @param dest writer instance+ * @return the total number of characters copied (source.length)+ * @throws IOException when a read/write error occurred+ * @throws NullPointerException when a parameter is null+ */public static int copy(final String source, final Writer dest) throws IOException {dest.write(source);dest.flush();return source.length();}+ /**+ * Copy a whole Reader to a Writer.+ * Important : it is the responsibility of the caller to close the input reader and output writer.+ *+ * @param source InputStream instance+ * @param dest Writer instance+ * @return the total number of characters copied.+ * @throws IOException when a read/write error occurred+ * @throws NullPointerException when a parameter is null+ */public static int copy(final Reader source, final Writer dest) throws IOException {assert source != null;assert dest != null;@@ -160,6 +211,15 @@ public final class FileUtils {return count;}+ /**+ * Copy a whole InputStream to a File.+ * Important : it is the responsibility of the caller to close the input stream.+ *+ * @param source InputStream instance+ * @param dest File instance+ * @throws IOException when a read/write error occurred+ * @throws NullPointerException when a parameter is null+ */public static void copy(final InputStream source, final File dest) throws IOException {copy(source, dest, -1);}@@ -167,10 +227,11 @@ public final class FileUtils {/*** Copies an InputStream to a File. Important : it is the responsibility of the caller to close the source stream.*- * @param source InputStream- * @param dest File- * @param count the amount of bytes to copy- * @throws IOException+ * @param source InputStream instance+ * @param dest File instance+ * @param count the amount of bytes to copy (-1 for all, else must be greater than zero)+ * @throws IOException when a read/write error occurred+ * @throws NullPointerException when a parameter is null* @see #copy(InputStream source, OutputStream dest)* @see #copyRange(File source, OutputStream dest, int start)* @see #copy(File source, OutputStream dest)@@ -200,11 +261,13 @@ public final class FileUtils {/*** Copies a part of a File to an OutputStream.- *- * @param source File- * @param dest OutputStream+ * Important : it is the responsibility of the caller to close the destination stream.+ * @param source File instance+ * @param dest OutputStream instance* @param start Number of bytes to skip from the beginning of the File- * @throws IOException+ * @throws IOException when a read/write error occurred+ * @throws NullPointerException when a parameter is null+ * @throws IllegalStateException when an error occurred while skipping bytes* @see #copy(InputStream source, OutputStream dest)* @see #copy(InputStream source, File dest)* @see #copy(File source, OutputStream dest)@@ -237,9 +300,10 @@ public final class FileUtils {/*** Copies a File to an OutputStream. Important : it is the responsibility of the caller to close the output stream.*- * @param source File- * @param dest OutputStream- * @throws IOException+ * @param source File instance+ * @param dest OutputStream instance+ * @throws IOException when a read/write error occurred+ * @throws NullPointerException when a parameter is null* @see #copy(InputStream source, OutputStream dest)* @see #copy(InputStream source, File dest)* @see #copyRange(File source, OutputStream dest, int start)@@ -260,11 +324,28 @@ public final class FileUtils {}}+ /**+ * Copy a whole byte array to an output stream.+ * Important : it is the responsibility of the caller to close the output stream.+ *+ * @param source a byte array+ * @param dest OutputStream instance+ * @throws IOException when a read/write error occurred+ * @throws NullPointerException when a parameter is null+ */public static void copy(final byte[] source, final OutputStream dest) throws IOException {dest.write(source, 0, source.length);dest.flush();}+ /**+ * Copy a whole byte array to a destination file.+ *+ * @param source a byte array+ * @param dest File instance+ * @throws IOException when a read/write error occurred+ * @throws NullPointerException when a parameter is null+ */public static void copy(final byte[] source, final File dest) throws IOException {copy(new ByteArrayInputStream(source), dest);}@@ -273,7 +354,8 @@ public final class FileUtils {* Read fully source stream and close it.* @param source must not be null* @return source content as a byte array.- * @throws IOException when a read/write error occured+ * @throws IOException when a read/write error occurred+ * @throws NullPointerException when source parameter is null*/public static byte[] read(final InputStream source) throws IOException {byte[] content;@@ -289,6 +371,14 @@ public final class FileUtils {return content;}+ /**+ * Read the specified amount of bytes from a source stream.+ * Important : it is the responsibility of the caller to close the stream.+ * @param source InputStream instance. Must not be null+ * @return source content as a byte array.+ * @throws IOException when a read/write error occurred+ * @throws NullPointerException when source parameter is null+ */public static byte[] read(final InputStream source, final int count) throws IOException {if ( count > 0 ) {final byte[] b = new byte[count];diff --git a/test/java/net/yacy/kelondro/util/FileUtilsTest.java b/test/java/net/yacy/kelondro/util/FileUtilsTest.javanew file mode 100644index 000000000..d7c4747f2--- /dev/null+++ b/test/java/net/yacy/kelondro/util/FileUtilsTest.java@@ -0,0 +1,117 @@+// FileUtilsTest.java+// Copyright 2016 by luccioman; https://github.com/luccioman+//+// This is a part of YaCy, a peer-to-peer based web search engine+//+// LICENSE+//+// This program is free software; you can redistribute it and/or modify+// it under the terms of the GNU General Public License as published by+// the Free Software Foundation; either version 2 of the License, or+// (at your option) any later version.+//+// This program is distributed in the hope that it will be useful,+// but WITHOUT ANY WARRANTY; without even the implied warranty of+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the+// GNU General Public License for more details.+//+// You should have received a copy of the GNU General Public License+// along with this program; if not, write to the Free Software+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA++package net.yacy.kelondro.util;++import java.io.ByteArrayInputStream;+import java.io.ByteArrayOutputStream;+import java.io.IOException;+import java.io.InputStream;+import java.nio.charset.StandardCharsets;++import org.junit.Assert;+import org.junit.Test;++/**+ * Unit tests for the {@link FileUtils} class.+ *+ */+public class FileUtilsTest {++ /**+ * Copy stream : normal case+ * @throws IOException when a read/write error occurred+ */+ @Test+ public void testCopyInputStreamOutputStream() throws IOException {+ InputStream source = new ByteArrayInputStream("A test string".getBytes(StandardCharsets.UTF_8));+ ByteArrayOutputStream dest = new ByteArrayOutputStream();+ try {+ FileUtils.copy(source, dest);+ } finally {+ source.close();+ dest.close();+ }+ String resultStr = new String(dest.toByteArray(), StandardCharsets.UTF_8);+ Assert.assertEquals("A test string", resultStr);+ }++ /**+ * Copy stream : empty input+ * @throws IOException when a read/write error occurred+ */+ @Test+ public void testCopyEmptyInputStreamOutputStream() throws IOException {+ InputStream source = new ByteArrayInputStream(new byte[0]);+ ByteArrayOutputStream dest = new ByteArrayOutputStream();+ try {+ FileUtils.copy(source, dest);+ } finally {+ source.close();+ dest.close();+ }+ String resultStr = new String(dest.toByteArray(), StandardCharsets.UTF_8);+ Assert.assertEquals("", resultStr);+ }++ /**+ * Copy stream : output stream with existing content+ * @throws IOException when a read/write error occurred+ */+ @Test+ public void testCopyInputStreamOutputStreamNotEmpty() throws IOException {+ InputStream source = new ByteArrayInputStream("An input String".getBytes(StandardCharsets.UTF_8));+ ByteArrayOutputStream dest = new ByteArrayOutputStream();+ try {+ dest.write("Non empty out stream.".getBytes(StandardCharsets.UTF_8));+ FileUtils.copy(source, dest);+ } finally {+ source.close();+ dest.close();+ }+ String resultStr = new String(dest.toByteArray(), StandardCharsets.UTF_8);+ Assert.assertEquals("Non empty out stream.An input String", resultStr);+ }++ /**+ * Partial Stream Copy+ * @throws IOException when a read/write error occurred+ */+ @Test+ public void testPartialCopyInputStreamOutputStream() throws IOException {+ /* Fill an input stream with more bytes than FileUtils.DEFAULT_BUFFER_SIZE */+ byte[] sourceBytes = new byte[2000];+ for(int i = 0; i < sourceBytes.length; i++) {+ sourceBytes[i] = (byte)(i % Byte.MAX_VALUE);+ }+ InputStream source = new ByteArrayInputStream(sourceBytes);+ ByteArrayOutputStream dest = new ByteArrayOutputStream();+ final int COUNT = 8;+ try {+ FileUtils.copy(source, dest, COUNT);+ } finally {+ source.close();+ dest.close();+ }+ Assert.assertEquals(COUNT, dest.size());+ }++}