View Javadoc

    1   /**
    2    * BSD-style license; for more info see http://pmd.sourceforge.net/license.html
    3    */
    4   package net.sourceforge.pmd.renderers;
    5
    6   import java.io.IOException;
    7   import java.io.Writer;
    8   import java.util.Map;
    9
    10  import net.sourceforge.pmd.PropertySource;
    11  import net.sourceforge.pmd.Report;
    12  import net.sourceforge.pmd.util.datasource.DataSource;
    13
    14  /**
    15   * This is an interface for rendering a Report.  When a Renderer is being
    16   * invoked, the sequence of method calls is something like the following:
    17   * <ol>
    18   * 	<li>Renderer construction/initialization</li>
    19   * 	<li>{@link Renderer#setShowSuppressedViolations(boolean)}</li>
    20   * 	<li>{@link Renderer#setWriter(Writer)}</li>
    21   * 	<li>{@link Renderer#start()}</li>
    22   * 	<li>{@link Renderer#startFileAnalysis(DataSource)} for each source file processed</li>
    23   * 	<li>{@link Renderer#renderFileReport(Report)} for each Report instance</li>
    24   * 	<li>{@link Renderer#end()}</li>
    25   * </ol>
    26   * <p>
    27   * An implementation of the Renderer interface is expected to have a default constructor.
    28   * Properties should be defined using the {@link #definePropertyDescriptor(net.sourceforge.pmd.PropertyDescriptor)}
    29   * method. After the instance is created, the property values are set. This means, you won't
    30   * have access to property values in your constructor.
    31   */
    32  // TODO Are implementations expected to be thread-safe?
    33  public interface Renderer extends PropertySource {
    34
    35      /**
    36       * Get the name of the Renderer.
    37       * @return The name of the Renderer.
    38       */
    39      String getName();
    40
    41      /**
    42       * Set the name of the Renderer.
    43       * @param name The name of the Renderer.
    44       */
    45      void setName(String name);
    46
    47      /**
    48       * Get the description of the Renderer.
    49       * @return The description of the Renderer.
    50       */
    51      String getDescription();
    52
    53      /**
    54       * Return the default filename extension to use.
    55       *
    56       * @return String
    57       */
    58      String defaultFileExtension();
    59
    60      /**
    61       * Set the description of the Renderer.
    62       * @param description The description of the Renderer.
    63       */
    64      void setDescription(String description);
    65
    66      /**
    67       * Get the configuration property definitions for Renderer.
    68       * The keys in the map are the configuration property names, with the
    69       * corresponding value being a description.
    70       * @return The configuration property definition map.
    71       */
    72      @Deprecated // use PropertySource.getPropertyDescriptors() instead
    73      Map<String, String> getPropertyDefinitions();
    74
    75      /**
    76       * Get the indicator for whether to show suppressed violations.
    77       * @return <code>true</code> if suppressed violations should show, <code>false</code> otherwise.
    78       */
    79      boolean isShowSuppressedViolations();
    80
    81      /**
    82       * Set the indicator for whether to show suppressed violations.
    83       * @param showSuppressedViolations Whether to show suppressed violations.
    84       */
    85      void setShowSuppressedViolations(boolean showSuppressedViolations);
    86
    87      /**
    88       * Get the Writer for the Renderer.
    89       * @return The Writer.
    90       */
    91      Writer getWriter();
    92
    93      /**
    94       * Set the Writer for the Renderer.
    95       * @param writer The Writer.
    96       */
    97      void setWriter(Writer writer);
    98
    99      /**
    100      * This method is called before any source files are processed.
    101      * The Renderer will have been fully initialized by the time this method
    102      * is called, so the Writer and other state will be available.
    103      * @throws IOException
    104      */
    105     void start() throws IOException;
    106
    107     /**
    108      * This method is called each time a source file is processed.  It is called
    109      * after {@link Renderer#start()}, but before
    110      * {@link Renderer#renderFileReport(Report)} and {@link Renderer#end()}.
    111      *
    112      * This method may be invoked by different threads which are processing
    113      * files independently.  Therefore, any non-trivial implementation of this
    114      * method needs to be thread-safe.
    115      *
    116      * @param dataSource The source file.
    117      */
    118     void startFileAnalysis(DataSource dataSource);
    119
    120     /**
    121      * Render the given file Report.  There may be multiple Report instances
    122      * which need to be rendered if produced by different threads.
    123      * It is called after {@link Renderer#start()} and
    124      * {@link Renderer#startFileAnalysis(DataSource)}, but before {@link Renderer#end()}.
    125      *
    126      * @param report A file Report.
    127      * @throws IOException
    128      *
    129      * @see Report
    130      */
    131     void renderFileReport(Report report) throws IOException;
    132
    133     /**
    134      * This method is at the very end of the Rendering process, after
    135      * {@link Renderer#renderFileReport(Report)}.
    136      * @throws IOException
    137      */
    138     void end() throws IOException;
    139
    140     void flush() throws IOException;
    141 }