Add call-stack reporting methods into Debug

Added two public methods to Debug. These methods return a String
indicating the caller (getCaller()) or callers (getCallers(int depth))
of the calling method. The String indicates the class, method and line
number of the caller(s). Similar to using Throwable.fillInStackTrace()
but much more concise.

Change-Id: I53d0085aa50e4501d28e8eb3ad5b91ef700ac218

2 files changed, 105 insertions, 0 deletions

diff --git a/core/java/android/os/Debug.java b/core/java/android/os/Debug.java
index 20a731e..98fe06a 100644
--- a/core/java/android/os/Debug.java
+++ b/core/java/android/os/Debug.java
@@ -1324,4 +1324,42 @@ href="{@docRoot}guide/developing/tools/traceview.html">Traceview: A Graphical Lo
             return false;
         }
     }
+
+    /**
+     * Return a String describing the calling method and location at a particular stack depth.
+     * @param callStack the Thread stack 
+     * @param depth the depth of stack to return information for.
+     * @return the String describing the caller at that depth.
+     */
+    private static String getCaller(StackTraceElement callStack[], int depth) {
+        // callStack[4] is the caller of the method that called getCallers()
+        if (4 + depth >= callStack.length) {
+            return "<bottom of call stack>";
+        }
+        StackTraceElement caller = callStack[4 + depth];
+        return caller.getClassName() + "." + caller.getMethodName() + ":" + caller.getLineNumber();
+    }
+
+    /**
+     * Return a string consisting of methods and locations at multiple call stack levels.
+     * @param depth the number of levels to return, starting with the immediate caller.
+     * @return a string describing the call stack.
+     * {@hide}
+     */
+    public static String getCallers(final int depth) {
+        final StackTraceElement[] callStack = Thread.currentThread().getStackTrace();
+        StringBuffer sb = new StringBuffer();
+        for (int i = 0; i < depth; i++) {
+            sb.append(getCaller(callStack, i)).append(" ");
+        }
+        return sb.toString();
+    }
+
+    /**
+     * @return a String describing the immediate caller of the calling function.
+     * {@hide}
+     */
+    public static String getCaller() {
+        return getCaller(Thread.currentThread().getStackTrace(), 0);
+    }
 }
diff --git a/core/tests/coretests/src/com/android/internal/os/DebugTest.java b/core/tests/coretests/src/com/android/internal/os/DebugTest.java
new file mode 100644
index 0000000..88c7d1b
--- /dev/null
+++ b/core/tests/coretests/src/com/android/internal/os/DebugTest.java
@@ -0,0 +1,67 @@
+/*
+ * Copyright (C) 2012 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.android.internal.os;
+
+import android.os.Debug;
+
+import android.test.suitebuilder.annotation.SmallTest;
+import junit.framework.TestCase;
+
+@SmallTest
+public class DebugTest extends TestCase {
+
+    private final static String EXPECTED_GET_CALLER =
+            "com\\.android\\.internal\\.os\\.DebugTest\\.testGetCaller:\\d\\d";
+    private final static String EXPECTED_GET_CALLERS =
+            "com\\.android\\.internal\\.os\\.DebugTest.callDepth3:\\d\\d " +
+            "com\\.android\\.internal\\.os\\.DebugTest.callDepth2:\\d\\d " +
+            "com\\.android\\.internal\\.os\\.DebugTest.callDepth1:\\d\\d ";
+
+    /**
+     * @return String consisting of the caller to this method.
+     */
+    private String callDepth0() {
+        return Debug.getCaller();
+    }
+
+    public void testGetCaller() {
+        assertTrue(callDepth0().matches(EXPECTED_GET_CALLER));
+    }
+
+    /**
+     * @return String consisting of the callers to this method.
+     */
+    private String callDepth4() {
+        return Debug.getCallers(3);
+    }
+
+    private String callDepth3() {
+        return callDepth4();
+    }
+
+    private String callDepth2() {
+        return callDepth3();
+    }
+
+    private String callDepth1() {
+        return callDepth2();
+    }
+
+    public void testGetCallers() {
+        assertTrue(callDepth1().matches(EXPECTED_GET_CALLERS));
+    }
+}