Module java.base
Package java.lang.classfile.componentsPREVIEW

# Interface CodeStackTracker

All Superinterfaces:
  `ClassFileTransformPREVIEW<CodeTransformPREVIEW,CodeElementPREVIEW,CodeBuilderPREVIEW>`, `CodeTransformPREVIEW`

public sealed interface CodeStackTracker extends CodeTransformPREVIEW
`CodeStackTracker` is a preview API of the Java platform.
Programs can only use `CodeStackTracker` when preview features are enabled.
Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
`CodeStackTracker`PREVIEW is a `CodeTransform`PREVIEW tracking stack content and calculating max stack size.

Sample use:

        var stackTracker = CodeStackTracker.of();
        codeBuilder.transforming(stackTracker, trackedBuilder -> {
            trackedBuilder.aload(0);
            trackedBuilder.lconst_0();
            trackedBuilder.ifThen(...);
            ...
            var stack = stackTracker.stack().get();
            int maxStack = stackTracker.maxStackSize().get();
        });

Since:
  22

- ## Nested Class Summary

  ## Nested classes/interfaces declared in interface java.lang.classfile.ClassFileTransformPREVIEW

  `ClassFileTransform.ResolvedTransformPREVIEW<E extends ClassFileElementPREVIEW>`

- ## Field Summary

  ### Fields declared in interface java.lang.classfile.CodeTransformPREVIEW

  `ACCEPT_ALL`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Optional<Integer>`
  `maxStackSize()`
  Returns tracked max stack size.
  `static CodeStackTrackerPREVIEW`
  `of(TypeKindPREVIEW... initialStack)`
  Creates new instance of `CodeStackTracker`PREVIEW initialized with provided stack items.
  `Optional<Collection<TypeKindPREVIEW>>`
  `stack()`
  Returns Collection of TypeKindPREVIEW representing current stack.

  ### Methods declared in interface java.lang.classfile.ClassFileTransformPREVIEW

  `accept, atEnd, atStart`

  ### Methods declared in interface java.lang.classfile.CodeTransformPREVIEW

  `andThen, resolve`

- ## Method Details

  - ### of

    static CodeStackTrackerPREVIEW of(TypeKindPREVIEW... initialStack)
    Creates new instance of `CodeStackTracker`PREVIEW initialized with provided stack items.
    Parameters:
      `initialStack` - initial stack content
    Returns:
      new instance of `CodeStackTracker`PREVIEW

  - ### stack

    Optional<Collection<TypeKindPREVIEW>> stack()
    Returns Collection of TypeKindPREVIEW representing current stack. Returns an empty Optional when the Stack content is unknown (right after `xRETURN, ATHROW, GOTO, GOTO_W, LOOKUPSWITCH, TABLESWITCH` instructions).

    Temporary unknown stack content can be recovered by binding of a LabelPREVIEW used as target of a branch instruction from existing code with known stack (forward branch target), or by binding of a LabelPREVIEW defining an exception handler (exception handler code start).

    Returns:
      actual stack content, or an empty Optional if unknown

  - ### maxStackSize

    Optional<Integer> maxStackSize()
    Returns tracked max stack size. Returns an empty Optional when max stack size tracking has been lost.

    Max stack size tracking is permanently lost when a stack instruction appears and the actual stack content is unknown.

    Returns:
      tracked max stack size, or an empty Optional if tracking has been lost