Return-Path: X-Original-To: apmail-commons-commits-archive@minotaur.apache.org Delivered-To: apmail-commons-commits-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 0FD4A18A4D for ; Thu, 19 Nov 2015 21:29:59 +0000 (UTC) Received: (qmail 42389 invoked by uid 500); 19 Nov 2015 21:29:58 -0000 Delivered-To: apmail-commons-commits-archive@commons.apache.org Received: (qmail 42307 invoked by uid 500); 19 Nov 2015 21:29:58 -0000 Mailing-List: contact commits-help@commons.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@commons.apache.org Delivered-To: mailing list commits@commons.apache.org Received: (qmail 42289 invoked by uid 99); 19 Nov 2015 21:29:58 -0000 Received: from Unknown (HELO spamd1-us-west.apache.org) (209.188.14.142) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 19 Nov 2015 21:29:58 +0000 Received: from localhost (localhost [127.0.0.1]) by spamd1-us-west.apache.org (ASF Mail Server at spamd1-us-west.apache.org) with ESMTP id 674FCC48A3 for ; Thu, 19 Nov 2015 21:29:53 +0000 (UTC) X-Virus-Scanned: Debian amavisd-new at spamd1-us-west.apache.org X-Spam-Flag: NO X-Spam-Score: 1.247 X-Spam-Level: * X-Spam-Status: No, score=1.247 tagged_above=-999 required=6.31 tests=[KAM_ASCII_DIVIDERS=0.8, KAM_LAZY_DOMAIN_SECURITY=1, RP_MATCHES_RCVD=-0.554, URIBL_BLOCKED=0.001] autolearn=disabled Received: from mx1-eu-west.apache.org ([10.40.0.8]) by localhost (spamd1-us-west.apache.org [10.40.0.7]) (amavisd-new, port 10024) with ESMTP id jSAyXgwC4spW for ; Thu, 19 Nov 2015 21:29:48 +0000 (UTC) Received: from mailrelay1-us-west.apache.org (mailrelay1-us-west.apache.org [209.188.14.139]) by mx1-eu-west.apache.org (ASF Mail Server at mx1-eu-west.apache.org) with ESMTP id D3C8A23047 for ; Thu, 19 Nov 2015 21:29:47 +0000 (UTC) Received: from svn01-us-west.apache.org (svn.apache.org [10.41.0.6]) by mailrelay1-us-west.apache.org (ASF Mail Server at mailrelay1-us-west.apache.org) with ESMTP id 2BBEBE00B6 for ; Thu, 19 Nov 2015 21:29:47 +0000 (UTC) Received: from svn01-us-west.apache.org (localhost [127.0.0.1]) by svn01-us-west.apache.org (ASF Mail Server at svn01-us-west.apache.org) with ESMTP id 2A2073A00E5 for ; Thu, 19 Nov 2015 21:29:47 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1715287 - in /commons/proper/configuration/trunk/src/site/xdoc/userguide: quick_start.xml user_guide.xml Date: Thu, 19 Nov 2015 21:29:47 -0000 To: commits@commons.apache.org From: oheger@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20151119212947.2A2073A00E5@svn01-us-west.apache.org> Author: oheger Date: Thu Nov 19 21:29:46 2015 New Revision: 1715287 URL: http://svn.apache.org/viewvc?rev=1715287&view=rev Log: Added a quick start chapter to the user's guide. This gives a short introduction into the most important key features of the library. Added: commons/proper/configuration/trunk/src/site/xdoc/userguide/quick_start.xml Modified: commons/proper/configuration/trunk/src/site/xdoc/userguide/user_guide.xml Added: commons/proper/configuration/trunk/src/site/xdoc/userguide/quick_start.xml URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/site/xdoc/userguide/quick_start.xml?rev=1715287&view=auto ============================================================================== --- commons/proper/configuration/trunk/src/site/xdoc/userguide/quick_start.xml (added) +++ commons/proper/configuration/trunk/src/site/xdoc/userguide/quick_start.xml Thu Nov 19 21:29:46 2015 @@ -0,0 +1,261 @@ + + + + + + + Quick start + + + +
+

+ This document is a short introduction into the basic use cases of + Commons Configuration for the impatient. Later chapters of this + user's guide explain the concepts presented here in more detail. +

+ + +

+ Configuration information is frequently stored in properties files. + Consider the following simple file that defines some properties related + to accessing a database. We assume that it is stored as + database.properties in the local file system: +

+ +

+ The easiest way to read this file is via the + + Configurations helper class. This class offers a bunch of + convenience methods for creating configuration objects from different + sources. For reading a properties file the code looks as follows: +

+ + + + +

+ The + Configuration object obtained in the last step can now be used + to query the values for the stored configuration properties. For this + purpose, numerous get methods for different property types are available. + For the properties contained in the example file the following methods + can be used: +

+ +

+ Note that the keys passed to the get methods match the keys contained in + the properties file. If a key cannot be resolved, the default behavior of + a configuration is to return null. (Methods that return + a primitive type throw an exception because in this case there is no + null value.) It is possible to provide a default value + which is used when the key cannot be found. +

+ + + +

+ XML is also a suitable format for storing configuration information, + especially if the data becomes more complex. For instance, lists of + values can be stored in a natural way by just repeating tags. The + example file for this section defines some directory paths that are to be + processed by an application. It is named paths.xml and looks + as follows: +

+ + + + + /data/path1 + /data/otherpath + /var/log + + + +]]> +

+ Reading this file works analogously to reading a properties file. Again a + + Configurations instance is needed (by the way, this class is + thread-safe, and an instance can be shared and reused to read multiple + configuration sources), but this time we use the xml() + method rather than properties(): +

+ +

+ The xml() method returns an object of type + + XMLConfiguration. This class implements the + Configuration interface, but offers some more functionality + to access properties in a more structured manner. The reader may also have + noticed that we passed a string to xml() while we used a + java.io.File object in the properties example. All these + methods come in several overloaded variants allowing the caller to specify + the configuration source in different ways: as a file, as a URL, or as a + string. In the latter case, the file is searched for in various places, + including at an absolute file path, at a relative file path, as a resource + in the classpath, or in the current user's home directory. +

+ + + +

+ Accessing properties in a XML configuration (or any other hierarchical + configuration) supports the same query methods as for regular + configurations. There are some additional facilities that take the + hierarchical nature of these sources into account. The properties in the + example configuration can be read in the following way: +

+ paths = config.getList(String.class, "processing.paths.path"); +]]> +

+ The keys for properties are generated by concatening the possibly nested + tag names in the XML document (ignoring the root element). For attributes, + there is a special syntax as shown for the stage property. + Because the path element appears multiple times it actually + defines a list. With the getList() method all values can be + queried at once. +

+

+ Hierarchical configurations support an advanced syntax for keys that + allows a navigation to a specific element in the source document. This is + achieved by adding numeric indices in parentheses after the single key parts. For + instance, in order to reference the second path element in the + list, the following key can be used (indices are 0-based): +

+ +

+ For elements which are not repeated such indices can be dropped. It is + also possible to set an alternative expression engine - the + component that evaluates and interprets configuration keys. There is an + implementation available which can deal with XPath expressions. Refer to + Expression engines + for further details. +

+ + + +

+ The Configuration interface defines some methods for + manipulating configuration properties. Typical CRUD operations are + available for all properties. The following code fragment shows how the + example properties configuration can be changed. The port of the database + is changed to a new value, and a new property is added: +

+ +

+ addProperty() always adds a new value to the configuration. + If the affected key already exists, the value is added to this key, so + that it becomes a list. setProperty() in contrast overrides + an existing value (or creates a new one if the key does not exist). Both + methods can be passed an arbitrary value object. This can also be an + array or a collection, which makes it possible to add multiple values in a + single step. +

+ + + +

+ After a configuration has been manipulated, it should probably be saved + again to make the changes persistent. Otherwise, the changes are only in + memory. If configurations are to be changed, it is preferrable to obtain + them via a different mechanism: a configuration builder. + Builders are the most powerful and flexible way to construct + configurations. They support many settings that impact the way the + configuration data is loaded and the resulting configuration object + behaves. Builders for file-based configurations also offer a + save() method that writes all configuration data back to + disk. Configuration builders are typically created using a fluent API + which allows a convenient and flexible configuration of the builder. This + API is described in the section + Configuration + builders. For simple use cases, the + + Configurations class we have already used has again some convenience + methods. The following code fragment shows how a configuration is read via + a builder, manipulated, and finally saved again: +

+ builder = configs.xmlBuilder("paths.xml"); + XMLConfiguration config = builder.getConfiguration(); + + // update property + config.addProperty("newProperty", "newValue"); + + // save configuration + builder.save(); +} +catch (ConfigurationException cex) +{ + // Something went wrong +} +]]> + + +
+ + + \ No newline at end of file Modified: commons/proper/configuration/trunk/src/site/xdoc/userguide/user_guide.xml URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/site/xdoc/userguide/user_guide.xml?rev=1715287&r1=1715286&r2=1715287&view=diff ============================================================================== --- commons/proper/configuration/trunk/src/site/xdoc/userguide/user_guide.xml (original) +++ commons/proper/configuration/trunk/src/site/xdoc/userguide/user_guide.xml Thu Nov 19 21:29:46 2015 @@ -38,6 +38,7 @@