diff options
Diffstat (limited to 'documentation/content/xdocs/Qpid Design - Configuration.html')
| -rwxr-xr-x | documentation/content/xdocs/Qpid Design - Configuration.html | 166 |
1 files changed, 166 insertions, 0 deletions
diff --git a/documentation/content/xdocs/Qpid Design - Configuration.html b/documentation/content/xdocs/Qpid Design - Configuration.html new file mode 100755 index 0000000000..34c2b38f25 --- /dev/null +++ b/documentation/content/xdocs/Qpid Design - Configuration.html @@ -0,0 +1,166 @@ +<html> + <head> + <title>Apache Qpid : Qpid Design - Configuration</title> + <link rel="stylesheet" href="styles/site.css" type="text/css" /> + <META http-equiv="Content-Type" content="text/html; charset=UTF-8"> + </head> + + <body> + <table class="pagecontent" border="0" cellpadding="0" cellspacing="0" width="100%" bgcolor="#ffffff"> + <tr> + <td valign="top" class="pagebody"> + <div class="pageheader"> + <span class="pagetitle"> + Apache Qpid : Qpid Design - Configuration + </span> + </div> + <div class="pagesubheading"> + This page last changed on Oct 19, 2006 by <font color="#0050B2">rgreig</font>. + </div> + + <h3><a name="QpidDesign-Configuration-ConfigurationMethods"></a>Configuration Methods</h3> + +<p>QPID supports two methods of configuration:</p> +<ol> + <li>command line switches (e.g. passing a -p flag on startup to specify the port)</li> + <li>configuration file</li> +</ol> + + +<p>It is intended that the configuration file will be used for nearly all configuration but that some very common or useful options are exposed using command line switches.</p> + +<h3><a name="QpidDesign-Configuration-CLI"></a>CLI</h3> + +<p>QPID uses <a href="http://jakarta.apache.org/commons/cli" title="Visit page outside Confluence">Commons CLI</a> to parse command line arguments. It provides the following features:</p> +<ul> + <li>Ability to parse both short and long flags (e.g. -p and --port) and treat them as the same logical option</li> + <li>Generation of well formatted usage messages</li> + <li>Ability to specify configuration options in different ways, such as from files or from system properties, which can help when writing unit tests</li> +</ul> + + +<p>The result of parsing options, however they are specified, is a CommandLine object which can then be queried to find out specific values. Currently this is done in org.openamq.broker.Main and the CommandLine object is not exposed elsewhere but if it does require to be more widely used it could be added to the ApplicationRegistry. However it is strongly recommended that the configuration approach in the follow section is used where possible.</p> + +<h3><a name="QpidDesign-Configuration-ConfigurationFile"></a>Configuration File</h3> + +<p>QPID uses <a href="http://jakarta.apache.org/commons/configuration" title="Visit page outside Confluence">Commons Configuration</a> to handle nearly all configuration. It provides methods that allow parsing of options from a range of sources, including configuration files, system properties or simply hard coded classes of values (which is very useful in unit test cases).</p> + +<p>The file format used by QPID is XML, and Commons Configuration allows a very simple XPath-like syntax to query individual elements from the configuration file.</p> + +<p>In order to make using configuration as non-intrusive, flexible and strongly-typed as possible we do the following:</p> +<ul> + <li><a name="QpidDesign-Configuration-ConfiguredObjects"></a> Create classes representing configuration options for a particular component. For example, we have an object to represent all the connection (transport) configuration options. That object is used by the transport-related code rather than dealing with the Commons Configuration objects directly. As well as being strongly typed and easily used in unit tests, this means that a developer can see all the configuration options related to a particular feature in one place.</li> + <li>To make it easier to map between elements in the configuration file and fields in the configuration objects, a Configurable annotation (Java 5 annotation) is applied to the fields in the configuration object which contains the path expression in the configuration file, and default values should no value be specified</li> + <li>The configuration objects are stored in the ApplicationRegistry</li> + <li><a name="QpidDesign-Configuration-Configuration"></a>The commons configuration object is stored in the ApplicationRegistry allowing "direct access" to the raw options should this be required</li> +</ul> + + +<h3><a name="QpidDesign-Configuration-Example"></a>Example</h3> + +<p>An example should make this clearer. Consider a (fictional) configuration file containing the following XM</p> +<div class="code"><div class="codeContent"> +<pre class="code-java"><qpid>
+ <connector>
+ <ssl><span class="code-keyword">true</span></ssl>
+ <port>5672</port>
+ </connector>
+</qpid></pre> +</div></div> +<p>To use this in the application we would define a class to represent it:</p> +<div class="code"><div class="codeContent"> +<pre class="code-java"><span class="code-keyword">public</span> class ConnectionConfig
+{
+ <span class="code-keyword">public</span> <span class="code-keyword">static</span> <span class="code-keyword">final</span> <span class="code-object">String</span> SSL_PORT = <span class="code-quote">"8672"</span>;
+
+ @Configured(path = <span class="code-quote">"connector.port"</span>,
+ defaultValue = DEFAULT_PORT)
+ <span class="code-keyword">public</span> <span class="code-object">int</span> port;
+
+ @Configured(path = <span class="code-quote">"connector.ssl"</span>,
+ defaultValue = <span class="code-quote">"<span class="code-keyword">false</span>"</span>)
+ <span class="code-keyword">public</span> <span class="code-object">boolean</span> enableSSL;
+}</pre> +</div></div> +<p>Note the use of @Configured to define the mapping between the configuration file and the field values.</p> + +<p>All we need to do the access this configuration object <em>anywhere within the application</em> is call:</p> +<div class="code"><div class="codeContent"> +<pre class="code-java">ConnectionConfig cfg = ApplicationRegistry.getInstance().getConfiguredObject(ConnectionConfig.class);</pre> +</div></div> +<p>The ApplicationRegistry is documented elsewhere but from the configuration perspective all you need to know is that the first time getConfiguredObject is called for a particular class, the configuration file is parsed and the configuration object is stored for future use. Subsequent calls to getConfiguredObject for the same class are very cheap since only a hash table lookup is done.</p> + +<h3><a name="QpidDesign-Configuration-CommandLineOptions"></a>Command Line Options</h3> + +<p>The following options are available:</p> + +<table class='confluenceTable'><tbody> +<tr> +<th class='confluenceTh'>Option</th> +<th class='confluenceTh'>Long Option</th> +<th class='confluenceTh'>Description</th> +</tr> +<tr> +<td class='confluenceTd'>b</td> +<td class='confluenceTd'>bind</td> +<td class='confluenceTd'>Bind to the specified address overriding any value in the config file</td> +</tr> +<tr> +<td class='confluenceTd'>c</td> +<td class='confluenceTd'>config</td> +<td class='confluenceTd'>Use the given configuration file</td> +</tr> +<tr> +<td class='confluenceTd'>h</td> +<td class='confluenceTd'>help</td> +<td class='confluenceTd'>Prints list of options</td> +</tr> +<tr> +<td class='confluenceTd'>l</td> +<td class='confluenceTd'>logconfig</td> +<td class='confluenceTd'>Use the specified log4j.xml file rather than that in the etc directory</td> +</tr> +<tr> +<td class='confluenceTd'>p</td> +<td class='confluenceTd'>port</td> +<td class='confluenceTd'>Specify port to listen on. Overrides value in config file</td> +</tr> +<tr> +<td class='confluenceTd'>v</td> +<td class='confluenceTd'>version</td> +<td class='confluenceTd'>Print version information and exit</td> +</tr> +<tr> +<td class='confluenceTd'>w</td> +<td class='confluenceTd'>logwatch</td> +<td class='confluenceTd'>Specify interval for checking for logging config changes. Zero means no checking</td> +</tr> +</tbody></table> + +<h3><a name="QpidDesign-Configuration-Logging"></a>Logging</h3> + +<p>Logging is handled slightly differently. The main reason for this is that logging is something we want configured before the main configuration file is processed.</p> + +<p>The broker uses log4j as the logging implementation, and configuration must be done using the more expressive XML format. A couple of command line switches are used to configure logging:</p> +<ul> + <li>-l, --logconfig specifies the log configuration file to use. By default it looks for a file called log4j.xml located in the same directory as the config.xml file</li> + <li>-w, --logwatch the interval in seconds to poll the log configuration file for changes. The default is 60 seconds and zero means do not poll for changes.</li> +</ul> + + +<p>By using the logwatch option it is possible to make changes to the logging configuration at runtime without restarting the broker. (For example, enabling more logging on certain packages in order to diagnose a problem).</p> + + + </td> + </tr> + </table> + <table border="0" cellpadding="0" cellspacing="0" width="100%"> + <tr> + <td height="12" background="border/border_bottom.gif"><img src="border/spacer.gif" width="1" height="1" border="0"/></td> + </tr> + <tr> + <td align="center"><font color="grey">Document generated by Confluence on Apr 22, 2008 02:47</font></td> + </tr> + </table> + </body> +</html>
\ No newline at end of file |