Struts Message Resources.pdf

Struts Message Resources http://www.systemmobile.com/articles/strutsMessageResources.html

1 of 7 03-Jul-04 12:38

Struts Message Resources

Overview: Many programmers new to Struts experience a great deal of difficulty makinguse of the MessageResources functionality. This article will explain the benefits of thisfeature and provide information and examples on how to make it work for you.

Author: Nick Heudecker, System Mobile Inc.

Table of Contents:

OverviewUsage

Creating the Resource BundleConfigurationWhere To Put The FileTagsActions

InternationalizationJSTLConclusionAbout the AuthorResourcesNotes

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 thatproperly using resource bundles will allow the developer to store label strings in a centralized location, without having to duplicate the same string throughout your JSPcode. For example, instead of having the string "First Name" in each form with a field forthe 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:

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

http://www.systemmobile.com/articles/strutsMessageResources.html


2 of 7 03-Jul-04 12:38

[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=Usernamelabel.password=Passwordlabel.first.name=First Namelabel.last.name=Last Namelabel.email=Email Addresslabel.phone.number=Phone Numberlabel.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 parametersthat 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 specifyingit 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 bundlesbased 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 methodas 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



3 of 7 03-Jul-04 12:38

it gives you quite a bit of additional flexibility:

You can list multiple message-resources tags to load messages from multiplefiles. 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 automatedtesting of your JSPs, making in-container unit testing more complete. (Details abouthow 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/filesmust exist somewhere in your classpath. This can mean putting it into a JAR file, orputting it in the /WEB-INF/classes directory, or in a subdirectory under classes. Thetable 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

/WEB-INF/classes/ApplicationResources.properties ApplicationResources

/WEB-INF/classes/resources/ApplicationResources.properties resources.ApplicationResources



4 of 7 03-Jul-04 12:38

In the app.jar file, in the com.systemmobile.example package/directory. com.systemmobile.example.ApplicationResources

[top]

Tags

The most common Struts tag to use is the bean:message tag. This tag allows you toload a specific message resource from the bundle using the "key" attribute. It also allowsyou 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 bepresent in the request, obviously, or there will be nothing to display. Here is an exampleof 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. Thehtml:link tag allows you to specify the title text with the "titleKey" attribute. Many of thehtml tags support the "altKey" attribute to load the alternate text label value from the resources bundle.

Actions

[top]

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

// returns a resource bundle for the locale specified in the requestprotected 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/> elementprotected 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 localepublic 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);



5 of 7 03-Jul-04 12:38

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 HttpServletRequestpublic 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:messagearg0...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 theJSP. Messages can apply to specific bean properties or can be generic. TheActionError, 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.

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 inApplicationResources_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 bundlesare tried until the default Locale is used.

1.

If the message key is found, it is added to a Locale-specific cache and returned as a java.lang.String.

2.

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.

3.

[top]

JSTL

The JSTL (JavaServer Pages Standard Tag Library) fmt tag has recently come into



6 of 7 03-Jul-04 12:38

vogue as the preferred way to utilize the message resources functionality with JSPs. Italso works quite well with Struts. Setting it up is pretty simple, as the rules aboutclasspath and file location still apply. After downloading the JSTL jar and TLDs andcopying 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 usingthe Struts tags, although the JSTL tags are rapidly gaining favor. I hope that this articleclarified 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 designingand 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 Ann Arbor, Michigan.


http://java.sun.com/jstl/fmt


7 of 7 03-Jul-04 12:38

[top]

Resources

The following resources will be helpful when researching MessageResources:

JavaDoc for the classes of interest:java.util.ResourceBundlejava.util.Localeorg.apache.struts.util.MessageResourcesorg.apache.struts.action.ActionErrororg.apache.struts.action.ActionMessage

Ted Husted's Struts Tips: Very handy advice, especially for resource bundle usage.Struts Home PageStruts-User Mailing List Archive: Many people use Struts, so there is a very good chance that your question has be answered already. Please use all availableresources before asking your question on the mailing list.JSTL Homepage and the Jakarta JSTL Implementation

[top]

Notes

Packages are just directory structures used to avoid naming conflicts. If you put amessage 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, thispoint seems to trip up many new programmers.

1.


Documents

Struts Message Resources.pdf