org.apache.struts.util.package-info Maven / Gradle / Ivy
/*
* $Id$
*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
/**
* The Utilities package provides a variety of families of classes,
* to solve problems that are commonly encountered in building web applications.
*
*
*
*
*
*
*
*
*
* 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 - A small set of utility beans useful
* for
* encapsulating form elements.
* - Servlet Utilities - A set of classes
* useful
* for working with servlet-related classes.
* - Message Resources - A family of classes
* that
* features access to internationalized message strings based on a
* message
* key coupled with a
java.util.Locale object representing a
* particular user's preferred language.
*
*
*
*
*
*
* 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 {@code RequestUtils} is a general purpose utility methods
* related to processing a servlet request. The {@code ResponseUtils}
* is a general purpose utility methods related to generating a servlet
* response. The {@code ServletContextWriter} is a PrintWriter
* implementation that uses the logging facilities of a
* {@code jakarta.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:
*
* - Internationalization Info - General information on Java's
* standard
* support for internationalized applications can be found at
*
<$JAVA_HOME/docs/guide/internat/index.html>.
* The "Internationalization Overview" section includes useful
* information
* about Locales, localized resources, message formatting, and other
* relevant topics.
* - Internationalization Tutorial - The Java Language Tutorial
* has a
* comprehensive trail covering internationalization, available at:
*
* https://docs.oracle.com/javase/tutorial/i18n/index.html.
* - Javadoc APIs - You will want to consult the Javadoc API
* documentation for the following standard Java classes:
*
* java.text.MessageFormat
* java.util.ResourceBundle
* java.util.PropertyResourceBundle
* java.util.Properties - See the documentation for
* the
* load() method for the valid syntax of properties
* files
* that you prepare.
*
*
* 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:
*
* - Create a customized subclass of
*
org.apache.struts.util.MessageResources that implements
* message lookup operations as you require.
* - Create a customized subclass of
*
org.apache.struts.util.MessageResourcesFactory that will
* create an instance of your custom MessageResources class
* when the createResources method is called. Note that the
* "config" argument to this method can be used to select families of
* messages in any manner appropriate to your needs - you are not
* required
* to emulate the "fully qualified Java class name" approach that is used
* by the standard PropertyMessageResourcesFactory class.
*
* - Tell the
MessageResourcesFactory class the name of the
* customized MessageResourcesFactory implementation to use
* when creating new factory instances.
* - Create a new factory instance.
* - Ask the new factory instance to create a
MessageResources
* instance for you.
*
*
* 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:
*
*
* - application - The configuration string that will be
* passed to the
createResources() method of the message
* resources factory, in order to identify the family of resources to be
* supported. If you use the standard message resources factory, this
* must
* be the base fully qualified name of the property resources files used
* to contain these messages, as illustrated above.
* - factory - Fully qualified Java class name of the
*
MessageResourcesFactory to be used. By default, the
* standard
* implementation provided by Struts
* (org.apache.struts.util.PropertyMessageResourcesFactory)
* will be used.
*
*
* 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:
*
* - To have this service performed on every request submitted to the
* controller
* servlet, set the servlet initialization parameter
locale
* to
* the value true in the application deployment descriptor.
*
* - To have this service performed by a JSP page when it is accessed
* directly
* by a user, utilize a
<form:html ... locale="true" ...
* />
* tag at the top of each page.
*
*/
package org.apache.struts.util;