001    /*
002     * Sonar, open source software quality management tool.
003     * Copyright (C) 2008-2012 SonarSource
004     * mailto:contact AT sonarsource DOT com
005     *
006     * Sonar is free software; you can redistribute it and/or
007     * modify it under the terms of the GNU Lesser General Public
008     * License as published by the Free Software Foundation; either
009     * version 3 of the License, or (at your option) any later version.
010     *
011     * Sonar is distributed in the hope that it will be useful,
012     * but WITHOUT ANY WARRANTY; without even the implied warranty of
013     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014     * Lesser General Public License for more details.
015     *
016     * You should have received a copy of the GNU Lesser General Public
017     * License along with Sonar; if not, write to the Free Software
018     * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02
019     */
020    package org.sonar.channel;
021    
022    import java.io.IOException;
023    import java.io.Reader;
024    
025    /**
026     * This class can be extended to provide filtering capabilities for the CodeReader class. <br>
027     * The purpose is to filter the character flow before the CodeReader class passes it to the different channels. It is possible to give
028     * several filters to a CodeReader: they will be called one after another, following the declaration order in the CodeReader constructor, to
029     * sequentially filter the character flow.
030     * 
031     * @see CodeReader
032     * @see CodeBufferTest#testCodeReaderFilter()
033     * @see CodeBufferTest#testSeveralCodeReaderFilter()
034     * 
035     */
036    public abstract class CodeReaderFilter<OUTPUT> {
037    
038      private Reader reader;
039    
040      private OUTPUT output;
041    
042      private CodeReaderConfiguration configuration;
043    
044      public CodeReaderFilter() {
045      }
046    
047      public CodeReaderFilter(OUTPUT output) {
048        this.output = output;
049      }
050    
051      /**
052       * Returns the reader from which this class reads the character stream.
053       * 
054       * @return the reader
055       */
056      public Reader getReader() {
057        return reader;
058      }
059    
060      /**
061       * Sets the reader from which this class will read the character stream.
062       * 
063       * @param reader
064       *          the reader
065       */
066      public void setReader(Reader reader) {
067        this.reader = reader;
068      }
069    
070      /**
071       * Returns the output object.
072       * 
073       * @return the output
074       */
075      public OUTPUT getOutput() {
076        return output;
077      }
078    
079      /**
080       * Sets the output object
081       * 
082       * @param output
083       *          the output to set
084       */
085      public void setOutput(OUTPUT output) {
086        this.output = output;
087      }
088    
089      /**
090       * Returns the configuration used for the CodeReader
091       * 
092       * @return the configuration
093       */
094      public CodeReaderConfiguration getConfiguration() {
095        return configuration;
096      }
097    
098      /**
099       * Sets the configuration that must be used by the CodeReader
100       * 
101       * @param configuration
102       *          the configuration to set
103       */
104      public void setConfiguration(CodeReaderConfiguration configuration) {
105        this.configuration = configuration;
106      }
107    
108      /**
109       * This method implements the filtering logic, that is:
110       * <ul>
111       * <li>
112       * get the characters from the reader,</li>
113       * <li>
114       * filter the character flow (and grab more characters from the reader if the filtering removes some),</li>
115       * <li>
116       * and fill the given buffer to its full capacity with the filtered data.</li>
117       * </ul>
118       * 
119       * @param filteredBuffer
120       *          the output buffer that must contain the filtered data
121       * @param offset
122       *          the offset to start reading from the reader
123       * @param length
124       *          the number of characters to read from the reader
125       * @return The number of characters read, or -1 if the end of the stream has been reached
126       * @throws IOException
127       *           If an I/O error occurs
128       */
129      public abstract int read(char[] filteredBuffer, int offset, int length) throws IOException;
130    
131    }