| <!DOCTYPE html> |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 1.8.1 |
| | Rendered using Apache Maven Fluido Skin 1.6 |
| --> |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta charset="UTF-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /> |
| <meta name="author" content="Brett Porter" /> |
| <meta http-equiv="Content-Language" content="en" /> |
| <title>Spring Registry Component – Plexus Registry Component</title> |
| <link rel="stylesheet" href="./css/apache-maven-fluido-1.6.min.css" /> |
| <link rel="stylesheet" href="./css/site.css" /> |
| <link rel="stylesheet" href="./css/print.css" media="print" /> |
| <script type="text/javascript" src="./js/apache-maven-fluido-1.6.min.js"></script> |
| <!-- Google Analytics --> |
| <script type="text/javascript"> |
| var _gaq = _gaq || []; |
| _gaq.push(['_setAccount', 'UA-140879-5']); |
| _gaq.push(['_trackPageview']); |
| (function() { |
| var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; |
| ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; |
| var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); |
| })(); |
| </script> |
| </head> |
| <body class="topBarEnabled"> |
| <a href="https://github.com/apache/archiva"> |
| <img style="position: absolute; top: 0; right: 0; border: 0; z-index: 10000;" |
| src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png" |
| alt="Fork me on GitHub"> |
| </a> |
| <div id="topbar" class="navbar navbar-fixed-top "> |
| <div class="navbar-inner"> |
| <div class="container"><div class="nav-collapse"> |
| <ul class="nav"> |
| <li class="dropdown"> |
| <a href="#" class="dropdown-toggle" data-toggle="dropdown">Modules <b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| <li><a href="spring-registry-api/index.html" title="Redback Spring Registry Api">Redback Spring Registry Api</a></li> |
| <li><a href="spring-registry-commons/index.html" title="Redback Spring Registry commons-configuration">Redback Spring Registry commons-configuration</a></li> |
| </ul> |
| </li> |
| <li class="dropdown"> |
| <a href="#" class="dropdown-toggle" data-toggle="dropdown">ASF <b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| <li><a href="http://www.apache.org/foundation/how-it-works.html" title="How Apache Works">How Apache Works</a></li> |
| <li><a href="http://www.apache.org/foundation/" title="Foundation">Foundation</a></li> |
| <li><a href="http://www.apache.org/foundation/sponsorship.html" title="Sponsoring Apache">Sponsoring Apache</a></li> |
| <li><a href="http://www.apache.org/foundation/thanks.html" title="Thanks">Thanks</a></li> |
| </ul> |
| </li> |
| <li class="dropdown"> |
| <a href="#" class="dropdown-toggle" data-toggle="dropdown">Project Documentation <b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| <li class="dropdown-submenu"> |
| <a href="project-info.html" title="Project Information">Project Information</a> |
| <ul class="dropdown-menu"> |
| <li><a href="index.html" title="About">About</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| <form id="search-form" action="https://www.google.com/search" method="get" class="navbar-search pull-right" > |
| <input value="http://archiva.apache.org/redback/components" name="sitesearch" type="hidden"/> |
| <input class="search-query" name="q" id="query" type="text" /> |
| </form> |
| <script type="text/javascript">asyncJs( 'https://cse.google.com/brand?form=search-form' )</script> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="container"> |
| <div id="banner"> |
| <div class="pull-left"><a href="http://archiva.apache.org/index.html" id="bannerLeft"><img src="http://archiva.apache.org/images/archiva.png" alt="Apache Archiva"/></a></div> |
| <div class="pull-right"><a href="http://www.apache.org/" id="bannerRight"><img src="http://www.apache.org/images/asf_logo_wide.png" alt="Apache Software Foundation"/></a></div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| <li class=""><a href="http://archiva.apache.org/index.html" class="externalLink" title="Archiva">Archiva</a><span class="divider">/</span></li> |
| <li class=""><a href="../index.html" title="Redback Components">Redback Components</a><span class="divider">/</span></li> |
| <li class=""><a href="index.html" title="Spring Registry">Spring Registry</a><span class="divider">/</span></li> |
| <li class="active ">Plexus Registry Component</li> |
| <li id="projectVersion" class="pull-right">Version: 2.5-SNAPSHOT</li> |
| </ul> |
| </div> |
| <div id="bodyColumn" > |
| <div class="section"> |
| <h2><a name="Plexus_Registry"></a>Plexus Registry</h2> |
| <p>The Plexus registry is a single source of external configuration for Plexus components and applications. It can be used by components to source configuration, knowing that it can be used from within applications without the information being hard coded into the component.</p> |
| <p>To facilitate a variety of providers, <a class="externalLink" href="http://jakarta.apache.org/commons/configuration/"> Commons Configuration</a> is used to implement the backing storage.</p> |
| <p>This relies on a pull-based (or lookup) mechanism - the applications request specific pieces of configuration at the time they need them, and it is retrieved from the registry.</p> |
| <p>The registry is configurable so that configuration can be placed in any location desired, and is shared container wide. A registry using the same file as other running VMs should operate correctly.</p> |
| <p><i>Note:</i> Inside the application server, this means that the scope is application wide as each application has it's own container. It may be feasible to provide a single registry for the whole server, but this has not yet been tested. This would only be necessary if the server was to dictate configuration locations that the registry was not already configured to use. Of course, such additional locations could be added to the application registry instances programmatically as well.</p> |
| <div class="section"> |
| <h3><a name="Example_Configuration"></a>Example Configuration</h3> |
| <div> |
| <pre><component> |
| <role>org.codehaus.redback.components.registry.Registry</role> |
| <implementation>org.codehaus.plexus.registry.CommonsConfigurationRegistry</implementation> |
| <role-hint>commons-configuration</role-hint> |
| <configuration> |
| <properties> |
| <system/> |
| <jndi prefix="java:comp/env" config-optional="true"/> |
| <xml fileName="${user.home}/.m2/archiva.xml" config-optional="true" config-name="org.apache.maven.archiva" |
| config-at="org.apache.maven.archiva" config-forceCreate="true"/> |
| <properties fileName="${user.home}/.m2/security.properties" config-optional="true" |
| config-at="org.codehaus.plexus.security"/> |
| </properties> |
| </configuration> |
| </component></pre></div> |
| <p>The configuration inside the outer <tt><properties></tt> element is equivalent to the <a class="externalLink" href="http://jakarta.apache.org/commons/configuration/howto_configurationbuilder.html#Using_DefaultConfigurationBuilder"> builder syntax</a> for Commons Configuration. This maps to similar concepts in the registry.</p> |
| <p>In this example, the precedence is to first look in the system properties, then JNDI, then the given XML file, and finally the given properties file.</p> |
| <p>Registries can have 'sections', which are declared as partitioned areas of the registry. This is done using the <tt>config-name</tt> attribute in Commons Configuration. While the sections behave normally as a part of the global registry, they can easily be retrieved independently. This is particularly useful for write-back operations so the file the section is stored in can be saved when the registry is modified.</p> |
| <p>Each configuration source can be configured with a given mount-point in the registry using the <tt>config-at</tt> attribute. This will cause all of the properties to be stored with the given prefix.</p></div> |
| <div class="section"> |
| <h3><a name="Using_the_Registry"></a>Using the Registry </h3> |
| <p>The registry can be used as a simple directory, for example:</p> |
| <div> |
| <pre>int value = registry.getInt( "test.property" ); |
| String text = registry.getString( "text.data" ); |
| boolean enabled = registry.getBoolean( "system.enabled", true );</pre></div> |
| <p>The first parameter is always a key. The registry is hierachical, so in the key, a <tt>.</tt> (period) represents a nested configuration, and can be traversed to any level.</p> |
| <p>The second parameter specifies a default value. If it is not given, then <tt>null</tt> is returned for strings if the key is not found in the registry, and an exception is thrown for integers and booleans under the same circumstances.</p> |
| <div class="section"> |
| <h4><a name="Subsets_and_Sections"></a>Subsets and Sections</h4> |
| <p>There are two ways to work with a portion of the registry at a time: subsets and sections.</p> |
| <p>Sections were encountered earlier - and while they return a subset it may span a number of different base prefixes, depending on whether <tt>config-at</tt> was specified on the section or not. Even so, if it is a subset of the hierachy, some elements of the hierachy at the same level might not be returned because they come from a different section.</p> |
| <p>On the other hand, subsets are reductions of the registry to keys descending from a given prefix.</p> |
| <p>Once a subset (or section) is obtained, it behaves the same as the registry as a whole, however it will have fewer values, and looking up values will not have the prefix as a part of the key.</p> |
| <p>For example:</p> |
| <div> |
| <pre>String value = registry.getString( "org.codehaus.plexus.registry.value" ); |
| Registry subset = registry.getSubset( "org.codehaus.plexus.registry" ); |
| value = subset.getString( "value" ); // this will equal the earlier value retrieved</pre></div></div> |
| <div class="section"> |
| <h4><a name="Lists_and_Maps"></a>Lists and Maps</h4> |
| <p>It is also possible to retrieve subsets of the registry as collections.</p> |
| <ul> |
| <li><tt>getProperties(key)</tt>: Maps and properties are straightforward - the subset is converted into key/value pairs and returned as a map.</li> |
| <li><tt>getSubsetList(key)</tt>: For lists of complex types that will still contain more than one key/value pair, this method can be used to retrieve them as a list of subset registries.</li> |
| <li><tt>getList(key)</tt>: For lists of simple types, this method can be used to get a list of value objects.</li></ul></div> |
| <div class="section"> |
| <h4><a name="Using_Models"></a>Using Models</h4> |
| <p>To simplify the translation of configuration into reusable beans and to produce a self-documenting system, Modello can be used to generate registry I/O classes. The appropriate goals in the plugin are <tt>registry-reader</tt> and <tt>registry-writer</tt>.</p></div> |
| <div class="section"> |
| <h4><a name="Saving_Changes"></a>Saving Changes</h4> |
| <p>Saving changes to a registry is quite simple:</p> |
| <div> |
| <pre>registry.save();</pre></div> |
| <p>Note that the registry must be a file-based section (saving the entire registry will not succeed). It will be saved to the same location that it was loaded from.</p></div> |
| <div class="section"> |
| <h4><a name="Adding_Change_Listeners"></a>Adding Change Listeners</h4></div></div></div> |
| </div> |
| </div> |
| <hr/> |
| <footer> |
| <div class="container"> |
| <div class="row"> |
| <p>Copyright ©2006–2018 |
| <a href="http://www.apache.org/">The Apache Software Foundation</a>. |
| All rights reserved.</p> |
| </div> |
| <p id="poweredBy" class="pull-right"> <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="./images/logos/maven-feather.png" /></a> |
| </p> |
| <div id="ohloh" class="pull-right"> |
| <script type="text/javascript" src="https://www.ohloh.net/p/6670/widgets/project_thin_badge.js"></script> |
| </div> |
| </div> |
| </footer> |
| </body> |
| </html> |
