java/14 : java.base/java/lang/StackTraceElement.java

StackTraceElement

https://openjdk.java.net/

GPLv2 + Classpath Exception

/*
 * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package java.lang;

import jdk.internal.loader.BuiltinClassLoader;
import jdk.internal.misc.VM;
import jdk.internal.module.ModuleHashes;
import jdk.internal.module.ModuleReferenceImpl;

import java.lang.module.ModuleDescriptor.Version;
import java.lang.module.ModuleReference;
import java.lang.module.ResolvedModule;
import java.util.HashSet;
import java.util.Objects;
import java.util.Optional;
import java.util.Set;

An element in a stack trace, as returned by Throwable.getStackTrace(). Each element represents a single stack frame. All stack frames except for the one at the top of the stack represent a method invocation. The frame at the top of the stack represents the execution point at which the stack trace was generated. Typically, this is the point at which the throwable corresponding to the stack trace was created. 
Author: Josh Bloch
Since:  1.4/**
 * An element in a stack trace, as returned by {@link
 * Throwable#getStackTrace()}.  Each element represents a single stack frame.
 * All stack frames except for the one at the top of the stack represent
 * a method invocation.  The frame at the top of the stack represents the
 * execution point at which the stack trace was generated.  Typically,
 * this is the point at which the throwable corresponding to the stack trace
 * was created.
 *
 * @since  1.4
 * @author Josh Bloch
 */
public final class StackTraceElement implements java.io.Serializable {

    // For Throwables and StackWalker, the VM initially sets this field to a
    // reference to the declaring Class.  The Class reference is used to
    // construct the 'format' bitmap, and then is cleared.
    //
    // For STEs constructed using the public constructors, this field is not used.
    private transient Class<?> declaringClassObject;

    // Normally initialized by VM
    private String classLoaderName;
    private String moduleName;
    private String moduleVersion;
    private String declaringClass;
    private String methodName;
    private String fileName;
    private int    lineNumber;
    private byte   format = 0; // Default to show all

    Creates a stack trace element representing the specified execution point. The module name and module version of the stack trace element will be null. 
Params: declaringClass – the fully qualified name of the class containing
       the execution point represented by the stack trace element
methodName – the name of the method containing the execution point
       represented by the stack trace element
fileName – the name of the file containing the execution point represented by the stack trace element, or null if this information is unavailable
lineNumber – the line number of the source line containing the
        execution point represented by this stack trace element, or
        a negative number if this information is unavailable. A value
        of -2 indicates that the method containing the execution point
        is a native method
Throws: NullPointerException – if declaringClass or methodName is null
Since: 1.5
@revised 9
@spec JPMS/**
     * Creates a stack trace element representing the specified execution
     * point. The {@link #getModuleName module name} and {@link
     * #getModuleVersion module version} of the stack trace element will
     * be {@code null}.
     *
     * @param declaringClass the fully qualified name of the class containing
     *        the execution point represented by the stack trace element
     * @param methodName the name of the method containing the execution point
     *        represented by the stack trace element
     * @param fileName the name of the file containing the execution point
     *         represented by the stack trace element, or {@code null} if
     *         this information is unavailable
     * @param lineNumber the line number of the source line containing the
     *         execution point represented by this stack trace element, or
     *         a negative number if this information is unavailable. A value
     *         of -2 indicates that the method containing the execution point
     *         is a native method
     * @throws NullPointerException if {@code declaringClass} or
     *         {@code methodName} is null
     * @since 1.5
     * @revised 9
     * @spec JPMS
     */
    public StackTraceElement(String declaringClass, String methodName,
                             String fileName, int lineNumber) {
        this(null, null, null, declaringClass, methodName, fileName, lineNumber);
    }

    Creates a stack trace element representing the specified execution
point.
Params: classLoaderName – the class loader name if the class loader of the class containing the execution point represented by the stack trace is named; otherwise null
moduleName – the module name if the class containing the execution point represented by the stack trace is in a named module; otherwise null
moduleVersion – the module version if the class containing the execution point represented by the stack trace is in a named module that has a version; otherwise null
declaringClass – the fully qualified name of the class containing
       the execution point represented by the stack trace element
methodName – the name of the method containing the execution point
       represented by the stack trace element
fileName – the name of the file containing the execution point represented by the stack trace element, or null if this information is unavailable
lineNumber – the line number of the source line containing the
       execution point represented by this stack trace element, or
       a negative number if this information is unavailable. A value
       of -2 indicates that the method containing the execution point
       is a native method
Throws: NullPointerException – if declaringClass is null or methodName is null
Since: 9
@spec JPMS/**
     * Creates a stack trace element representing the specified execution
     * point.
     *
     * @param classLoaderName the class loader name if the class loader of
     *        the class containing the execution point represented by
     *        the stack trace is named; otherwise {@code null}
     * @param moduleName the module name if the class containing the
     *        execution point represented by the stack trace is in a named
     *        module; otherwise {@code null}
     * @param moduleVersion the module version if the class containing the
     *        execution point represented by the stack trace is in a named
     *        module that has a version; otherwise {@code null}
     * @param declaringClass the fully qualified name of the class containing
     *        the execution point represented by the stack trace element
     * @param methodName the name of the method containing the execution point
     *        represented by the stack trace element
     * @param fileName the name of the file containing the execution point
     *        represented by the stack trace element, or {@code null} if
     *        this information is unavailable
     * @param lineNumber the line number of the source line containing the
     *        execution point represented by this stack trace element, or
     *        a negative number if this information is unavailable. A value
     *        of -2 indicates that the method containing the execution point
     *        is a native method
     *
     * @throws NullPointerException if {@code declaringClass} is {@code null}
     *         or {@code methodName} is {@code null}
     *
     * @since 9
     * @spec JPMS
     */
    public StackTraceElement(String classLoaderName,
                             String moduleName, String moduleVersion,
                             String declaringClass, String methodName,
                             String fileName, int lineNumber) {
        this.classLoaderName = classLoaderName;
        this.moduleName      = moduleName;
        this.moduleVersion   = moduleVersion;
        this.declaringClass  = Objects.requireNonNull(declaringClass, "Declaring class is null");
        this.methodName      = Objects.requireNonNull(methodName, "Method name is null");
        this.fileName        = fileName;
        this.lineNumber      = lineNumber;
    }

    /*
     * Private constructor for the factory methods to create StackTraceElement
     * for Throwable and StackFrameInfo
     */
    private StackTraceElement() {}

    Returns the name of the source file containing the execution point represented by this stack trace element. Generally, this corresponds to the SourceFile attribute of the relevant class file (as per The Java Virtual Machine Specification, Section
4.7.7).  In some systems, the name may refer to some source code unit
other than a file, such as an entry in source repository.
Returns: the name of the file containing the execution point represented by this stack trace element, or null if this information is unavailable./**
     * Returns the name of the source file containing the execution point
     * represented by this stack trace element.  Generally, this corresponds
     * to the {@code SourceFile} attribute of the relevant {@code class}
     * file (as per <i>The Java Virtual Machine Specification</i>, Section
     * 4.7.7).  In some systems, the name may refer to some source code unit
     * other than a file, such as an entry in source repository.
     *
     * @return the name of the file containing the execution point
     *         represented by this stack trace element, or {@code null} if
     *         this information is unavailable.
     */
    public String getFileName() {
        return fileName;
    }

    Returns the line number of the source line containing the execution point represented by this stack trace element. Generally, this is derived from the LineNumberTable attribute of the relevant class file (as per The Java Virtual Machine
Specification, Section 4.7.8).
Returns: the line number of the source line containing the execution
        point represented by this stack trace element, or a negative
        number if this information is unavailable./**
     * Returns the line number of the source line containing the execution
     * point represented by this stack trace element.  Generally, this is
     * derived from the {@code LineNumberTable} attribute of the relevant
     * {@code class} file (as per <i>The Java Virtual Machine
     * Specification</i>, Section 4.7.8).
     *
     * @return the line number of the source line containing the execution
     *         point represented by this stack trace element, or a negative
     *         number if this information is unavailable.
     */
    public int getLineNumber() {
        return lineNumber;
    }

    Returns the module name of the module containing the execution point
represented by this stack trace element.
See Also: Module.getName()
Returns: the module name of the Module containing the execution point represented by this stack trace element; null if the module name is not available.
Since: 9
@spec JPMS/**
     * Returns the module name of the module containing the execution point
     * represented by this stack trace element.
     *
     * @return the module name of the {@code Module} containing the execution
     *         point represented by this stack trace element; {@code null}
     *         if the module name is not available.
     * @since 9
     * @spec JPMS
     * @see Module#getName()
     */
    public String getModuleName() {
        return moduleName;
    }

    Returns the module version of the module containing the execution point
represented by this stack trace element.
See Also: Version
Returns: the module version of the Module containing the execution point represented by this stack trace element; null if the module version is not available.
Since: 9
@spec JPMS/**
     * Returns the module version of the module containing the execution point
     * represented by this stack trace element.
     *
     * @return the module version of the {@code Module} containing the execution
     *         point represented by this stack trace element; {@code null}
     *         if the module version is not available.
     * @since 9
     * @spec JPMS
     * @see java.lang.module.ModuleDescriptor.Version
     */
    public String getModuleVersion() {
        return moduleVersion;
    }

    Returns the name of the class loader of the class containing the
execution point represented by this stack trace element.
See Also: ClassLoader.getName()
Returns: the name of the class loader of the class containing the execution point represented by this stack trace element; null if the class loader is not named.
Since: 9
@spec JPMS/**
     * Returns the name of the class loader of the class containing the
     * execution point represented by this stack trace element.
     *
     * @return the name of the class loader of the class containing the execution
     *         point represented by this stack trace element; {@code null}
     *         if the class loader is not named.
     *
     * @since 9
     * @spec JPMS
     * @see java.lang.ClassLoader#getName()
     */
    public String getClassLoaderName() {
        return classLoaderName;
    }

    Returns the fully qualified name of the class containing the
execution point represented by this stack trace element.
Returns: the fully qualified name of the Class containing the execution point represented by this stack trace element./**
     * Returns the fully qualified name of the class containing the
     * execution point represented by this stack trace element.
     *
     * @return the fully qualified name of the {@code Class} containing
     *         the execution point represented by this stack trace element.
     */
    public String getClassName() {
        return declaringClass;
    }

    Returns the name of the method containing the execution point
represented by this stack trace element.  If the execution point is
contained in an instance or class initializer, this method will return
the appropriate special method name, <init> or <clinit>, as per Section 3.9 of The Java Virtual
Machine Specification.
Returns: the name of the method containing the execution point
        represented by this stack trace element./**
     * Returns the name of the method containing the execution point
     * represented by this stack trace element.  If the execution point is
     * contained in an instance or class initializer, this method will return
     * the appropriate <i>special method name</i>, {@code <init>} or
     * {@code <clinit>}, as per Section 3.9 of <i>The Java Virtual
     * Machine Specification</i>.
     *
     * @return the name of the method containing the execution point
     *         represented by this stack trace element.
     */
    public String getMethodName() {
        return methodName;
    }

    Returns true if the method containing the execution point
represented by this stack trace element is a native method.
Returns: true if the method containing the execution point represented by this stack trace element is a native method./**
     * Returns true if the method containing the execution point
     * represented by this stack trace element is a native method.
     *
     * @return {@code true} if the method containing the execution point
     *         represented by this stack trace element is a native method.
     */
    public boolean isNativeMethod() {
        return lineNumber == -2;
    }

    Returns a string representation of this stack trace element.
See Also: Throwable.printStackTrace()
API Note: The format of this string depends on the implementation, but the
following examples may be regarded as typical:

 "com.foo.loader/foo@9.0/com.foo.Main.run(Main.java:101)" - See the description below. 
 "com.foo.loader/foo@9.0/com.foo.Main.run(Main.java)" - The line number is unavailable. 
 "com.foo.loader/foo@9.0/com.foo.Main.run(Unknown Source)" - Neither the file name nor the line number is available. 
 "com.foo.loader/foo@9.0/com.foo.Main.run(Native Method)" - The method containing the execution point is a native method. 
 "com.foo.loader//com.foo.bar.App.run(App.java:12)" - The class of the execution point is defined in the unnamed module of the class loader named com.foo.loader. 
 "acme@2.1/org.acme.Lib.test(Lib.java:80)" - The class of the execution point is defined in acme module loaded by a built-in class loader such as the application class loader. 
 "MyClass.mash(MyClass.java:9)" - MyClass class is on the application class path. 

 The first example shows a stack trace element consisting of three elements, each separated by "/" followed with the source file name and the line number of the source line containing the execution point. The first element "com.foo.loader" is the name of the class loader. The second element "foo@9.0" is the module name and version. The third element is the method containing the execution point; "com.foo.Main"" is the fully-qualified class name and "run" is the name of the method. "Main.java" is the source file name and "101" is the line number. 
 If a class is defined in an unnamed module then the second element is omitted as shown in "com.foo.loader//com.foo.bar.App.run(App.java:12)". 
 If the class loader is a 
built-in class loader or is not named then the first element and its following "/" are omitted as shown in "acme@2.1/org.acme.Lib.test(Lib.java:80)". If the first element is omitted and the module is an unnamed module, the second element and its following "/" are also omitted as shown in "MyClass.mash(MyClass.java:9)". 
 The toString method may return two different values on two StackTraceElement instances that are equal, for example one created via the constructor, and one obtained from Throwable or StackFrame, where an implementation may choose to omit some element in the returned string.
@revised 9
@spec JPMS/**
     * Returns a string representation of this stack trace element.
     *
     * @apiNote The format of this string depends on the implementation, but the
     * following examples may be regarded as typical:
     * <ul>
     * <li>
     *     "{@code com.foo.loader/foo@9.0/com.foo.Main.run(Main.java:101)}"
     * - See the description below.
     * </li>
     * <li>
     *     "{@code com.foo.loader/foo@9.0/com.foo.Main.run(Main.java)}"
     * - The line number is unavailable.
     * </li>
     * <li>
     *     "{@code com.foo.loader/foo@9.0/com.foo.Main.run(Unknown Source)}"
     * - Neither the file name nor the line number is available.
     * </li>
     * <li>
     *     "{@code com.foo.loader/foo@9.0/com.foo.Main.run(Native Method)}"
     * - The method containing the execution point is a native method.
     * </li>
     * <li>
     *     "{@code com.foo.loader//com.foo.bar.App.run(App.java:12)}"
     * - The class of the execution point is defined in the unnamed module of
     * the class loader named {@code com.foo.loader}.
     * </li>
     * <li>
     *     "{@code acme@2.1/org.acme.Lib.test(Lib.java:80)}"
     * - The class of the execution point is defined in {@code acme} module
     * loaded by a built-in class loader such as the application class loader.
     * </li>
     * <li>
     *     "{@code MyClass.mash(MyClass.java:9)}"
     * - {@code MyClass} class is on the application class path.
     * </li>
     * </ul>
     *
     * <p> The first example shows a stack trace element consisting of
     * three elements, each separated by {@code "/"} followed with
     * the source file name and the line number of the source line
     * containing the execution point.
     *
     * The first element "{@code com.foo.loader}" is
     * the name of the class loader.  The second element "{@code foo@9.0}"
     * is the module name and version.  The third element is the method
     * containing the execution point; "{@code com.foo.Main"}" is the
     * fully-qualified class name and "{@code run}" is the name of the method.
     * "{@code Main.java}" is the source file name and "{@code 101}" is
     * the line number.
     *
     * <p> If a class is defined in an <em>unnamed module</em>
     * then the second element is omitted as shown in
     * "{@code com.foo.loader//com.foo.bar.App.run(App.java:12)}".
     *
     * <p> If the class loader is a <a href="ClassLoader.html#builtinLoaders">
     * built-in class loader</a> or is not named then the first element
     * and its following {@code "/"} are omitted as shown in
     * "{@code acme@2.1/org.acme.Lib.test(Lib.java:80)}".
     * If the first element is omitted and the module is an unnamed module,
     * the second element and its following {@code "/"} are also omitted
     * as shown in "{@code MyClass.mash(MyClass.java:9)}".
     *
     * <p> The {@code toString} method may return two different values on two
     * {@code StackTraceElement} instances that are
     * {@linkplain #equals(Object) equal}, for example one created via the
     * constructor, and one obtained from {@link java.lang.Throwable} or
     * {@link java.lang.StackWalker.StackFrame}, where an implementation may
     * choose to omit some element in the returned string.
     *
     * @revised 9
     * @spec JPMS
     * @see    Throwable#printStackTrace()
     */
    public String toString() {
        String s = "";
        if (!dropClassLoaderName() && classLoaderName != null &&
                !classLoaderName.isEmpty()) {
            s += classLoaderName + "/";
        }
        if (moduleName != null && !moduleName.isEmpty()) {
            s += moduleName;

            if (!dropModuleVersion() && moduleVersion != null &&
                    !moduleVersion.isEmpty()) {
                s += "@" + moduleVersion;
            }
        }
        s = s.isEmpty() ? declaringClass : s + "/" + declaringClass;

        return s + "." + methodName + "(" +
             (isNativeMethod() ? "Native Method)" :
              (fileName != null && lineNumber >= 0 ?
               fileName + ":" + lineNumber + ")" :
                (fileName != null ?  ""+fileName+")" : "Unknown Source)")));
    }

    Returns true if the specified object is another StackTraceElement instance representing the same execution point as this instance. Two stack trace elements a and b are equal if and only if: 
    equals(a.getClassLoaderName(), b.getClassLoaderName()) &&
    equals(a.getModuleName(), b.getModuleName()) &&
    equals(a.getModuleVersion(), b.getModuleVersion()) &&
    equals(a.getClassName(), b.getClassName()) &&
    equals(a.getMethodName(), b.getMethodName())
    equals(a.getFileName(), b.getFileName()) &&
    a.getLineNumber() == b.getLineNumber()
 where equals has the semantics of Objects.equals. 
Params: obj – the object to be compared with this stack trace element.
Returns: true if the specified object is another StackTraceElement instance representing the same execution point as this instance.
@revised 9
@spec JPMS/**
     * Returns true if the specified object is another
     * {@code StackTraceElement} instance representing the same execution
     * point as this instance.  Two stack trace elements {@code a} and
     * {@code b} are equal if and only if:
     * <pre>{@code
     *     equals(a.getClassLoaderName(), b.getClassLoaderName()) &&
     *     equals(a.getModuleName(), b.getModuleName()) &&
     *     equals(a.getModuleVersion(), b.getModuleVersion()) &&
     *     equals(a.getClassName(), b.getClassName()) &&
     *     equals(a.getMethodName(), b.getMethodName())
     *     equals(a.getFileName(), b.getFileName()) &&
     *     a.getLineNumber() == b.getLineNumber()
     *
     * }</pre>
     * where {@code equals} has the semantics of {@link
     * java.util.Objects#equals(Object, Object) Objects.equals}.
     *
     * @param  obj the object to be compared with this stack trace element.
     * @return true if the specified object is another
     *         {@code StackTraceElement} instance representing the same
     *         execution point as this instance.
     *
     * @revised 9
     * @spec JPMS
     */
    public boolean equals(Object obj) {
        if (obj==this)
            return true;
        if (!(obj instanceof StackTraceElement))
            return false;
        StackTraceElement e = (StackTraceElement)obj;
        return Objects.equals(classLoaderName, e.classLoaderName) &&
            Objects.equals(moduleName, e.moduleName) &&
            Objects.equals(moduleVersion, e.moduleVersion) &&
            e.declaringClass.equals(declaringClass) &&
            e.lineNumber == lineNumber &&
            Objects.equals(methodName, e.methodName) &&
            Objects.equals(fileName, e.fileName);
    }

    Returns a hash code value for this stack trace element.
/**
     * Returns a hash code value for this stack trace element.
     */
    public int hashCode() {
        int result = 31*declaringClass.hashCode() + methodName.hashCode();
        result = 31*result + Objects.hashCode(classLoaderName);
        result = 31*result + Objects.hashCode(moduleName);
        result = 31*result + Objects.hashCode(moduleVersion);
        result = 31*result + Objects.hashCode(fileName);
        result = 31*result + lineNumber;
        return result;
    }


    Called from of() methods to set the 'format' bitmap using the Class
reference stored in declaringClassObject, and then clear the reference.

If the module is a non-upgradeable JDK module, then set
JDK_NON_UPGRADEABLE_MODULE to omit its version string.

If the loader is one of the built-in loaders (`boot`, `platform`, or `app`)
then set BUILTIN_CLASS_LOADER to omit the first element (`/`).
/**
     * Called from of() methods to set the 'format' bitmap using the Class
     * reference stored in declaringClassObject, and then clear the reference.
     *
     * <p>
     * If the module is a non-upgradeable JDK module, then set
     * JDK_NON_UPGRADEABLE_MODULE to omit its version string.
     * <p>
     * If the loader is one of the built-in loaders (`boot`, `platform`, or `app`)
     * then set BUILTIN_CLASS_LOADER to omit the first element (`<loader>/`).
     */
    private synchronized void computeFormat() {
        try {
            Class<?> cls = (Class<?>) declaringClassObject;
            ClassLoader loader = cls.getClassLoader0();
            Module m = cls.getModule();
            byte bits = 0;

            // First element - class loader name
            // Call package-private ClassLoader::name method

            if (loader instanceof BuiltinClassLoader) {
                bits |= BUILTIN_CLASS_LOADER;
            }

            // Second element - module name and version

            // Omit if is a JDK non-upgradeable module (recorded in the hashes
            // in java.base)
            if (isHashedInJavaBase(m)) {
                bits |= JDK_NON_UPGRADEABLE_MODULE;
            }
            format = bits;
        } finally {
            // Class reference no longer needed, clear it
            declaringClassObject = null;
        }
    }

    private static final byte BUILTIN_CLASS_LOADER       = 0x1;
    private static final byte JDK_NON_UPGRADEABLE_MODULE = 0x2;

    private boolean dropClassLoaderName() {
        return (format & BUILTIN_CLASS_LOADER) == BUILTIN_CLASS_LOADER;
    }

    private boolean dropModuleVersion() {
        return (format & JDK_NON_UPGRADEABLE_MODULE) == JDK_NON_UPGRADEABLE_MODULE;
    }

    Returns true if the module is hashed with java.base.

This method returns false when running on the exploded image
since JDK modules are not hashed. They have no Version attribute
and so "@" part will be omitted anyway.
/**
     * Returns true if the module is hashed with java.base.
     * <p>
     * This method returns false when running on the exploded image
     * since JDK modules are not hashed. They have no Version attribute
     * and so "@<version>" part will be omitted anyway.
     */
    private static boolean isHashedInJavaBase(Module m) {
        // return true if module system is not initialized as the code
        // must be in java.base
        if (!VM.isModuleSystemInited())
            return true;

        return ModuleLayer.boot() == m.getLayer() && HashedModules.contains(m);
    }

    /*
     * Finds JDK non-upgradeable modules, i.e. the modules that are
     * included in the hashes in java.base.
     */
    private static class HashedModules {
        static Set<String> HASHED_MODULES = hashedModules();

        static Set<String> hashedModules() {

            Optional<ResolvedModule> resolvedModule = ModuleLayer.boot()
                    .configuration()
                    .findModule("java.base");
            assert resolvedModule.isPresent();
            ModuleReference mref = resolvedModule.get().reference();
            assert mref instanceof ModuleReferenceImpl;
            ModuleHashes hashes = ((ModuleReferenceImpl)mref).recordedHashes();
            if (hashes != null) {
                Set<String> names = new HashSet<>(hashes.names());
                names.add("java.base");
                return names;
            }

            return Set.of();
        }

        static boolean contains(Module m) {
            return HASHED_MODULES.contains(m.getName());
        }
    }


    /*
     * Returns an array of StackTraceElements of the given depth
     * filled from the backtrace of a given Throwable.
     */
    static StackTraceElement[] of(Throwable x, int depth) {
        StackTraceElement[] stackTrace = new StackTraceElement[depth];
        for (int i = 0; i < depth; i++) {
            stackTrace[i] = new StackTraceElement();
        }

        // VM to fill in StackTraceElement
        initStackTraceElements(stackTrace, x);

        // ensure the proper StackTraceElement initialization
        for (StackTraceElement ste : stackTrace) {
            ste.computeFormat();
        }
        return stackTrace;
    }

    /*
     * Returns a StackTraceElement from a given StackFrameInfo.
     */
    static StackTraceElement of(StackFrameInfo sfi) {
        StackTraceElement ste = new StackTraceElement();
        initStackTraceElement(ste, sfi);

        ste.computeFormat();
        return ste;
    }

    /*
     * Sets the given stack trace elements with the backtrace
     * of the given Throwable.
     */
    private static native void initStackTraceElements(StackTraceElement[] elements,
                                                      Throwable x);
    /*
     * Sets the given stack trace element with the given StackFrameInfo
     */
    private static native void initStackTraceElement(StackTraceElement element,
                                                     StackFrameInfo sfi);

    @java.io.Serial
    private static final long serialVersionUID = 6992337162326171013L;
}

Params:	declaringClass – the fully qualified name of the class containing the execution point represented by the stack trace element methodName – the name of the method containing the execution point represented by the stack trace element fileName – the name of the file containing the execution point represented by the stack trace element, or `null` if this information is unavailable lineNumber – the line number of the source line containing the execution point represented by this stack trace element, or a negative number if this information is unavailable. A value of -2 indicates that the method containing the execution point is a native method
Throws:	NullPointerException – if `declaringClass` or `methodName` is null
Since:	1.5
@revised	9
@spec	JPMS

Params:	classLoaderName – the class loader name if the class loader of the class containing the execution point represented by the stack trace is named; otherwise `null` moduleName – the module name if the class containing the execution point represented by the stack trace is in a named module; otherwise `null` moduleVersion – the module version if the class containing the execution point represented by the stack trace is in a named module that has a version; otherwise `null` declaringClass – the fully qualified name of the class containing the execution point represented by the stack trace element methodName – the name of the method containing the execution point represented by the stack trace element fileName – the name of the file containing the execution point represented by the stack trace element, or `null` if this information is unavailable lineNumber – the line number of the source line containing the execution point represented by this stack trace element, or a negative number if this information is unavailable. A value of -2 indicates that the method containing the execution point is a native method
Throws:	NullPointerException – if `declaringClass` is `null` or `methodName` is `null`
Since:	9
@spec	JPMS

See Also:	Module.getName()
Returns:	the module name of the `Module` containing the execution point represented by this stack trace element; `null` if the module name is not available.
Since:	9
@spec	JPMS

See Also:	Version
Returns:	the module version of the `Module` containing the execution point represented by this stack trace element; `null` if the module version is not available.
Since:	9
@spec	JPMS

See Also:	ClassLoader.getName()
Returns:	the name of the class loader of the class containing the execution point represented by this stack trace element; `null` if the class loader is not named.
Since:	9
@spec	JPMS

See Also:	Throwable.printStackTrace()
API Note:	The format of this string depends on the implementation, but the following examples may be regarded as typical: "`com.foo.loader/foo@9.0/com.foo.Main.run(Main.java:101)`" - See the description below. "`com.foo.loader/foo@9.0/com.foo.Main.run(Main.java)`" - The line number is unavailable. "`com.foo.loader/foo@9.0/com.foo.Main.run(Unknown Source)`" - Neither the file name nor the line number is available. "`com.foo.loader/foo@9.0/com.foo.Main.run(Native Method)`" - The method containing the execution point is a native method. "`com.foo.loader//com.foo.bar.App.run(App.java:12)`" - The class of the execution point is defined in the unnamed module of the class loader named `com.foo.loader`. "`acme@2.1/org.acme.Lib.test(Lib.java:80)`" - The class of the execution point is defined in `acme` module loaded by a built-in class loader such as the application class loader. "`MyClass.mash(MyClass.java:9)`" - `MyClass` class is on the application class path. The first example shows a stack trace element consisting of three elements, each separated by `"/"` followed with the source file name and the line number of the source line containing the execution point. The first element "`com.foo.loader`" is the name of the class loader. The second element "`foo@9.0`" is the module name and version. The third element is the method containing the execution point; "`com.foo.Main"`" is the fully-qualified class name and "`run`" is the name of the method. "`Main.java`" is the source file name and "`101`" is the line number. If a class is defined in an unnamed module then the second element is omitted as shown in "`com.foo.loader//com.foo.bar.App.run(App.java:12)`". If the class loader is a built-in class loader or is not named then the first element and its following `"/"` are omitted as shown in "`acme@2.1/org.acme.Lib.test(Lib.java:80)`". If the first element is omitted and the module is an unnamed module, the second element and its following `"/"` are also omitted as shown in "`MyClass.mash(MyClass.java:9)`". The `toString` method may return two different values on two `StackTraceElement` instances that are equal, for example one created via the constructor, and one obtained from `Throwable` or `StackFrame`, where an implementation may choose to omit some element in the returned string.
@revised	9
@spec	JPMS

Params:	obj – the object to be compared with this stack trace element.
Returns:	true if the specified object is another `StackTraceElement` instance representing the same execution point as this instance.
@revised	9
@spec	JPMS

/

java/ 14/ java.base/java/lang/StackTraceElement.java