qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ritch...@apache.org
Subject svn commit: r888363 - /qpid/branches/0.5.x-dev/qpid/java/broker/src/main/java/org/apache/qpid/server/logging/messages/LogMessages.properties
Date Tue, 08 Dec 2009 12:15:16 GMT
Author: ritchiem
Date: Tue Dec  8 12:15:15 2009
New Revision: 888363

URL: http://svn.apache.org/viewvc?rev=888363&view=rev
Log:
QPID-1992 : Re-added comments to top of LogMessages

Modified:
    qpid/branches/0.5.x-dev/qpid/java/broker/src/main/java/org/apache/qpid/server/logging/messages/LogMessages.properties

Modified: qpid/branches/0.5.x-dev/qpid/java/broker/src/main/java/org/apache/qpid/server/logging/messages/LogMessages.properties
URL: http://svn.apache.org/viewvc/qpid/branches/0.5.x-dev/qpid/java/broker/src/main/java/org/apache/qpid/server/logging/messages/LogMessages.properties?rev=888363&r1=888362&r2=888363&view=diff
==============================================================================
--- qpid/branches/0.5.x-dev/qpid/java/broker/src/main/java/org/apache/qpid/server/logging/messages/LogMessages.properties
(original)
+++ qpid/branches/0.5.x-dev/qpid/java/broker/src/main/java/org/apache/qpid/server/logging/messages/LogMessages.properties
Tue Dec  8 12:15:15 2009
@@ -17,6 +17,195 @@
 #  under the License.
 #
 # Default File used for all non-defined locales.
+#
+# LogMessages used within the Java Broker as originally defined on the wiki:
+# http://cwiki.apache.org/confluence/display/qpid/Status+Update+Design#StatusUpdateDesign-InitialStatusMessages
+#
+# Technical Notes:
+#  This is a standard Java Properties file so white space is respected at the
+#  end of the lines. This file is processed in a number of ways.
+# 1) ResourceBundle
+#   This file is loaded through a ResourceBundle named LogMessages. 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 is en_US.
+#
+# 2) MessasgeFormat
+#  Each entry is prepared with the Java Core MessageFormat methods. Therefore
+#  most functionality you can do via MessageFormat can be done here:
+#
+#  http://java.sun.com/javase/6/docs/api/java/text/MessageFormat.html
+#
+#  The cavet 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 requried then the GenerateLogMessages class should be updated to
+#  provide support.
+#
+#  Format Note:
+#   As mentioned earlier white space in this file is very important. One thing
+#  in particular to note is the way MessageFormat peforms its replacements.
+#  The replacement text will totally replace the {xxx} section so there will be
+#  no addtion of white space or removal e.g.
+#     MSG = Text----{0}----
+#  When given parameter 'Hello' result in text:
+#     Text----Hello----
+#
+#  For simple arguments this is expected however when using Style formats then
+#  it can be a little unexepcted. 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 formating. 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".
+#
+#  What you may not expect is that {0,number, #} would produce the String " 1234567"
+#  note the space after the ','   here      /\   has resulted in a space  /\ in
+#  the output.
+#
+#  More details on the SubformatPattern can be found on the API link above.
+#
+# 3) GenerateLogMessage/Velocity Macro
+#  This is the first and final stage of processing that this file goes through.
+#   1) Class Generation:
+#      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.
+#
+#   2) Property Processing:
+#      During the class generation the message properties ({x}) are identified
+#      and used to create the method signature.
+#
+#   3) Option Processing:
+#      The Classes perform final formatting of the messages at runtime based on
+#      optional parameters that are defined within the message. Optional
+#      paramters are enclosed in square brackets e.g. [optional].
+#
+#  To provide fixed log messages as required by the Technical Specification:
+#  http://cwiki.apache.org/confluence/display/qpid/Operational+Logging+-+Status+Update+-+Technical+Specification#OperationalLogging-StatusUpdate-TechnicalSpecification-Howtoprovidefixedlogmessages
+#
+#  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.
+#
+#  For details of what processing is done see GenerateLogMessages.
+#
+#  What a localiser or developer need know is the following:
+#
+#  The Property structure is important is it defines how the class and methods
+#  will be built.
+#
+#  Class Generation:
+#  =================
+#
+#  Each class of messages will be split in to their own <Class>Messages.java
+#  Currently the following classes are created and are populated with the
+#  messages that bear their 3-digit type identifier:
+#
+#        Class              | Type
+#      ---------------------|--------
+#        Broker             |  BKR
+#        ManagementConsole  |  MNG
+#        VirtualHost        |  VHT
+#        MessageStore       |  MST
+#        ConfigStore        |  CFG
+#        TransactionLog     |  TXN
+#        Connection         |  CON
+#        Channel            |  CHN
+#        Queue              |  QUE
+#        Exchange           |  EXH
+#        Binding            |  BND
+#        Subscription       |  SUB
+#
+#  Property Format
+#  ===============
+#   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.
+#
+#   The property file should contain entries in the following format
+#
+#   <Log Identifier, developer focused> = <Log Identifier, Operate focus> : <Log
Message>
+#
+#   eg:
+#    BRK_SHUTTING_DOWN = BRK-1003 : Shuting down : {0} port {1,number,#}
+#
+#   Note: the developer focused identifier will become a method name so only a
+#   valid method name should be used. Currently only '-' are converted to '_'.
+#
+#   That said properties generate the logging code at build time so any error
+#   can be easily identified.
+#
+#  Property Processing:
+#  ====================
+#
+#   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:
+#   Property:
+#    BRK_SHUTTING_DOWN = BRK-1003 : Shuting down : {0} port {1,number,#}
+#   becomes Method:
+#    public static LogMessage BRK_SHUTTING_DOWN(String param1, Number param2)
+#
+#   This improves our compile time validation of log message content and
+#   ensures that change in the message format does not accidentally cause
+#   erroneous messages.
+#
+#  Option Processing:
+#  ====================
+#
+#  Options are identified in the log message as being surrounded by square
+#  brackets ([ ]). These optional values can themselves contain paramters
+#  however nesting of options is not permitted. Identification is performed on
+#  first matchings so give the message:
+#   Msg = Log Message [option1] [option2]
+#  Two options will be identifed and enabled to select text 'option1 and
+#  'option2'.
+#
+#  The nesting of a options is not supported and will provide
+#  unexpected results. e.g. Using Message:
+#   Msg = Log Message [option1 [sub-option2]]
+#
+#  The options will be 'option1 [sub-option2' and 'sub-option2'. The first
+#  option includes the second option as the nesting is not detected.
+#
+#  The detected options are presented in the method signature as boolean options
+#  numerically identified by their position in the message. e.g.
+#   Property:
+#    CON-1001 = Open : Client ID {0} [: Protocol Version : {1}]
+#  becomes Method:
+#    public static LogMessage CON_1001(String param1, String param2, boolean opt1)
+#
+#  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.
+#
+#  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:
+# QUE-1001 = Create : Owner: {0} [AutoDelete] [Durable] [Transient] [Priority: {1,number,#}]
+#  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:
+#  "Create : Owner: guest    Priority: 1"
+#  Note the spaces here   /\ This is because only the text between the brackets
+#  has been removed.
+#
+#  Each option needs to include white space to correctly format the message. So
+#  the correct definition of QUE-1001 is as follows:
+# QUE-1001 = Create : Owner: {0}[ AutoDelete][ Durable][ Transient][ Priority: {1,number,#}]
+#  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:
+#  "Create : Owner: guest Priority: 1"
+#
+#  The final processing that is done in the generation is the conversion of the
+#  property name. As a '-' is an illegal character in the method name it is
+#  converted to '_' This processing gives the final method signature as follows:
+#   <Class>Message.<Type>_<Number>(<parmaters>,<options>)
+#
+# Default File used for all non-defined locales.
 #Broker
 # 0 - Version
 # 1 = Build



---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project:      http://qpid.apache.org
Use/Interact: mailto:commits-subscribe@qpid.apache.org


Mime
View raw message