fix checkstyle violations by adding javadoc
Project: http://git-wip-us.apache.org/repos/asf/commons-io/repo Commit: http://git-wip-us.apache.org/repos/asf/commons-io/commit/d357d9d5 Tree: http://git-wip-us.apache.org/repos/asf/commons-io/tree/d357d9d5 Diff: http://git-wip-us.apache.org/repos/asf/commons-io/diff/d357d9d5 Branch: refs/heads/master Commit: d357d9d563c4a34fa2ab3cdc68221c851a9de4f5 Parents: cdc90d7 Author: pascalschumacher <pascalschumac...@gmx.net> Authored: Sun Apr 23 18:33:45 2017 +0200 Committer: pascalschumacher <pascalschumac...@gmx.net> Committed: Sun Apr 23 18:33:45 2017 +0200 ---------------------------------------------------------------------- .../MessageDigestCalculatingInputStream.java | 15 +++++++++ .../commons/io/input/ObservableInputStream.java | 32 ++++++++++++++++++-- .../commons/io/output/WriterOutputStream.java | 5 +++ 3 files changed, 50 insertions(+), 2 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/commons-io/blob/d357d9d5/src/main/java/org/apache/commons/io/input/MessageDigestCalculatingInputStream.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/io/input/MessageDigestCalculatingInputStream.java b/src/main/java/org/apache/commons/io/input/MessageDigestCalculatingInputStream.java index c360560..21d2d5c 100644 --- a/src/main/java/org/apache/commons/io/input/MessageDigestCalculatingInputStream.java +++ b/src/main/java/org/apache/commons/io/input/MessageDigestCalculatingInputStream.java @@ -31,9 +31,16 @@ import java.security.NoSuchAlgorithmException; */ public class MessageDigestCalculatingInputStream extends ObservableInputStream { + /** + * Maintains the message digest. + */ public static class MessageDigestMaintainingObserver extends Observer { private final MessageDigest md; + /** + * Creates an MessageDigestMaintainingObserver for the given MessageDigest. + * @param pMd the message digest to use + */ public MessageDigestMaintainingObserver(MessageDigest pMd) { md = pMd; } @@ -53,6 +60,8 @@ public class MessageDigestCalculatingInputStream extends ObservableInputStream { /** Creates a new instance, which calculates a signature on the given stream, * using the given {@link MessageDigest}. + * @param pStream the stream to calculate the message digest for + * @param pDigest the message digest to use */ public MessageDigestCalculatingInputStream(InputStream pStream, MessageDigest pDigest) { super(pStream); @@ -62,6 +71,9 @@ public class MessageDigestCalculatingInputStream extends ObservableInputStream { /** Creates a new instance, which calculates a signature on the given stream, * using a {@link MessageDigest} with the given algorithm. + * @param pStream the stream to calculate the message digest for + * @param pAlgorithm the name of the algorithm to use + * @throws NoSuchAlgorithmException if no Provider supports a MessageDigestSpi implementation for the specified algorithm. */ public MessageDigestCalculatingInputStream(InputStream pStream, String pAlgorithm) throws NoSuchAlgorithmException { this(pStream, MessageDigest.getInstance(pAlgorithm)); @@ -69,6 +81,8 @@ public class MessageDigestCalculatingInputStream extends ObservableInputStream { /** Creates a new instance, which calculates a signature on the given stream, * using a {@link MessageDigest} with the "MD5" algorithm. + * @param pStream the stream to calculate the message digest for + * @throws NoSuchAlgorithmException if no Provider supports a MessageDigestSpi implementation for the specified algorithm. */ public MessageDigestCalculatingInputStream(InputStream pStream) throws NoSuchAlgorithmException { this(pStream, MessageDigest.getInstance("MD5")); @@ -80,6 +94,7 @@ public class MessageDigestCalculatingInputStream extends ObservableInputStream { * This is probably not, what you expect. Make sure, that the complete data has been * read, if that is what you want. The easiest way to do so is by invoking * {@link #consume()}. + * @return the message digest used */ public MessageDigest getMessageDigest() { return messageDigest; http://git-wip-us.apache.org/repos/asf/commons-io/blob/d357d9d5/src/main/java/org/apache/commons/io/input/ObservableInputStream.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/io/input/ObservableInputStream.java b/src/main/java/org/apache/commons/io/input/ObservableInputStream.java index a8dd078..bae3b46 100644 --- a/src/main/java/org/apache/commons/io/input/ObservableInputStream.java +++ b/src/main/java/org/apache/commons/io/input/ObservableInputStream.java @@ -18,7 +18,6 @@ package org.apache.commons.io.input; import java.io.IOException; import java.io.InputStream; -import java.security.MessageDigest; import java.util.ArrayList; import java.util.List; @@ -36,13 +35,17 @@ import java.util.List; * @see MessageDigestCalculatingInputStream */ public class ObservableInputStream extends ProxyInputStream { + public static abstract class Observer { + /** Called to indicate, that {@link InputStream#read()} has been invoked * on the {@link ObservableInputStream}, and will return a value. * @param pByte The value, which is being returned. This will never be -1 (EOF), * because, in that case, {@link #finished()} will be invoked instead. + * @throws IOException if an i/o-error occurs */ void data(int pByte) throws IOException {} + /** Called to indicate, that {@link InputStream#read(byte[])}, or * {@link InputStream#read(byte[], int, int)} have been called, and are about to * invoke data. @@ -50,37 +53,59 @@ public class ObservableInputStream extends ProxyInputStream { * data has been stored. * @param pOffset The offset within the byte array, where data has been stored. * @param pLength The number of bytes, which have been stored in the byte array. + * @throws IOException if an i/o-error occurs */ void data(byte[] pBuffer, int pOffset, int pLength) throws IOException {} + /** Called to indicate, that EOF has been seen on the underlying stream. * This method may be called multiple times, if the reader keeps invoking * either of the read methods, and they will consequently keep returning * EOF. + * @throws IOException if an i/o-error occurs */ void finished() throws IOException {} + /** Called to indicate, that the {@link ObservableInputStream} has been closed. + * @throws IOException if an i/o-error occurs */ void closed() throws IOException {} + /** * Called to indicate, that an error occurred on the underlying stream. + * @throws IOException if an i/o-error occurs */ void error(IOException pException) throws IOException { throw pException; } } private final List<Observer> observers = new ArrayList<>(); - + + /** + * Creates a new ObservableInputStream for the given InputStream. + * @param pProxy the input stream to proxy + */ public ObservableInputStream(InputStream pProxy) { super(pProxy); } + /** + * Adds an Observer. + * @param pObserver the observer to add + */ public void add(Observer pObserver) { observers.add(pObserver); } + /** + * Removes an Observer. + * @param pObserver the observer to remove + */ public void remove(Observer pObserver) { observers.remove(pObserver); } + /** + * Removes all Observers. + */ public void removeAllObservers() { observers.clear(); } @@ -201,6 +226,9 @@ public class ObservableInputStream extends ProxyInputStream { } } + /** Gets all currently registered observers. + * @return a list of the currently registered observers + */ protected List<Observer> getObservers() { return observers; } http://git-wip-us.apache.org/repos/asf/commons-io/blob/d357d9d5/src/main/java/org/apache/commons/io/output/WriterOutputStream.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/io/output/WriterOutputStream.java b/src/main/java/org/apache/commons/io/output/WriterOutputStream.java index 0043d87..5838283 100644 --- a/src/main/java/org/apache/commons/io/output/WriterOutputStream.java +++ b/src/main/java/org/apache/commons/io/output/WriterOutputStream.java @@ -310,6 +310,11 @@ public class WriterOutputStream extends OutputStream { } } + /** + * Check if the JDK in use properly supports the given charset. + * + * @param charset the charset to check the support for + */ private static void checkIbmJdkWithBrokenUTF16(Charset charset){ if (!"UTF-16".equals(charset.name())) { return;