svn commit: r619243 - /maven/site/trunk/src/site/apt/guides/plugin/guide-java-plugin-development.apt

[vs...@apache.org]

Author: vsiveton
Date: Wed Feb  6 18:52:45 2008
New Revision: 619243

URL: http://svn.apache.org/viewvc?rev=619243&view=rev
Log:
MNG-3273: Point out known pitfalls when developing plugins
Submitted by: Benjamin Bentmann
Reviewed by: Vincent Siveton

o applied

Modified:
    maven/site/trunk/src/site/apt/guides/plugin/guide-java-plugin-development.apt

Modified: maven/site/trunk/src/site/apt/guides/plugin/guide-java-plugin-development.apt
URL: http://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/guides/plugin/guide-java-plugin-development.apt?rev=619243&r1=619242&r2=619243&view=diff
==============================================================================
--- maven/site/trunk/src/site/apt/guides/plugin/guide-java-plugin-development.apt (original)
+++ maven/site/trunk/src/site/apt/guides/plugin/guide-java-plugin-development.apt Wed Feb  6 18:52:45 2008
@@ -715,6 +715,48 @@
   Therefore, always provide a dedicated bundle for the default locale of your bundle family (e.g. <<<mymojo-report_en.properties>>>). This
   bundle should be empty such that it retrieves strings via the parent chain from the base bundle.
 
+** Getting the Output Directory for a Report Mojo
+
+ A report mojo that subclasses <<<AbstractReportMojo>>> needs to implement <<<AbstractReportMojo.getOutputDirectory()>>>. This method
+ should <never> be called during the generation of the report, i.e. the code shown below is buggy:
+
++-----+
+public MyReportMojo extends AbstractReportMojo
+{
+    /**
+     * The base directory of the report output. Only relevant if the mojo is not run as part of a site generation.
+     *
+     * @parameter expression="${project.reporting.outputDirectory}"
+     */
+    private File outputDirectory;
+
+    /**
+     * @see org.apache.maven.reporting.AbstractMavenReport#getOutputDirectory()
+     */
+    protected String getOutputDirectory()
+    {
+        return outputDirectory.toString();
+    }
+
+    /**
+     * @see org.apache.maven.reporting.AbstractMavenReport#executeReport( java.util.Locale )
+     */
+    public void executeReport( Locale locale )
+    {
+        // will fail during a site generation
+        File outputFile = new File( getOutputDirectory(), "summary.txt" );
+    }
+}
++-----+
+
+  <<Explanation>>: There are in principal two situations in which a report mojo could be invoked. The mojo might be run
+  directly from the command line or it might be run indirectly as part of the site generation along with other report mojos.
+  The glaring difference between these two invocations is the way the output directory is controlled. In the first case,
+  the parameter <<<outputDirectory>>> from the mojo itself is used. In the second case however, the Maven Site Plugin
+  will set the output directory according to its own configuration by calling <<<MavenReport.setReportOutputDirectory()>>>
+  on the reports being generated. Therefore, developers should always use <<<MavenReport.getReportOutputDirectory()>>> if they
+  need to query the effective output directory for the report. 
+
 * Resources
 
     [[1]] {{{../../developers/mojo-api-specification.html}Mojo Documentation}}: Mojo API, Mojo annotations