[SONAR-1853] Create a new CodeReaderFilter mechanism to prevent logic duplications between Channel(s)

http://jira.codehaus.org/browse/SONAR-1853

Javadoc added

1 files changed, 35 insertions, 1 deletions

diff --git a/sonar-channel/src/main/java/org/sonar/channel/CodeReaderFilter.java b/sonar-channel/src/main/java/org/sonar/channel/CodeReaderFilter.java
index e65136106b6..4c63bcd9f90 100644
--- a/sonar-channel/src/main/java/org/sonar/channel/CodeReaderFilter.java
+++ b/sonar-channel/src/main/java/org/sonar/channel/CodeReaderFilter.java
@@ -3,8 +3,42 @@ package org.sonar.channel;
 import java.io.IOException;
 import java.io.Reader;
 
+/**
+ * This class can be extended to provide filtering capabilities for the CodeReader class. <br>
+ * The purpose is to filter the character flow before the CodeReader class passes it to the different channels. It is possible to give
+ * several filters to a CodeReader: they will be called one after another, following the declaration order in the CodeReader constructor, to
+ * sequentially filter the character flow.
+ * 
+ * @see CodeReader
+ * @see CodeBufferTest#testCodeReaderFilter()
+ * @see CodeBufferTest#testSeveralCodeReaderFilter()
+ * 
+ */
 public abstract class CodeReaderFilter {
 
-  public abstract int read(Reader in, char[] cbuf, int off, int len) throws IOException;
+  /**
+   * This method implements the filtering logic, that is:
+   * <ul>
+   * <li>
+   * get the characters from the reader,</li>
+   * <li>
+   * filter the character flow (and grab more characters from the reader if the filtering removes some),</li>
+   * <li>
+   * and fill the given buffer to its full capacity with the filtered data.</li>
+   * </ul>
+   * 
+   * @param reader
+   *          the input character flow
+   * @param filteredBuffer
+   *          the output buffer that must contain the filtered data
+   * @param offset
+   *          the offset to start reading from the reader
+   * @param lenght
+   *          the number of characters to read from the reader
+   * @return The number of characters read, or -1 if the end of the stream has been reached
+   * @throws IOException
+   *           If an I/O error occurs
+   */
+  public abstract int read(Reader reader, char[] filteredBuffer, int offset, int lenght) throws IOException;
 
 }