[jboss-dev-forums] [JBoss AS 7 Development] - JBoss Logging Tooling
Hardy Ferentschik
do-not-reply at jboss.com
Tue Mar 27 04:02:25 EDT 2012
Hardy Ferentschik [https://community.jboss.org/people/hardy.ferentschik] modified the document:
"JBoss Logging Tooling"
To view the document, visit: https://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)+.
**
#Why Why?
**
#How_does_it_work How does it work?
**
#Dependencies Dependencies
**
#Constraints Constraints
**
#Example_Code Example Code
**
#How_to_set_it_up_in_your_project How to set it up in your project?
***
#Maven Maven
****
#mavencompilerplugin maven-compiler-plugin
****
#mavenprocessorplugin maven-processor-plugin
***
#IDE IDE
****
#Eclipse Eclipse
****
#NetBeans NetBeans
****
#Intellij Intellij
**
#Issue_tracking Issue tracking
h2. Why?
If you want to internationalize (i18n) your logging, exception messages and messages in general, then along with JBoss Logging 3.x, JBoss Logging Tools is for you. It provides an easy way to offer internationalized messages, exceptions and logger messages to your project.
With JBoss Logging Tools you write interfaces and annotate the methods with a default message. Then you or a translator will create a properties file with the translated text.
h2. How does it work?
JBoss Logging Tools uses an annotation processor to implement concrete classes of your annotated interfaces. If you have also provided translation properties files, then a new concrete class will be created extending the implementation and overriding the messages returned.
The translation properties files must exist in the same directory structure as the interface. The name of the properties file +InterfaceName.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+.
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.
h3. Maven
For a maven project you are having two options
h4. maven-compiler-plugin
In this case the JBoss Logging Tool library needs to be specified as project dependency.
...
<dependencies>
...
<dependency>
<groupId>org.jboss.logging</groupId>
<artifactId>jboss-logging-processor</artifactId>
<version>${jbossLoggingProcessorVersion}</version>
</dependency>
</dependencies>
<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>
...
h4. maven-processor-plugin
In this approach the +maven-processor-plugin+ is used for running the annotation processor. The +jboss-logging-processor+ dependency is now local to the plugin and the Maven bugs http://jira.codehaus.org/browse/MCOMPILER-62 MCOMPILER-62 and http://jira.codehaus.org/browse/MCOMPILER-66 MCOMPILER-66 are avoided.
...
<plugin>
<groupId>org.bsc.maven</groupId>
<artifactId>maven-processor-plugin</artifactId>
<version>2.0.2</version>
<executions>
<!-- Run annotation processors on src/main/java sources -->
<execution>
<id>process</id>
<goals>
<goal>process</goal>
</goals>
<phase>generate-sources</phase>
<configuration>
<processors>
<processor>org.jboss.logging.generator.apt.LoggingToolsProcessor</processor>
</processors>
</configuration>
</execution>
<!-- Run annotation processors on src/test/java sources -->
<execution>
<id>process-test</id>
<goals>
<goal>process-test</goal>
</goals>
<phase>generate-test-sources</phase>
<configuration>
<processors>
<processor>org.jboss.logging.generator.apt.LoggingToolsProcessor</processor>
</processors>
</configuration>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>org.jboss.logging</groupId>
<artifactId>jboss-logging-processor</artifactId>
<version>${jbossLoggingProcessorVersion}</version>
<scope>compile</scope>
</dependency>
</dependencies>
</plugin>
...
This approach is also described on this http://in.relation.to/17636.lace blog entry on in.relation.to
h3. IDE
h4. Eclipse
When using an Eclipse project follow the instructions here http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.jdt.doc.isv/guide/jdt_apt_getting_started.htm (http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.jdt.doc.isv/guide/jdt_apt_getting_started.htm) to enable annotation processing.
h4. NetBeans
When using NetBeans as long as the library is in the class path, the annotations will automatically be processed.
h4. Intellij
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)
h2. Issue tracking
JBoss issue tracker - https://issues.jboss.org/browse/JBLOGGING JBLogging
--------------------------------------------------------------
Comment by going to Community
[https://community.jboss.org/docs/DOC-16818]
Create a new document in JBoss AS 7 Development at Community
[https://community.jboss.org/choose-container!input.jspa?contentType=102&containerType=14&container=2225]
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/jboss-dev-forums/attachments/20120327/e67ba530/attachment.html
More information about the jboss-dev-forums
mailing list