Status

The charter for the DB Commons subproject of the Apache DB project was approved by the Apache DB PMC in February of 2003.

Charter

Guidelines

Terminology:

• The expressions "IS", "HAS", "WILL", and "MUST" indicate guidelines that are required.
• The expressions "may", "should", and "are encouraged" indicate guidelines that are optional but recommended.

Guidelines:

1. The primary unit of reuse IS the primary unit of release. Within these guidelines, we refer to this unit as a "component".
2. The subproject IS a collection of components designed to be used independently, not a framework.
3. Each component MUST have a clearly defined purpose, scope, and API -- Do one thing well, and keep your contracts.
4. Each component IS treated as a product in its own right.
   1. Each component HAS its own status file, release schedule, version number, QA tests, documentation, defect category, and distribution.
   2. Each component MUST clearly specify any external dependencies, including any other Commons components and external libraries.
   3. Each component MUST maintain a list of its active committers in its status file or other resource as determined by the DB Commons committers.
5. External dependencies on optional and third-party codebases should be minimized.
6. The components should use a standard scheme for versioning, QA tests, and directory layouts, and a common format for documentation and build scripts.
7. Where appropriate, the components should fit within a unified package or namespace hierarchy.
8. In general, components should provide an interface and one or more implementations of that interface, or implement another interface already in use.
9. Each component WILL be hosted on its own directory on the subproject Web site, and WILL also be indexed in a master directory or listing.
10. The subproject WILL provide a catalog of components and related resources.
11. The subproject WILL also host a top-level 'general' mailing list in addition to any lists for specific components.
12. The subproject may provide distribution "bundles" that combine several individual components into a single artifact.
13. Volunteers MUST become committers to the DB Commons subproject in the same way they are entered to any Apache DB subproject. Being a committer in another DB subproject is not a prerequisite.
14. Each committer HAS karma to all the components, but committers are required to add their name to a package's status file before their first commit to that component.
15. New components MUST be proposed to the DB Commons developer mailing list. To be accepted, a component proposal MUST receive majority approval of the subproject committers. Proposals MUST identify the rationale for the component, its scope, its interaction with other components and products, the Commons resources, if any, to be created, the initial source from which the component is to be created (together with a statement that this code may be distributed under an ASF license), the coding conventions used for the component (if any) and the initial set of committers. (As stated in the Apache DB guidelines, an action requiring majority approval must receive at least 3 binding +1 votes and more +1 votes than -1 votes.)
16. It is expected that the scope of components may sometimes overlap.
17. Anyone may propose a new component to the Commons, and list themselves as the initial committers. The vote on the proposal is then also a vote to enter new committers to the subproject as needed.
18. A CVS repository WILL be available to all Apache DB committers as a workplace for new components or other projects. Before release to the public, code or documentation developed here MUST be sponsored by (and moved to) a DB subproject (including but not limited to the DB Commons subproject), or to the oversight of some other Apache PMC.
19. Each Commons component should use an internally consistent and documented coding style. When the source code for a component originates in a pre-existing code base outside of Commons, the coding style of that code base may be retained at the discretion of the component committers.
20. Component developers are strongly encouraged to adhere to the following design principles:

    The Release/Reuse Equivalence Principle (REP)

    The unit of release should be equivalent to the unit of reuse. (Also see the CRP).

    The Common Closure Principle (CCP)

    The artifacts within a component should be closed against the same kinds of change. A change the affects one artifact in a component should be likely to affect them all.

    The Common Reuse Principle (CRP)

    The artifacts within a component should be (re)used together. A client that uses one artifact in a component should be likely use them all. (Also see the REP.)

    The Acyclic Dependencies Principle (ADP)

    There should be no cycles within the dependency graph.

    The Stable Dependencies Principle (SDP)

    A component should only depend upon components at least as stable as the component itself.

    The Stable Abstractions Principle (SAP)

    A component should contain as many stable abstractions as possible, and these should be isolated from the artifacts that are likely to change.

    The Open Closed Principle (OCP)

    An artifact should open for extension but closed for modification. In other words, it should be depend possible to alter the behavior of an artifact without modifying its source.

    The Liskov Substitution Principle (LSP)

    An instance of a derived type should be able to replace any instance of its parent. In other words, subclasses should adhere to the contracts of their parents, so that clients of the base class function equally well when provided with an instance of some class derived from that base.

    The Interface Segregation Principle (ISP)

    An artifact should depend upon the smallest possible interface. Prefer many specific interfaces to a single monolithic one.

    The Dependency Inversion Principle (DIP)

    An artifact should depend abstract interfaces rather than concrete implementations.

    See http://www.c2.com/cgi/wiki?OoDesignPriciples and many other sources for additional information.
21. As an Apache DB subproject, the Commons adopts all other guidelines and procedures of the DB project and the Apache Software Foundation, as they may be amended from time to time.

Example Package Proposal

This is simply an example. It is not a formal proposal, let alone a binding one.

(0) rationale

Many DB projects and DB Commons components rely upon Java's JDBC API. The JDK defines an interface for this API, but does not (and realistically, probably can not) provide a standard or base implementation of this interface. Hence it can be difficult to develop test suites for JDBC-based components without a full-blown JDBC (i.e., relational database) implementation.

One popular alternative to "functional" testing using an external system (in our case, a relational database) is known as a "Mock Objects" or "Endo-Testing" approach [1]. Using Mock Objects, rather than building a full implementation of the external system, we build just enough functionality to validate the code being tested. For example, when testing a connection pooling system, we don't really need to be able to execute an arbitrary SQL statement, we simply need some DataSource from which can obtain some Connection. Most of the underlying database functionality is unimportant to the connection pool.

The availability of an extensible collection of "mock" JDBC objects under an ASF license will support the development and testing of a number of JDBC related and JDBC based components, within DB Commons, with the Apache DB project, and within the Java development community as a whole.

[1] See http://www.mockobjects.com/endotesting.html

(1) scope of the component

The component shall create and maintain a collection of "mock" JDBC objects to be distributed under the ASF license, supporting unit testing of JDBC based or derived applications using an endo-testing approach.

The component should be extensible so that clients that require additional "mock" functionality are able to add it.

(1.5) interaction with other components

It is expected, but certainly not required, that other DB Commons components will take advantage of this component.

(2) identify the initial source for the component

The initial codebase was developed within the Jakarta Commons DBCP component, and further developed within the Jakarta Commons Sandbox under the DbUtils component.

(2.1) identify the base name for the component

org.apache.dbcommons.mockjdbc

(2.2) identify the coding conventions for this component

The code follows the standard Sun code conventions.

(3) identify any DB Commons resources to be created

(3.1) mailing list

Until traffic justifies, the component will use the general DB Commons lists for communications.

(3.2) CVS repositories

For the time being, the component will use a mockjdbc branch of the DB-Commons CVS.

(3.3) Bugzilla

The component should be listed as a component of the DB Commons Bugzilla entry.

(3.4) Jyve FAQ (when available)

dbcommons-mockjdbc

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

Steven Caswell

Rodney Waldhoff

Henri Yandell