001 /**
002 * BSD-style license; for more info see http://pmd.sourceforge.net/license.html
003 */
004 package net.sourceforge.pmd.renderers;
005
006 import java.io.IOException;
007 import java.io.Writer;
008 import java.util.Map;
009
010 import net.sourceforge.pmd.Report;
011 import net.sourceforge.pmd.util.datasource.DataSource;
012
013 /**
014 * This is an interface for rendering a Report. When a Renderer is being
015 * invoked, the sequence of method calls is something like the following:
016 * <ol>
017 * <li>Renderer construction/initialization</li>
018 * <li>{@link Renderer#setShowSuppressedViolations(boolean)}</li>
019 * <li>{@link Renderer#setWriter(Writer)}</li>
020 * <li>{@link Renderer#start()}</li>
021 * <li>{@link Renderer#startFileAnalysis(DataSource)} for each source file processed</li>
022 * <li>{@link Renderer#renderFileReport(Report)} for each Report instance</li>
023 * <li>{@link Renderer#end()}</li>
024 * </ol>
025 * <p>
026 * An implementation of the Renderer interface is expected to have a constructor
027 * which takes a single {@link java.util.Properties} argument. This is to allow
028 * easy factory creation and initialization of the Renderer, as well as to
029 * provide flexibility with regards to initialization in subclasses of the
030 * Renderer.
031 */
032 // TODO Are implementations expected to be thread-safe?
033 public interface Renderer {
034
035 /**
036 * Get the name of the Renderer.
037 * @return The name of the Renderer.
038 */
039 String getName();
040
041 /**
042 * Set the name of the Renderer.
043 * @param name The name of the Renderer.
044 */
045 void setName(String name);
046
047 /**
048 * Get the description of the Renderer.
049 * @return The description of the Renderer.
050 */
051 String getDescription();
052
053 /**
054 * Set the description of the Renderer.
055 * @param description The description of the Renderer.
056 */
057 void setDescription(String description);
058
059 /**
060 * Get the configuration property definitions for Renderer.
061 * The keys in the map are the configuration property names, with the
062 * corresponding value being a description.
063 * @return The configuration property definition map.
064 */
065 Map<String, String> getPropertyDefinitions();
066
067 /**
068 * Get the indicator for whether to show suppressed violations.
069 * @return <code>true</code> if suppressed violations should show, <code>false</code> otherwise.
070 */
071 boolean isShowSuppressedViolations();
072
073 /**
074 * Set the indicator for whether to show suppressed violations.
075 * @param showSuppressedViolations Whether to show suppressed violations.
076 */
077 void setShowSuppressedViolations(boolean showSuppressedViolations);
078
079 /**
080 * Get the Writer for the Renderer.
081 * @return The Writer.
082 */
083 Writer getWriter();
084
085 /**
086 * Set the Writer for the Renderer.
087 * @param writer The Writer.
088 */
089 void setWriter(Writer writer);
090
091 /**
092 * This method is called before any source files are processed.
093 * The Renderer will have been fully initialized by the time this method
094 * is called, so the Writer and other state will be available.
095 * @throws IOException
096 */
097 void start() throws IOException;
098
099 /**
100 * This method is called each time a source file is processed. It is called
101 * after {@link Renderer#start()}, but before
102 * {@link Renderer#renderFileReport(Report)} and {@link Renderer#end()}.
103 *
104 * This method may be invoked by different threads which are processing
105 * files independently. Therefore, any non-trivial implementation of this
106 * method needs to be thread-safe.
107 *
108 * @param dataSource The source file.
109 */
110 void startFileAnalysis(DataSource dataSource);
111
112 /**
113 * Render the given file Report. There may be multiple Report instances
114 * which need to be rendered if produced by different threads.
115 * It is called after {@link Renderer#start()} and
116 * {@link Renderer#startFileAnalysis(DataSource)}, but before {@link Renderer#end()}.
117 *
118 * @param report A file Report.
119 * @throws IOException
120 *
121 * @see Report
122 */
123 void renderFileReport(Report report) throws IOException;
124
125 /**
126 * This method is at the very end of the Rendering process, after
127 * {@link Renderer#renderFileReport(Report)}.
128 * @throws IOException
129 */
130 void end() throws IOException;
131 }
|