Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit c822b157 authored by Orion Hodson's avatar Orion Hodson Committed by Automerger Merge Worker
Browse files

Merge "Document return values from android.util.Log logging functions" am: 07166bf3 

Original change: https://android-review.googlesource.com/c/platform/frameworks/base/+/2158819



Change-Id: Ia50d0d1945460168b0e8699e3142d17c573905bb
Signed-off-by: default avatarAutomerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com>
parents 41a5df2f 07166bf3

core/java/android/util/Log.java

+37 −9
Original line number Diff line number Diff line
@@ -66,6 +66,10 @@ import java.net.UnknownHostException; 
 * <p>When calling the log methods that take a Throwable parameter,

 * if any of the throwables in the cause chain is an <code>UnknownHostException</code>,

 * then the stack trace is not logged.

 *

 * <p>Note: The return value from the logging functions in this class may vary between Android

 * releases due to changes in the logging implementation. For the methods that return an integer,

 * a positive value may be considered as a successful invocation.

 */

public final class Log {

    /** @hide */
@@ -134,6 +138,7 @@ public final class Log { 
     * @param tag Used to identify the source of a log message.  It usually identifies

     *        the class or activity where the log call occurs.

     * @param msg The message you would like logged.

     * @return A positive value if the message was loggable (see {@link #isLoggable}).

     */

    public static int v(@Nullable String tag, @NonNull String msg) {

        return println_native(LOG_ID_MAIN, VERBOSE, tag, msg);
@@ -144,7 +149,8 @@ public final class Log { 
     * @param tag Used to identify the source of a log message.  It usually identifies

     *        the class or activity where the log call occurs.

     * @param msg The message you would like logged.

     * @param tr An exception to log

     * @param tr An exception to log.

     * @return A positive value if the message was loggable (see {@link #isLoggable}).

     */

    public static int v(@Nullable String tag, @Nullable String msg, @Nullable Throwable tr) {

        return printlns(LOG_ID_MAIN, VERBOSE, tag, msg, tr);
@@ -155,6 +161,7 @@ public final class Log { 
     * @param tag Used to identify the source of a log message.  It usually identifies

     *        the class or activity where the log call occurs.

     * @param msg The message you would like logged.

     * @return A positive value if the message was loggable (see {@link #isLoggable}).

     */

    public static int d(@Nullable String tag, @NonNull String msg) {

        return println_native(LOG_ID_MAIN, DEBUG, tag, msg);
@@ -165,7 +172,8 @@ public final class Log { 
     * @param tag Used to identify the source of a log message.  It usually identifies

     *        the class or activity where the log call occurs.

     * @param msg The message you would like logged.

     * @param tr An exception to log

     * @param tr An exception to log.

     * @return A positive value if the message was loggable (see {@link #isLoggable}).

     */

    public static int d(@Nullable String tag, @Nullable String msg, @Nullable Throwable tr) {

        return printlns(LOG_ID_MAIN, DEBUG, tag, msg, tr);
@@ -176,6 +184,7 @@ public final class Log { 
     * @param tag Used to identify the source of a log message.  It usually identifies

     *        the class or activity where the log call occurs.

     * @param msg The message you would like logged.

     * @return A positive value if the message was loggable (see {@link #isLoggable}).

     */

    public static int i(@Nullable String tag, @NonNull String msg) {

        return println_native(LOG_ID_MAIN, INFO, tag, msg);
@@ -186,7 +195,7 @@ public final class Log { 
     * @param tag Used to identify the source of a log message.  It usually identifies

     *        the class or activity where the log call occurs.

     * @param msg The message you would like logged.

     * @param tr An exception to log

     * @param tr An exception to log.

     */

    public static int i(@Nullable String tag, @Nullable String msg, @Nullable Throwable tr) {

        return printlns(LOG_ID_MAIN, INFO, tag, msg, tr);
@@ -197,6 +206,7 @@ public final class Log { 
     * @param tag Used to identify the source of a log message.  It usually identifies

     *        the class or activity where the log call occurs.

     * @param msg The message you would like logged.

     * @return A positive value if the message was loggable (see {@link #isLoggable}).

     */

    public static int w(@Nullable String tag, @NonNull String msg) {

        return println_native(LOG_ID_MAIN, WARN, tag, msg);
@@ -207,7 +217,8 @@ public final class Log { 
     * @param tag Used to identify the source of a log message.  It usually identifies

     *        the class or activity where the log call occurs.

     * @param msg The message you would like logged.

     * @param tr An exception to log

     * @param tr An exception to log.

     * @return A positive value if the message was loggable (see {@link #isLoggable}).

     */

    public static int w(@Nullable String tag, @Nullable String msg, @Nullable Throwable tr) {

        return printlns(LOG_ID_MAIN, WARN, tag, msg, tr);
@@ -239,7 +250,8 @@ public final class Log { 
     * Send a {@link #WARN} log message and log the exception.

     * @param tag Used to identify the source of a log message.  It usually identifies

     *        the class or activity where the log call occurs.

     * @param tr An exception to log

     * @param tr An exception to log.

     * @return A positive value if the message was loggable (see {@link #isLoggable}).

     */

    public static int w(@Nullable String tag, @Nullable Throwable tr) {

        return printlns(LOG_ID_MAIN, WARN, tag, "", tr);
@@ -250,6 +262,7 @@ public final class Log { 
     * @param tag Used to identify the source of a log message.  It usually identifies

     *        the class or activity where the log call occurs.

     * @param msg The message you would like logged.

     * @return A positive value if the message was loggable (see {@link #isLoggable}).

     */

    public static int e(@Nullable String tag, @NonNull String msg) {

        return println_native(LOG_ID_MAIN, ERROR, tag, msg);
@@ -260,7 +273,8 @@ public final class Log { 
     * @param tag Used to identify the source of a log message.  It usually identifies

     *        the class or activity where the log call occurs.

     * @param msg The message you would like logged.

     * @param tr An exception to log

     * @param tr An exception to log.

     * @return A positive value if the message was loggable (see {@link #isLoggable}).

     */

    public static int e(@Nullable String tag, @Nullable String msg, @Nullable Throwable tr) {

        return printlns(LOG_ID_MAIN, ERROR, tag, msg, tr);
@@ -274,6 +288,7 @@ public final class Log { 
     * immediately with an error dialog.

     * @param tag Used to identify the source of a log message.

     * @param msg The message you would like logged.

     * @return A positive value if the message was loggable (see {@link #isLoggable}).

     */

    public static int wtf(@Nullable String tag, @Nullable String msg) {

        return wtf(LOG_ID_MAIN, tag, msg, null, false, false);
@@ -293,6 +308,7 @@ public final class Log { 
     * Similar to {@link #wtf(String, String)}, with an exception to log.

     * @param tag Used to identify the source of a log message.

     * @param tr An exception to log.

     * @return A positive value if the message was loggable (see {@link #isLoggable}).

     */

    public static int wtf(@Nullable String tag, @NonNull Throwable tr) {

        return wtf(LOG_ID_MAIN, tag, tr.getMessage(), tr, false, false);
@@ -304,6 +320,7 @@ public final class Log { 
     * @param tag Used to identify the source of a log message.

     * @param msg The message you would like logged.

     * @param tr An exception to log.  May be null.

     * @return A positive value if the message was loggable (see {@link #isLoggable}).

     */

    public static int wtf(@Nullable String tag, @Nullable String msg, @Nullable Throwable tr) {

        return wtf(LOG_ID_MAIN, tag, msg, tr, false, false);
@@ -348,7 +365,7 @@ public final class Log { 


     * <p>If any of the throwables in the cause chain is an <code>UnknownHostException</code>,

     * this returns an empty string.

     * @param tr An exception to log

     * @param tr An exception to log.

     */

    @NonNull

    public static String getStackTraceString(@Nullable Throwable tr) {
@@ -379,7 +396,7 @@ public final class Log { 
     * @param tag Used to identify the source of a log message.  It usually identifies

     *        the class or activity where the log call occurs.

     * @param msg The message you would like logged.

     * @return The number of bytes written.

     * @return A positive value if the message was loggable (see {@link #isLoggable}).

     */

    public static int println(@Level int priority, @Nullable String tag, @NonNull String msg) {

        return println_native(LOG_ID_MAIN, priority, tag, msg);
@@ -391,7 +408,16 @@ public final class Log { 
    /** @hide */ public static final int LOG_ID_SYSTEM = 3;

    /** @hide */ public static final int LOG_ID_CRASH = 4;



    /** @hide */

    /**

     * Low-level logging call.

     * @param bufID The buffer ID to receive the message.

     * @param priority The priority of the message.

     * @param tag Used to identify the source of a log message.  It usually identifies

     *        the class or activity where the log call occurs.

     * @param msg The message you would like logged.

     * @return A positive value if the message was loggable (see {@link #isLoggable}).

     * @hide

     */

    @UnsupportedAppUsage

    public static native int println_native(int bufID, int priority, String tag, String msg);
@@ -407,6 +433,7 @@ public final class Log { 
     * @param tag Used to identify the source of a log message.  It usually identifies

     *        the class or activity where the log call occurs.

     * @param message The message you would like logged.

     * @return A positive value if the message was loggable (see {@link #isLoggable}).

     * @hide

     */

    @SystemApi(client = SystemApi.Client.MODULE_LIBRARIES)
@@ -425,6 +452,7 @@ public final class Log { 
     * Helper function for long messages. Uses the LineBreakBufferedWriter to break

     * up long messages and stacktraces along newlines, but tries to write in large

     * chunks. This is to avoid truncation.

     * @return A positive value if the message was loggable (see {@link #isLoggable}).

     * @hide

     */

    public static int printlns(int bufID, int priority, @Nullable String tag, @NonNull String msg,