6.2.2.3. Create Internationalized Exceptions

This task shows you how to create internationalized exceptions and how to use them. This task does not cover all optional features or the process of localization of those exceptions.
Refer to the logging-tools quick start for a complete example.
For this task it is assumed that you already have a software project, that is being built in either JBoss Developer Studio or Maven, to which you want to add internationalized exceptions.

Procedure 6.3. Create and use Internationalized Exceptions

  1. Add JBoss Logging Tools configuration

    Add the required project configuration to support JBoss Logging Tools. Refer to Section 6.2.6.1, “JBoss Logging Tools Maven Configuration”
  2. Create an interface for the exceptions

    JBoss Logging Tools defines internationalized exceptions in interfaces. Name each interface descriptively for the exceptions that will be defined in it.
    The interface has the following requirements:
    • It must be declared as public.
    • It must be annotated with @org.jboss.logging.MessageBundle.
    • The interface must define a field that is a message bundle of the same type as the interface.
    @MessageBundle(projectCode="")
    public interface ExceptionBundle 
    {
       ExceptionBundle EXCEPTIONS = Messages.getBundle(ExceptionBundle.class);
    }
    
    
  3. Add method definitions

    Add a method definition to the interface for each exception. Name each method descriptively for the exception that it represents.
    Each method has the following requirements:
    • It must return an object of type Exception or a sub-type of Exception.
    • It must be annotated with the @org.jboss.logging.Message annotation.
    • The value attribute of @org.jboss.logging.Message must be set to the default exception message. This is the message that is used if no translation is available.
    • If the exception being returned has a constructor that requires parameters in addition to a message string, then those parameters must be supplied in the method definition using the @Param annotation. The parameters must be the same type and order as the constructor.
    @Message(value = "The config file could not be opened.")
    IOException configFileAccessError();
    
    @Message(id = 13230, value = "Date string '%s' was invalid.")
    ParseException dateWasInvalid(String dateString, @Param int errorOffset);
    
  4. Invoke methods

    Invoke the interface methods in your code where you need to obtain one of the exceptions. The methods do not throw the exceptions, they return the exception object which you can then throw.
    try 
    {
       propsInFile=new File(configname);
       props.load(new FileInputStream(propsInFile));
    }
    catch(IOException ioex) //in case props file does not exist
    {
       throw ExceptionBundle.EXCEPTIONS.configFileAccessError(); 
    }
    
RESULT: the project now supports internationalized exceptions that can be localized.