1 /*
2  * Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved.
3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4  *
5  * This code is free software; you can redistribute it and/or modify it
6  * under the terms of the GNU General Public License version 2 only, as
7  * published by the Free Software Foundation.  Oracle designates this
8  * particular file as subject to the "Classpath" exception as provided
9  * by Oracle in the LICENSE file that accompanied this code.
10  *
11  * This code is distributed in the hope that it will be useful, but WITHOUT
12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14  * version 2 for more details (a copy is included in the LICENSE file that
15  * accompanied this code).
16  *
17  * You should have received a copy of the GNU General Public License version
18  * 2 along with this work; if not, write to the Free Software Foundation,
19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20  *
21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22  * or visit www.oracle.com if you need additional information or have any
23  * questions.
24  */
25 
26 
27 package java.util.logging;
28 
29 /**
30  * A Formatter provides support for formatting LogRecords.
31  * <p>
32  * Typically each logging Handler will have a Formatter associated
33  * with it.  The Formatter takes a LogRecord and converts it to
34  * a string.
35  * <p>
36  * Some formatters (such as the XMLFormatter) need to wrap head
37  * and tail strings around a set of formatted records. The getHeader
38  * and getTail methods can be used to obtain these strings.
39  *
40  * @since 1.4
41  */
42 
43 public abstract class Formatter {
44 
45     /**
46      * Construct a new formatter.
47      */
Formatter()48     protected Formatter() {
49     }
50 
51     /**
52      * Format the given log record and return the formatted string.
53      * <p>
54      * The resulting formatted String will normally include a
55      * localized and formatted version of the LogRecord's message field.
56      * It is recommended to use the {@link Formatter#formatMessage}
57      * convenience method to localize and format the message field.
58      *
59      * @param record the log record to be formatted.
60      * @return the formatted log record
61      */
format(LogRecord record)62     public abstract String format(LogRecord record);
63 
64 
65     /**
66      * Return the header string for a set of formatted records.
67      * <p>
68      * This base class returns an empty string, but this may be
69      * overridden by subclasses.
70      *
71      * @param   h  The target handler (can be null)
72      * @return  header string
73      */
getHead(Handler h)74     public String getHead(Handler h) {
75         return "";
76     }
77 
78     /**
79      * Return the tail string for a set of formatted records.
80      * <p>
81      * This base class returns an empty string, but this may be
82      * overridden by subclasses.
83      *
84      * @param   h  The target handler (can be null)
85      * @return  tail string
86      */
getTail(Handler h)87     public String getTail(Handler h) {
88         return "";
89     }
90 
91 
92     /**
93      * Localize and format the message string from a log record.  This
94      * method is provided as a convenience for Formatter subclasses to
95      * use when they are performing formatting.
96      * <p>
97      * The message string is first localized to a format string using
98      * the record's ResourceBundle.  (If there is no ResourceBundle,
99      * or if the message key is not found, then the key is used as the
100      * format string.)  The format String uses java.text style
101      * formatting.
102      * <ul>
103      * <li>If there are no parameters, no formatter is used.
104      * <li>Otherwise, if the string contains "{0" then
105      *     java.text.MessageFormat  is used to format the string.
106      * <li>Otherwise no formatting is performed.
107      * </ul>
108      * <p>
109      *
110      * @param  record  the log record containing the raw message
111      * @return   a localized and formatted message
112      */
formatMessage(LogRecord record)113     public synchronized String formatMessage(LogRecord record) {
114         String format = record.getMessage();
115         java.util.ResourceBundle catalog = record.getResourceBundle();
116         if (catalog != null) {
117             try {
118                 format = catalog.getString(record.getMessage());
119             } catch (java.util.MissingResourceException ex) {
120                 // Drop through.  Use record message as format
121                 format = record.getMessage();
122             }
123         }
124         // Do the formatting.
125         try {
126             Object parameters[] = record.getParameters();
127             if (parameters == null || parameters.length == 0) {
128                 // No parameters.  Just return format string.
129                 return format;
130             }
131             // Is it a java.text style format?
132             // Ideally we could match with
133             // Pattern.compile("\\{\\d").matcher(format).find())
134             // However the cost is 14% higher, so we cheaply check for
135             // 1 of the first 4 parameters
136             if (format.indexOf("{0") >= 0 || format.indexOf("{1") >=0 ||
137                         format.indexOf("{2") >=0|| format.indexOf("{3") >=0) {
138                 return java.text.MessageFormat.format(format, parameters);
139             }
140             return format;
141 
142         } catch (Exception ex) {
143             // Formatting failed: use localized format string.
144             return format;
145         }
146     }
147 }
148