Return-Path: 
 <commits-return-15770-apmail-maven-commits-archive=maven.apache.org@maven.apache.org>
Delivered-To: apmail-maven-commits-archive@www.apache.org
Received: (qmail 29249 invoked from network); 15 Jan 2008 04:17:55 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2)
  by minotaur.apache.org with SMTP; 15 Jan 2008 04:17:55 -0000
Received: (qmail 2159 invoked by uid 500); 15 Jan 2008 04:17:44 -0000
Delivered-To: apmail-maven-commits-archive@maven.apache.org
Received: (qmail 2107 invoked by uid 500); 15 Jan 2008 04:17:44 -0000
Mailing-List: contact commits-help@maven.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:commits-help@maven.apache.org>
List-Unsubscribe: <mailto:commits-unsubscribe@maven.apache.org>
List-Post: <mailto:commits@maven.apache.org>
List-Id: <commits.maven.apache.org>
Reply-To: dev@maven.apache.org
Delivered-To: mailing list commits@maven.apache.org
Received: (qmail 2094 invoked by uid 99); 15 Jan 2008 04:17:44 -0000
Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230)
    by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 14 Jan 2008 20:17:44 -0800
X-ASF-Spam-Status: No, hits=-99.8 required=10.0
	tests=ALL_TRUSTED,WHOIS_MYPRIVREG
X-Spam-Check-By: apache.org
Received: from [140.211.11.3] (HELO eris.apache.org) (140.211.11.3)
    by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 15 Jan 2008 04:17:30 +0000
Received: by eris.apache.org (Postfix, from userid 65534)
	id B58CA1A9832; Mon, 14 Jan 2008 20:17:21 -0800 (PST)
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r612011 -
 /maven/site/trunk/src/site/apt/guides/plugin/guide-java-plugin-development.apt
Date: Tue, 15 Jan 2008 04:17:21 -0000
To: commits@maven.apache.org
From: vsiveton@apache.org
X-Mailer: svnmailer-1.0.8
Message-Id: <20080115041721.B58CA1A9832@eris.apache.org>
X-Virus-Checked: Checked by ClamAV on apache.org

Author: vsiveton
Date: Mon Jan 14 20:17:20 2008
New Revision: 612011

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

o applied
o added "Commons Bugs thread" link

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=612011&r1=612010&r2=612011&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 Mon Jan 14 20:17:20 2008
@@ -100,11 +100,12 @@
   * The <<<getLog>>> method (defined in <<<AbstractMojo>>>) returns a
     log4j-like logger object which allows plugins to create messages at levels
     of "debug", "info", "warn", and "error".  This logger is the accepted means
-    to display information to the user.
+    to display information to the user. Please have a look at the section about
+    pitfalls for a hint on its proper usage.
 
   []
 
- All Mojo annotations are described {{{../../developers/mojo-api-specification.html#The_Descriptor_and_Annotations}here}}.
+ All Mojo annotations are described by the {{{../../developers/mojo-api-specification.html#The_Descriptor_and_Annotations}Mojo API Specification}}.
 
 ** Project Definition
 
@@ -319,7 +320,7 @@
   the variable as a mojo parameter.  The "<<<expression>>>"
   parameter defines the default value for the variable.  This value can
   include expressions which reference the project, such as
-  "<<<${project.version}>>>" (more can be found in the
+  "<<<$\{project.version\}>>>" (more can be found in the
   "Parameter Expressions" document).  The name of the variable is used
   as the name of the parameter.
 
@@ -696,6 +697,24 @@
   into the mojo fields. If you really need to use <<<java.lang.String>>> for the parameter type (e.g. to allow the user to alternatively specify
   a class path resource or URL), be sure to always resolve relative file paths manually against the base directory of the project.
 
+** Creating Resource Bundles
+
+ Omitting an explicit resource bundle for the default locale provided by the base bundle is not allowed. For example, the following family
+ of resource bundles does not provide reliable internationalization for your mojo:
+
++-----+
+mymojo-report.properties
+mymojo-report_de.properties
++-----+
+
+  <<Explanation>>: As described in the method javadoc about
+  <<<{{{http://java.sun.com/javase/6/docs/api/java/util/ResourceBundle.html#getBundle(java.lang.String,%20java.util.Locale,%20java.lang.ClassLoader)}ResourceBundle.getBundle(String, Locale, ClassLoader)}}>>>,
+  the lookup strategy to find a bundle for a specific locale will prefer the bundle for the JVM's default locale over the base bundle.
+  However, the JVM's default locale needs not to match the locale of the base bundle. In the example above, a request for the locale "en" will
+  retrieve the bundle <<<mymojo-report_de.properties>>> instead of <<<mymojo-report.properties>>> if the JVM's default locale happens to be "de".
+  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.
+
 * Resources
 
     [[1]] {{{../../developers/mojo-api-specification.html}Mojo Documentation}}: Mojo API, Mojo annotations
@@ -707,5 +726,7 @@
     [[4]] {{{http://plexus.codehaus.org/plexus-utils/}Plexus Common Utilities}}: Set of utilities classes useful for Mojo development.
 
     [[5]] {{{http://commons.apache.org/io/}Commons IO}}: Set of utilities classes useful for file/path handling.
+
+    [[6]] {{{http://www.nabble.com/Common-Bugs-td14783703s177.html}Common Bugs Thread}}.
 
     []