[PROPOSAL] The Commons

"The Commons"

Charter

(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 and a master index of reusable packages related to Jakarta products.

(1.5) interaction with other subprojects

(1.5.1) the sandbox

The subproject will host a CVS repository available to all Jakarta committers as a workplace for new packages or other projects. Before release to the public, code or documentation developed here must be sponsored by a Jakarta subproject. The sponsoring subproject(s) will distribute the code or documentation along with the rest of their codebase.

(1.5.2) the directory

The subproject will also catalog packages and other resources available to the public related to other Jakarta subprojects and ASF projects. This will be a dynamic catalog, like Bugzilla and Jyve, similar in functionality to download.com, cpan.org, or SourceForge.net. New entries may be added by Jakarta committers, developers, and users. Entries by developers and users will be approved by a committer before being made public.

(2) identify the initial source from which the subproject is to be populated

The initial packages would be based on existing ASF codebases, including those that provide services for DataSource/Database Pools, XML Configuration, Message Resources and i18n, JNDI and Naming, and Testing Suites. The initial committers have agreed to first create and maintain a Database Connection Pool package, along with related testing suites and subproject infrastructure.

(3) identify the initial Jakarta resources to be created

(3.1) mailing list(s)

jakarta-commons

(3.2) CVS repositories

jakarta-commons
jakarta-commons-sandbox

(3.3) Bugzilla

program - commons
components - Web site, Directory, dbcp

(3.4) Jyve FAQ (when available)

commons-general
commons-dbcp
commons-sandbox

(4) identify the initial set of committers

Morgan Delagrange
Ted Husted
Conor MacNeill
Geir Magnusson Jr.
Costin Manolache
Remy Maucherat
Craig R. McClanahan
Ignacio J. Ortega
Rodney Waldhoff
David Weinrich

Guidelines

is, has, will, shall, must - required.

may, should, are encouraged - optional but recommended.

The primary unit of reuse and release is the package.
The package library is not a framework but a collection of components designed to be used independently.
Each package must have a clearly defined purpose, scope, and API -- Do one thing well, and keep your contracts.
Each package is treated as a product in its own right.
1. Each package has its own status file, release schedule, version number, QA tests, documentation, mailing list, bug category, and individual JAR.
2. Each package must clearly specify any external dependencies, including any other Commons packages, and the earliest JDK version required.
  1. External dependencies on optional and third-party codebases should be minimized.
  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".
3. Each package must maintain a list of its active committers in its status file.
The packages should use a standard scheme for versioning, QA tests, and directory layouts, and a common format for documentation and Ant build files.
The packages should fit within a unified package hierarchy.
In general, packages should provide an interface and one or more implementations of that interface, or implement another interface already in use.
- The packages should have boring functional names. Implementations may choose more "exciting" designations.
Packages are encouraged to either use JavaBeans as core objects, a JavaBean-style API, or to provide an optional JavaBean wrapper.
External configuration files are discouraged, but if required, XML format files are preferred for configuration options.
Each package will be hosted on its own page on the subproject Web site, and will also be indexed in a master directory.
The subproject directory will also provide a distribution mechanism, or catalog of packages and related resources.
The subproject will also host a top-level "general" mailing list in addition to any lists for specific packages.
The subproject will also provide a single JAR of all stable package releases. It may also provide a second JAR with a subset of only JDK 1.1 compatible releases. A gump of nightly builds will also be provided.
Volunteers become committers to this subproject in the same way they are entered to any Jakarta subproject. Being a committer in another Jakarta subproject is not a prerequisite.
Each committer has karma to all the packages, but committers are required to add their name to a package's status file before their first commit to that package.
The committers shall elect a committee of three committers to provide general oversight, in the style of the Jakarta PMC.
New packages may be proposed to the Jakarta Commons mailing list. To be accepted, a package proposal must receive a positive super-majority vote of the subproject committers. Proposals are to identify the rationale for the package, its scope, its interaction with other packages and products, the Commons resources, if any, to be created, the initial source from which the package is to be created, and the initial set of committers.
1. The whole number of positive votes needed for a super majority is calculated by dividing the total number of active subproject committers by four, multiplying by three, and rounding to the nearest whole number (>= .5 rounds up).
It is expected that the scope of packages may sometimes overlap.
Anyone may propose a new package to the Commons, and list themselves as the initial committers for the package. The vote on the proposal is then also a vote to enter new committers to the subproject as needed.
A CVS repository will be available to all Jakarta committers as a workplace for new packages or other projects.. Before release to the public, code or documentation developed here must be sponsored by Jakarta subproject. The sponsoring subproject(s) will distribute the code or documentation along with the rest of their codebase.
The subproject catalog will also list packages and resources available to the public related to other Jakarta subprojects and ASF projects.
As a Jakarta subproject, the Commons adopts all other guidelines and procedures of Jakarta and the Apache Software Foundation, as they may be amended from time to time.

Example Package Proposal

Proposal for Database Connection Pool Package

(0) rationale

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

be configured via an external file (e.g. Turbine), and

expose its status, exceptions, or other events to an external logging system (e.g. Log4)..

(2) identify the initial source for the package

The initial codebase was contributed by Rodney Waldhorf from a working project and can be distributed under the Apache license. The source is available as dbpool.jar from < http://www.webappcabaret.com/rwald/dbcp/ >

(2.1) identify the base name for the package

org.apache.commons.dbcp

(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.

(3.3) Bugzilla

The package should be listed as a component of under the Jakarta-Commons Bugzilla entry.

(3.4) Jyve FAQ (when available)

commons-dbcp

(4) identify the initial set of committers to be listed in the Status File.

Morgan Delagrange
Geir Magnusson Jr.
Craig R. McClanahan
Rodney Waldhoff
David Weinrich

FAQ

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 Jakarta 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, and just list it in the Commons directory where other developers and users can find it.

What will be listed in the Commons directory?

Any package or other resource that is related to a Jakarta product may be entered into the directory. This will be a dynamic application, like Bugzilla or Jyve. Users and developers can complete an online form with their entry, which will be reviewed by a Commons committer before public release. Jakarta committers may have a higher level of access so that their entry goes online without review.

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 Jakarta 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.

Resources

Jakarta Guidelines
- http://jakarta.apache.org/site/guidelines.html
Code Conventions for the Java Programming Language
- http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html
Javadoc Tool Home Page
- http://java.sun.com/j2se/javadoc/index.html
Elements of Java Style - 6. Packaging Conventions
- http://www.ambysoft.com/elementsJavaStyle.html

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.

The Common Reuse Principle - A package consists of classes you reuse together. If you use one of the classes in the package, you use all of them.

The Common Closure Principle - A package consists of classes, all closed against the same kind of changes. A change that affects the package affects all the classes in that package.

The Reuse/Release Equivalence Principle - The unit of reuse is the unit of release. Effective reuse requires tracking of releases from a change control system. The package is the effective unit of reuse and release.

The Acyclic Dependencies Principle - The dependency structure between packages must be a direct acyclic graph; there must be no cycles in the dependency structure.

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.

The Stable Dependencies Principle - The dependencies between packages should be orientated in the direction of increasing stability. A package should only depend on packages more stable than it is.

107. Maximize abstraction to maximize stability.

The Stable Abstractions Principle - The stability exhibited by a package is directly proportional to its level of abstraction. The more abstract a package is, the most stable it tends to be. The more concrete a package is, the more unstable it tends to be.

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.