You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by cr...@apache.org on 2003/01/07 02:59:34 UTC
cvs commit: jakarta-commons-sandbox/resources/src/java overview.html
craigmcc 2003/01/06 17:59:34
Modified: resources build.xml
Added: resources/src/java overview.html
Removed: resources/src/doc contents.xml
resources/src/doc/stylesheets package.xsl
Log:
Revise the commons-resources documentation to be on the overview page
(so it's visible on the front page of the Javadocs), and bring it up to
date with the refactored functionality.
Revision Changes Path
1.20 +5 -11 jakarta-commons-sandbox/resources/build.xml
Index: build.xml
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/resources/build.xml,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -r1.19 -r1.20
--- build.xml 6 Jan 2003 21:09:51 -0000 1.19
+++ build.xml 7 Jan 2003 01:59:33 -0000 1.20
@@ -84,7 +84,7 @@
<property name="component.package" value="org.apache.commons.resources"/>
<!-- The title of this component -->
- <property name="component.title" value="Resources Facilities"/>
+ <property name="component.title" value="Application Resources Facilities"/>
<!-- The current version number of this component -->
<property name="component.version" value="0.1-dev"/>
@@ -233,7 +233,6 @@
description="Clean build and distribution directories">
<delete dir="${build.home}"/>
<delete dir="${dist.home}"/>
- <delete failonerror="false" file="${source.home}/org/apache/commons/resources/package.html" />
</target>
@@ -241,7 +240,7 @@
description="Clean and compile all components"/>
- <target name="javadoc" depends="docs"
+ <target name="javadoc" depends="compile"
description="Create component Javadoc documentation">
<mkdir dir="${dist.home}"/>
<mkdir dir="${dist.home}/docs"/>
@@ -250,19 +249,14 @@
destdir="${dist.home}/docs/api"
packagenames="org.apache.commons.*"
author="true"
+ overview="src/java/overview.html"
private="true"
version="true"
doctitle="<h1>${component.title}</h1>"
windowtitle="${component.title} (Version ${component.version})"
- bottom="Copyright (c) 2001 - Apache Software Foundation">
+ bottom="Copyright (c) 2002-2003 - Apache Software Foundation">
<classpath refid="compile.classpath"/>
</javadoc>
- </target>
-
- <target name="docs" depends="compile">
- <delete failonerror="false" file="${source.home}/org/apache/commons/resources/package.html" />
- <style in="${doc.home}/contents.xml" out="${source.home}/org/apache/commons/resources/package.html"
- style="${doc.home}/stylesheets/package.xsl" />
</target>
1.1 jakarta-commons-sandbox/resources/src/java/overview.html
Index: overview.html
===================================================================
<html>
<head>
<title>The Jakarta Commons Resources Package</title>
</head>
<body bgcolor="white">
<p>The Jakarta Commons Resources Package.</p>
<div align="center">
[<a href="#overview">Overview</a>]
[<a href="#dependencies">Dependencies</a>]
[<a href="#resources">Using Resources</a>]
[<a href="#messages">Using Messages</a>]
[<a href="#implementing">Implementing Resources</a>]
</div>
<a name="overview"></a>
<h3>Overview</h3>
<p>The <em>Jakarta Commons Resources Package</em> provides a general
framework for retrieving localized application resources (based on either an
explicitly specified <code>java.util.Locale</code> instance, or the system
default <code>Locale</code>). In addition, since a very common use case for
localized resources is to prepare prompt and error messages for a user
interface, convenient mechanisms are provided to retrieve a localized message
string (suitable for use with the <code>java.text.MessageFormat</code> class)
plus substitution parameters, and prepare a localized and customized message
string.</p>
<p>The Commons Resources package is organized around the following fundamental
interfaces and classes (in the <code>org.apache.commons.resources</code>
package):</p>
<ul>
<li><a href="org/apache/commons/resources/Resources.html">Resources</a> -
Abstract representation of a set of internationalized resources, which
can be retrieved by specifying a <code>resource key</code>, and optional
<code>java.util.Locale</code> and <code>java.util.TimeZone</code>
parameters.</li>
<li><a href="org/apache/commons/resources/ResourcesFactory.html">
ResourcesFactory</a> - Factory pattern interface for creating
<code>Resources</code> instances with a specified logical name,
configured by a parameter String whose meaning is defined by the
particular <code>ResourcesFactory</code> implementation you are
using.</li>
<li><a href="org/apache/commons/resources/Messages.html">Messages</a> -
Wrapper for use around any <code>Resources</code> instance that provides
message formatting services (including parameter substitution), as
long as the resources are legal arguments to the <code>format()</code>
method of the <code>java.text.MessageFormat</code> class.</li>
</ul>
<p>The following standard <code>Resources</code> implementations, with
corresponding <code>ResourcesFactory</code> implementations, are
included (in the <code>org.apache.commons.resources.impl</code> package):</p>
<ul>
<li><a href="org/apache/commons/resources/impl/PropertyResources.html">
PropertyResources</a> - Resources are defined in a family of properties
files that share a common base URL, a Locale-based suffix (following the
same rules as for <code>java.util.ResourceBundle</code>), and
a <code>.properties</code> extension.</li>
<li><a href="org/apache/commons/resources/impl/ResourceBundleResources.html">
ResourceBundleResources</a> - Resources are defined in a family of
<code>ResourceBundle</code> implementation classes (or properties
files) loaded from the classpath of the application.</li>
<li><a href="org/apache/commons/resources/impl/XMLResources.html">
XMLResources</a> - Resources are defined in a family of XML documents
that share a common base URL, a Locale-based suffix (following the
same rules as for <code>java.util.ResourceBundle</code>), and
a <code>.xml</code> extension.</li>
</ul>
<a name="dependencies"></a>
<h3>Dependencies</h3>
<p>Applications utilizing the <code>commons-resources</code> package will have
the following mandatory and conditional dependencies on other packages,
as follows:</p>
<ul>
<li><strong>commons-beanutils.jar</strong> (Version 1.5 or later) -
Only required if you are using <code>XMLResources</code>.</li>
<li><strong>commons-collections.jar</strong> (Version 2.1 or later) -
Only required if you are using <code>XMLResources</code>.</li>
<li><strong>commons-digester.jar</strong> (Version 1.3 or later) -
Only required if you are using <code>XMLResources</code>.</li>
<li><strong>commons-discovery.jar</strong> (Version 1.0 or later) -
Only required if you are using <code>ResourcesFactoryFinder</code>.</li>
<li><strong>commons-logging.jar</strong> (Version 1.0.2 or later) -
Required by all standard <code>Resources</code> implementations.</li>
<li><strong>XML Parser</strong> (Version JAXP/1.1 or later) -
Only required if you are using <code>XMLResources</code>.</li>
</ul>
<a name="resources"></a>
<h3>Using Resources</h3>
<p>Using the Commons Resources package to retrieve localized resources is a
simple three-step process:</p>
<ul>
<li>Acquire a <code>ResourcesFactory</code> instance for the type
of <code>Resources</code> implementation you wish to use.</li>
<li>Acquire a <code>Resources</code> instance of the desired type
by calling the <code>getResources()</code> method of
the <code>ResourcesFactory</code> acquired in the previous step.</li>
<li>Retrieve a localized value from the <code>Resources</code> instance,
in the desired format, by specifying a resource identifier, an
optional <code>Locale</code>, and an optional <code>TimeZone</code>
parameter to one of the content retrieval methods.</li>
</ul>
<p>These steps are illustrated in more detail below.</p>
<h5>Acquiring a ResourcesFactory Instance</h5>
<p>The simplest way to acquire a <code>ResourcesFactory</code> instance is to
simply construct a new one, since <code>ResourcesFactory</code> implementations
are required to provide a public zeo-arguments constructor:</p>
<pre>
ResourcesFactory factory = new XMLResourcesFactory();
</pre>
<p>However, doing this hard codes into your application the knowledge of which
particular <code>ResourcesFactory</code> implementation will be used. It is
also possible to defer this decision until runtime, where a check for any
available implementation available on the class path can be performed:
<pre>
ResourcesFactory factory =
ResourcesFactoryFinder.getResourcesFactory();
</pre>
<p>Using this technique allows you to select a particular implementation at
runtime based on the rules defined by the
<a href="http://jakarta.apache.org/commons/discovery/">commons-discovery</a>
package, through the use of either a system property or including a JAR file
(with a <code>ResourcesFactory</code> implementation included) that includes
a <code>META-INF/services/org.apache.commons.resources.ResourcesFactory</code>
file that specifies the actual implementation class to be used.</p>
<h5>Acquiring a Resources Instance</h5>
<p>Once you have a <code>ResourcesFactory</code> instance, use the
<code>getResources()</code> method to retrieve a <code>Resources</code>
instance for your use. You will specify either one or two parameters to
this method:</p>
<ul>
<li><strong>name</strong> - Logical name of the <code>Resources</code>
instance you wish to utilize. Most <code>ResourcesFactory</code>
implementations (including all of the standard ones) will cache
previously created <code>Resources</code> instance by name, so that
repeated requests for the same name will return the same instance.</li>
<li><strong>config</strong> - Configuration parameter string, whose meaning
is determined by the specific <code>Resources</code> implementation class
that is being utilized. For example, the configuration parameter for
an instance of <code>XMLResources</code> contains the base URL for the
family of XML documents that comprise the name/value mappings (one
XML document per Locale).</li>
</ul>
<pre>
Resources resources = factory.getResources
("messages", "http://localhost/mymessages");
</pre>
<h5>Calling a Content Retrieval Method</h5>
<p>Now that you have a <code>Resources</code> instance available, you can
utilize its content retrieval methods to acquire a localized resource value
for the specified resource identifier. The actual content of the resource
value can be retrieved in different formats (byte array, input stream, object,
reader, or String), but the most common use of resources is for strings.</p>
<pre>
Locale locale =
... locale to use for localization ...;
String message =
resources.getString("invalid.login", locale, null);
</pre>
<a name="messages"></a>
<h3>Using Messages</h3>
<h5>Parameterized Message Strings</h5>
<p>The most common use for localized resources is to support
internationalization of prompts and messages when you create the user interface
for an application intended for use by an international audience. Beyond the
basic capability of looking up the localized strings (which is already
supported by the <code>Resources</code> implementations described above),
it would also be very useful to treat the retrieved message string as a
format argument to an instance of <code>java.text.MessageFormat</code>,
complete with substitution parameters. The Commons Resources package
includes a class
(<a href="org/apache/commons/resources/Messages.html">Messages</a>) that
supports these extra features.</p>
<p>A typical message resource will use substitution patterns to
identify where the replacement text should go. Consider a properties file
(for a <code>PropertyResources</code> or <code>ResourceBundleResources</code>
instance) with the following line:
<pre>
invalid.value=The value you entered ({0}) is not valid
</pre>
<p>where the <code>{0}</code> will be replaced by the first of the replacement
values that you include. See the Javadocs for
<code>java.text.MessageFormat</code> for a description of all the possible
syntaxes that are supported.</p>
<p>You can use a <code>Messages</code> instance as a wrapper around any
<code>Resources</code> instance that you have previously acquired (decorator
pattern):</p>
<pre>
String input = ...; // Input value from user
Locale locale = ...; // User's locale
Resources resources = ...; // Desired resources
Messages messages = new Messages(resources);
String message =
messages.getMessage("invalid.value", locale, input);
</pre>
<p>which, if the input string has a value "ABC" will result in the following
message value:</p>
<pre>
The value you entered (ABC) is not valid
</pre>
<h5>Shortcut for Application Classes</h5>
<p>In addition to user interfaces, a common requirement for internationalized
applications is to support the localization of log messages, and exception
descriptions, that are rendered by an application. To support these
requirements, the <code>Messages</code> class includes additional shortcut
features that make it easy to meet them. Consider the following class:</p>
<pre>
package com.mycompany.mypackage;
public class MyClass {
private static Messages messages =
Messages.getMessages("com.mycompany.mypackage");
public class do() {
try {
...
} catch (Exception e) {
log.error(messages.getMessage("got.exception"), e);
}
}
}
</pre>
<p>The <code>getMessages()</code> method acquires an instance of
<code>ResourceBundleResources</code> for a resource bundle named
<code>LocalStrings</code> in the package you specify (normally the
package containing this class) on the class path for your application.
Most people will find it convenient to specify the actual resources
with property files that are included in the JAR file (or directory)
that your application is running from. Thus, an application that
includes the above class might have the following files in its
JAR file (or application directory):</p>
<ul>
<li><code>com/mycompany/mypackage/LocalStrings.properties</code> -
Default resources (if not overridden by more specific ones)</li>
<li><code>com/mycompany/mypackage/LocalStrings_en.properties</code> -
Resources for English users.</li>
<li><code>com/mycompany/mypackage/LocalStrings_en_US.properties</code> -
Resources for English users in the United States.</li>
</ul>
<p>See the Javadocs for <code>java.util.ResourceBundle</code> and
<code>java.util.PropertyResourceBundle</code> for more information on the
mapping of property file names to locales.</p>
<a name="implementing"></a>
<h3>Implementing Resources</h3>
<p>It is straightforward to create your own custom implementations of
<code>ResourcesFactory</code> and <code>Resources</code>. The following
information describes the recommended approach.</p>
<p>First, create a new class that implements the <code>ResourcesFactory</code>
interface, or (recommended) subclasses the provided abstract base class
(<a href="org/apache/commons/resources/impl/ResourcesFactoryBase.html">
ResourcesFactoryBase</a>). The provided base class implements the common
functionality of most <code>ResourcesFactory</code> implementations (such
as caching created <code>Resources</code> instances by logical name. It
only requires you to implement the <code>createResources()</code> method to
construct a <code>Resources</code> instance (given the specified name
and configuration parameter string). Be sure that your implementation
calls the <code>init()</code> method on the <code>Resources</code> instance
that is created before returning it.</p>
<p>Next, create a new class that implements <code>Resources</code> or
(recommended) subclasses one of the provided abstract base classes. You have
a choice of two abstract base classes to start from:</p>
<ul>
<li><a href="org/apache/commons/resources/impl/ResourcesBase.html">
ResourcesBase</a> - Provides default implementation of all the
content retrieval methods except <code>getObject()</code>, which
must be implemented by the concrete subclass.</li>
<li><a href="org/apache/commons/resources/impl/CollectionResourcesBase.html">
CollectionResourcesBase</a> - Many <code>Resources</code> implementations
(including the standard <code>PropertyResources</code> and
<code>XMLResources</code> implementations) share a "family of related
files with a common base URL" design paradigm, and can also choose to
represent the name/value mappings for each locale as an instance of
<code>java.util.Map</code>. In addition, this class assumes that
resources for a particular <code>Locale</code> can be inherited from
more general locales, using the algorithms described in the Javadocs
for <code>java.util.ResourceBundle</code>.
The only method that must be implemented
by a concrete subclass is <code>getLocaleMap(Locale)</code>, which will
be called only once per Locale.</li>
</ul>
<p>If you wish to utilize your custom implementation in an application
environment that uses the <code>ResourcesFactoryFinder</code> class to
discover the desired implementation at runtime, you should also package
your <code>ResourcesFactory</code> and <code>Resources</code> implementation
classes (plus any additional support classes that they need) into a JAR file
that includes a services identifier file named
<code>META-INF/services/org.apache.commons.resources.ResourcesFactory</code>
whose first line contains the fully qualified Java class name of your
<code>ResourcesFactory</code> implementation class. See the documentation
for the <a href="http://jakarta.apache.org/commons/discovery/">Commons
Discovery</a> package for more information about automatic service
discovery.</p>
</body>
</html>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>