View Javadoc
1   /**
2    * Copyright (c) 2004-2011 QOS.ch
3    * All rights reserved.
4    *
5    * Permission is hereby granted, free  of charge, to any person obtaining
6    * a  copy  of this  software  and  associated  documentation files  (the
7    * "Software"), to  deal in  the Software without  restriction, including
8    * without limitation  the rights to  use, copy, modify,  merge, publish,
9    * distribute,  sublicense, and/or sell  copies of  the Software,  and to
10   * permit persons to whom the Software  is furnished to do so, subject to
11   * the following conditions:
12   *
13   * The  above  copyright  notice  and  this permission  notice  shall  be
14   * included in all copies or substantial portions of the Software.
15   *
16   * THE  SOFTWARE IS  PROVIDED  "AS  IS", WITHOUT  WARRANTY  OF ANY  KIND,
17   * EXPRESS OR  IMPLIED, INCLUDING  BUT NOT LIMITED  TO THE  WARRANTIES OF
18   * MERCHANTABILITY,    FITNESS    FOR    A   PARTICULAR    PURPOSE    AND
19   * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
20   * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
21   * OF CONTRACT, TORT OR OTHERWISE,  ARISING FROM, OUT OF OR IN CONNECTION
22   * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
23   *
24   */
25  package org.slf4j.helpers;
26  
27  import java.text.MessageFormat;
28  import java.util.HashMap;
29  import java.util.Map;
30  
31  // contributors: lizongbo: proposed special treatment of array parameter values
32  // Joern Huxhorn: pointed out double[] omission, suggested deep array copy
33  /**
34   * Formats messages according to very simple substitution rules. Substitutions
35   * can be made 1, 2 or more arguments.
36   *
37   * <p>
38   * For example,
39   *
40   * <pre>
41   * MessageFormatter.format(&quot;Hi {}.&quot;, &quot;there&quot;)
42   * </pre>
43   *
44   * will return the string "Hi there.".
45   * <p>
46   * The {} pair is called the <em>formatting anchor</em>. It serves to designate
47   * the location where arguments need to be substituted within the message
48   * pattern.
49   * <p>
50   * In case your message contains the '{' or the '}' character, you do not have
51   * to do anything special unless the '}' character immediately follows '{'. For
52   * example,
53   *
54   * <pre>
55   * MessageFormatter.format(&quot;Set {1,2,3} is not equal to {}.&quot;, &quot;1,2&quot;);
56   * </pre>
57   *
58   * will return the string "Set {1,2,3} is not equal to 1,2.".
59   *
60   * <p>
61   * If for whatever reason you need to place the string "{}" in the message
62   * without its <em>formatting anchor</em> meaning, then you need to escape the
63   * '{' character with '\', that is the backslash character. Only the '{'
64   * character should be escaped. There is no need to escape the '}' character.
65   * For example,
66   *
67   * <pre>
68   * MessageFormatter.format(&quot;Set \\{} is not equal to {}.&quot;, &quot;1,2&quot;);
69   * </pre>
70   *
71   * will return the string "Set {} is not equal to 1,2.".
72   *
73   * <p>
74   * The escaping behavior just described can be overridden by escaping the escape
75   * character '\'. Calling
76   *
77   * <pre>
78   * MessageFormatter.format(&quot;File name is C:\\\\{}.&quot;, &quot;file.zip&quot;);
79   * </pre>
80   *
81   * will return the string "File name is C:\file.zip".
82   *
83   * <p>
84   * The formatting conventions are different than those of {@link MessageFormat}
85   * which ships with the Java platform. This is justified by the fact that
86   * SLF4J's implementation is 10 times faster than that of {@link MessageFormat}.
87   * This local performance difference is both measurable and significant in the
88   * larger context of the complete logging processing chain.
89   *
90   * <p>
91   * See also {@link #format(String, Object)},
92   * {@link #format(String, Object, Object)} and
93   * {@link #arrayFormat(String, Object[])} methods for more details.
94   *
95   * @author Ceki G&uuml;lc&uuml;
96   * @author Joern Huxhorn
97   */
98  final public class MessageFormatter {
99      static final char DELIM_START = '{';
100     static final char DELIM_STOP = '}';
101     static final String DELIM_STR = "{}";
102     private static final char ESCAPE_CHAR = '\\';
103 
104     /**
105      * Performs single argument substitution for the 'messagePattern' passed as
106      * parameter.
107      * <p>
108      * For example,
109      *
110      * <pre>
111      * MessageFormatter.format(&quot;Hi {}.&quot;, &quot;there&quot;);
112      * </pre>
113      *
114      * will return the string "Hi there.".
115      * <p>
116      *
117      * @param messagePattern
118      *          The message pattern which will be parsed and formatted
119      * @param arg
120      *          The argument to be substituted in place of the formatting anchor
121      * @return The formatted message
122      */
123     final public static FormattingTuple format(String messagePattern, Object arg) {
124         return arrayFormat(messagePattern, new Object[] { arg });
125     }
126 
127     /**
128      *
129      * Performs a two argument substitution for the 'messagePattern' passed as
130      * parameter.
131      * <p>
132      * For example,
133      *
134      * <pre>
135      * MessageFormatter.format(&quot;Hi {}. My name is {}.&quot;, &quot;Alice&quot;, &quot;Bob&quot;);
136      * </pre>
137      *
138      * will return the string "Hi Alice. My name is Bob.".
139      *
140      * @param messagePattern
141      *          The message pattern which will be parsed and formatted
142      * @param arg1
143      *          The argument to be substituted in place of the first formatting
144      *          anchor
145      * @param arg2
146      *          The argument to be substituted in place of the second formatting
147      *          anchor
148      * @return The formatted message
149      */
150     final public static FormattingTuple format(final String messagePattern, Object arg1, Object arg2) {
151         return arrayFormat(messagePattern, new Object[] { arg1, arg2 });
152     }
153 
154     final public static FormattingTuple arrayFormat(final String messagePattern, final Object[] argArray) {
155         Throwable throwableCandidate = MessageFormatter.getThrowableCandidate(argArray);
156         Object[] args = argArray;
157         if (throwableCandidate != null) {
158             args = MessageFormatter.trimmedCopy(argArray);
159         }
160         return arrayFormat(messagePattern, args, throwableCandidate);
161     }
162 
163     /**
164      * Assumes that argArray only contains arguments with no throwable as last element.
165      * 
166      * @param messagePattern
167      * @param argArray
168      */
169     final public static String basicArrayFormat(final String messagePattern, final Object[] argArray) {
170         FormattingTuple ft = arrayFormat(messagePattern, argArray, null);
171         return ft.getMessage();
172     }
173 
174     public static String basicArrayFormat(NormalizedParameters np) {
175         return basicArrayFormat(np.getMessage(), np.getArguments());
176     }
177 
178     final public static FormattingTuple arrayFormat(final String messagePattern, final Object[] argArray, Throwable throwable) {
179 
180         if (messagePattern == null) {
181             return new FormattingTuple(null, argArray, throwable);
182         }
183 
184         if (argArray == null) {
185             return new FormattingTuple(messagePattern);
186         }
187 
188         int i = 0;
189         int j;
190         // use string builder for better multicore performance
191         StringBuilder sbuf = new StringBuilder(messagePattern.length() + 50);
192 
193         int L;
194         for (L = 0; L < argArray.length; L++) {
195 
196             j = messagePattern.indexOf(DELIM_STR, i);
197 
198             if (j == -1) {
199                 // no more variables
200                 if (i == 0) { // this is a simple string
201                     return new FormattingTuple(messagePattern, argArray, throwable);
202                 } else { // add the tail string which contains no variables and return
203                     // the result.
204                     sbuf.append(messagePattern, i, messagePattern.length());
205                     return new FormattingTuple(sbuf.toString(), argArray, throwable);
206                 }
207             } else {
208                 if (isEscapedDelimeter(messagePattern, j)) {
209                     if (!isDoubleEscaped(messagePattern, j)) {
210                         L--; // DELIM_START was escaped, thus should not be incremented
211                         sbuf.append(messagePattern, i, j - 1);
212                         sbuf.append(DELIM_START);
213                         i = j + 1;
214                     } else {
215                         // The escape character preceding the delimiter start is
216                         // itself escaped: "abc x:\\{}"
217                         // we have to consume one backward slash
218                         sbuf.append(messagePattern, i, j - 1);
219                         deeplyAppendParameter(sbuf, argArray[L], new HashMap<>());
220                         i = j + 2;
221                     }
222                 } else {
223                     // normal case
224                     sbuf.append(messagePattern, i, j);
225                     deeplyAppendParameter(sbuf, argArray[L], new HashMap<>());
226                     i = j + 2;
227                 }
228             }
229         }
230         // append the characters following the last {} pair.
231         sbuf.append(messagePattern, i, messagePattern.length());
232         return new FormattingTuple(sbuf.toString(), argArray, throwable);
233     }
234 
235     final static boolean isEscapedDelimeter(String messagePattern, int delimeterStartIndex) {
236 
237         if (delimeterStartIndex == 0) {
238             return false;
239         }
240         char potentialEscape = messagePattern.charAt(delimeterStartIndex - 1);
241         if (potentialEscape == ESCAPE_CHAR) {
242             return true;
243         } else {
244             return false;
245         }
246     }
247 
248     final static boolean isDoubleEscaped(String messagePattern, int delimeterStartIndex) {
249         if (delimeterStartIndex >= 2 && messagePattern.charAt(delimeterStartIndex - 2) == ESCAPE_CHAR) {
250             return true;
251         } else {
252             return false;
253         }
254     }
255 
256     // special treatment of array values was suggested by 'lizongbo'
257     private static void deeplyAppendParameter(StringBuilder sbuf, Object o, Map<Object[], Object> seenMap) {
258         if (o == null) {
259             sbuf.append("null");
260             return;
261         }
262         if (!o.getClass().isArray()) {
263             safeObjectAppend(sbuf, o);
264         } else {
265             // check for primitive array types because they
266             // unfortunately cannot be cast to Object[]
267             if (o instanceof boolean[]) {
268                 booleanArrayAppend(sbuf, (boolean[]) o);
269             } else if (o instanceof byte[]) {
270                 byteArrayAppend(sbuf, (byte[]) o);
271             } else if (o instanceof char[]) {
272                 charArrayAppend(sbuf, (char[]) o);
273             } else if (o instanceof short[]) {
274                 shortArrayAppend(sbuf, (short[]) o);
275             } else if (o instanceof int[]) {
276                 intArrayAppend(sbuf, (int[]) o);
277             } else if (o instanceof long[]) {
278                 longArrayAppend(sbuf, (long[]) o);
279             } else if (o instanceof float[]) {
280                 floatArrayAppend(sbuf, (float[]) o);
281             } else if (o instanceof double[]) {
282                 doubleArrayAppend(sbuf, (double[]) o);
283             } else {
284                 objectArrayAppend(sbuf, (Object[]) o, seenMap);
285             }
286         }
287     }
288 
289     private static void safeObjectAppend(StringBuilder sbuf, Object o) {
290         try {
291             String oAsString = o.toString();
292             sbuf.append(oAsString);
293         } catch (Throwable t) {
294             Util.report("SLF4J: Failed toString() invocation on an object of type [" + o.getClass().getName() + "]", t);
295             sbuf.append("[FAILED toString()]");
296         }
297 
298     }
299 
300     private static void objectArrayAppend(StringBuilder sbuf, Object[] a, Map<Object[], Object> seenMap) {
301         sbuf.append('[');
302         if (!seenMap.containsKey(a)) {
303             seenMap.put(a, null);
304             final int len = a.length;
305             for (int i = 0; i < len; i++) {
306                 deeplyAppendParameter(sbuf, a[i], seenMap);
307                 if (i != len - 1)
308                     sbuf.append(", ");
309             }
310             // allow repeats in siblings
311             seenMap.remove(a);
312         } else {
313             sbuf.append("...");
314         }
315         sbuf.append(']');
316     }
317 
318     private static void booleanArrayAppend(StringBuilder sbuf, boolean[] a) {
319         sbuf.append('[');
320         final int len = a.length;
321         for (int i = 0; i < len; i++) {
322             sbuf.append(a[i]);
323             if (i != len - 1)
324                 sbuf.append(", ");
325         }
326         sbuf.append(']');
327     }
328 
329     private static void byteArrayAppend(StringBuilder sbuf, byte[] a) {
330         sbuf.append('[');
331         final int len = a.length;
332         for (int i = 0; i < len; i++) {
333             sbuf.append(a[i]);
334             if (i != len - 1)
335                 sbuf.append(", ");
336         }
337         sbuf.append(']');
338     }
339 
340     private static void charArrayAppend(StringBuilder sbuf, char[] a) {
341         sbuf.append('[');
342         final int len = a.length;
343         for (int i = 0; i < len; i++) {
344             sbuf.append(a[i]);
345             if (i != len - 1)
346                 sbuf.append(", ");
347         }
348         sbuf.append(']');
349     }
350 
351     private static void shortArrayAppend(StringBuilder sbuf, short[] a) {
352         sbuf.append('[');
353         final int len = a.length;
354         for (int i = 0; i < len; i++) {
355             sbuf.append(a[i]);
356             if (i != len - 1)
357                 sbuf.append(", ");
358         }
359         sbuf.append(']');
360     }
361 
362     private static void intArrayAppend(StringBuilder sbuf, int[] a) {
363         sbuf.append('[');
364         final int len = a.length;
365         for (int i = 0; i < len; i++) {
366             sbuf.append(a[i]);
367             if (i != len - 1)
368                 sbuf.append(", ");
369         }
370         sbuf.append(']');
371     }
372 
373     private static void longArrayAppend(StringBuilder sbuf, long[] a) {
374         sbuf.append('[');
375         final int len = a.length;
376         for (int i = 0; i < len; i++) {
377             sbuf.append(a[i]);
378             if (i != len - 1)
379                 sbuf.append(", ");
380         }
381         sbuf.append(']');
382     }
383 
384     private static void floatArrayAppend(StringBuilder sbuf, float[] a) {
385         sbuf.append('[');
386         final int len = a.length;
387         for (int i = 0; i < len; i++) {
388             sbuf.append(a[i]);
389             if (i != len - 1)
390                 sbuf.append(", ");
391         }
392         sbuf.append(']');
393     }
394 
395     private static void doubleArrayAppend(StringBuilder sbuf, double[] a) {
396         sbuf.append('[');
397         final int len = a.length;
398         for (int i = 0; i < len; i++) {
399             sbuf.append(a[i]);
400             if (i != len - 1)
401                 sbuf.append(", ");
402         }
403         sbuf.append(']');
404     }
405 
406     /**
407      * Helper method to determine if an {@link Object} array contains a {@link Throwable} as last element
408      *
409      * @param argArray
410      *          The arguments off which we want to know if it contains a {@link Throwable} as last element
411      * @return if the last {@link Object} in argArray is a {@link Throwable} this method will return it,
412      *          otherwise it returns null
413      */
414     public static Throwable getThrowableCandidate(final Object[] argArray) {
415         return NormalizedParameters.getThrowableCandidate(argArray);
416     }
417 
418     /**
419      * Helper method to get all but the last element of an array
420      *
421      * @param argArray
422      *          The arguments from which we want to remove the last element
423      *
424      * @return a copy of the array without the last element
425      */
426     public static Object[] trimmedCopy(final Object[] argArray) {
427         return NormalizedParameters.trimmedCopy(argArray);
428     }
429 
430 }