James Perkins [http://community.jboss.org/people/jamezp] modified the document: "JBoss Logging Tooling" To view the document, visit: http://community.jboss.org/docs/DOC-16818 -------------------------------------------------------------- *+** Note:+* +This document is currently targeted at JBoss Logging 3.0.0 CR1 and JBoss Logging Tooling 1.0.0 Beta8-SNAPSHOT (the reason for the snapshot is a bug retrieving loggers from translated loggers)+. Want to internationalize (i18n) your logging, exception messages and messages in general? Then along with JBoss Logging 3.x, JBoss Logging Tooling is for you. It provides an easy way to offer internationalized messages, exceptions and logger messages to your project. With JBoss Logging Tooling you write interfaces and annotate the methods with a default message. Then you or a translator will create a properties file with the same name as your class in a directory that matches your package name and append the file name with ".i18n" followed by the language, country (optional) and variant (optional). The basic pattern for the file name is +qualified/package/as/path/ClassName.i18n_language_country_variant.properties+. For example if you have a class named +org.jboss.as.As7RocksMessages+ and you want to translate this into French you create a properties file called +As7RocksMessages.i18n_fr.properties+ in a directory +org/jboss/as+. At this point you're probably thinking, "Big deal, I can already do this with resource bundles.". You could, but we all know you love performance. The beautiful thing about using the tooling is it creates concrete classes from the interface which gives you better runtime performance. You could write some singleton style class to do the same thing, but why not let the tooling handle that for you? Okay, before I bore you to death let's see some code. In the following example you will see a logger interface, the translation files and the generated code. h2. Dependencies * JBoss Logging 3 * tools.jar or CodeModel (which can be found here http://codemodel.java.net/ http://codemodel.java.net/) h2. Constraints *The following annotations are defined:* * @org.jboss.logging.MessageBundle - This annotation is attached to an interface which is intended to be a message bundle (a generic source of translated strings; i.e. there are no logging methods on the interface). Interfaces annotated with this annotation can be instantiated via the Messages.getBundle(InterfaceName.class) method. * @org.jboss.logging.MessageLogger - This annotation is attached to an interface which is intended to act as a translating message logger. Such interfaces may include plain bundle messages as well as logger messages.  Interfaces annotated with this annotation can be instantiated via the Logger.getMessageLogger(InterfaceName.class, "category.name") method. * @org.jboss.logging.Message - this annotation is attached to any interface method which corresponds to a message which may be translated.  This includes both simple messages and log messages. * @org.jboss.logging.LogMessage - this annotation is attached to log messages (in addition to Message above), and includes additional information such as the log level for the message. * @org.jboss.logging.Cause - this annotation is attached to a method parameter which should be considered to be the causing java.lang.Throwable (or subclass thereof). *Message bundle interfaces must conform to these rules:* * The message bundle annotation may specify a project code. * All methods defined on the message bundle interface must have a @org.jboss.logging.Message annotation present, unless the method has the same name as another method on the interface and same number of parameters (minus the cause parameter) which has the annotation present. * All methods defined on the message bundle interface must return either java.lang.String or one of its supertypes, or java.lang.Throwable or one of its subtypes. * All methods defined on the message bundle interface must accept a number of parameters consistent with the format string on the value attribute of the @org.jboss.logging.Message annotation. This assertion is complex to ascertain at compile-time, thus the no errors are shown at compile time. * The @org.jboss.logging.Cause annotation may appear at most once on any given method's parameter list. * If the method returns a java.lang.Throwable, the parameter marked as @Cause is passed in to that Throwable's constructor if it has such a parameter; if not, then it is passed in to the Throwable's initCause() method after the Throwable is constructed. * If the method returns a java.lang.Throwable the message of the Throwable will initialized with the message from the annotation if available. * All of the @org.jboss.logging.Message annotations found on methods on all message bundle interfaces with the same project code which specify an id must specify a unique number, INHERIT, or NONE. * A message bundle interface may extend other message bundle interfaces. * A message bundle interface may extend java.io.Serializable; however, doing so is superfluous as the implementation class will implement this interface regardless. * A message bundle interface may not extend any other interfaces which do not fit the criteria specified above. *Message logger interfaces must conform to the above rules, except:* * A message logger interface may not specify a @org.jboss.logging.MessageBundle annotation; instead, it must specify a @org.jboss.logging.MessageLogger annotation (which also has a property for project code). * Any method on a message logger interface may additionally specify a @org.jboss.logging.LogMessage annotation. This annotation signifies that the method is a logger method. * All logger methods must be declared to return void. * A logger method may have a specified log level in the level property of the @LogMessage annotation. * If multiple methods of the same name exist, any number of them may have @LogMessage annotations.  Only methods so annotated are log message methods.  The rules regarding equally-named methods on message bundles continue to apply. * Log methods with a parameter marked as @Cause will pass that parameter in to the appropriate log method as the causing exception. * Message logger interfaces may extend other message logger interfaces in addition to the rules for message bundle interfaces. * Message logger interfaces may extend the @org.jboss.logging.BasicLogger interface. All methods of the BasicLogger will be delegated to the logger being used for the log methods. *Parameter count rules:* ** You should be aware parameters are counted a little differently than a normal overloaded method. The parameter count used for validation is comprised of a count of all the parameters minus the *@Cause* parameter. h2. Example Code More examples to come, but for now is is a source repository of examples on how to create the interfaces for loggers and message bundles. https://github.com/jamezp/jboss-logging-example https://github.com/jamezp/jboss-logging-example h2. How to set it up in your project? Using the logging tool requires minimal set-up. For a maven project, the JBoss Logging Tool library just needs to be in the build class path. The annotation processor must not be disabled either.     <build>         <plugins>             <plugin>                 <groupId>org.apache.maven.plugins</groupId>                 <artifactId>maven-compiler-plugin</artifactId>                 <!-- Must be at least version 2.2 with a target of 1.6 to generate the source files in                      target/generated-sources -->                 <version>2.3.2</version>                 <configuration>                     <source>1.6</source>                     <target>1.6</target>                     <showWarnings>true</showWarnings>                     <!-- Optional if you wan to generate skeleton translation properties files -->                     <compilerArgument>                         -AgeneratedTranslationFilesPath=${project.basedir}/target/generated-translation-files                     </compilerArgument>                 </configuration>             </plugin>         </plugins>     </build> When using an Eclipse project follow the instructions here http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.jdt.doc.isv/g... (http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.jdt.doc.isv/g...) to enable annotation processing. When using NetBeans as long as the library is in the class path, the annotations will automatically be processed. Intellij IDEA offers the following documentation to enable annotation processing. http://www.jetbrains.com/idea/webhelp/compiler-annotation-processors.html (http://www.jetbrains.com/idea/webhelp/compiler-annotation-processors.html) -------------------------------------------------------------- Comment by going to Community [http://community.jboss.org/docs/DOC-16818] Create a new document in JBoss AS7 Development at Community [http://community.jboss.org/choose-container!input.jspa?contentType=102&am...]