Renderer xref
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 }