View Javadoc

1   package org.apache.maven.plugins.surefire.report;
2   
3   import java.util.ArrayList;
4   import java.util.Iterator;
5   import java.util.List;
6   
7   import org.apache.maven.plugin.AbstractMojo;
8   import org.apache.maven.plugin.MojoExecutionException;
9   
10  /**
11   * Display help information on maven-surefire-report-plugin.<br/> Call <pre>  mvn surefire-report:help -Ddetail=true -Dgoal=&lt;goal-name&gt;</pre> to display parameter details.
12   *
13   * @version generated on Wed Nov 30 15:03:23 CET 2011
14   * @author org.apache.maven.tools.plugin.generator.PluginHelpGenerator (version 2.8)
15   * @goal help
16   * @requiresProject false
17   * @threadSafe
18   */
19  public class HelpMojo
20      extends AbstractMojo
21  {
22      /**
23       * If <code>true</code>, display all settable properties for each goal.
24       * 
25       * @parameter expression="${detail}" default-value="false"
26       */
27      private boolean detail;
28  
29      /**
30       * The name of the goal for which to show help. If unspecified, all goals will be displayed.
31       * 
32       * @parameter expression="${goal}"
33       */
34      private java.lang.String goal;
35  
36      /**
37       * The maximum length of a display line, should be positive.
38       * 
39       * @parameter expression="${lineLength}" default-value="80"
40       */
41      private int lineLength;
42  
43      /**
44       * The number of spaces per indentation level, should be positive.
45       * 
46       * @parameter expression="${indentSize}" default-value="2"
47       */
48      private int indentSize;
49  
50  
51      /** {@inheritDoc} */
52      public void execute()
53          throws MojoExecutionException
54      {
55          if ( lineLength <= 0 )
56          {
57              getLog().warn( "The parameter 'lineLength' should be positive, using '80' as default." );
58              lineLength = 80;
59          }
60          if ( indentSize <= 0 )
61          {
62              getLog().warn( "The parameter 'indentSize' should be positive, using '2' as default." );
63              indentSize = 2;
64          }
65  
66          StringBuffer sb = new StringBuffer();
67  
68          append( sb, "org.apache.maven.plugins:maven-surefire-report-plugin:2.11", 0 );
69          append( sb, "", 0 );
70  
71          append( sb, "Maven Surefire Report Plugin", 0 );
72          append( sb, "Surefire is a test framework project.", 1 );
73          append( sb, "", 0 );
74  
75          if ( goal == null || goal.length() <= 0 )
76          {
77              append( sb, "This plugin has 4 goals:", 0 );
78              append( sb, "", 0 );
79          }
80  
81          if ( goal == null || goal.length() <= 0 || "failsafe-report-only".equals( goal ) )
82          {
83              append( sb, "surefire-report:failsafe-report-only", 0 );
84              append( sb, "Creates a nicely formatted Failsafe Test Report in html format. This goal does not run the tests, it only builds the reports. See http://jira.codehaus.org/browse/SUREFIRE-257", 1 );
85              append( sb, "", 0 );
86              if ( detail )
87              {
88                  append( sb, "Available parameters:", 1 );
89                  append( sb, "", 0 );
90  
91                  append( sb, "aggregate (Default: false)", 2 );
92                  append( sb, "Whether to build an aggregated report at the root, or build individual reports.", 3 );
93                  append( sb, "Expression: ${aggregate}", 3 );
94                  append( sb, "", 0 );
95  
96                  append( sb, "alwaysGenerateFailsafeReport (Default: false)", 2 );
97                  append( sb, "If set to true the failsafe report will be generated even when there are no failsafe result files. Defaults to false to preserve legacy behaviour pre 2.10", 3 );
98                  append( sb, "Expression: ${alwaysGenerateFailsafeReport}", 3 );
99                  append( sb, "", 0 );
100 
101                 append( sb, "linkXRef (Default: true)", 2 );
102                 append( sb, "Whether to link the XRef if found.", 3 );
103                 append( sb, "Expression: ${linkXRef}", 3 );
104                 append( sb, "", 0 );
105 
106                 append( sb, "outputDirectory", 2 );
107                 append( sb, "Location where generated html will be created.", 3 );
108                 append( sb, "Expression: ${project.reporting.outputDirectory}", 3 );
109                 append( sb, "", 0 );
110 
111                 append( sb, "outputName (Default: failsafe-report)", 2 );
112                 append( sb, "The filename to use for the report.", 3 );
113                 append( sb, "Required: Yes", 3 );
114                 append( sb, "Expression: ${outputName}", 3 );
115                 append( sb, "", 0 );
116 
117                 append( sb, "project", 2 );
118                 append( sb, "Maven Project", 3 );
119                 append( sb, "Required: Yes", 3 );
120                 append( sb, "Expression: ${project}", 3 );
121                 append( sb, "", 0 );
122 
123                 append( sb, "reportsDirectories", 2 );
124                 append( sb, "Directories containing the XML Report files that will be parsed and rendered to HTML format.", 3 );
125                 append( sb, "", 0 );
126 
127                 append( sb, "reportsDirectory", 2 );
128                 append( sb, "(Deprecated, use reportsDirectories) This directory contains the XML Report files that will be parsed and rendered to HTML format.", 3 );
129                 append( sb, "", 0 );
130 
131                 append( sb, "showSuccess (Default: true)", 2 );
132                 append( sb, "If set to false, only failures are shown.", 3 );
133                 append( sb, "Required: Yes", 3 );
134                 append( sb, "Expression: ${showSuccess}", 3 );
135                 append( sb, "", 0 );
136 
137                 append( sb, "skipFailsafeReport (Default: false)", 2 );
138                 append( sb, "If set to true the failsafe report generation will be skipped.", 3 );
139                 append( sb, "Expression: ${skipFailsafeReport}", 3 );
140                 append( sb, "", 0 );
141 
142                 append( sb, "xrefLocation (Default: ${project.reporting.outputDirectory}/xref-test)", 2 );
143                 append( sb, "Location of the Xrefs to link.", 3 );
144                 append( sb, "", 0 );
145             }
146         }
147 
148         if ( goal == null || goal.length() <= 0 || "help".equals( goal ) )
149         {
150             append( sb, "surefire-report:help", 0 );
151             append( sb, "Display help information on maven-surefire-report-plugin.\nCall\n\u00a0\u00a0mvn\u00a0surefire-report:help\u00a0-Ddetail=true\u00a0-Dgoal=<goal-name>\nto display parameter details.", 1 );
152             append( sb, "", 0 );
153             if ( detail )
154             {
155                 append( sb, "Available parameters:", 1 );
156                 append( sb, "", 0 );
157 
158                 append( sb, "detail (Default: false)", 2 );
159                 append( sb, "If true, display all settable properties for each goal.", 3 );
160                 append( sb, "Expression: ${detail}", 3 );
161                 append( sb, "", 0 );
162 
163                 append( sb, "goal", 2 );
164                 append( sb, "The name of the goal for which to show help. If unspecified, all goals will be displayed.", 3 );
165                 append( sb, "Expression: ${goal}", 3 );
166                 append( sb, "", 0 );
167 
168                 append( sb, "indentSize (Default: 2)", 2 );
169                 append( sb, "The number of spaces per indentation level, should be positive.", 3 );
170                 append( sb, "Expression: ${indentSize}", 3 );
171                 append( sb, "", 0 );
172 
173                 append( sb, "lineLength (Default: 80)", 2 );
174                 append( sb, "The maximum length of a display line, should be positive.", 3 );
175                 append( sb, "Expression: ${lineLength}", 3 );
176                 append( sb, "", 0 );
177             }
178         }
179 
180         if ( goal == null || goal.length() <= 0 || "report".equals( goal ) )
181         {
182             append( sb, "surefire-report:report", 0 );
183             append( sb, "Creates a nicely formatted Surefire Test Report in html format.", 1 );
184             append( sb, "", 0 );
185             if ( detail )
186             {
187                 append( sb, "Available parameters:", 1 );
188                 append( sb, "", 0 );
189 
190                 append( sb, "aggregate (Default: false)", 2 );
191                 append( sb, "Whether to build an aggregated report at the root, or build individual reports.", 3 );
192                 append( sb, "Expression: ${aggregate}", 3 );
193                 append( sb, "", 0 );
194 
195                 append( sb, "alwaysGenerateSurefireReport (Default: true)", 2 );
196                 append( sb, "If set to true the surefire report will be generated even when there are no surefire result files. Defaulyts to true to preserve legacy behaviour pre 2.10.", 3 );
197                 append( sb, "Expression: ${alwaysGenerateSurefireReport}", 3 );
198                 append( sb, "", 0 );
199 
200                 append( sb, "linkXRef (Default: true)", 2 );
201                 append( sb, "Whether to link the XRef if found.", 3 );
202                 append( sb, "Expression: ${linkXRef}", 3 );
203                 append( sb, "", 0 );
204 
205                 append( sb, "outputDirectory", 2 );
206                 append( sb, "Location where generated html will be created.", 3 );
207                 append( sb, "Expression: ${project.reporting.outputDirectory}", 3 );
208                 append( sb, "", 0 );
209 
210                 append( sb, "outputName (Default: surefire-report)", 2 );
211                 append( sb, "The filename to use for the report.", 3 );
212                 append( sb, "Required: Yes", 3 );
213                 append( sb, "Expression: ${outputName}", 3 );
214                 append( sb, "", 0 );
215 
216                 append( sb, "project", 2 );
217                 append( sb, "Maven Project", 3 );
218                 append( sb, "Required: Yes", 3 );
219                 append( sb, "Expression: ${project}", 3 );
220                 append( sb, "", 0 );
221 
222                 append( sb, "reportsDirectories", 2 );
223                 append( sb, "Directories containing the XML Report files that will be parsed and rendered to HTML format.", 3 );
224                 append( sb, "", 0 );
225 
226                 append( sb, "reportsDirectory", 2 );
227                 append( sb, "(Deprecated, use reportsDirectories) This directory contains the XML Report files that will be parsed and rendered to HTML format.", 3 );
228                 append( sb, "", 0 );
229 
230                 append( sb, "showSuccess (Default: true)", 2 );
231                 append( sb, "If set to false, only failures are shown.", 3 );
232                 append( sb, "Required: Yes", 3 );
233                 append( sb, "Expression: ${showSuccess}", 3 );
234                 append( sb, "", 0 );
235 
236                 append( sb, "skipSurefireReport (Default: false)", 2 );
237                 append( sb, "If set to true the surefire report generation will be skipped.", 3 );
238                 append( sb, "Expression: ${skipSurefireReport}", 3 );
239                 append( sb, "", 0 );
240 
241                 append( sb, "xrefLocation (Default: ${project.reporting.outputDirectory}/xref-test)", 2 );
242                 append( sb, "Location of the Xrefs to link.", 3 );
243                 append( sb, "", 0 );
244             }
245         }
246 
247         if ( goal == null || goal.length() <= 0 || "report-only".equals( goal ) )
248         {
249             append( sb, "surefire-report:report-only", 0 );
250             append( sb, "Creates a nicely formatted Surefire Test Report in html format. This goal does not run the tests, it only builds the reports. This is a workaround for http://jira.codehaus.org/browse/SUREFIRE-257", 1 );
251             append( sb, "", 0 );
252             if ( detail )
253             {
254                 append( sb, "Available parameters:", 1 );
255                 append( sb, "", 0 );
256 
257                 append( sb, "aggregate (Default: false)", 2 );
258                 append( sb, "Whether to build an aggregated report at the root, or build individual reports.", 3 );
259                 append( sb, "Expression: ${aggregate}", 3 );
260                 append( sb, "", 0 );
261 
262                 append( sb, "alwaysGenerateSurefireReport (Default: true)", 2 );
263                 append( sb, "If set to true the surefire report will be generated even when there are no surefire result files. Defaulyts to true to preserve legacy behaviour pre 2.10.", 3 );
264                 append( sb, "Expression: ${alwaysGenerateSurefireReport}", 3 );
265                 append( sb, "", 0 );
266 
267                 append( sb, "linkXRef (Default: true)", 2 );
268                 append( sb, "Whether to link the XRef if found.", 3 );
269                 append( sb, "Expression: ${linkXRef}", 3 );
270                 append( sb, "", 0 );
271 
272                 append( sb, "outputDirectory", 2 );
273                 append( sb, "Location where generated html will be created.", 3 );
274                 append( sb, "Expression: ${project.reporting.outputDirectory}", 3 );
275                 append( sb, "", 0 );
276 
277                 append( sb, "outputName (Default: surefire-report)", 2 );
278                 append( sb, "The filename to use for the report.", 3 );
279                 append( sb, "Required: Yes", 3 );
280                 append( sb, "Expression: ${outputName}", 3 );
281                 append( sb, "", 0 );
282 
283                 append( sb, "project", 2 );
284                 append( sb, "Maven Project", 3 );
285                 append( sb, "Required: Yes", 3 );
286                 append( sb, "Expression: ${project}", 3 );
287                 append( sb, "", 0 );
288 
289                 append( sb, "reportsDirectories", 2 );
290                 append( sb, "Directories containing the XML Report files that will be parsed and rendered to HTML format.", 3 );
291                 append( sb, "", 0 );
292 
293                 append( sb, "reportsDirectory", 2 );
294                 append( sb, "(Deprecated, use reportsDirectories) This directory contains the XML Report files that will be parsed and rendered to HTML format.", 3 );
295                 append( sb, "", 0 );
296 
297                 append( sb, "showSuccess (Default: true)", 2 );
298                 append( sb, "If set to false, only failures are shown.", 3 );
299                 append( sb, "Required: Yes", 3 );
300                 append( sb, "Expression: ${showSuccess}", 3 );
301                 append( sb, "", 0 );
302 
303                 append( sb, "skipSurefireReport (Default: false)", 2 );
304                 append( sb, "If set to true the surefire report generation will be skipped.", 3 );
305                 append( sb, "Expression: ${skipSurefireReport}", 3 );
306                 append( sb, "", 0 );
307 
308                 append( sb, "xrefLocation (Default: ${project.reporting.outputDirectory}/xref-test)", 2 );
309                 append( sb, "Location of the Xrefs to link.", 3 );
310                 append( sb, "", 0 );
311             }
312         }
313 
314         if ( getLog().isInfoEnabled() )
315         {
316             getLog().info( sb.toString() );
317         }
318     }
319 
320     /**
321      * <p>Repeat a String <code>n</code> times to form a new string.</p>
322      *
323      * @param str String to repeat
324      * @param repeat number of times to repeat str
325      * @return String with repeated String
326      * @throws NegativeArraySizeException if <code>repeat < 0</code>
327      * @throws NullPointerException if str is <code>null</code>
328      */
329     private static String repeat( String str, int repeat )
330     {
331         StringBuffer buffer = new StringBuffer( repeat * str.length() );
332 
333         for ( int i = 0; i < repeat; i++ )
334         {
335             buffer.append( str );
336         }
337 
338         return buffer.toString();
339     }
340 
341     /** 
342      * Append a description to the buffer by respecting the indentSize and lineLength parameters.
343      * <b>Note</b>: The last character is always a new line.
344      * 
345      * @param sb The buffer to append the description, not <code>null</code>.
346      * @param description The description, not <code>null</code>.
347      * @param indent The base indentation level of each line, must not be negative.
348      */
349     private void append( StringBuffer sb, String description, int indent )
350     {
351         for ( Iterator it = toLines( description, indent, indentSize, lineLength ).iterator(); it.hasNext(); )
352         {
353             sb.append( it.next().toString() ).append( '\n' );
354         }
355     }
356 
357     /** 
358      * Splits the specified text into lines of convenient display length.
359      * 
360      * @param text The text to split into lines, must not be <code>null</code>.
361      * @param indent The base indentation level of each line, must not be negative.
362      * @param indentSize The size of each indentation, must not be negative.
363      * @param lineLength The length of the line, must not be negative.
364      * @return The sequence of display lines, never <code>null</code>.
365      * @throws NegativeArraySizeException if <code>indent < 0</code>
366      */
367     private static List toLines( String text, int indent, int indentSize, int lineLength )
368     {
369         List lines = new ArrayList();
370 
371         String ind = repeat( "\t", indent );
372         String[] plainLines = text.split( "(\r\n)|(\r)|(\n)" );
373         for ( int i = 0; i < plainLines.length; i++ )
374         {
375             toLines( lines, ind + plainLines[i], indentSize, lineLength );
376         }
377 
378         return lines;
379     }
380 
381     /** 
382      * Adds the specified line to the output sequence, performing line wrapping if necessary.
383      * 
384      * @param lines The sequence of display lines, must not be <code>null</code>.
385      * @param line The line to add, must not be <code>null</code>.
386      * @param indentSize The size of each indentation, must not be negative.
387      * @param lineLength The length of the line, must not be negative.
388      */
389     private static void toLines( List lines, String line, int indentSize, int lineLength )
390     {
391         int lineIndent = getIndentLevel( line );
392         StringBuffer buf = new StringBuffer( 256 );
393         String[] tokens = line.split( " +" );
394         for ( int i = 0; i < tokens.length; i++ )
395         {
396             String token = tokens[i];
397             if ( i > 0 )
398             {
399                 if ( buf.length() + token.length() >= lineLength )
400                 {
401                     lines.add( buf.toString() );
402                     buf.setLength( 0 );
403                     buf.append( repeat( " ", lineIndent * indentSize ) );
404                 }
405                 else
406                 {
407                     buf.append( ' ' );
408                 }
409             }
410             for ( int j = 0; j < token.length(); j++ )
411             {
412                 char c = token.charAt( j );
413                 if ( c == '\t' )
414                 {
415                     buf.append( repeat( " ", indentSize - buf.length() % indentSize ) );
416                 }
417                 else if ( c == '\u00A0' )
418                 {
419                     buf.append( ' ' );
420                 }
421                 else
422                 {
423                     buf.append( c );
424                 }
425             }
426         }
427         lines.add( buf.toString() );
428     }
429 
430     /** 
431      * Gets the indentation level of the specified line.
432      * 
433      * @param line The line whose indentation level should be retrieved, must not be <code>null</code>.
434      * @return The indentation level of the line.
435      */
436     private static int getIndentLevel( String line )
437     {
438         int level = 0;
439         for ( int i = 0; i < line.length() && line.charAt( i ) == '\t'; i++ )
440         {
441             level++;
442         }
443         for ( int i = level + 1; i <= level + 4 && i < line.length(); i++ )
444         {
445             if ( line.charAt( i ) == '\t' )
446             {
447                 level++;
448                 break;
449             }
450         }
451         return level;
452     }
453 }