Overview   Package  Class  Use  Tree  Deprecated  Index  Help 
 PREV PACKAGE   NEXT PACKAGE FRAMES    NO FRAMES    

Package org.apache.struts.util

The Utilities package provides a variety of families of classes, to solve problems that are commonly encountered in building web applications.

See:
          Description

Class Summary
ImageButtonBean A simple JavaBean to encapsulate the request parameters sent for an HTML input element of type image.
IteratorAdapter Utility method for converting Enumeration to an Iterator class.
LabelValueBean A simple JavaBean to represent label-value pairs.
MessageResources General purpose abstract class that describes an API for retrieving Locale-sensitive messages from underlying resource locations of an unspecified design, and optionally utilizing the MessageFormat class to produce internationalized messages with parametric replacement.
MessageResourcesFactory Factory for MessageResources instances.
ModuleUtils General purpose utility methods related to module processing.
PropertyMessageResources Concrete subclass of MessageResources that reads message keys and corresponding strings from named property resources in a similar manner (see modes below) that java.util.PropertyResourceBundle does.
PropertyMessageResourcesFactory Factory for PropertyMessageResources instances.
RequestUtils General purpose utility methods related to processing a servlet request in the Struts controller framework.
ResponseUtils General purpose utility methods related to generating a servlet response in the Struts controller framework.
ServletContextWriter A PrintWriter implementation that uses the logging facilities of a javax.servlet.ServletContext to output its results.
TokenProcessor TokenProcessor is responsible for handling all token related functionality.
WildcardHelper This class is an utility class that perform wilcard-patterns matching and isolation taken from Apache Cocoon.
 

Exception Summary
ModuleException Used for specialized exception handling.
 

Package org.apache.struts.util Description

The Utilities package provides a variety of families of classes, to solve problems that are commonly encountered in building web applications.

[Introduction] [Beans] [Servlet Utilities] [Message Resources]

Introduction

The Struts Utilities Package offers several families of classes that assist in solving commonly encountered problems when building web applications. Most of the classes in this package do not rely on the controller servlet framework, or the custom tag libraries, so they are also suitable for general Java application programming. The following families are included:

Beans

The ImageButtonBean is a simple JavaBean to encapsulate the request parameters sent for an HTML input element of type image. The LabelValueBean is a simple JavaBean to represent label-value pairs, especially useful for html option elements.

Servlet Utilities

The RequestUtils is a general purpose utility methods related to processing a servlet request. The ResponseUtils is a general purpose utility methods related to generating a servlet response. The ServletContextWriter is a PrintWriter implementation that uses the logging facilities of a javax.servlet.ServletContext to output its results.

Message Resources

Background

Modern applications often include the requirement to support multiple languages, for users who prefer to interact in a language other than the default language configured on the server platform. In addition, sentences often need to be constructed, with dynamic content whose placement in the message depends on the standard sentence structure in that particular language.

The standard Java platform includes a family of classes (java.util.ResourceBundle) designed to support looking up message strings based on a standard "key". The resource bundle classes automatically access a Java class (or properties file) that is named with a naming convention that includes the Locale to which messages in that class (or file) pertain. However, this selection is based only on the default Locale of the server platform, and cannot be adjusted on a per-user basis as required for an internationalized web application.

Struts includes a family of classes (org.apache.struts.util.MessageResources) that extends the basic approach to looking up message strings by key, allowing you to optionally specify a Locale along with the key. In this way, you can build applications that let your users select which Locale they wish to operate within, and then look up messages in that language - using the same message keys no matter what language is selected.

In addition to supporting dynamic selection of a Locale for message lookup, the MessageResources family of classes optionally allow you to specify up to four parameter replacement objects, which are used to replace the parameter placeholders "{0}" through "{3}" in the retrieved message. This replacement uses the facilities of the standard Java java.text.MessageFormat class, which supports many extended formatting capabilities as well.

For more information about internationalized messages, consult the following resources in your Java Development Kit documentation bundle:

Using the Standard MessageResources Implementation

The standard MessageResources implementation provided by the Struts library uses Java properties files to initialize message strings, in a manner very similar to that supported by the java.util.PropertyResourceBundle class. The following steps are required to use these facilities in your Java application.

First, prepare a Java properties file for each language (or Locale) in which you wish to support your messages. The filenames you use must conform to the naming convention for property resource bundles, as described in the documentation referenced above. Be sure you use the same message keys in each file to identify the same message.

For example, you might prepare files in French, Spanish, and English that contain language-specific versions of the word "Hello". The French file would be named Messages_fr.properties and contain the following: 

    hi=Bonjour

while the Spanish and English files would be named Messages_es.properties and Messages_en.properties respectively. The corresponding message string definitions would say hi=Hola and hi=Hello in these files.

Second, place these properties files into the class path for your application, exactly as you would with class files themselves. The name actually used to load resources will look like a fully qualified Java class name (with appropriate package prefixes), so the file should be nested inside a directory structure that matches the packaging (either in an unpacked directory, or within a JAR file, as appropriate). For example, assume you place directory "foo" on your classpath, and stored the above properties files in directory "foo/com/mycompany/mypackage". (If you were using a JAR file like "foo.jar" instead, the files would be in directory "com/mycompany/mypackage" within the JAR file).

Third, initialize a MessageResources object that corresponds to the set of properties files for a particular name, within a particular package. The easiest way to do this is to initialize a variable in your main application class, like this:

    public static MessageResources messages =
    MessageResources.getMessageResources("com.mycompany.mypackage.Messages");

Note that the "com.mycompany.mypackage" part of the name matches the package directory into which you placed your properties files, and "Messages" is the filename prefix for the particular family of properties files supported by this MessageResources instance. Depending on your development process, you might find it convenient to store all message strings for an entire application in a single properties file family, or to have several families - in Struts, for example, there is a family of properties files for each Java package.

To access a message string with a particular Locale, execute a statement like this:

    Locale locale = ... select the locale to be used ...
    String message = messages.getMessage(locale, "hi");

In this case, the variable message will contain the message string corresponding to the key "hi", in the language that corresponds to the locale that was selected.

For an example of message formatting with replaceable parameters, assume that the message strings looked like this, instead (only the English version is shown - corresponding changes would be made in the other files):

    hi=Hello {0}

Now, you can personalize the retrieved message like this:

    Locale locale = ... select the locale to be used ...
    String name = "Joe";
    String message = messages.getMessage(locale, "hi", name);

and the marker "{0}" will have been replaced by the specified name (Joe), no matter which language is in use. See the JavaDoc API documentation for the java.text.MessageFormat class for more advanced uses of the parameter replacement mechanism.

Developing Your Own MessageResources Implementation

In the above example, we were using the default MessageResources implementation supplied by Struts, which uses property files to store the message strings. It is also possible to create customized mechanisms to retrieve messages (such as loading them on demand from a database). The steps required are as follows:

A code example that illustrates this technique is:

    MessageResourcesFactory.setFactoryClass("com.mycompany.mypkg.MyFactory");
    MessageResourcesFactory factory = MessageResourcesFactory.createFactory();
    MessageResources resources =
    factory.createResources("configuration information");

Once you have created your custom MessageResources instance, you utilize it to access message strings (with or without parameter replacement objects), exactly as we illustrated with the standard implementation in the previous section.

Using MessageResources With Struts

If your application uses the Struts controller servlet, you can optionally configure Struts to load an application-specific message resources instance for you, and make it available as a servlet context attribute (in JSP terms, an application-scope bean). This mechanism is managed by setting the following servlet initialization parameters in the web application deployment descriptor:

Struts provides several JSP custom tags that assume the existence of a java.util.Locale attribute in the user's session, under the key named by the constant string value of Action.LOCALE_KEY. Your own application logic can set this attribute at any time, or you can ask Struts to set it automatically (if not already set) based on the Accept-Language HTTP header included with the request. There are two mechanisms by which you request Struts to perform this service:

Overview   Package  Class  Use  Tree  Deprecated  Index  Help 
 PREV PACKAGE   NEXT PACKAGE FRAMES    NO FRAMES    
Copyright © 2000-2008 Apache Software Foundation. All Rights Reserved.