자카르타 Commons를 위한 다음의 헌장이 자카르타 프로젝트관리위원회에 의하여 2001년 3월 19일에 승인되었다.

(0) 근본

아파치-자바와 자카르타는 원래 하나로 크게 묶이는 제품-베이스드 서브프로젝트들을 호스트했다. 그러나 자바 언어는 패키지-베이스이고, 이들 제품의 대부분은 쓸만한 많은 유틸리티들을 가진다. 약간의 프로젝트들은 스스로를 깨기 시작했고, 그들은 독립적으로 사용될 수 없었다. 독립적인 패키지들로 외롭게 만들어지고 유지되어온 자카르타 서브프로젝트들이 이 과정을 촉진하고 가이드하기위하여 제안한다.

(1) 서브프로젝트의 범위

서브프로젝트는 자바언어로 쓰여진 패키지들을 만들고 유지할 것이다. 서버-관계된 개발에 사용을 의도한, 그리고 어떤 레이어의 프로젝트나 프레임워크에도 독립적으로 쓸 수 있게 설계된 패키지들 말이다. 각 패키지들은 커다란 자카르타 제품과 같은 방식으로 관리될 것이다. 더 나아간 목표는, 서브프로젝트는 또한 자카르타 커미트들을 위한 작업공간을 호스트하고 재사용가능한 패키지들의 마스터 인덱스가 자카르타 제품들에 연계될 것이다.

(1.5) 서브프로젝트들과 상호작용

(1.5.1) 모래박스

이 서브프로젝트는 새로운 패키지 또는 다른 프로젝트들을 위한 작업공간으로서, 모든 자카르타 커미터에게 유용한 CVS저장소를 호스트할 것이다. 공공에 릴리즈하기 전에, 여기에서 개발된 코드나 문서들은 자카르타 서브프로젝트에 의하여 지지되어야 한다. 지지하는 서브프로젝트(들)는 이 코드베이스가 죽을 때까지 코드와 문서를 배포할 것이다.

(1.5.2) 디렉토리

이 서브 프로젝트는 또한 다른 자카르타 서브프로젝트들과 ASF 프로젝트들에 연관된, 공공에 유용한 패키지들과 다른 리소스들의 목록을 열거할 것이다. 이는 Bugzilla와 Jyve와 같은, download.com, cpan.org, 또는 SourceForge.net 의 기능과 유사한 동적인 카탈로그가 될 것이다. 새로운 엔트리가 자카르타 커미터들과 개발자 그리고 사용자들에 의하여 추가될 수 있고, 공공에로 배포되기전에 커미터에 의하여 승인될 것이다.

(2) 이 서브프로젝트가 어디로부터 정착되었는가를 말한느 초기 소스를 정의하기

초기 패키지들은 존재하는 ASF 코드기반에 기초될 것이다. 이는 데이타소스/데이타베이스 풀들을 위한 서비스들을 제공하는 것들과 XML 구성물, 메세지 리소스들과 i18n, JNDI 와 Naming, 그리고 Testing Suite들을 포함한다. 초기 커미터들은 테스팅 쉬트들과 서버프로젝트 인프라까지 데이타베이스 연결 풀 패키지들을 첫번째로 만들고 유지한다는데 동의한다.

(3) 창조된 초기 자카르타 리소스를 정의하기

(3.1) 메일링 리스트(들)

jakarta-commons

(3.2) CVS 저장소

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) 초기 커미터들의 구성을 정의하기

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

Note :

• 이다,가진다,일 것이다,해야한다 - 필수적인 것.
• 일지도 모른다, 해야하지 않겠는다,격려된다 - 선택적이나 추천되는 것.

1. 재용되고 배포되는 주요 단위는 패키징이다.
2. 패키지 라이브러리는 프레임워크가 아니라 독립적으로 사용되도록 디자인된 컴프넌트들의 집합이다.
3. 각 패키들은 명확히 정의된 목적과 범위 그리고 API를 가져야 한다. -- 한 가지라도 잘하라, 그리고 차별성를 견지하라!
4. 각 패키지들은 자신의 권리를 가진 제품으로 대우받는다.
   1. 각 패키지들은 자신의 상태화일과 배포일정, 버전, QA 테스트들,문서,메일링 리스트,버그카테고리,그리고 개별적인 JAR을 가진다.
   2. 각 패키지들은 어떠한 외부적인(다른 Commons 패키지들로 포함하여 그리고 요구되는 가장 이른 JDK버전도) 의존성도 명확히 설정해야 한다.
      1. 선택적인 그리고 외부업체의 코드에 대한 외부의존성은 최소화돼어야 한다.
      2. 모든 필수적인 의존성은, '시스템 연장'을 기술하고 있는 JDK 1.3에서 추천되는 방법을 사용하여 패키지 JAR안의 MANIFEST.MF에 기록되어야 한다.
   3. 각 패키지들은 자신의 상태 화일에 자신의 활동하고 있는 커미터들의 리스트를 유지해야 한다.
5. 패키지들은 버전닝(versioning), QA 테스트들, 그리고 디렉토리 레이아웃들에 표준 스키마를 사용해야 하며, 그리고 문서들과 안트 빌드화일들을 위해 공통 포맷을 사용해야 한다.
6. 패키지들은 통일된 패키지 구조트리내에 맞추어야 한다.
7. 일반적으로, 패키지들은 인터페이스와 그 인터페이스의 하나 또는 추가의 구현을 제공하거나 이미 사용중인 다른 인터페이스를 구현해야 한다.
   • 패키지들은 기능적인 이름들을 드러내야 한다. 구현들은 더 '재미있는' 명칭을 고를 수도 있을 것이다.
8. 패키지들은 코어 오브젝트들로서 자바빈즈를 또는 자바빈-스타일 api를 사용하든가 또는 선택적인 자바빈 랩퍼를 제공할 것을 격려한다.
9. 외부 설정 화일들은 좋지 않다. 그러나 만약 필요하다면, XML 포맷 화일들이 설정 옵션을 위해 선호된다.
10. 각 패키지는 서브프로젝트 웹 사이트상의 자신의 페이지위에서 호스트되어질 것이다. 그리고 또한 마스터 디렉토리에서 인덱스되어 질 것이다.
11. 서브프로젝트 디렉토리는 또한 배포매카니즘을 제공할 것이다, 또는 패키지들과 연관된 리소스들의 카탈로그가 제공될 것이다.
12. The subproject will also host a top-level 'general' mailing list in addition to any lists for specific packages.
13. 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.
14. 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.
15. 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.
16. The committers shall elect a committee of three committers to provide general oversight, in the style of the Jakarta PMC.
17. New packages may be proposed to the Jakarta Commons mailing list. To be accepted, a package proposal must receive majority approval 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.
    • As stated in the Jakarta guidelines, an action requiring majority approval must receive at least 3 binding +1 votes and more +1 votes than -1 votes.
18. It is expected that the scope of packages may sometimes overlap.
19. 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.
20. 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.
21. The subproject catalog will also list packages and resources available to the public related to other Jakarta subprojects and ASF projects.
22. 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.

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 Waldhoff 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

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.

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