Add an utility class to improve java logs.

base/android/java/src/org/chromium/base/Log.java

+// Copyright 2015 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+package org.chromium.base;
+
+import org.chromium.base.annotations.NoSideEffects;
+
+import java.util.Locale;
+
+/**
+ * Utility class for Logging.
+ *
+ * <p>
+ * Defines logging access points for each feature. They format and forward the logs to
+ * {@link android.util.Log}, allowing to standardize the output, to make it easy to identify
+ * the origin of logs, and enable or disable logging in different parts of the code.
+ * </p>
+ * <p>
+ * Please make use of the formatting capability of the logging methods rather than doing
+ * concatenations in the calling code. In the release builds of Chrome, debug and verbose log
+ * calls will be stripped out of the binary. Concatenations and method calls however will still
+ * remain and be executed. If they can't be avoided, use {@link Log#isEnabled(int)} to guard
+ * such calls. Another possibility is to annotate methods to be called with {@link NoSideEffects}.
+ * </p>
+ *
+ * Usage:
+ * <pre>
+ * Log.FEATURE.d("MyTag", "My %s message", awesome);
+ * </pre>
+ *
+ * Logcat output:
+ * <pre>
+ * D/chromium.Feature (999): [MyTag] My awesome message
+ * </pre>
+ *
+ * Set the log level for a given feature:
+ * <pre>
+ * adb shell setprop log.tag.chromium:Feature VERBOSE
+ * </pre>
+ *
+ *<p>
+ *<b>Notes:</b>
+ * <ul>
+ * <li>New features or features not having a dedicated logger: please make a new one rather
+ * than using {@link #ROOT}.</li>
+ * <li>The class exposes different versions of the log functions based on the number of arguments
+ * needed. This is to allow proguard to properly remove them from the release builds. The usage
+ * is exactly the same.</li>
+ * </ul>
+ * </p>
+ */
+public class Log {
+    /**
+     * Logger for the "chromium" tag.
+     * Note: Disabling logging for that one will not disable the others.
+     */
+    public static final Log ROOT = new Log(null);
+
+    private static final String BASE_TAG = "chromium";
+
+    /**
+     * Maximum length for the feature tag.
+     *
+     * A complete tag will look like <code>chromium:FooFeature</code>. Because of the 23 characters
+     * limit on log tags, feature tags have to be restricted to fit.
+     */
+    private static final int MAX_FEATURE_TAG_LENGTH = 23 - 1 - BASE_TAG.length();
+
+    @VisibleForTesting final String mTag;
+
+    /**
+     * Creates a new logging access point for the given tag.
+     * @throws IllegalArgumentException If <code>featureTag</code> is too long. The complete
+     *                                  tag has to fit within 23 characters.
+     */
+    protected Log(String featureTag) {
+        if (featureTag == null) {
+            mTag = BASE_TAG;
+            return;
+        } else if (featureTag.length() > MAX_FEATURE_TAG_LENGTH) {
+            throw new IllegalArgumentException(
+                    "The feature tag can be at most " + MAX_FEATURE_TAG_LENGTH + " characters.");
+        } else {
+            mTag = BASE_TAG + "." + featureTag;
+        }
+    }
+
+    /** Returns whether this logger is currently allowed to send logs.*/
+    public boolean isEnabled(int level) {
+        return android.util.Log.isLoggable(mTag, level);
+    }
+
+    /** Returns a formatted log message, using the supplied format and arguments.*/
+    @VisibleForTesting
+    protected String formatLog(String secondaryTag, String messageTemplate, Object... params) {
+        if (params != null && params.length != 0) {
+            messageTemplate = String.format(Locale.US, messageTemplate, params);
+        }
+
+        return "[" + secondaryTag + "] " + messageTemplate;
+    }
+
+    /**
+     * Sends a {@link android.util.Log#VERBOSE} log message.
+     *
+     * For optimization purposes, use the fixed parameters versions if possible.

[Yaron, 2015/04/01 20:47:31]

How does a client decide that? I assume this is just an implementation detail of
java which prefers the strict match before varargs or am I missing something?

[Torne, 2015/04/02 10:50:05]

It has a different name.

[dgn, 2015/04/02 12:47:20]

The function names are different, so Log.X.v() instead of Log.X.verbose(). But
yes, Java also prefers strict match.

[Yaron, 2015/04/02 14:29:47]

Yeesh. Sorry for my poor reading :S

+     *
+     * @param secondaryTag Used to identify the source of a log message. It usually identifies the
+     *                     class where the log call occurs.
+     * @param messageTemplate The message you would like logged. It is to be specified as a format
+     *                        string.
+     * @param args Arguments referenced by the format specifiers in the format string.
+     */
+    public void verbose(String secondaryTag, String messageTemplate, Object... args) {

[Yaron, 2015/04/01 20:47:31]

Do we have any examples using more than 7? Perhaps make this private so it's
clearer what's going on

[Torne, 2015/04/02 10:50:05]

Yeah, I'd be inclined to make this private and if people need more than 7
parameters, either explain why this is crazy or add more overloads here.

[dgn, 2015/04/02 14:47:15]

Done. For consistency, I removed the Log.i() variants, since those are going to
stay in anyway.

+        if (isEnabled(android.util.Log.VERBOSE)) {
+            android.util.Log.v(mTag, formatLog(secondaryTag, messageTemplate, args));
+        }
+    }
+
+    /** Sends a {@link android.util.Log#VERBOSE} log message. 0 arg version. */
+    public void v(String secondaryTag, String message) {

[Yaron, 2015/04/01 20:47:31]

So for release builds, all of these variants are stripped?

[dgn, 2015/04/02 12:47:20]

Yes. Proguard config (CL here:
https://chrome-internal-review.googlesource.com/#/c/211310/) has


assumenosideeffects on @NoSideEffects <methods> and on Log {d(...), v(...)}
(TODO: need to add verbose() and debug() there)
If the return value is unused, proguard should remove the function calls. If all
function calls are removed, the function itself is also supposed to go away.

+        verbose(secondaryTag, message);
+    }
+
+    /** Sends a {@link android.util.Log#VERBOSE} log message. 1 arg version. */
+    public void v(String secondaryTag, String messageTemplate, Object arg1) {
+        verbose(secondaryTag, messageTemplate, arg1);
+    }
+
+    /** Sends a {@link android.util.Log#VERBOSE} log message. 2 args version */
+    public void v(String secondaryTag, String messageTemplate, Object arg1, Object arg2) {
+        verbose(secondaryTag, messageTemplate, arg1, arg2);
+    }
+
+    /** Sends a {@link android.util.Log#VERBOSE} log message. 3 args version */
+    public void v(
+            String secondaryTag, String messageTemplate, Object arg1, Object arg2, Object arg3) {
+        verbose(secondaryTag, messageTemplate, arg1, arg2, arg3);
+    }
+
+    /** Sends a {@link android.util.Log#VERBOSE} log message. 4 args version */
+    public void v(String secondaryTag, String messageTemplate, Object arg1, Object arg2,
+            Object arg3, Object arg4) {
+        verbose(secondaryTag, messageTemplate, arg1, arg2, arg3, arg4);
+    }
+
+    /** Sends a {@link android.util.Log#VERBOSE} log message. 5 args version */
+    public void v(String secondaryTag, String messageTemplate, Object arg1, Object arg2,
+            Object arg3, Object arg4, Object arg5) {
+        verbose(secondaryTag, messageTemplate, arg1, arg2, arg3, arg4, arg5);
+    }
+
+    /** Sends a {@link android.util.Log#VERBOSE} log message. 6 args version */
+    public void v(String secondaryTag, String messageTemplate, Object arg1, Object arg2,
+            Object arg3, Object arg4, Object arg5, Object arg6) {
+        verbose(secondaryTag, messageTemplate, arg1, arg2, arg3, arg4, arg5, arg6);
+    }
+
+    /** Sends a {@link android.util.Log#VERBOSE} log message. 7 args version */
+    public void v(String secondaryTag, String messageTemplate, Object arg1, Object arg2,
+            Object arg3, Object arg4, Object arg5, Object arg6, Object arg7) {
+        verbose(secondaryTag, messageTemplate, arg1, arg2, arg3, arg4, arg5, arg6, arg7);
+    }
+
+    /**
+     * Sends a {@link android.util.Log#DEBUG} log message.
+     *
+     * For optimization purposes, use the fixed parameters versions if possible.
+     *
+     * @param secondaryTag Used to identify the source of a log message. It usually identifies the
+     *                     class where the log call occurs.
+     * @param messageTemplate The message you would like logged. It is to be specified as a format
+     *                        string.
+     * @param args Arguments referenced by the format specifiers in the format string.
+     */
+    public void debug(String secondaryTag, String messageTemplate, Object... args) {
+        if (isEnabled(android.util.Log.DEBUG)) {
+            android.util.Log.d(mTag, formatLog(secondaryTag, messageTemplate, args));
+        }
+    }
+
+    /** Sends a {@link android.util.Log#DEBUG} log message. 0 arg version. */
+    public void d(String secondaryTag, String message) {
+        debug(secondaryTag, message);
+    }
+
+    /** Sends a {@link android.util.Log#DEBUG} log message. 1 arg version. */
+    public void d(String secondaryTag, String messageTemplate, Object arg1) {
+        debug(secondaryTag, messageTemplate, arg1);
+    }
+    /** Sends a {@link android.util.Log#DEBUG} log message. 2 args version */
+    public void d(String secondaryTag, String messageTemplate, Object arg1, Object arg2) {
+        debug(secondaryTag, messageTemplate, arg1, arg2);
+    }
+    /** Sends a {@link android.util.Log#DEBUG} log message. 3 args version */
+    public void d(
+            String secondaryTag, String messageTemplate, Object arg1, Object arg2, Object arg3) {
+        debug(secondaryTag, messageTemplate, arg1, arg2, arg3);
+    }
+
+    /** Sends a {@link android.util.Log#DEBUG} log message. 4 args version */
+    public void d(String secondaryTag, String messageTemplate, Object arg1, Object arg2,
+            Object arg3, Object arg4) {
+        debug(secondaryTag, messageTemplate, arg1, arg2, arg3, arg4);
+    }
+
+    /** Sends a {@link android.util.Log#DEBUG} log message. 5 args version */
+    public void d(String secondaryTag, String messageTemplate, Object arg1, Object arg2,
+            Object arg3, Object arg4, Object arg5) {
+        debug(secondaryTag, messageTemplate, arg1, arg2, arg3, arg4, arg5);
+    }
+
+    /** Sends a {@link android.util.Log#DEBUG} log message. 6 args version */
+    public void d(String secondaryTag, String messageTemplate, Object arg1, Object arg2,
+            Object arg3, Object arg4, Object arg5, Object arg6) {
+        debug(secondaryTag, messageTemplate, arg1, arg2, arg3, arg4, arg5, arg6);
+    }
+
+    /** Sends a {@link android.util.Log#DEBUG} log message. 7 args version */
+    public void d(String secondaryTag, String messageTemplate, Object arg1, Object arg2,
+            Object arg3, Object arg4, Object arg5, Object arg6, Object arg7) {
+        debug(secondaryTag, messageTemplate, arg1, arg2, arg3, arg4, arg5, arg6, arg7);
+    }
+
+    /**
+     * Sends an {@link android.util.Log#INFO} log message.
+     *
+     * For optimization purposes, use the fixed parameters versions if possible.
+     *
+     * @param secondaryTag Used to identify the source of a log message. It usually identifies the
+     *                     class where the log call occurs.
+     * @param messageTemplate The message you would like logged. It is to be specified as a format
+     *                        string.
+     * @param args Arguments referenced by the format specifiers in the format string.
+     */
+    public void info(String secondaryTag, String messageTemplate, Object... args) {
+        if (isEnabled(android.util.Log.INFO)) {
+            android.util.Log.i(mTag, formatLog(secondaryTag, messageTemplate, args));
+        }
+    }
+    /** Sends an {@link android.util.Log#INFO} log message. 0 arg version. */
+    public void i(String secondaryTag, String message) {
+        info(secondaryTag, message);
+    }
+    /** Sends an {@link android.util.Log#INFO} log message. 1 arg version. */
+    public void i(String secondaryTag, String messageTemplate, Object arg1) {
+        info(secondaryTag, messageTemplate, arg1);
+    }
+    /** Sends an {@link android.util.Log#INFO} log message. 2 args version */
+    public void i(String secondaryTag, String messageTemplate, Object arg1, Object arg2) {
+        info(secondaryTag, messageTemplate, arg1, arg2);
+    }
+    /** Sends an {@link android.util.Log#INFO} log message. 3 args version */
+    public void i(
+            String secondaryTag, String messageTemplate, Object arg1, Object arg2, Object arg3) {
+        info(secondaryTag, messageTemplate, arg1, arg2, arg3);
+    }
+
+    /** Sends an {@link android.util.Log#INFO} log message. 4 args version */
+    public void i(String secondaryTag, String messageTemplate, Object arg1, Object arg2,
+            Object arg3, Object arg4) {
+        info(secondaryTag, messageTemplate, arg1, arg2, arg3, arg4);
+    }
+
+    /** Sends an {@link android.util.Log#INFO} log message. 5 args version */
+    public void i(String secondaryTag, String messageTemplate, Object arg1, Object arg2,
+            Object arg3, Object arg4, Object arg5) {
+        info(secondaryTag, messageTemplate, arg1, arg2, arg3, arg4, arg5);
+    }
+
+    /** Sends an {@link android.util.Log#INFO} log message. 6 args version */
+    public void i(String secondaryTag, String messageTemplate, Object arg1, Object arg2,
+            Object arg3, Object arg4, Object arg5, Object arg6) {
+        info(secondaryTag, messageTemplate, arg1, arg2, arg3, arg4, arg5, arg6);
+    }
+
+    /** Sends an {@link android.util.Log#INFO} log message. 7 args version */
+    public void i(String secondaryTag, String messageTemplate, Object arg1, Object arg2,
+            Object arg3, Object arg4, Object arg5, Object arg6, Object arg7) {
+        info(secondaryTag, messageTemplate, arg1, arg2, arg3, arg4, arg5, arg6, arg7);
+    }
+
+    /**
+     * Sends a {@link android.util.Log#WARN} log message.
+     *
+     * @param secondaryTag Used to identify the source of a log message. It usually identifies the
+     *                     class where the log call occurs.
+     * @param messageTemplate The message you would like logged. It is to be specified as a format
+     *                        string.
+     * @param args Arguments referenced by the format specifiers in the format string.
+     */
+    public void w(String secondaryTag, String messageTemplate, Object... args) {
+        if (isEnabled(android.util.Log.WARN)) {
+            android.util.Log.w(mTag, formatLog(secondaryTag, messageTemplate, args));
+        }
+    }
+
+    /**
+     * Sends an {@link android.util.Log#ERROR} log message.
+     *
+     * @param secondaryTag Used to identify the source of a log message. It usually identifies the
+     *                     class where the log call occurs.
+     * @param messageTemplate The message you would like logged. It is to be specified as a format
+     *                        string.
+     * @param args Arguments referenced by the format specifiers in the format string.
+     */
+    public void e(String secondaryTag, String messageTemplate, Object... args) {
+        if (isEnabled(android.util.Log.ERROR)) {
+            android.util.Log.e(mTag, formatLog(secondaryTag, messageTemplate, args));
+        }
+    }
+}