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 }