Formatter.java revision 51b1b6997fd3f980076b8081f7f1165ccc2a4008 
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
27package 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
43public abstract class Formatter {
44
45    /**
46     * Construct a new formatter.
47     */
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     */
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     */
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     */
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     */
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