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 }