Module java.base
Package java.lang.classfilePREVIEW

# Interface CodeBuilder.CatchBuilder

Enclosing interface:
  `CodeBuilderPREVIEW`

public static sealed interface CodeBuilder.CatchBuilder
`CatchBuilder` is a preview API of the Java platform.
Programs can only use `CatchBuilder` when preview features are enabled.
Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
A builder to add catch blocks.

Since:
  22
See Also:
  - `CodeBuilder.trying(java.util.function.Consumer<java.lang.classfile.CodeBuilder.BlockCodeBuilder>, java.util.function.Consumer<java.lang.classfile.CodeBuilder.CatchBuilder>)`PREVIEW

- ## Method Summary

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

- ## Method Details

  - ### catching

    CodeBuilder.CatchBuilderPREVIEW catching(ClassDesc exceptionType, Consumer<CodeBuilder.BlockCodeBuilderPREVIEW> 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.

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

    Parameters:
      `exceptionType` - the type of exception to catch.
      `catchHandler` - handler that receives a CodeBuilderPREVIEW to generate the body of the catch block.
    Returns:
      this builder
    Throws:
      `IllegalArgumentException` - if an existing catch block catches an exception of the given type or `exceptionType` represents a primitive type
    See Also:
      - `catchingMulti(java.util.List<java.lang.constant.ClassDesc>, java.util.function.Consumer<java.lang.classfile.CodeBuilder.BlockCodeBuilder>)`
      - `catchingAll(java.util.function.Consumer<java.lang.classfile.CodeBuilder.BlockCodeBuilder>)`

  - ### catchingMulti

    CodeBuilder.CatchBuilderPREVIEW catchingMulti(List<ClassDesc> exceptionTypes, Consumer<CodeBuilder.BlockCodeBuilderPREVIEW> 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.

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

    Parameters:
      `exceptionTypes` - the types of exception to catch.
      `catchHandler` - handler that receives a CodeBuilderPREVIEW to generate the body of the catch block.
    Returns:
      this builder
    Throws:
      `IllegalArgumentException` - if an existing catch block catches one or more exceptions of the given types.
    See Also:
      - `catching(java.lang.constant.ClassDesc, java.util.function.Consumer<java.lang.classfile.CodeBuilder.BlockCodeBuilder>)`
      - `catchingAll(java.util.function.Consumer<java.lang.classfile.CodeBuilder.BlockCodeBuilder>)`

  - ### catchingAll

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

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

    Parameters:
      `catchAllHandler` - handler that receives a CodeBuilderPREVIEW to generate the body of the catch block
    Throws:
      `IllegalArgumentException` - if an existing catch block catches all exceptions.
    See Also:
      - `catching(java.lang.constant.ClassDesc, java.util.function.Consumer<java.lang.classfile.CodeBuilder.BlockCodeBuilder>)`
      - `catchingMulti(java.util.List<java.lang.constant.ClassDesc>, java.util.function.Consumer<java.lang.classfile.CodeBuilder.BlockCodeBuilder>)`