<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="xdoc.xsl"?>
<!--
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</title>
  <author email="dev@commons.apache.org">Commons Documentation Team</author>
 </properties>
<body>
<!-- ================================================== -->
<section name="Proposal for Primitives Component">
<!-- ================================================== -->
<subsection name="(0) Rationale">
<p>
The Java language has a fundamental distinction between Object and primitive
types. The JDK provides many method for manipulating and working with
Objects. However, there is relatively little support for working with
primitive types.
</p>
<p>
One key example is the Java Collection Framework. This defines a well-known
and widely used API for object-based collections. The framework requires
each primitive to be wrapped in an object, such as Integer, before they can
be used in collections. This has a memory and performance overhead.
</p>
<p>
The primitives component will provide an API for collections and utilities
based on primitives. Wrappers and adaptors will be provided for integration
with object-based APIs.
</p>
</subsection>
<!-- ================================================== -->
<subsection name="(1) Scope of the Package">
<p>
The package will create and maintain a set of collections and utilities for
primitive types, distributed under the ASF license.
</p>
</subsection>
<!-- ================================================== -->
<subsection name="(1.5) Interaction With Other Packages">
<p>
<em>Primitives</em> relies only on standard JDK 1.2 (or later) APIs for
production deployment.  It utilizes the JUnit unit testing framework for
developing and executing unit tests, but this is of interest only to
developers of the component.
</p>
<p>
No external configuration files are utilized.
</p>
</subsection>
<!-- ================================================== -->
<subsection name="(2) Initial Source of the Package">
<p>
The initial codebase was harvested from code in the Commons Collections CVS.
</p>
<p>
The proposed package name for the new component is
<code>org.apache.commons.primitives</code>.
</p>
</subsection>
<!-- ================================================== -->
<subsection name="(3)  Required Jakarta-Commons Resources">
<ul>
<li>CVS Repository - New directory <code>primitives</code> in the
    <code>jakarta-commons</code> CVS repository.</li>
<li>Mailing List - Discussions will take place on the general
    <em>dev@commons.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
    [primitives].</li>
<li>Bugzilla - New component "Primitives" under the "Commons" product
    category, with appropriate version identifiers as needed.</li>
<li>Jyve FAQ - New category "commons-primitives" (when available).</li>
</ul>
</subsection>
<!-- ================================================== -->
<subsection name="(4) Initial Committers">
<ul>
   <li>Rodney Waldhoff</li>
   <li>Stephen Colebourne</li>
</ul>
</subsection>
<!-- ================================================== -->
</section>
<!-- ================================================== -->
</body>
</document>
