Author: oheger
Date: Wed Sep 24 20:29:01 2014
New Revision: 923442
Log:
Added user guide for version 1.10.
Added:
websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/
websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_basicfeatures.html
websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_beans.html
websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_combinedconfiguration.html
websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_compositeconfiguration.html
websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_configurationbuilder.html
websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_events.html
websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_filebased.html
websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_filesystems.html
websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_multitenant.html
websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_properties.html
websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_utilities.html
websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_xml.html
websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/overview.html
websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/user_guide.html
Added:
websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_basicfeatures.html
==============================================================================
---
websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_basicfeatures.html
(added)
+++
websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_basicfeatures.html
Wed Sep 24 20:29:01 2014
@@ -0,0 +1,634 @@
+<!DOCTYPE html>
+<!--
+ | Generated by Apache Maven Doxia at 24 September 2014
+ | Rendered using Apache Maven Fluido Skin 1.3.0
+-->
+<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en">
+ <head>
+ <meta charset="iso-8859-1" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <meta name="author" content="Oliver Heger" />
+ <meta name="Date-Revision-yyyymmdd" content="20140924" />
+ <meta http-equiv="Content-Language" content="en" />
+ <title>Commons Configuration -
+ Basic Features</title>
+
+ <link rel="stylesheet" href="../css/bootstrap.min.css" type="text/css"
/>
+ <link rel="stylesheet" href="../css/site.css" type="text/css" />
+ <link rel="stylesheet" href="../css/print.css" media="print" />
+
+ <script type="text/javascript" src="../js/jquery.min.js"></script>
+ <script type="text/javascript" src="../js/bootstrap.min.js"></script>
+ <script type="text/javascript" src="../js/prettify.min.js"></script>
+ <script type="text/javascript" src="../js/site.js"></script>
+
+
+<link rel="stylesheet" type="text/css" media="all"
href="../css/prettify.css"/>
+<script src="../js/prettify.js" type="text/javascript"></script>
+<script type="text/javascript">window.onload=function() {
+ prettyPrint();
+ }</script>
+ </head>
+
+ <body class="composite">
+ <a href="http://commons.apache.org/"; id="bannerLeft"
title="Apache Commons logo">
+
<img class="logo-left" src="../images/commons-logo.png" alt="Apache
Commons logo"/>
+ </a>
+ <a href="../index.html"
id="bannerRight">
+
<img class="logo-right" src="../images/logo.png" alt="Commons
Configuration"/>
+ </a>
+ <div class="clear"></div>
+
+ <div class="navbar">
+ <div class="navbar-inner">
+ <div class="container-fluid">
+ <a class="brand"
href="http://commons.apache.org/proper/commons-configuration/";>Apache Commons
Configuration ™</a>
+ <ul class="nav">
+
+ <li id="publishDate">Last Published: 24 September 2014</li>
+ <li class="divider">|</li> <li id="projectVersion">Version: 1.10</li>
+ </ul>
+ <div class="pull-right"> <ul class="nav">
+ <li>
+ <a href="http://www.apachecon.com/";
class="externalLink" title="ApacheCon">
+ ApacheCon</a>
+ </li>
+ <li>
+ <a href="http://www.apache.org";
class="externalLink" title="Apache">
+ Apache</a>
+ </li>
+ <li>
+ <a href="../../../" title="Commons">
+ Commons</a>
+ </li>
+ </ul>
+</div>
+ </div>
+ </div>
+ </div>
+
+ <div class="container-fluid">
+ <table class="layout-table">
+ <tr>
+ <td class="sidebar">
+ <div class="well sidebar-nav">
+
<ul class="nav nav-list">
+
<li class="nav-header">Configuration</li>
+
<li class="none">
+ <a href="../index.html" title="Home">
+ Home</a>
+ </li>
+
<li class="none">
+ <a
href="../../../configuration/download_configuration.cgi" title="Download">
+ Download</a>
+ </li>
+
<li class="none">
+ <a href="../changes-report.html" title="Release
History">
+ Release History</a>
+ </li>
+
<li class="none">
+ <a href="../userguide/user_guide.html"
title="User's Guide">
+ User's Guide</a>
+ </li>
+
<li class="none">
+ <a href="../dependencies.html" title="Runtime
Dependencies">
+ Runtime Dependencies</a>
+ </li>
+
<li class="none">
+ <a href="../apidocs/index.html" title="Javadoc">
+ Javadoc</a>
+ </li>
+ </ul>
+ <ul class="nav nav-list">
+
<li class="nav-header"><i
class="icon-cog"></i>Development</li>
+
<li class="none">
+ <a href="../building.html" title="Building">
+ Building</a>
+ </li>
+
<li class="none">
+ <a href="../issue-tracking.html" title="Issue
Tracking">
+ Issue Tracking</a>
+ </li>
+ </ul>
+ <ul class="nav nav-list">
+
<li class="nav-header"><i
class="icon-info-sign"></i>Project Documentation</li>
+
<li class="collapsed">
+ <a href="../project-info.html" title="Project
Information">
+ Project Information</a>
+ </li>
+
<li class="collapsed">
+ <a href="../project-reports.html" title="Project
Reports">
+ Project Reports</a>
+ </li>
+ </ul>
+ <ul class="nav nav-list">
+
<li class="nav-header">Commons</li>
+
<li class="none">
+ <a href="../../../" title="Home">
+ Home</a>
+ </li>
+
<li class="none">
+ <a href="http://www.apache.org/licenses/";
class="externalLink" title="License">
+ License</a>
+ </li>
+
<li
class="collapsed">
+ <a href="../../../components.html"
title="Components">
+ Components</a>
+ </li>
+
<li
class="collapsed">
+ <a href="../../../sandbox/index.html"
title="Sandbox">
+ Sandbox</a>
+ </li>
+
<li
class="collapsed">
+ <a href="../../../dormant/index.html"
title="Dormant">
+ Dormant</a>
+ </li>
+ </ul>
+ <ul class="nav nav-list">
+
<li class="nav-header">General Information</li>
+
<li class="none">
+ <a href="../../../volunteering.html"
title="Volunteering">
+ Volunteering</a>
+ </li>
+
<li class="none">
+ <a href="../../../patches.html"
title="Contributing Patches">
+ Contributing Patches</a>
+ </li>
+
<li class="none">
+ <a href="../../../building.html" title="Building
Components">
+ Building Components</a>
+ </li>
+
<li class="none">
+ <a href="../../../releases/index.html"
title="Releasing Components">
+ Releasing Components</a>
+ </li>
+
<li class="none">
+ <a
href="http://wiki.apache.org/commons/FrontPage"; class="externalLink"
title="Wiki">
+ Wiki</a>
+ </li>
+ </ul>
+ <ul class="nav nav-list">
+
<li class="nav-header">ASF</li>
+
<li class="none">
+ <a
href="http://www.apache.org/foundation/how-it-works.html"; class="externalLink"
title="How the ASF works">
+ How the ASF works</a>
+ </li>
+
<li class="none">
+ <a
href="http://www.apache.org/foundation/getinvolved.html"; class="externalLink"
title="Get Involved">
+ Get Involved</a>
+ </li>
+
<li class="none">
+ <a href="http://www.apache.org/dev/";
class="externalLink" title="Developer Resources">
+ Developer Resources</a>
+ </li>
+
<li class="none">
+ <a
href="http://www.apache.org/foundation/sponsorship.html"; class="externalLink"
title="Sponsorship">
+ Sponsorship</a>
+ </li>
+
<li class="none">
+ <a
href="http://www.apache.org/foundation/thanks.html"; class="externalLink"
title="Thanks">
+ Thanks</a>
+ </li>
+ </ul>
+ </div>
+ <div id="poweredBy">
+
<a href="http://www.apache.org/events/current-event.html"; title="ApacheCon"
class="builtBy">
+ <img class="builtBy" alt="ApacheCon"
src="http://www.apache.org/events/current-event-125x125.png"; />
+ </a>
+
<a href="http://maven.apache.org/"; title="Maven"
class="builtBy">
+ <img class="builtBy" alt="Maven"
src="http://maven.apache.org/images/logos/maven-feather.png"; />
+ </a>
+ </div>
+ </td>
+ <td class="content">
+ <!-- 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. -->
+
+
+ <div class="section">
+<h2>Basic features and AbstractConfiguration<a
name="Basic_features_and_AbstractConfiguration"></a></h2>
+
+<p>
+ The <tt>Configuration</tt> interface defines a whole bunch of methods.
+ Implementing these methods all from scratch can be quite hard. Because of
+ that the <tt><a
href="../apidocs/org/apache/commons/configuration/AbstractConfiguration.html">
+ AbstractConfiguration</a></tt> class exists. This class serves as a
+ common base class for most of the <tt>Configuration</tt> implementations
+ in <i>Commons Configuration</i> and provides a great deal of the
+ functionality required by the interface. So for creating a custom
+ <tt>Configuration</tt> implementation this class will be a good
+ starting point.
+ </p>
+
+<p>
+ In addition to base implementations for lots of the methods declared in
+ the <tt>Configuration</tt> interface the <tt>AbstractConfiguration</tt>
+ class provides some other handy and convenient features. Because this
+ class is at the very root of the class hierarchy in <i>Commons
+ Configuration</i> these features are available in most of the specific
+ implementations of the <tt>Configuration</tt> interface provided by
+ this library. We will cover some of these basic features in this section.
+ </p>
+
+
+<div class="section">
+<h3>Handling of missing properties<a
name="Handling_of_missing_properties"></a></h3>
+
+<p>
+ What is a configuration object supposed to do if you pass in a key to one
+ of its get methods that does not map to an existing property? Well, the
+ default behavior as implemented in <tt>AbstractConfiguration</tt> is
+ to return <b>null</b> if the return value is an object type. For
primitive
+ types as return values returning <b>null</b> (or any other special
+ value) is not possible, so in this case a <tt>NoSuchElementException</tt>
+ is thrown:
+ </p>
+
+<div class="source">
+<pre>
+// This will return null if no property with key
"NonExistingProperty" exists
+String strValue = config.getString("NonExistingProperty");
+
+// This will throw a NoSuchElementException exception if no property with
+// key "NonExistingProperty" exists
+long longValue = config.getLong("NonExistingProperty");
+</pre></div>
+
+<p>
+ For object types like <tt>String</tt>, <tt>BigDecimal</tt>, or
+ <tt>BigInteger</tt> this default behavior can be changed: If the
+ <tt>setThrowExceptionOnMissing()</tt> method is called with an
+ argument of <b>true</b>, these methods will behave like their primitive
+ counter parts and also throw an exception if the passed in property key
+ cannot be resolved.
+ </p>
+
+<p>
+ <i>Note:</i> Unfortunately support for the
<tt>throwExceptionOnMissing</tt>
+ property is not always consistent: The methods <tt>getList()</tt> and
+ <tt>getStringArray()</tt> do not evaluate this flag, but return an
+ empty list or array if the requested property cannot be found. Maybe this
+ behavior will be changed in a future major release.
+ </p>
+ </div>
+
+
+<div class="section">
+<h3>List handling<a name="List_handling"></a></h3>
+
+<p>
+ With <tt>getList()</tt> and <tt>getStringArray()</tt> the
+ <tt>Configuration</tt> interface defines methods for dealing with
+ properties that have multiple values. When a configuration source (e.g.
+ a properties file, an XML document, or a JNDI context) is processed the
+ corresponding <tt>Configuration</tt> implementation detects such
+ properties with multiple values and ensures that the data is correctly
+ stored.
+ </p>
+
+<p>
+ When modifying properties the <tt>addProperty()</tt> and
+ <tt>setProperty()</tt> methods of <tt>AbstractConfiguration</tt>
+ also implement special list handling. The property value that is passed
+ to these methods can be a list or an array resulting in a property
+ with multiple values. If the property value is a string, it is checked
+ whether it contains the <i>list delimiter character</i>. If this is
+ the case, the string is splitted, and its single parts are added one
+ by one. The list delimiter character is the comma by default. It is
+ also taken into account when the configuration source is loaded
+ (i.e. string values of properties will be checked whether they contain
+ this delimiter). By using the <tt>setListDelimiter()</tt>
+ method you can set it to a different character. Here are some examples:
+ </p>
+
+<div class="source">
+<pre>
+// Change the list delimiter character to a slash
+config.setListDelimiter('/');
+// Now add some properties
+config.addProperty("greeting", "Hello, how are you?");
+config.addProperty("colors.pie",
+ new String[] { "#FF0000", "#00FF00", "#0000FF"
});
+config.addProperty("colors.graph",
"#808080/#00FFCC/#6422FF");
+
+// Access data
+String salut = config.getString("greeting");
+List<Object> colPie = config.getList("colors.pie");
+String[] colGraph = config.getStringArray("colors.graph");
+
+String firstPieColor = config.getString("colors.pie");
+</pre></div>
+
+<p>
+ In this example the list delimiter character is changed from a comma
+ to a slash. Because of this the <tt>greeting</tt> property won't
+ be split, but remains a single string. The string passed as value
+ for the <tt>colors.graph</tt> property in opposite contains the
+ new delimiter character and thus will result in a property with three
+ values. Note that lists are of type <tt>Object</tt>. This is because
+ the concrete class of the values of a property is not known. For
instance,
+ if you call <tt>addProperty("answer", 42)</tt>, an
+ <tt>Integer</tt> object will be stored in the configuration.
+ </p>
+
+<p>
+ Of interest is also the last line of the example fragment. Here the
+ <tt>getString()</tt> method is called for a property that has
+ multiple values. This call will return the first value of the list.
+ </p>
+
+<p>
+ If you want to change the list delimiter character for all configuration
+ objects, you can use the static <tt>setDefaultListDelimiter()</tt>
+ method of <tt>AbstractConfiguration</tt>. It is also possible to
+ disable splitting of string properties at all for a Configuration
+ instance by calling its <tt>setDelimiterParsingDisabled()</tt>
+ method with a value of <b>true</b>.
+ </p>
+ </div>
+
+
+<div class="section">
+<h3>Variable Interpolation<a name="Variable_Interpolation"></a></h3>
+
+<p>
+ If you are familiar with Ant or Maven, you have most certainly already
encountered
+ the variables (like <tt>${token}</tt>) that are automatically expanded
when the
+ configuration file is loaded. Commons Configuration supports this
feature as well,
+ here is an example (we use a properties file in this example, but other
+ configuration sources work the same way; you can learn more about
+ properties files in the chapter <a
href="howto_properties.html">Properties
+ files</a>):
+ </p>
+
+<div class="source">
+<pre>
+application.name = Killer App
+application.version = 1.6.2
+
+application.title = ${application.name} ${application.version}
+</pre></div>
+
+<p>
+ If you now retrieve the value for the <tt>application.title</tt>
+ property, the result will be <tt>Killer App 1.6.2</tt>. So per default
+ variables are interpreted as the keys of other properties. This is only a
+ special case, the general syntax of a variable name is
+ <tt>${prefix:name}</tt>. The prefix tells Commons Configuration that
+ the variable is to be evaluated in a certain context. We have already
seen
+ that the context is the current configuration instance if the prefix is
+ missing. The following other prefix names are supported by default:
+ </p>
+<table class="bodyTable" border="1">
+
+<tr class="a">
+
+<th>Prefix</th>
+
+<th>Description</th>
+ </tr>
+
+<tr class="b">
+
+<td valign="top">sys</td>
+
+<td>This prefix marks a variable to be a system property. Commons
+ Configuration will search for a system property with the given name and
+ replace the variable by its value. This is a very easy means for
+ accessing the values of system properties in every configuration
+ implementation.</td>
+ </tr>
+
+<tr class="a">
+
+<td valign="top">const</td>
+
+<td>The <tt>const</tt> prefix indicates that a variable is to be
+ interpreted as a constant member field of a class (i.e. a field with
the
+ <b>static final</b> modifiers). The name of the variable must be of
the form
+ <tt><full qualified class name>.<field name></tt>. The
+ specified class will be loaded and the value of this field will be
+ obtained.</td>
+ </tr>
+
+<tr class="b">
+
+<td valign="top">env</td>
+
+<td>Variables can also reference OS-specific environment properties.
+ This is indicated by the <tt>env</tt> prefix.</td>
+ </tr>
+ </table>
+ Here are some examples (again using properties syntax):
+
+
+<div class="source">
+<pre>
+user.file = ${sys:user.home}/settings.xml
+
+action.key = ${const:java.awt.event.KeyEvent.VK_CANCEL}
+
+java.home = ${env:JAVA_HOME}
+</pre></div>
+
+<p>
+ If a variable cannot be resolved, e.g. because the name is invalid or an
+ unknown prefix is used, it won't be replaced, but is returned as is
+ including the dollar sign and the curly braces.
+ </p>
+ </div>
+
+
+<div class="section">
+<h3>Customizing interpolation<a name="Customizing_interpolation"></a></h3>
+
+<p>
+ This sub section goes a bit behind the scenes of interpolation and
+ explains some approaches how you can add your own interpolation
facilities.
+ Under the hood interpolation is implemented using the
+ <tt>StrSubstitutor</tt> class of the <tt>text</tt> package of
+ <a class="externalLink" href="http://commons.apache.org/lang/";>Commons
Lang</a>. This
+ class uses objects derived from the <tt>StrLookup</tt> class for
+ resolving variables. <tt>StrLookup</tt> defines a simple
+ <tt>lookup()</tt> method that must be implemented by custom
+ implementations; it expects the name of a variable as argument and
+ returns the corresponding value (further details can be found in the
+ documentation of Commons Lang). The standard prefixes for variables we
+ have covered so far are indeed realized by special classes derived from
+ <tt>StrLookup</tt>.
+ </p>
+
+<p>
+ It is now possible to create your own implementation of
<tt>StrLookup</tt>
+ and make it available for all configuration objects under a custom
+ prefix. We will show how this can be achieved. The first step is to
+ create a new class derived from <tt>StrLookup</tt>, which must
+ implement the <tt>lookup()</tt> method. As an example we implement a
+ rather dull lookup object that simply returns a kind of "echo"
+ for the variable passed in:
+ </p>
+
+<div class="source">
+<pre>
+import org.apache.commons.lang.text.StrLookup;
+
+public class EchoLookup extends StrLookup
+{
+ public String lookup(String varName)
+ {
+ return "Value of variable " + varName;
+ }
+}
+</pre></div>
+
+<p>
+ Now we want this class to be called for variables with the prefix
+ <tt>echo</tt>. For this purpose the <tt>EchoLookup</tt> class
+ has to be registered at the
+ <tt><a
href="../apidocs/org/apache/commons/configuration/interpol/ConfigurationInterpolator.html">
+ ConfigurationInterpolator</a></tt> class with the desired prefix.
+ <tt>ConfigurationInterpolator</tt> implements a thin wrapper over the
+ <tt>StrLookup</tt> API defined by Commons Lang. It has a static
+ <tt>registerGlobalLookup()</tt> method, which we have to call as
+ follows:
+ </p>
+
+<div class="source">
+<pre>
+// Place this code somewhere in an initialization section of your application
+ConfigurationInterpolator.registerGlobalLookup("echo", new
EchoLookup());
+ </pre></div>
+
+<p>
+ Each <tt>AbstractConfiguration</tt> object that is created after this
+ line is executed will contain the new lookup class and can thus resolve
+ variables of the form <tt>${echo:my_variable}</tt>.
+ </p>
+
+<p>
+ Each instance of <tt>AbstractConfiguration</tt> is associated with a
+ <tt>ConfigurationInterpolator</tt> object. This object is created by
+ the <tt>createInterpolator()</tt> method on first access of one of
+ the interpolation features. By overriding this method even deeper
+ intervention in the interpolation mechanism is possible. For instance
+ a custom implementation can add further lookup objects to the
interpolator,
+ which are then only used by this configuration instance.
+ </p>
+ </div>
+
+<div class="section">
+<h3>Using Expressions<a name="Using_Expressions"></a></h3>
+
+<p>
+ In addition to the simple lookup mechanisms previously described,
Commond Configuration
+ provides <tt>ExprLookup</tt> which uses <a class="externalLink"
href="http://commons.apache.org/jexl";>Apache
+ Commons Jexl</a> to allow expressions to be resolved wherever a
StrLookup is allowed. This
+ example shows an alternate way of obtaining a system property if the
ExprLookup is
+ configured.
+ </p>
+
+<div class="source">
+<pre>
+user.file = ${expr:System.getProperty("user.home"}/settings.xml
+</pre></div>
+
+<p>
+ <tt>ExprLookup</tt> is not enabled by default, it must be manually
added or configured via
+ <tt>DefaultConfigurationBuilder</tt>. Builds that use Maven 2 and
reference Commons
+ Configuration will not include a dependency on Jexl, so if this
feature is used the
+ dependency on Jexl must be manually added to the project.
+ </p>
+
+<p>
+ When using <tt>DefaultConfigurationBuilder</tt> adding
<tt>ExprLookup</tt> is
+ straightforward.
+ </p>
+
+<div class="source">
+<pre>
+<configuration>
+ <header>
+ <result/>
+ <lookups>
+ <lookup config-prefix="expr"
+
config-class="org.apache.commons.configuration.interpol.ExprLookup">
+ <variables>
+ <variable name="System"
value="Class:java.lang.System"/>
+ <variable name"net"
value="Class:java.net.InetAddress"/>
+ <variable name="String"
value="Class:org.apache.commons.lang.StringUtils"/>
+ </variables>
+ </lookup>
+ </lookups>
+ </header>
+ <override>
+ <xml fileName="${expr:System.getProperty('basePath') +
+ String.lowercase(net.localHost.hostName) +
'/testMultiConfiguration_default.xml'}"
+ config-name="defaultConfig"
delimiterParsingDisabled="true">
+ </xml>
+ </override>
+</configuration>
+</pre></div>
+
+<p>
+ The example above shows how to invoke static methods during expression
evaluation. The
+ next example shows mixing expression evaluation with a subordinate
lookup to
+ obtain the "basePath" system property. Note the difference
in how the
+ system property was obtained in the previous example.
+ </p>
+
+<div class="source">
+<pre>
+<configuration>
+ <header>
+ <result/>
+ <lookups>
+ <lookup config-prefix="expr"
+
config-class="org.apache.commons.configuration.interpol.ExprLookup">
+ <variables>
+ <variable name"net"
value="Class:java.net.InetAddress"/>
+ <variable name="String"
value="Class:org.apache.commons.lang.StringUtils"/>
+ </variables>
+ </lookup>
+ </lookups>
+ </header>
+ <override>
+ <xml fileName="${expr:$[sys:basePath] +
+ String.lowercase(net.localHost.hostName) +
'/testMultiConfiguration_default.xml'}"
+ config-name="defaultConfig"
delimiterParsingDisabled="true">
+ </xml>
+ </override>
+</configuration>
+</pre></div>
+ </div>
+ </div>
+
+
+
+ </td>
+ </tr>
+ </table>
+ </div>
+
+ <div class="footer">
+ <p>Copyright © 2001-2014
+ <a href="http://www.apache.org/";>The Apache Software
Foundation</a>.
+ All Rights Reserved.</p>
+
+<div class="center">Apache Commons, Apache Commons Configuration, Apache, the
Apache feather logo, and the Apache Commons project logos are trademarks of The
Apache Software Foundation.
+ All other marks mentioned may be trademarks or registered trademarks of
their respective owners.</div>
+ </div>
+ </body>
+
+</html>
Added:
websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_beans.html
==============================================================================
---
websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_beans.html
(added)
+++
websites/production/commons/content/proper/commons-configuration/javadocs/v1.10/userguide/howto_beans.html
Wed Sep 24 20:29:01 2014
@@ -0,0 +1,627 @@
+<!DOCTYPE html>
+<!--
+ | Generated by Apache Maven Doxia at 24 September 2014
+ | Rendered using Apache Maven Fluido Skin 1.3.0
+-->
+<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en">
+ <head>
+ <meta charset="iso-8859-1" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <meta name="author" content="Oliver Heger" />
+ <meta name="Date-Revision-yyyymmdd" content="20140924" />
+ <meta http-equiv="Content-Language" content="en" />
+ <title>Commons Configuration -
+ Declaring Beans Howto</title>
+
+ <link rel="stylesheet" href="../css/bootstrap.min.css" type="text/css"
/>
+ <link rel="stylesheet" href="../css/site.css" type="text/css" />
+ <link rel="stylesheet" href="../css/print.css" media="print" />
+
+ <script type="text/javascript" src="../js/jquery.min.js"></script>
+ <script type="text/javascript" src="../js/bootstrap.min.js"></script>
+ <script type="text/javascript" src="../js/prettify.min.js"></script>
+ <script type="text/javascript" src="../js/site.js"></script>
+
+
+<link rel="stylesheet" type="text/css" media="all"
href="../css/prettify.css"/>
+<script src="../js/prettify.js" type="text/javascript"></script>
+<script type="text/javascript">window.onload=function() {
+ prettyPrint();
+ }</script>
+ </head>
+
+ <body class="composite">
+ <a href="http://commons.apache.org/"; id="bannerLeft"
title="Apache Commons logo">
+
<img class="logo-left" src="../images/commons-logo.png" alt="Apache
Commons logo"/>
+ </a>
+ <a href="../index.html"
id="bannerRight">
+
<img class="logo-right" src="../images/logo.png" alt="Commons
Configuration"/>
+ </a>
+ <div class="clear"></div>
+
+ <div class="navbar">
+ <div class="navbar-inner">
+ <div class="container-fluid">
+ <a class="brand"
href="http://commons.apache.org/proper/commons-configuration/";>Apache Commons
Configuration ™</a>
+ <ul class="nav">
+
+ <li id="publishDate">Last Published: 24 September 2014</li>
+ <li class="divider">|</li> <li id="projectVersion">Version: 1.10</li>
+ </ul>
+ <div class="pull-right"> <ul class="nav">
+ <li>
+ <a href="http://www.apachecon.com/";
class="externalLink" title="ApacheCon">
+ ApacheCon</a>
+ </li>
+ <li>
+ <a href="http://www.apache.org";
class="externalLink" title="Apache">
+ Apache</a>
+ </li>
+ <li>
+ <a href="../../../" title="Commons">
+ Commons</a>
+ </li>
+ </ul>
+</div>
+ </div>
+ </div>
+ </div>
+
+ <div class="container-fluid">
+ <table class="layout-table">
+ <tr>
+ <td class="sidebar">
+ <div class="well sidebar-nav">
+
<ul class="nav nav-list">
+
<li class="nav-header">Configuration</li>
+
<li class="none">
+ <a href="../index.html" title="Home">
+ Home</a>
+ </li>
+
<li class="none">
+ <a
href="../../../configuration/download_configuration.cgi" title="Download">
+ Download</a>
+ </li>
+
<li class="none">
+ <a href="../changes-report.html" title="Release
History">
+ Release History</a>
+ </li>
+
<li class="none">
+ <a href="../userguide/user_guide.html"
title="User's Guide">
+ User's Guide</a>
+ </li>
+
<li class="none">
+ <a href="../dependencies.html" title="Runtime
Dependencies">
+ Runtime Dependencies</a>
+ </li>
+
<li class="none">
+ <a href="../apidocs/index.html" title="Javadoc">
+ Javadoc</a>
+ </li>
+ </ul>
+ <ul class="nav nav-list">
+
<li class="nav-header"><i
class="icon-cog"></i>Development</li>
+
<li class="none">
+ <a href="../building.html" title="Building">
+ Building</a>
+ </li>
+
<li class="none">
+ <a href="../issue-tracking.html" title="Issue
Tracking">
+ Issue Tracking</a>
+ </li>
+ </ul>
+ <ul class="nav nav-list">
+
<li class="nav-header"><i
class="icon-info-sign"></i>Project Documentation</li>
+
<li class="collapsed">
+ <a href="../project-info.html" title="Project
Information">
+ Project Information</a>
+ </li>
+
<li class="collapsed">
+ <a href="../project-reports.html" title="Project
Reports">
+ Project Reports</a>
+ </li>
+ </ul>
+ <ul class="nav nav-list">
+
<li class="nav-header">Commons</li>
+
<li class="none">
+ <a href="../../../" title="Home">
+ Home</a>
+ </li>
+
<li class="none">
+ <a href="http://www.apache.org/licenses/";
class="externalLink" title="License">
+ License</a>
+ </li>
+
<li
class="collapsed">
+ <a href="../../../components.html"
title="Components">
+ Components</a>
+ </li>
+
<li
class="collapsed">
+ <a href="../../../sandbox/index.html"
title="Sandbox">
+ Sandbox</a>
+ </li>
+
<li
class="collapsed">
+ <a href="../../../dormant/index.html"
title="Dormant">
+ Dormant</a>
+ </li>
+ </ul>
+ <ul class="nav nav-list">
+
<li class="nav-header">General Information</li>
+
<li class="none">
+ <a href="../../../volunteering.html"
title="Volunteering">
+ Volunteering</a>
+ </li>
+
<li class="none">
+ <a href="../../../patches.html"
title="Contributing Patches">
+ Contributing Patches</a>
+ </li>
+
<li class="none">
+ <a href="../../../building.html" title="Building
Components">
+ Building Components</a>
+ </li>
+
<li class="none">
+ <a href="../../../releases/index.html"
title="Releasing Components">
+ Releasing Components</a>
+ </li>
+
<li class="none">
+ <a
href="http://wiki.apache.org/commons/FrontPage"; class="externalLink"
title="Wiki">
+ Wiki</a>
+ </li>
+ </ul>
+ <ul class="nav nav-list">
+
<li class="nav-header">ASF</li>
+
<li class="none">
+ <a
href="http://www.apache.org/foundation/how-it-works.html"; class="externalLink"
title="How the ASF works">
+ How the ASF works</a>
+ </li>
+
<li class="none">
+ <a
href="http://www.apache.org/foundation/getinvolved.html"; class="externalLink"
title="Get Involved">
+ Get Involved</a>
+ </li>
+
<li class="none">
+ <a href="http://www.apache.org/dev/";
class="externalLink" title="Developer Resources">
+ Developer Resources</a>
+ </li>
+
<li class="none">
+ <a
href="http://www.apache.org/foundation/sponsorship.html"; class="externalLink"
title="Sponsorship">
+ Sponsorship</a>
+ </li>
+
<li class="none">
+ <a
href="http://www.apache.org/foundation/thanks.html"; class="externalLink"
title="Thanks">
+ Thanks</a>
+ </li>
+ </ul>
+ </div>
+ <div id="poweredBy">
+
<a href="http://www.apache.org/events/current-event.html"; title="ApacheCon"
class="builtBy">
+ <img class="builtBy" alt="ApacheCon"
src="http://www.apache.org/events/current-event-125x125.png"; />
+ </a>
+
<a href="http://maven.apache.org/"; title="Maven"
class="builtBy">
+ <img class="builtBy" alt="Maven"
src="http://maven.apache.org/images/logos/maven-feather.png"; />
+ </a>
+ </div>
+ </td>
+ <td class="content">
+ <!-- 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. -->
+
+
+ <div class="section">
+<h2>Declaring and Creating Beans<a
name="Declaring_and_Creating_Beans"></a></h2>
+
+<p>
+ Often it is good practice to make heavy use of Java interfaces and
program
+ an application or components against these interfaces rather than
concrete
+ implementation classes. This makes it possible to switch to different
implementations
+ without having to modify calling code. However the problem remains how a
+ concrete implementation of an interface is obtained. Simply using the
+ <b>new</b> operator on a specific implementation class would somehow
break
+ the interface concept because then the code would have an explicit
reference
+ to a concrete implementation.
+ </p>
+
+<p>
+ A solution to this problem is to define the concrete implementation class
+ that should be used in a configuration file. Client code would obtain an
+ object (or a bean) from the configuration and cast it to the service
+ interface. This way the caller would have no knowledge about which
concrete
+ implementation is used; it would only interact with the service through
+ the interface. By changing the configuration file and entering a
different
+ class name for the implementation class the behavior of the application
+ can be altered, e.g. to inject a test stub for the used service.
+ </p>
+
+<p>
+ <i>Note: The concept of defining service objects in configuration files
+ and let them be created by a special container has grown popular these
+ days. Especially IoC containers like <a class="externalLink"
href="http://jakarta.apache.org/hivemind/";>HiveMind</a>
+ or <a class="externalLink"
href="http://www.springframework.org/";>Spring</a> offer wide
+ functionality related to this topic. Commons Configuration is not and has
+ no ambitions to become an IoC container. The provided functionality for
+ declaring and creating beans is very basic and limited compared to the
+ specialists. So if you are in need of enhanced features like the creation
+ of complete networks of service objects, life cycle handling and such
things,
+ you should in any case use a real IoC container. For simple use cases
+ however the functionality of Commons Configuration might be sufficient,
+ and we have tried to provide hooks for extending the predefined
mechanisms.</i>
+ </p>
+
+
+<div class="section">
+<h3>Basic Concepts<a name="Basic_Concepts"></a></h3>
+
+<p>
+ Beans (we use the term <i>bean</i> here to name any plain old Java
+ object that is defined in a configuration file and can be instantiated
+ by Commons Configuration) are defined in configuration files in a
specific
+ format, a so called <i>Bean declaration</i>. Such a declaration
contains
+ all information needed to create an instance of this bean class, e.g.
+ the full qualified name of the class and initialization parameters. We
will
+ explain how a bean declaration looks like in short.
+ </p>
+
+<p>
+ On the Java side three entities are involved in the creation of a bean:
+ </p>
+<ul>
+
+<li>A <i>bean factory</i>: This is an object that implements the
+ <tt><a
href="../apidocs/org/apache/commons/configuration/beanutils/BeanFactory.html">BeanFactory</a></tt>
+ interface and knows how to create an instance of a bean class. In
most
+ cases calling code does not directly deal with a bean factory.</li>
+
+<li>An implementation of the
+ <tt><a
href="../apidocs/org/apache/commons/configuration/beanutils/BeanDeclaration.html">BeanDeclaration</a></tt>
+ interface. This object knows how the bean declaration in the
configuration
+ file is organized and how the needed information can be extracted. So
+ the way the bean is declared in the configuration file must match the
+ expectations of this object.</li>
+
+<li>The utility class
+ <tt><a
href="../apidocs/org/apache/commons/configuration/beanutils/BeanHelper.html">BeanHelper</a></tt>
+ brings all these together and performs the bean creation operation.
+ Usually client code will create a <tt>BeanDeclaration</tt> object
+ from a <tt>Configuration</tt> implementation and then pass it to
+ one of the <tt>createBean()</tt> methods of <tt>BeanHelper</tt>.
+ That's it!</li>
+ </ul>
+ For all of the interfaces mentioned above default implementations are
+ provided, which in many cases can be used out of the box.
+
+ </div>
+
+
+<div class="section">
+<h3>An Example<a name="An_Example"></a></h3>
+
+<p>
+ After this theory let's get into practice using an example. Consider a
+ GUI application that makes use of a <i>Window manager</i> to display
+ its windows and dialogs to the user. There is a <tt>WindowManager</tt>
+ interface containing methods for opening, displaying, hiding, and
+ disposing windows. Different implementations of this interface exist,
e.g.
+ providing different look & feel or special functionality. The
concrete
+ set of methods of the interface does not matter for this example.
+ </p>
+
+<p>
+ Now in the application's configuration it shall be specified that the
+ concrete implementation <tt>DefaultWindowManager</tt> should be
+ used as <tt>WindowManager</tt>. This is a plain Java class implementing
+ the <tt>WindowManager</tt> interface. Some fragments are shown in
+ the following listing:
+ </p>
+
+<div class="source">
+<pre>
+package examples.windows;
+
+public class DefaultWindowManager implements WindowManager
+{
+ // are windows allowed to be resized?
+ private boolean resizable;
+ // do windows have a close button?
+ private boolean closable;
+
+ // Default size of new windows
+ private int defaultWidth;
+ private int defaultHeight;
+
+ WindowStyleDefinition styleDefinition;
+
+ // getters and setters ommitted, also the WindowManager methods
+}
+</pre></div>
+
+<p>
+ As you can see, the <tt>DefaultWindowManager</tt> class has some
+ simple properties for defining the windows. There is also a property
+ named <tt>StyleDefinition</tt> whose type is another bean (such
+ a style definition may contain information about themes, colors, fonts
+ of the window and so on). How can we now write a configuration file so
+ that a bean of the <tt>DefaultWindowManager</tt> class is declared
+ and initialization properties are defined? In an XML configuration file
+ this will look as follows:
+ </p>
+
+<div class="source">
+<pre>
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<config>
+ <gui>
+ <windowManager
config-class="examples.windows.DefaultWindowManager"
+ closable="false" resizable="true"
defaultWidth="400"
+ defaultHeight="250">
+ <styleDefinition
config-class="examples.windows.WindowStyleDefinition"
+ backColor="#ffffff" foreColor="0080ff"
iconName="myicon" />
+ </windowManager>
+ </gui>
+</config>
+</pre></div>
+
+<p>
+ This XML document contains a valid bean declaration starting with the
+ <tt>windowManager</tt> element and including its sub elements. Note
+ the following points:
+ </p>
+<ul>
+
+<li>The (full qualified) class of the bean is specified using the
+ <tt>config-class</tt> attribute. (Attributes starting with the
+ prefix "config-" are reserved; they contain special meta
+ data for the bean creation process.)</li>
+
+<li>Other attributes of the <tt>windowManager</tt> element correspond
+ to properties of the <tt>DefaultWindowManager</tt> class. These
+ properties will be initialized with the values specified here.</li>
+
+<li>For the <tt>styleDefinition</tt> property, which is itself a
+ bean, a sub element (matching the property's name) exists. The
structure
+ of this element is analogous to the structure of the
<tt>windowManager</tt>
+ element; indeed it could even have further sub elements defining
+ bean properties of the <tt>WindowStyleDefinition</tt> class.</li>
+ </ul>
+ The basic structure of a bean declaration should have become clear by
+ this example.
+
+
+<p>
+ Now let's see how we can access this declaration and create an
instance.
+ This is demonstrated in the code fragment below:
+ </p>
+
+<div class="source">
+<pre>
+XMLConfiguration config = new XMLConfiguration("windowconfig.xml");
+BeanDeclaration decl = new XMLBeanDeclaration(config,
"gui.windowManager");
+WindowManager wm = (WindowManager) BeanHelper.createBean(decl);
+</pre></div>
+
+<p>
+ This fragment loads the configuration file using a
<tt>XMLConfiguration</tt>
+ object. Then a bean declaration object is created, in this case an
+ instance of the <tt><a
href="../apidocs/org/apache/commons/configuration/beanutils/XMLBeanDeclaration.html">XMLBeanDeclaration</a></tt>
+ class, which can deal with bean declarations in XML documents. This
+ declaration is passed to the static <tt>createBean()</tt> method of
+ the <tt><a
href="../apidocs/org/apache/commons/configuration/beanutils/BeanHelper.html">BeanHelper</a></tt>
+ class, which returns the new bean instance.
+ </p>
+
+<p>
+ <tt>BeanHelper</tt> defines some overloaded versions of the
+ <tt>createBean()</tt> method. Some allow to pass in a default bean
+ class; then it is not necessary to define the class in the bean
declaration
+ - an instance of this default class will be created if it is lacking in
+ the configuration file. If the bean cannot be created for some reason
+ (e.g. a wrong class name was specified), a
<tt>ConfigurationRuntimeException</tt>
+ will be thrown.
+ </p>
+ </div>
+
+
+<div class="section">
+<h3>Extending the Basic Mechanism<a
name="Extending_the_Basic_Mechanism"></a></h3>
+
+<p>
+ As was pointed out in the introduction of this chapter support for
creating
+ beans is focused on the basics. But there are some possibilities of
hooking
+ in and add custom extensions. This can be done in the following ways:
+ </p>
+<ul>
+
+<li>By defining a custom <tt>BeanDeclaration</tt> implementation</li>
+
+<li>By providing a custom <tt>BeanFactory</tt> implementation</li>
+ </ul>
+
+
+<p>
+ A specialized bean declaration is needed when you have to deal with
+ configuration files that contain bean declarations in a different
format
+ than the ones supported by the available default implementations. Then
it
+ is the responsibility of your implementation to parse the configuration
+ data and extract the required information to create the bean. Basically
+ your <tt><a
href="../apidocs/org/apache/commons/configuration/beanutils/BeanDeclaration.html">BeanDeclaration</a></tt>
+ implementation must be able to provide the following data:
+ </p>
+<ul>
+
+<li>The name of the class for which an instance is to be created.</li>
+
+<li>The name of the bean factory that is used to create the bean. Here
+ <b>null</b> can be returned, then a default factory is used. (See
+ below for more information about working with custom bean
factories.)</li>
+
+<li>An optional parameter to be passed to the bean factory. If a factory
+ is used that supports additional parameters, the current parameter
+ values are also obtained from the bean declaration.</li>
+
+<li>A map with the properties to be set on the newly created bean.
+ This map's keys are names of properties, its values are the
corresponding
+ property values. The default bean factory will process this map and
+ call the corresponding setter methods on the newly created bean
object.</li>
+
+<li>A map with further <tt>BeanDeclaration</tt> objects for
+ initializing properties of the new bean that are itself beans. These
+ bean declarations are treated exactly as the one that is currently
+ processed. The resulting beans will then be set as properties on the
+ processed bean (the names of these properties are again obtained from
+ the keys of the map).</li>
+ </ul>
+
+
+<p>
+ While creating a custom <tt>BeanDeclaration</tt> implementation
+ allows you to adapt the format of bean declarations in configuration
files,
+ you can manipulate the bean creation mechanism itself by creating a
+ specialized implementation of the
+ <tt><a
href="../apidocs/org/apache/commons/configuration/beanutils/BeanFactory.html">BeanFactory</a></tt>
+ interface. For this purpose the following steps are necessary:
+ </p>
+<ol style="list-style-type: decimal">
+
+<li>Create a class implementing the <tt>BeanFactory</tt> interface.
+ This interface is quite simple. It defines one method for creating an
+ instance of a class whose <tt>Class</tt> object is provided, and
+ another method, which is called for querying a default class.</li>
+
+<li>Register this new factory class at the <tt>BeanHelper</tt>
+ class.</li>
+
+<li>In the bean declaration in your configuration file refer to the
+ factory that should be used for creating the bean.</li>
+ </ol>
+
+
+<p>
+ We will provide an example that covers all these steps. This example
+ deals with a <i>singleton</i> factory, i.e. an implementation of
+ <tt>BeanFactory</tt> that returns always the same instance of a
+ provided bean class.
+ </p>
+
+<p>
+ We start with the creation of the factory class. The basic idea is that
+ the functionality for creating and initializing beans is already
provided
+ by the <tt><a
href="../apidocs/org/apache/commons/configuration/beanutils/DefaultBeanFactory.html">DefaultBeanFactory</a></tt>
+ class, so we extend this class. Our implementation only has to deal
with
+ the singleton stuff: We keep a map that stores already created bean
+ instances and can be accessed by the name of their classes. In the
+ factory's <tt>createBean()</tt> method we check if for the passed in
+ class already an instance exists. If this is the case, it is directly
+ returned. Otherwise we call the inherited <tt>createBean()</tt> method
+ and store its result in the map. (Note that this implementation is a
bit
+ simplicistic; a real world implementation would also have to take the
+ initialization parameters into account. But for the purpose of an
example
+ it should be good enough). Here is the code:
+ </p>
+
+<div class="source">
+<pre>
+public class SingletonBeanFactory extends DefaultBeanFactory
+{
+ /** A map for the so far created instances.*/
+ private Map beans;
+
+ public SingletonBeanFactory()
+ {
+ super();
+ beans = new HashMap();
+ }
+
+ // Creates the bean. Checks if already an instance exists.
+ public synchronized Object createBean(Class beanClass, BeanDeclaration
decl,
+ Object param) throws Exception
+ {
+ Object bean = beans.get(beanClass.getName());
+ if (bean != null)
+ {
+ // Yes, there is already an instance
+ return bean;
+ }
+ else
+ {
+ // No, create it now (done by the super class)
+ bean = super.createBean(beanClass, decl, param);
+ // Store it in map
+ beans.put(beanClass.getName(), bean);
+ return bean;
+ }
+ }
+}
+</pre></div>
+
+<p>
+ Note the <b>synchronized</b> key word, which is necessary because the
+ method can be accessed by multiple threads concurrently. Now we have to
+ register an instance of this class at the <tt>BeanHelper</tt> class.
+ This can be done in the initialization phase of your application and
+ looks as follows:
+ </p>
+
+<div class="source">
+<pre>
+BeanHelper.registerBeanFactory("SINGLETON", new
SingletonBeanFactory());
+</pre></div>
+
+<p>
+ To make use of the new factory a bean declaration must contain an
+ attribute that refers to the name under which the factory was
registered.
+ This is demonstrated by the fragment below:
+ </p>
+
+<div class="source">
+<pre>
+<config>
+...
+ <services>
+ <fileService
config-class="my.package.services.FileServiceImpl"
+ config-factory="SINGLETON"
+ property1="value1" property2="value2">
+ <!-- Here can be nested bean declarations -->
+ </fileService>
+ ...
+</config>
+</pre></div>
+
+<p>
+ In this fragment the <tt>fileService</tt> element contains a bean
+ declaration for some service object. Apart from the
<tt>config-class</tt>
+ attribute the important part is the <tt>config-factory</tt> attribute.
+ This attribute tells the <tt>BeanHelper</tt> class that it should
+ use a special factory when it processes this bean declaration. As was
+ demonstrated by this example, it should not be too difficult to extend
+ the custom mechanism for creating beans.
+ </p>
+ </div>
+ </div>
+
+
+
+ </td>
+ </tr>
+ </table>
+ </div>
+
+ <div class="footer">
+ <p>Copyright © 2001-2014
+ <a href="http://www.apache.org/";>The Apache Software
Foundation</a>.
+ All Rights Reserved.</p>
+
+<div class="center">Apache Commons, Apache Commons Configuration, Apache, the
Apache feather logo, and the Apache Commons project logos are trademarks of The
Apache Software Foundation.
+ All other marks mentioned may be trademarks or registered trademarks of
their respective owners.</div>
+ </div>
+ </body>
+
+</html>
![http://www.apache.org/events/current-event-125x125.png"](http://www.apache.org/events/current-event-125x125.png"){kind=link}
![http://maven.apache.org/images/logos/maven-feather.png"](http://maven.apache.org/images/logos/maven-feather.png"){kind=link}