001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.harmony.vm;
018:
019: /**
020: * Provides the methods to get an information about the execution stack. These
021: * methods may be used by different Java APIs such as security classes, SQL
022: * packages, Class, ClassLoader and so on.
023: * <p>
024: * Note, that some of the methods do almost the same things, still the different
025: * methods must be used for different tasks to reach the better performance.
026: * <p>
027: * This class must be implemented according to the common policy for porting
028: * interfaces - see the porting interface overview for more details.
029: *
030: * @author Evgueni Brevnov, Roman S. Bushmanov
031: * @version $Revision: 1.1.6.4 $
032: *
033: * @api2vm
034: */
035: public final class VMStack {
036:
037: /**
038: * This class is not supposed to be instantiated.
039: */
040: private VMStack() {
041: }
042:
043: /**
044: * Returns the class from the specified depth in the stack. If the
045: * specified depth is equal to zero then the caller of the caller of this
046: * method should be returned. Reflection stack frames should not be taken
047: * into account.
048: *
049: * @param depth the stack depth to get a caller class from. It is not
050: * negative one.
051: * @return class a class from the stack. If there is no class in specified
052: * depth, null is returned.
053: * @api2vm
054: */
055: public static native Class<?> getCallerClass(int depth);
056:
057: /**
058: * Collects and returns the stack of the current thread as an array of
059: * classes. Resulting array should contain maxSize elements at the maximum.
060: * Note that reflection stack frames should not be taken into account. The
061: * caller of the caller of the caller of this method is stored as a first
062: * element of the array. If considerPrivileged is true then the last
063: * element of the array should be the caller of the most recent privileged
064: * method.
065: * <p>
066: * This method may be used by security checks implementation. It is not
067: * supposed to be used by Throwable class.
068: *
069: * @param maxSize maximum size of resulting array. If maxSize is less than
070: * zero array may contain any number of elements.
071: * @param considerPrivileged indicates that privileged methods should be
072: * taken into account. It means if considerPrivileged is true the
073: * last element of resulting array should be the caller of the most
074: * recent privileged method. If considerPrivileged is false then
075: * privileged methods don't affect resulting array.
076: *
077: * @return a stack of invoked methods as an array of classes.
078: * @api2vm
079: */
080: public static native Class[] getClasses(int maxSize,
081: boolean considerPrivileged);
082:
083: /**
084: * Saves stack information of currently executing thread. Returned object
085: * can be used as a handler to obtain an array of
086: * <code>java.lang.StackTraceElement</code> by means of the
087: * {@link VMStack#getStackTrace() VMStack.getStackTrace()} method.
088: *
089: * @return handler of the current stack.
090: */
091: public static native Object getStackState();
092:
093: /**
094: * Collects and returns the classes of invoked methods as an array of the
095: * {@link Class} objects. This method may be used by
096: * <code>java.lang.Throwable</code> class implementation.
097: * <p>
098: * Resulting stack should contain native stack frames as well as reflection
099: * stack frames.
100: * <p>
101: * <b>Note</b>, that it returns classes for all stack, without any checks.
102: * It's fast, simple version of {@link VMStack#getClasses() VMStack.getClasses()}
103: * method, and used from Throwable class implementation.
104: *
105: * @param state handler returned by the
106: * {@link VMStack#getStackState() VMStack.getStackState()} method.
107: * @return array of <code>Class</code> elements. If stack is
108: * empty then null should be returned.
109: * @api2vm
110: */
111: public static native Class[] getStackClasses(Object state);
112:
113: /**
114: * Collects and returns the stack of invoked methods as an array of the
115: * {@link StackTraceElement} objects. This method may be used by
116: * <code>java.lang.Throwable</code> class implementation.
117: * <p>
118: * Resulting stack should contain native stack frames as well as reflection
119: * stack frames.
120: * <p>
121: * <b>Note</b>, that stack frames corresponding to exception creation should
122: * be excluded form the resulting array. The most top (recently invoked)
123: * method is stored as a first element of the array.
124: *
125: * @param state handler returned by the
126: * {@link VMStack#getStackState() VMStack.getStackState()} method.
127: * @return array of <code>StackTraceElement</code> elements. If stack is
128: * empty then array of length 0 should be returned.
129: * @api2vm
130: */
131: public static native StackTraceElement[] getStackTrace(Object state);
132:
133: public static native StackTraceElement[] getThreadStackTrace(
134: Thread t);
135: }
|