General Rules:
- All exceptions and messages require a translation method in the @MessageBundle.
- All info and higher messages being logged require a translation method in the @MessageLogger.
- Messages in both the @MessageBundle and @MessageLogger should have an id*. Note though there are cases, specifically some methods in the @MessageBundle, that do not need id's. These typically include messages that are not being used in exceptions.
- All logged messages should use a static logger from the @MessageLogger interface. This includes debug and trace messages.
* A list of id's can be found here http://community.jboss.org/wiki/LoggingIds
Passing the cause:
Both @MessageLogger's and @MessageBundle's can except a java.lang.Throwable type as a parameter to either log the exception or intialize the exception return types cause. This is done by annotating the parameter with @Cause.
StartException unableToStart(@Cause Throwable cause);
Creating Exception Return Types:
Most @MessageBundle's methods will be returing exceptions. Some exceptions require a special constructor to be used or require a property/field to be set on the exception. JBoss Logging has 3 separate annotations for these requirements.
@Param - Is used for exception constructor.
SAXParseException invalidAttribute(@Param Locator locator, String attributeName, String tagName);
@Field({name=fieldName}) - Is used to set an instance variable.
XAException invalidTransaction(@Field Integer errorCode);
@Propert({name=propertyName}) - Is used to set a property via it's setter method.
Exception createException(@Property StackTrace[] stackTrace);
Examples:
Before:
@Override
public void start(StartContext context) throws StartException {
try {
final JBossThreadFactory threadFactory = new JBossThreadFactory(new ThreadGroup("ServerDeploymentRepository-temp-threads"), Boolean.FALSE, null, "%G - %t", null, null, AccessController.getContext());
tempFileProvider = TempFileProvider.create("temp", Executors.newScheduledThreadPool(2, threadFactory));
} catch (IOException e) {
throw new StartException("Failed to create temp file provider");
}
log.debugf("%s started", ServerDeploymentRepository.class.getSimpleName());
}
Methods added to DeploymentRepositoryMessages:
/**
* Creates an exception indicating a failure to create a temp file provider.
*
* @return a {@link StartException} for the error.
*/
@Message(id = 14900, value = "Failed to create temp file provider")
StartException failedCreatingTempProvider();
After:
@Override
public void start(StartContext context) throws StartException {
try {
final JBossThreadFactory threadFactory = new JBossThreadFactory(new ThreadGroup("ServerDeploymentRepository-temp-threads"), Boolean.FALSE, null, "%G - %t", null, null, AccessController.getContext());
tempFileProvider = TempFileProvider.create("temp", Executors.newScheduledThreadPool(2, threadFactory));
} catch (IOException e) {
throw MESSAGES.failedCreatingTempProvider();
}
ROOT_LOGGER.debugf("%s started", ServerDeploymentRepository.class.getSimpleName());
}