Getting startedIn order to get an impression of how this component works, we will start with an example showing the capabilities of this package. To get started you need at least the jar of this component and the dependent Defining the messages in an XML fileUsing XML based files has many advantages:
You have to initialize the message manager with an input stream giving access to the xml document containing the localized messages. <?xml version="1.0" encoding="UTF-8" ?> <messages> <message id="welcome"> <locale language="en"> <entry key="text">Welcome</entry> </locale> <locale language="de"> <entry key="text">Willkommen</entry> </locale> </message> <message id="usage"> <locale language="en"> <entry key="title">Usage</entry> <entry key="text">The application requires the following parameters:</entry> </locale> <locale language="de"> <entry key="title">Benutzung</entry> <entry key="text">Die folgenden Parameter werden erwartet:</entry> </locale> </message> <message id="validationFailed"> <locale language="en"> <entry key="title">Parameter {0} invalid</entry> <entry key="text">The given value of the parameter {0} is invalid</entry> <entry key="summary">Value of parameter {0} invalid</entry> <entry key="details">The given value {1} of parameter {0} is invalid.</entry> </locale> <locale language="de"> <entry key="title">Parametervalidierung fehlgeschlagen.</entry> <entry key="text">Die Validierung des Parameters {0} ist fehlgeschlagen.</entry> <entry key="summary">Validierung des Parameters {0} fehlgeschlagen.</entry> <entry key="details">Der Wert {1} des Parameters {0} ist ungültig.</entry> </locale> </message> </messages> This is an example that shows how to create localized bundles. As you can see each
message is identified by a message id and contains the bundled messages for the
defined locales. The language identifiers are well known from the Each bundle can consist of a number of message entries that belong to this bundle. You are free to add as many entries to each bundle as you like. The I18n component contains a number of classes that simplify the access to entries of frequently used bundles. NEW: Pluggable message providersSince version 0.3 of this component you can add your own custom message providers. This is a big plus if you already have your localized messages in a database for example.
You do not have to convert them into the supported XML or property-based format, but you
can write a simple NEW: ResourceBundle based message provider addedA new message provider made it into this component: The You can group entries messages by adding the key at the end of the existing message key. The following example shows how a property file should look like to work as the following XML example: As you know you'll need two files, each containing the messages for a specific locale. This one might be the default one calld myMessages.properties: welcome.text=Welcome usage.title=Usage usage.text=The application requires the following parameters: validationFailed.title=Parameter {0} invalid validationFailed.text=The given value of the parameter {0} is invalid validationFailed.summary=Value of parameter {0} invalid validationFailed.details=The given value {1} of parameter {0} is invalid. The following one would contain the corresponding german translations in a file called myMessages_de.properties: welcome.text=Willkommen usage.title=Benutzung usage.text=Die folgenden Parameter werden erwartet: validationFailed.title=Parametervalidierung fehlgeschlagen. validationFailed.text=Die Validierung des Parameters {0} ist fehlgeschlagen. validationFailed.summary=Validierung des Parameters {0} fehlgeschlagen. validationFailed.details=Der Wert {1} des Parameters {0} ist ungültig. Initializing the messagesNow that we created a file containing the desired messages, we want to make use of them.
To do so we have to initialize the Initializing messages depends on the ... try { FileInputStream inputStream = new FileInputStream("myMessages.xml"); XMLMessageProvider.install("myMessages", inputStream); } catch ( FileNotFoundException e ) { // handle exception } ... As you can see it is very easy to install new messages. All you need is an appropriate input stream to access the xml messages. Why is the manager initialized with an input stream and not using a file name? You might want to use the i18n component within web applications where you want probably load messages from you .war archive. So an input stream is much more flexible, even if it is a little bit more unconvenient than using a file name in our use case. In case of the brand new ... ResourceBundleMessageProvider.install("myMessages"); ... It's this simple, because the Using message bundlesNow we are ready to go! First of all we want to print out a simple localized welcome
message to the user. There are different way to do so: We can call the
... System.out.println(MessageManager.getText("welcome", "text", new Object[0], Locale.getDefault())); ... If you are familiar with text formatting in Java you will have guessed correctly that you have the ability to pass arguments to the localized text. In our case we don't pass any arguments but just an empty object array. The previous example might be useful if you want to print out some localized message quick and dirty, but the recommended way is the following: ... LocalizedText welcome = new LocalizedText("welcome"); // Using the default locale System.out.println(welcome.getText()); // Using some other locale System.out.println(welcome.getText(Locale.GERMAN)); ... In this example we make use of the predefined message bundle called ... LocalizedText welcome = new LocalizedText("undefined"); System.out.println(welcome.getText("notFound")); ... As the The Using localized exceptionsThe concept of message bundles is very useful when it comes to exception handling.
You can simple create a ... try { doSomething(); } catch ( SomeException exception ) { throw new LocalizedException( new LocalizedError("somethingFailed", new Object[] { agrument1 }), exception); } ... The big advantage of this approach is that you can create localized exceptions with all arguments that are describing the error in detail and print out localized details including this arguments lateron. Have a look at the Slide Projector to see how this can simplify your life ;-) DocumentationThe JavaDoc API documents are available online. |