Merge "Document return values from android.util.Log logging functions" (07166bf3) · Commits · e / os / android_frameworks_base

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,