Skip to content

Distributed Peer-to-Peer Web Search Engine and Intranet Search Appliance

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.java
index 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.java
new file mode 100644
index 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());
+ }
+
+}