CodeBuilder.CatchBuilder (Java SE 26 & JDK 26)
Description: declaration: module: java.base, package: java.lang.classfile, interface: CodeBuilder, interface: CatchBuilder
Keywords: java.lang.classfile.CodeBuilder.CatchBuilder interface

# Interface CodeBuilder.CatchBuilder

Enclosing interface:
  `CodeBuilder`

public static sealed interface CodeBuilder.CatchBuilder
A builder to add catch blocks.

The order of catch blocks is significant. When an exception is thrown by the try block, the first catch block whose exception type is the same class as or a superclass of the class of exception thrown is branched to (JVMS 2.10).

Since:
  24
See Also:
  - `CodeBuilder.trying(Consumer, Consumer)`
  - `ExceptionCatch`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `CodeBuilder.CatchBuilder`
  `catching(ClassDesc exceptionType, Consumer<CodeBuilder.BlockCodeBuilder> catchHandler)`
  Adds a catch block that catches an exception of the given type.
  `void`
  `catchingAll(Consumer<CodeBuilder.BlockCodeBuilder> catchAllHandler)`
  Adds a "catch" block that catches all exceptions.
  `CodeBuilder.CatchBuilder`
  `catchingMulti(List<ClassDesc> exceptionTypes, Consumer<CodeBuilder.BlockCodeBuilder> catchHandler)`
  Adds a catch block that catches exceptions of the given types.

- ## Method Details

  - ### catching

    CodeBuilder.CatchBuilder catching(ClassDesc exceptionType, Consumer<CodeBuilder.BlockCodeBuilder> catchHandler)
    Adds a catch block that catches an exception of the given type.

    The caught exception will be on top of the operand stack when the catch block is entered.

    The `CodeBuilder.BlockCodeBuilder.breakLabel()` for the catch block corresponds to the break label of the `tryHandler` block in `CodeBuilder.trying(Consumer, Consumer)`.

    If the type of exception is `null` then the catch block catches all exceptions.

    API Note:
      If the type of exception to catch is already handled by previous catch blocks, this block will never be executed.
    Parameters:
      `exceptionType` - the type of exception to catch, may be `null`
      `catchHandler` - handler that receives a `CodeBuilder.BlockCodeBuilder` to generate the body of the catch block
    Returns:
      this builder
    Throws:
      `IllegalArgumentException` - if `exceptionType` represents a primitive type
    See Also:
      - `catchingMulti(List, Consumer)`
      - `catchingAll(Consumer)`

  - ### catchingMulti

    CodeBuilder.CatchBuilder catchingMulti(List<ClassDesc> exceptionTypes, Consumer<CodeBuilder.BlockCodeBuilder> catchHandler)
    Adds a catch block that catches exceptions of the given types.

    The caught exception will be on top of the operand stack when the catch block is entered.

    The `CodeBuilder.BlockCodeBuilder.breakLabel()` for the catch block corresponds to the break label of the `tryHandler` block in `CodeBuilder.trying(Consumer, Consumer)`.

    If list of exception types is empty then the catch block catches all exceptions.

    API Note:
      If every type of exception to catch is already handled by previous catch blocks, this block will never be executed.
    Parameters:
      `exceptionTypes` - the types of exception to catch
      `catchHandler` - handler that receives a `CodeBuilder.BlockCodeBuilder` to generate the body of the catch block
    Returns:
      this builder
    Throws:
      `IllegalArgumentException` - if any exception type represents a primitive type
    See Also:
      - `catching(ClassDesc, Consumer)`
      - `catchingAll(Consumer)`

  - ### catchingAll

    void catchingAll(Consumer<CodeBuilder.BlockCodeBuilder> catchAllHandler)
    Adds a "catch" block that catches all exceptions.

    The `CodeBuilder.BlockCodeBuilder.breakLabel()` for the catch block corresponds to the break label of the `tryHandler` block in `CodeBuilder.trying(Consumer, Consumer)`.

    The caught exception will be on top of the operand stack when the catch block is entered.

    API Note:
      Since this block intercepts all exceptions, all subsequent catch blocks will never be executed.
    Parameters:
      `catchAllHandler` - handler that receives a `CodeBuilder.BlockCodeBuilder` to generate the body of the catch block
    See Also:
      - `catching(ClassDesc, Consumer)`
      - `catchingMulti(List, Consumer)`