Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "Document return values from android.util.Log logging functions"

Browse Source
This commit is contained in:
Orion Hodson
2022-07-21 13:49:30 +00:00
committed by Gerrit Code Review
parent be25d91e81 762723f190
commit 07166bf3b1
1 changed files with 37 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
core/java/android/util/Log.java
View File

@@ -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,