United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
JDK-4835240 : Poor documentation of java.util.logging.Logger methods

Details
Type:
Enhancement
Submit Date:
2003-03-20
Status:
Open
Updated Date:
2007-06-05
Project Name:
JDK
Resolved Date:
Component:
core-libs
OS:
windows_2000
Sub-Component:
java.util.logging
CPU:
x86
Priority:
P4
Resolution:
Unresolved
Affected Versions:
6
Targeted Versions:

Related Reports

Sub Tasks

Description

Name: rmT116609			Date: 03/20/2003


A DESCRIPTION OF THE PROBLEM :
Logger.log methods which accept an Object or array of Objects as arguments/parameters have extremely poor documentation.  The description of these parameters is "parameter to the message" or " parameters to the message."  There is no explanation of what this means nor any mention of the fact that internally java.text.MessageFormat is being used, and that the String message passed in must use the arguments in a specified format.  Users must view the source of Logger to determine the correct usage of these methods.

EXPECTED VERSUS ACTUAL BEHAVIOR :
At a bare minimum, a "@see" reference to MessageFormat.  Ideally, a full explanation of how to use the arguments to these log methods.
parameter to the message

http://java.sun.com/j2se/1.4.1/docs/api/java/util/logging/Logger.html#log(java.util.logging.Level,%20java.lang.String,%20java.lang.Object)

http://java.sun.com/j2se/1.4.1/docs/api/java/util/logging/Logger.html#log(java.util.logging.Level,%20java.lang.String,%20java.lang.Object[])
(Review ID: 182887) 
======================================================================

                                    

Comments
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
mustang


                                     
2004-06-14
EVALUATION

Will add explanation

###@###.### 2003-07-25

* Most of the logger output methods take a "msg" argument.  This
 * msg argument may be either a raw value or a localization key.
 * During formatting, if the logger has (or inherits) a localization
 * ResourceBundle and if the ResourceBundle has a mapping for the msg
 * string, then the msg string is replaced by the localized value.
 * Otherwise the original msg string is used.
 
 * The default formatters accept a java.text.MessageFormat style format
 * pattern as the msg argument and then uses the parameter argument,
 * if supplied, as input to the pattern. For example a msg argument
 * containing the pattern string "{0} {1}"  would format the first two
 * parameters arguments from the supplied params Object[] array as strings.


###@###.### 2003-09-09
                                     
2003-09-09



Hardware and Software, Engineered to Work Together