diff options
Diffstat (limited to 'qpid/doc/book/src/old/Java-Broker-StatusLogMessages.xml')
| -rw-r--r-- | qpid/doc/book/src/old/Java-Broker-StatusLogMessages.xml | 294 |
1 files changed, 294 insertions, 0 deletions
diff --git a/qpid/doc/book/src/old/Java-Broker-StatusLogMessages.xml b/qpid/doc/book/src/old/Java-Broker-StatusLogMessages.xml new file mode 100644 index 0000000000..98f876e532 --- /dev/null +++ b/qpid/doc/book/src/old/Java-Broker-StatusLogMessages.xml @@ -0,0 +1,294 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + + 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. + +--> +<?oxygen RNGSchema="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" type="xml"?> +<book xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"> + <info> + <title>Operational Logging</title> + <author> + <orgname>Apache Software Foundation</orgname> + </author> + </info> + <chapter> + <title>Status Log Messages</title> + <para>This file was derivied from LogMessages used within the Java Broker and originally defined on: + <tag xlink:href="http://cwiki.apache.org/confluence/display/qpid/Status+Update+Design#StatusUpdateDesign-InitialStatusMessages">Apache Wiki</tag></para> + <sect1> + <title>Technical Notes:</title> + <para>The status log messages file is a standard Java Properties file so white space is respected at the end of + the lines. This file could be processed in a number of ways:</para> + <para> + <orderedlist> + <listitem> + <para>ResourceBundle</para> + <para>This file is loaded as a ResourceBundle. The en_US addition to the + file is the localisation. Additional localisations can be provided and + will automatically be selected based on the <locale> value in the + config.xml. The default locale is en_US.</para> + </listitem> + <listitem> + <para>MessageFormat</para> + <para> Each entry is prepared with the Java Core MessageFormat methods. + Therefore most functionality you can do via MessageFormat can be done + here: </para> + <para><tag xlink:href="http://java.sun.com/javase/6/docs/api/java/text/MessageFormat.html">Java API for MessageFormat</tag></para> + <para>The caveat here is that only default String and number FormatTypes can + be used. This is due to the processing described in 3 below. If support + for date, time or choice is required then the GenerateLogMessages class + should be updated to provide support.</para> + </listitem> + <listitem> + <para>GenerateLogMessage/Velocity Macro</para> + <para>This is the only processing that this file goes through</para> + <orderedlist> + <listitem> + <para>Class Generation:</para> + <para>The GenerateLogMessage processes this file and uses the + velocity Macro to create classes with static methods to perform + the logging and give us compile time validation. </para> + </listitem> + <listitem> + <para>Property Processing</para> + <para>During the class generation the message properties ({x}) are + identified and used to create the method signature.</para> + </listitem> + <listitem> + <para>Option Processing</para> + <para>The Classes perform final formatting of the messages at + runtime based on optional parameters that are defined within the + message. Optional parameters are enclosed in square brackets + e.g. [optional].</para> + </listitem> + </orderedlist> + </listitem> + </orderedlist> + </para> + <para><emphasis role="bold">Format Note:</emphasis></para> + <para> As mentioned earlier white space in this file is very important. One thing in + particular to note is the way MessageFormat performs its replacements. The + replacement text will totally replace the {xxx} section so there will be no addition + of white space or removal e.g. </para> + <programlisting><![CDATA[MSG = Text----{0}----]]> + </programlisting> + <para> When given parameter 'Hello' result in text: </para> + <programlisting><![CDATA[Text----Hello----]]> + </programlisting> + <para>For simple arguments this is expected however when using Style formats then it can + be a little unexpected. In particular a common pattern is used for number + replacements : {0,number,}. This is used in the Broker to display an Integer simply + as the Integer with no formatting. e.g new Integer(1234567) becomes the String + "1234567" which is can be contrasted with the pattern without a style format field : + {0,number} which becomes string "1,234,567".</para> + <para>What you may not expect is that {0,number, } would produce the String " 1234567" + note that the space after the ',' here has resulted in a space in front of the + number in the output.</para> + <para>More details on the SubformatPattern can be found on the API link above. To + provide fixed log messages as required by the Technical Specification:</para> + <para><tag xlink:href="http://cwiki.apache.org/confluence/display/qpid/Operational+Logging+-+Status+Update+-+Technical+SpecificationOperationalLogging-StatusUpdate-TechnicalSpecification-Howtoprovidefixedlogmessages">Operational Logging Tech Specification</tag></para> + <para>This file is processed by Velocity to create a number of classes that contain + static methods that provide LogMessages in the code to provide compile time + validation.</para> + <para>For details of what processing is done see GenerateLogMessages. </para> + <para>What a localiser or developer need know is the following: </para> + <para>The Property structure is important as it defines how the class and methods will + be built.</para> + </sect1> + <sect1> + <title>Class Generation</title> + <para> Each class of messages will be split in to their own <Class>Messages.java. + Each logmessage file contains only one class of messages the <Class> name is + derived from the name of the logmessages file e.g. <Class>_logmessages.properties. + </para> + </sect1> + <sect1> + <title>Property Format</title> + <para>The property format MUST adhere to the follow format to make it easier to use the + logging API as a developer but also so that operations staff can easily locate log + messages in the output.</para> + <para>The property file should contain entries in the following format:</para> + <programlisting><![CDATA[<Log Identifier,developer focused>=<Log Identifier,Operate focus>:<Log Message>]]> + </programlisting> + + <para>eg:</para> + <programlisting><![CDATA[SHUTTING_DOWN = BRK-1003 : Shutting down : {0} port {1,number,}]]> + </programlisting> + + <para>Note: the developer focused identifier will become a method name so only a valid + method name should be used. Currently only '-' are converted to '_'.</para> + <para>That said properties generate the logging code at build time so any error can be + easily identified.</para> + <para>The three character identifier show above in BRK-1003 should ideally be unique. + This is the only requirement, limiting to 3 characters is not required.</para> + <para>The current broker contains the following mappings:</para> + <para> + <table> + <title>Status Messages Mapping</title> + <tgroup cols="2"> + <colspec colname="c1" colnum="1" colwidth="118.29pt"/> + <colspec colname="c2" colnum="2" colwidth="135.18pt"/> + <thead> + <row> + <entry>Class</entry> + <entry> Type</entry> + </row> + </thead> + <tbody> + <row> + <entry>Broker</entry> + <entry>BRK</entry> + </row> + <row> + <entry>Management Console</entry> + <entry>MNG</entry> + </row> + <row> + <entry>VirtualHost</entry> + <entry>VHT</entry> + </row> + <row> + <entry>MessageStore</entry> + <entry>MST</entry> + </row> + <row> + <entry>ConfigStore</entry> + <entry>CFG</entry> + </row> + <row> + <entry>TransactionLog</entry> + <entry>TXN</entry> + </row> + <row> + <entry>Connection</entry> + <entry>CON</entry> + </row> + <row> + <entry>Channel</entry> + <entry>CHN</entry> + </row> + <row> + <entry>Queue</entry> + <entry>QUE</entry> + </row> + <row> + <entry>Exchange</entry> + <entry>EXH</entry> + </row> + <row> + <entry>Binding</entry> + <entry>BND</entry> + </row> + <row> + <entry>Subscription</entry> + <entry>SUB</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + </sect1> + <sect1> + <title>Property Processing</title> + <para> + Each property is then processed by the GenerateLogMessages class to identify + the number and type of parameters, {x} entries. Parameters are defaulted to + String types but the use of FormatType number (e.g.{0,number}) will result + in a Number type being used. These parameters are then used to build the + method parameter list. e.g: + </para> + + <para>Property:</para> + <programlisting><![CDATA[SHUTTING_DOWN = BRK-1003 : Shutting down : {0} port {1,number,}]]></programlisting> + <para>becomes Method:</para> + <programlisting><![CDATA[public static LogMessage SHUTTING_DOWN(String param1, Number param2)]]> + </programlisting> + + <para> + This improves our compile time validation of log message content and + ensures that change in the message format does not accidentally cause + erroneous messages.</para> + </sect1> + <sect1> + <title>Option Processing</title> + <para> + Options are identified in the log message as being surrounded by square + brackets ([ ]). These optional values can themselves contain parameters + however nesting of options is not permitted. Identification is performed on + first matching so given the message: + </para> + <programlisting><![CDATA[Msg = Log Message [option1] [option2] ]]></programlisting> + <para> + Two options will be identified and enabled to select text 'option1' and + 'option2'. + </para> + <para> + The nesting of a options is not supported and will provide + unexpected results. e.g. Using Message: + </para> + <programlisting><![CDATA[Msg = Log Message [option1 [sub-option2]] ]]></programlisting> + <para> + The options will be 'option1 [sub-option2' and 'sub-option2'. The first + option includes the second option as the nesting is not detected. + </para> + <para> + The detected options are presented in the method signature as boolean options + numerically identified by their position in the message. e.g. + Property: + </para> + <programlisting><![CDATA[ CON-1001 = Open : Client ID {0} [: Protocol Version : {1}] ]]></programlisting> + <para>becomes Method:</para> + <programlisting><![CDATA[ public static LogMessage CON_1001(String param1, String param2, boolean opt1) ]]></programlisting> + <para> + The value of 'opt1' will show/hide the option in the message. Note that + 'param2' is still required however a null value can be used if the optional + section is not desired. + </para> + <para> + Again here the importance of white space needs to be highlighted. + Looking at the QUE-1001 message as an example. The first thought on how this + would look would be as follows: + </para> + <programlisting><![CDATA[ QUE-1001 = Create : Owner: {0} [AutoDelete] [Durable] [Transient] [Priority: {1,number,}] ]]></programlisting> + <para> + Each option is correctly defined so the text that is defined will appear when + selected. e.g. 'AutoDelete'. However, what may not be immediately apparent is + the white space. Using the above definition of QUE-1001 if we were to print + the message with only the Priority option displayed it would appear as this: + </para> + <programlisting><![CDATA[ "Create : Owner: guest Priority: 1" ]]></programlisting> + <para> + Note the spaces here in between gues and Priority are present because only the text between the brackets + has been removed. + </para> + <para> + Each option needs to include white space to correctly format the message. So + the correct definition of QUE-1001 is as follows: + </para> + <programlisting><![CDATA[ QUE-1001 = Create : Owner: {0}[ AutoDelete][ Durable][ Transient][ Priority: {1,number,}] ]]></programlisting> + <para> + Note that white space is included with each option and there is no extra + white space between the options. As a result the output with just Priority + enabled is as follows: + </para> + <programlisting><![CDATA[ "Create : Owner: guest Priority: 1" ]]></programlisting> + </sect1> + </chapter> +</book> |