| <?xml version="1.0"?> |
| <!-- |
| 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. |
| --> |
| <!-- ===================================================================== --> |
| <!-- $Id$ --> |
| <!-- ===================================================================== --> |
| <document> |
| |
| <properties> |
| <author email="pete@kazmier.com">Pete Kazmier</author> |
| <author email="mpoeschl@marmot.at">Martin Poeschl</author> |
| <author email="jason@zenplex.com">Jason van Zyl</author> |
| <author email="epugh@upstate.com">Eric Pugh</author> |
| <author email="tobrien@discursive.com">Tim O'Brien</author> |
| <author email="rgoers@apache.org">Ralph Goers</author> |
| <title>Java Configuration API</title> |
| </properties> |
| |
| <body> |
| <section name="Intro"> |
| <p> |
| The Commons Configuration software library provides a generic configuration interface which enables |
| a Java application to read configuration data from a variety of sources. Commons Configuration |
| provides typed access to single, and multi-valued configuration parameters as demonstrated |
| by the following code: |
| |
| <source><![CDATA[ |
| Double double = config.getDouble("number"); |
| Integer integer = config.getInteger("number"); |
| ]]></source> |
| |
| </p> |
| <p> |
| Configuration parameters may be loaded from the following sources: |
| |
| <ul> |
| <li>Properties files</li> |
| <li>XML documents</li> |
| <li>Windows INI files</li> |
| <li>Property list files (plist)</li> |
| <li>JNDI</li> |
| <li>JDBC Datasource</li> |
| <li>System properties</li> |
| <li>Applet parameters</li> |
| <li>Servlet parameters</li> |
| </ul> |
| |
| Configuration objects are created using configuration builders. |
| Different configuration sources can be mixed using a <code>CombinedConfigurationBuilder</code> and |
| a <code>CombinedConfiguration</code>. Additional sources of configuration parameters can |
| be created by using custom configuration objects. This customization can be achieved by |
| extending <code>AbstractConfiguration</code> or <code>AbstractHierarchicalConfiguration</code>. |
| </p> |
| <p> |
| The full Javadoc API documentation is available <a href="apidocs/index.html">here</a>. |
| </p> |
| </section> |
| |
| <section name="Commons Configuration 1.x and 2.x"> |
| <p> |
| After its initial release in 2004, Apache Commons Configuration has been steadily improved, |
| and a series of feature releases has been published over the years. All of these releases |
| were binary backwards-compatible. The latest release of this series is version 1.10. This code |
| base is now pretty mature and does what it is expected to do. |
| </p> |
| <p> |
| Nevertheless, there have been some design decisions made in the past which are problematic |
| in retrospect. For instance, access to configuration objects is always synchronized which |
| might be a performance issue in some use cases, or support for reloading of configuration |
| data is very limited - just to mention a few pain points. These problems could not be |
| fixed without breaking backwards compatibility in the affected areas. |
| </p> |
| <p> |
| Therefore, work has been spent on a major redesign of the library |
| addressing some of the weaknesses of the 1.x versions. The results |
| have been made available over a longer period as a series of alpha and beta releases. |
| Now the final version 2.0 is available incorporating feedback from the community. Note that |
| this is not a drop-in replacement for Commons Configuration 1.x! Changes on client code |
| are required to make use of the new version. There is |
| a <a href="userguide/upgradeto2_0.html">Migration guide</a> that can be |
| used as guideline when upgrading from version 1.x to 2.0. It describes the |
| most important changes. A good source of information is also the |
| <a href="changes-report.html">Changes Report</a> that explains all of the changes and bug |
| fixes that have been applied. |
| </p> |
| <p> |
| Both Commons Configuration 1.10 and the most recent 2.x release can be downloaded from the |
| <a href="https://commons.apache.org/configuration/download_configuration.cgi">Apache download area</a>. |
| The artifacts have also been deployed to |
| <a href="http://repo1.maven.org/maven2/">Maven central</a> (with different coordinates for |
| both versions to avoid conflicts). Which version should you use? Well, if you are a |
| long-term user of Commons Configuration 1.x and happy with its functionality, there is |
| no urgent pressure to upgrade to the newest version. New projects, however, should start |
| with the new API as it offers more functionality and makes some tasks easier and cleaner. |
| Also note that development currently focuses exclusively on the 2.x branch, so that the |
| probability for bug-fix releases for version 1.x is pretty low. |
| </p> |
| </section> |
| |
| <section name="History"> |
| <p> |
| Commons Configuration started as code in Apache JServ. The JServ code was subsequently |
| added to <a href="http://jakarta.apache.org/turbine">Jakarta Turbine</a>. After Jakarta |
| Turbine, this configuration interface moved to <a href="http://jakarta.apache.org/velocity">Jakarta Velocity</a> |
| and underwent various improvements. After Velocity, this code was introduced to the |
| <a href="https://commons.apache.org">Apache Commons</a> as <code>ExtendedProperties</code>. |
| Configuration began life in the Commons as a Sandbox component, and was promoted to the |
| Commons Proper in late 2003. |
| </p> |
| </section> |
| |
| <section name="Bugs"> |
| <p> |
| Bugs may be reported via the <a href="https://issues.apache.org/jira/browse/CONFIGURATION">ASF JIRA</a> |
| system. Detailed information can be found on the <a href="issue-tracking.html">issue tracking page</a>. |
| </p> |
| </section> |
| |
| </body> |
| </document> |