The following charter for Jakarta Commons was approved by the Jakarta Project Management Committee (PMC) on May 19, 2004. The original version, 1.0, was approved by the PMC on March 19, 2001. On June 20, 2007, the Apache Board voted to promote the Jakarta Commons subproject to Apache Commons.(0) rationale
Apache-Java and Jakarta originally hosted product-based subprojects, consisting of one major deliverable. The Java language however is package-based, and most of these products have many useful utilities. Some products are beginning to break these out so that they can be used independently. A Jakarta subproject to solely create and maintain independent packages is proposed to accelerate and guide this process.(1) scope of the subproject
The subproject shall create and maintain packages written in the Java language, intended for use in server-related development, and designed to be used independently of any larger product or framework. Each package will be managed in the same manner as a larger Jakarta product. To further this goal, the subproject shall also host a workplace for Jakarta committers.
(1.1) the sandbox
The subproject will host a CVS repository available to all Apache committers as a workplace for new packages or other projects.(2) identify the initial set of committers
Geir Magnusson Jr.
Craig R. McClanahan
Ignacio J. Ortega
Many Jakarta products support interaction with a relational database. Creating a new connection for each user can be time consuming (often requiring multiple seconds of clock time), in order to perform a database transaction that might take milliseconds. Opening a connection per user can be unfeasible in a publicly-hosted Internet application where the number of simultaneous users can be be very large. Accordingly, developers often wish to share a "pool" of open connections between all of the application's current users. The number of users actually performing a request at any given time is usually a very small percentage of the total number of active users, and during request processing is the only time that a database connection is required. The application itself logs into the DBMS, and a handles any user account issues internally.
There are several Database Connection Pools already available, both within Jakarta products and elsewhere. A Commons package would give committers an opportunity to coordinate their efforts to create and maintain a efficient, feature-rich package under the ASF license.
(1) scope of the package
The package shall create and maintain a database connection pool package written in the Java language to be distributed under the ASF license. The package shall be available as a pseudo-JDBC driver and via a DataSource interface. The package shall also support multiple logins to multiple database systems, reclamation of stale or dead connections, testing for valid connections, PreparedStatement pooling, and other features.
(1.5) interaction with other packages
Subclasses of the package should also be able to :
(2) identify the initial source for the package
The initial codebase was contributed by Rodney Waldhoff from a working project and can be distributed under the Apache license. The source is available as dbpool.jar from ...
(2.1) identify the base name for the package
(2.2) identify the coding conventions for this package
The code uses the conventions from the Jakarta Turbine package.
(3) identify any Jakarta-Commons resources to be created
(3.1) mailing list
Until traffic justifies, the package will use the Jakarta-Commons list for communications.
(3.2) CVS repositories
For the time being, the package will use a root branch of the Jakarta-Commons CVS.
The package should be listed as a component of under the Jakarta-Commons Bugzilla entry.
(4) identify the initial set of committers to be listed in the Status File.
Geir Magnusson Jr.
Craig R. McClanahan
What are the actual requirements for a Commons package?
Most of the guidelines are advisory and meant to describe 'best practices'. The hard requirements boil down to 'clearly declare your API and dependencies'. Or, taken from the guidelines:
3. Each package must have a clearly defined purpose, scope, and API -- Do one thing well, and keep your contracts.
4.1. Each package must clearly specify any external dependencies, including any other Commons packages, and the earliest JDK version required.
4.1.2. All necessary dependencies must be recorded in the MANIFEST.MF file of the package JAR, in the manner recommended in the JDK 1.3 documentation describing 'system extensions'.
Of course, the other requirement is that the authors submit a proposal to the Commons committers for approval.
Why not have a separate CVS tree for each package?
It's possible that we may, but the decision should be deferred until we have more packages to manage.
For now, we just ask that a Commons committer enter their name in the Status File of a package before making their first commit/
Should other Jakarta subprojects move their utility packages to the Commons?
They are welcome to do so. If they would like to experiment with refactoring a package outside their own CVS tree, they can setup shop in the Commons sandbox. Any Apache committer is entitled to write access to this CVS repository upon request. They could then decide to propose the package to the Commons, and thereby become committers to the Commons, or to move it back to their own CVS.
Why not just enroll all the Jakarta committers in the Commons?
If Jakarta adopts an open-door policy for all its subprojects, then of course the Commons will follow suit.
We do have an open-door policy for the sandbox CVS (jakarta-commons-sandbox). Any Apache committer is entitled to write access to the sandbox upon request, no vote required, no questions asked. Just subscribe to jakarta-commons-sandbox, and request authorization.
Why not just do this within Avalon, or another existing subproject?
Avalon is a large subproject that is being refactored. It's possible that the charter of one of the ensuing pieces may overlap with the Commons.
The focus of the Commons is squarely and solely on developing packages that can be reused by multiple products, both within and without Jakarta. To garner the interest of committers, it is important that the Commons and each of its packages be perceived as an independent entity. Since this is a volunteer meritocracy, the perception of committers is vital. No subproject can succeed without the earnest support of individual committers.
It is our firm position that the Commons will attract more committers on its own than if it were aligned with any existing subproject. What "committers will commit to" has to be the prime consideration. Darwin has been trying to tell us that; it's time we listened.
From the Elements of Java Style - 6. Packaging Conventions
Rules and Principles only - commentary omitted (buy the book!)
104. Place types that are commonly used, changed, and released together, or mutually dependant on each other, into the same package.
105. Isolate volatile classes and interfaces in separate packages.
106. Avoid making packages that are difficult to change dependent on packages that are easy to change.
107. Maximize abstraction to maximize stability.
108. Capture high-level design and architecture as stable abstractions organized into stable packages.
For more about these rules, and 103 others - get the book - highly recommended.