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, 0 insertions, 294 deletions
diff --git a/qpid/doc/book/src/old/Java-Broker-StatusLogMessages.xml b/qpid/doc/book/src/old/Java-Broker-StatusLogMessages.xml deleted file mode 100644 index 98f876e532..0000000000 --- a/qpid/doc/book/src/old/Java-Broker-StatusLogMessages.xml +++ /dev/null @@ -1,294 +0,0 @@ -<?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> |