<?xml version="1.0"?>
<!--
    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.
-->
<document>
<properties>
<title>Proposal for Resources Package</title>
</properties>
<body>


<section name="Proposal for Resources Package">



<subsection name="(0) Rationale">

<p>Many Java applications must support internationalization (i18n) of message
strings presented as part of the user interface, or in messages written to
log files.  The standard Java APIs offer the
<code>java.util.ResourceBundle</code> family of classes to support this
requirement; however, these classes have the following limitations that
reduce their usefulness:</p>
<ul>
<li>The classes assume that all messages should be presented based on
    a single Locale, while many applications require support for different
    Locales for each current application user.</li>
<li>The <code>ResourceBundle</code> implementation classes do not implement
    the <code>java.io.Serializable</code> interface, which is required in
    some operational environments.</li>
</ul>

<p>The classes in the proposed <code>Resources</code> package offer solutions
to these two problems, and provide a framework for providing customized
<code>MessageResources</code> implementations that can access resource strings
from any desired static or dynamically updated collection.</p>

</subsection>
<subsection name="(1) Scope of the Package">

<p>The proposal defines a miniature resources framework consisting of two
abstract classes:</p>
<ul>
<li><strong>MessageResources</strong> - Base class for a collection of
    message strings, keyed by a combination of a <code>java.util.Locale</code>
    and a message key.</li>
<li><strong>MessageResourcesFactory</strong> - Factory class to configure and
    instantiate an appropriate <code>MessageResources</code> instance.</li>
</ul>

<p>An initial (and default) implementation accesses the required message
strings from Properties files accessed via <code>Class.getResource()</code>.
These files are named with a base name, plus extensions identifying the
Locale of the contained message strings, in a manner identical to the
<code>java.util.PropertyResourceBundle</code> class of the standard APIs.</p>


</subsection>
<subsection name="(1.5) Interaction With Other Packages">

<p><em>Resource</em> relies on the standard JDK 1.2 (or later) APIs, plus
the <code>Collections</code> package from Apache Commons.</p>

<p>No external configuration files are utilized.</p>


</subsection>
<subsection name="(2) Initial Source of the Package">

<p>The four original Java classes (<code>MessageResources</code>,
<code>MessageResourcesFactory</code>, <code>PropertyMessageResources</code>,
and <code>PropertyMessageResourcesFactory</code>) are an integral
part of the <a href="http://struts.apache.org">Struts Framework</a>.
However, they have no dependencies on other aspects of Struts.
Once accepted and released as a Apache Commons component, Struts will
be modified to use the Commons version of these classes, and its internal
versions will be deprecated.</p>

<p>The proposed package name for the new component is
<code>org.apache.commons.resources</code>.</p>


</subsection>
<subsection name="(3)  Required Jakarta-Commons Resources">

<ul>
<li>CVS Repository - New directory <code>resources</code> in the
    <code>jakarta-commons</code> CVS repository.  All initial committers
    are already committers on <code>jakarta-commons</code>, so no
    additional user setups are required.</li>
<li>Mailing List - Discussions will take place on the general
    <em>jakarta-commons@jakarta.apache.org</em> mailing list.  To help
    list subscribers identify messages of interest, it is suggested that
    the message subject of messages about this component be prefixed with
    [Resources].</li>
<li>Bugzilla - New component "Resources" under the "Commons" product
    category, with appropriate version identifiers as needed.</li>
<li>Jyve FAQ - New category "commons-resources" (when available).</li>
</ul>


</subsection>
<subsection name="(4) Initial Committers">

<p>The initial committers on the Resources component shall be Craig
McClanahan, Michael Schachter, Jason van Zyl, and Daniel Rall.</p>


</subsection>
</section>
</body>
</document>
