web     learntechnology.net
Struts Message Resources
 [ print format ]

Author: Nick Heudecker, System Mobile Inc.


Table of Contents
Overview
The MessageResources class allows a developer to easily support multiple languages, in addition to supporting multiple date and numeric formats. Another useful trait is that properly using resource bundles will allow the developer to store label strings in a centralized location, without having to duplicate the same string throughout your JSP code. For example, instead of having the string "First Name" in each form with a field for the user's first name, you can simply refer to this property in the resources bundle with the following struts tag: 
<bean:write key="label.first.name"/>

This will allow you to make changes easily, without having to open multiple JSPs or resorting to complicated regular expressions to change the label strings.

Usage
Getting started with message resource bundles requires you to:
  1. Create a message resources bundle for each locale you wish to support.
  2. Configure the web application to load the message resources bundle.
  3. Use the appropriate JSP tags to load the resources, or...
  4. ...load the resource values from an Action class.

[top]

Creating the Resource Bundle
The default implementation of the MessageResources class takes a file with simple "key=value" lines as input. Below is our example message resources bundle file. 
label.username=Username
label.password=Password
label.first.name=First Name
label.last.name=Last Name
label.email=Email Address
label.phone.number=Phone Number
label.welcome=Welcome back {0} {1}!

error.min.length=The input must be at least {0} characters in length.
error.max.length=The input cannot be longer than {0} characters in length.

The values with integers surrounded by brackets are a carry-over from the java.text.MessageFormat class. They allow the developer to pass in parameters that are inserted into the string. You can have up to four parameter fields per value string.

[top]

Configuration
There are two ways to tell Struts the location of your resource bundle: either by specifying it in your web.xml or in the struts-config.xml file. First, the web.xml configuration: 
<servlet>
<servlet-name>action</servlet-name>
<servlet-class>
    org.apache.struts.action.ActionServlet
</servlet-class>
<init-param>
<param-name>

    application
</param-name>
<param-value>
    com.systemmobile.example.ApplicationResources
</param-value>
</init-param>
</servlet>

This configuration states that the name of the resources bundle is ApplicationResources.properties and it is located in the com.systemmobile.example package. The ".properties" extension is implied; you do not have to include it in the configuration. If you also have various resource bundles based on locale, such as ApplicationResources_fr.properties to support French, you only need to specify the base file name, as listed above.

The second, and likely preferred, method of making your resource bundle available to your Struts application is to specify it in the struts-config.xml file: 

<message-resources parameter="com.systemmobile.example.ApplicationResources"/>

The parameter attribute is required. The same notes apply for this configuration method as for the web.xml method regarding the location of the file in the package structure and multiple locales.

Using the struts-config.xml file to configure your message resources is preferred as it gives you quite a bit of additional flexibility:

  • You can list multiple message-resources tags to load messages from multiple files. If you do this, use the key attribute to give a unique name to each bundle. e.g.: 
    <message-resources key="myResources" parameter="com.systemmobile.example.ApplicationResources"/>

<message-resources key="moreResources" parameter="com.systemmobile.example.MoreApplicationResources"/>
    You would then have to give the key name when using the bean:message tag: 
    <bean:message bundle="moreResources" key="some.message.key"/>
  • Setting the null attribute to "false" will display missing resource values as ???key??? instead of displaying null. This string is easily found during automated testing of your JSPs, making in-container unit testing more complete. (Details about how messages are retrieved from resource bundles can be found in the Internationalization section.) 
    <message-resources parameter="com.systemmobile.example.ApplicationResources" null="false"/>
  • Additionally, the message-resources tag allows you to use your own implementation of the MessageResourcesFactory class, which is outside the scope of this article.

[top]

Where To Put The File
The most common cause of problems with the message resources on the struts-user mailing list is where to put the actual file in the WAR. The short answer is that the file/files must exist somewhere in your classpath. This can mean putting it into a JAR file, or putting it in the /WEB-INF/classes directory, or in a subdirectory under classes. The table below gives the location of the message bundle file, the assocated value of the "parameter" attribute for the message-resources tag, and a short description if necessary.

Resources Location parameter Value Description
/WEB-INF/classes/ApplicationResources.properties ApplicationResources The file is in the classes directory, which is in the web app's classpath.
/WEB-INF/classes/resources/ApplicationResources.properties resources.ApplicationResources The file is in the "resources" directory, and therefore package, so the directory name is given. [1]
In the app.jar file, in the com.systemmobile.example package/directory. com.systemmobile.example.ApplicationResources The full path to the file in the JAR file.

[top]

Tags
The most common Struts tag to use is the bean:message tag. This tag allows you to load a specific message resource from the bundle using the "key" attribute. It also allows you to populate any or all of the four arguments in the value: 
<bean:message key="label.password"/>
<bean:message key="error.min.length" arg0="6"/>

<bean:message key="label.welcome" arg0="Ralph" arg1="Nader"/>

The html:message tag allows you to display errors (default) or messages to the user, while html:errors will only display error messages. Messages and errors must be present in the request, obviously, or there will be nothing to display. Here is an example of displaying the messages: 

<logic:messagesPresent message="true">
  <html:messages id="msg" message="true">

    <div class="success">
      <bean:write name="msg"/>
    </div><br/>
  </html:messages>
</logic:messagesPresent>

Other tags have limited support for message resources, such as html:link. The html:link tag allows you to specify the title text with the "titleKey" attribute. Many of the html tags support the "altKey" attribute to load the alternate text label value from the resources bundle.

Actions
You can also access message resources from within Action classes. The Action class has the following methods to obtain a reference to a MessageResource instance: 

// returns a resource bundle for the locale specified in the request
protected MessageResources getResources(HttpServletRequest request);

// returns a resource bundle for the locale specified in the request,
// for the given key as given in the <message-resources/> element
protected MessageResources getResources(javax.servlet.http.HttpServletRequest request, java.lang.String key);

The MessageResources class will allow you to retrieve locale-dependent messages from the underlying resource bundle. The API for MessageResources can be found in Resources. Some of the more commonly used methods include: 

// these methods load a resources key for the given locale
public String getMessage(java.util.Locale locale, java.lang.String key);
public String getMessage(java.util.Locale locale, java.lang.String key,
       java.lang.Object arg0);
public String getMessage(java.util.Locale locale, java.lang.String key,
       java.lang.Object[] args);
public String getMessage(java.util.Locale locale, java.lang.String key,
       java.lang.Object arg0, java.lang.Object arg1)
public String getMessage(java.util.Locale locale, java.lang.String key,
       java.lang.Object arg0, java.lang.Object arg1, java.lang.Object arg2);
public String getMessage(java.util.Locale locale, java.lang.String key, java.lang.Object arg0,
       java.lang.Object arg1, java.lang.Object arg2, java.lang.Object arg3);

// these methods load a resources key for the locale retrieved
// from the HttpServletRequest
public String getMessage(java.lang.String key);
public String getMessage(java.lang.String key, java.lang.Object arg0);
public String getMessage(java.lang.String key, java.lang.Object[] args);
public String getMessage(java.lang.String key, java.lang.Object arg0,
       java.lang.Object arg1);
public String getMessage(java.lang.String key, java.lang.Object arg0,
       java.lang.Object arg1, java.lang.Object arg2);
public String getMessage(java.lang.String key, java.lang.Object arg0,
       java.lang.Object arg1, java.lang.Object arg2, java.lang.Object arg3);

Returned Strings can be set as attributes in the request or session and passed back to the view layer. You'll notice that some of the various overloaded getMessage(...) methods take Objects as arg0...arg3. This is the equivalent to the bean:message arg0...arg3 attributes.

In addition to the MessageResources class, a few other classes make use of resources bundles. ActionMessage is used to pass message resource keys from the action to the JSP. Messages can apply to specific bean properties or can be generic. The ActionError, subclass of ActionMessage, class uses the resource bundle keys to store error messages when form validation fails.

[top]

Internationalization
Loading a specific message resources bundle for a give locale is handled by the MessageResources class, or by it's immediate subclass, PropertyMessageResources. Since you're likely to use the PropertyMessageResources class, we'll examine how it loads message resources for a key using the getMessage(Locale, String) method.

  1. The message is located using specific Locales. If the message cannot be found, more generic Locales are used. For instance if the message can't be found in ApplicationResources_pt_br.properties (Brazilian Portuguese), the ApplicationResources_pt.properties file (and therefore Locale) will be searched. If the ApplicationResources_pt.properties file does not exist or the key is not found, the mesage will be retrieved from the ApplicationResources.properties file. Increasingly generic resource bundles are tried until the default Locale is used.
  2. If the message key is found, it is added to a Locale-specific cache and returned as a java.lang.String.
  3. If the message key is not found, null is returned if the returnNull attribute is true, which is the default. If returnNull is false, a string such as ???key??? is return, where key is the passed message resources key.

[top]

JSTL
The JSTL (JavaServer Pages Standard Tag Library) fmt tag has recently come into vogue as the preferred way to utilize the message resources functionality with JSPs. It also works quite well with Struts. Setting it up is pretty simple, as the rules about classpath and file location still apply. After downloading the JSTL jar and TLDs and copying them into the appropriate places in your application, put the following configuration block into your web.xml: 
<context-param>
  <param-name>javax.servlet.jsp.jstl.fmt.localizationContext</param-name>
  <param-value>ApplicationResources</param-value>
</context-param>

The above configuration is if the file ApplicationResources.properties is located in the /WEB-INF/classes directory. See above for the guidelines about configuration.

Then put this taglib directive into your JSP: 


<%@ taglib prefix="fmt" uri="http://java.sun.com/jstl/fmt" %>

Finally, the following tag will load a resource: 

<fmt:message key="label.first.name"/>

Here are some additional examples of using the fmt tags to load resource values. (Note: these were taken from the Jakarta JSTL examples.) 

// loading a resource from a specific bundle and populating a parameter
<fmt:message key="currentTime" bundle="${deBundle}">
 <fmt:param value="${currentDateString}"/>
</fmt:message>

// using the forEach iterator to populate paramters
<fmt:message key="serverInfo" bundle="${deBundle}">
 <c:forEach var="arg" items="${serverInfoArgs}">
  <fmt:param value="${arg}"/>

 </c:forEach>
</fmt:message>

[top]

Conclusion
The message resources functionality in Struts allows you to easily create fully internationalized web applications, as well as providing a convenient abstraction between messages and the JSPs. The resource values can be loaded from within actions or using the Struts tags, although the JSTL tags are rapidly gaining favor. I hope that this article clarified a few things for you regarding this handy and, sometimes confusing, feature of Struts.

[top]

About the Author
Nick Heudecker is a software developer with more than six years of experience designing and building enterprise applications. His firm, System Mobile, Inc., specializes in application integration, custom software development and wireless applications. He is a Sun Certified Java Programmer and is located in Chicago.

[top]

Resources
The following resources will be helpful when researching MessageResources:

[top]

Notes
  1. Packages are just directory structures used to avoid naming conflicts. If you put a message bundle in a directory named resources under /WEB-INF/classes, this is the equivalent of putting the file in a package named resrouces. While basic, this point seems to trip up many new programmers.

[top]