Breakpoint

java.lang.Object
- com.oracle.truffle.api.debug.Breakpoint

```
public class Breakpoint
extends Object
```
A request that guest language program execution be suspended at specified locations on behalf of a debugging client session.

Breakpoint lifetime
- A client of a DebuggerSession uses a Breakpoint.Builder to create a new breakpoint, choosing among multiple ways to specify the intended location. Examples include a specified source, a specified URI, line ranges, or an exact SourceSection.
- A new breakpoint cannot affect execution until after it has been installed by a session, which may be done only once.
- A breakpoint that is both installed and enabled (true by default) will suspend any guest language execution thread that arrives at a matching AST location. The breakpoint (synchronously) calls back to the responsible session on the execution thread.
- A breakpoint may be enabled or disabled any number of times.
- A breakpoint that is no longer needed may be disposed. A disposed breakpoint:
  - is disabled
  - is not installed in any session
  - can have no effect on program execution, and
  - must not be used again.
- A session being closed disposes all installed breakpoints.
Example usage: BreakpointSnippets.example()
Since:

0.9

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`class`	`Breakpoint.Builder` Builder implementation for a new `breakpoint`.
`class`	`Breakpoint.ExceptionBuilder` Builder implementation for a new `breakpoint` of `EXCEPTION` kind.
`static class`	`Breakpoint.Kind` Specifies a breakpoint kind.
`static interface`	`Breakpoint.ResolveListener` This listener is called when a breakpoint is resolved at the target location.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`dispose()` Permanently prevents this breakpoint from affecting execution.
`String`	`getCondition()` Returns the expression used to create the current breakpoint condition, null if no condition set.
`int`	`getHitCount()`
`int`	`getIgnoreCount()`
`Breakpoint.Kind`	`getKind()` Returns the kind of this breakpoint.
`String`	`getLocationDescription()`
`SuspendAnchor`	`getSuspendAnchor()` Returns the suspended position within the guest language source location.
`boolean`	`isDisposed()`
`boolean`	`isEnabled()`
`boolean`	`isModifiable()` Test whether this breakpoint can be modified.
`boolean`	`isOneShot()`
`boolean`	`isResolved()`
`static Breakpoint.Builder`	`newBuilder(Source source)` Creates a new breakpoint builder based on a `Source`.
`static Breakpoint.Builder`	`newBuilder(SourceSection sourceSection)` Creates a new breakpoint builder based on the textual region of a guest language source element.
`static Breakpoint.Builder`	`newBuilder(URI sourceUri)` Creates a new breakpoint builder based on a URI location.
`static Breakpoint.ExceptionBuilder`	`newExceptionBuilder(boolean caught, boolean uncaught)` Creates a new exception breakpoint builder.
`void`	`setCondition(String expression)` Assigns to this breakpoint a boolean expression whose evaluation will determine whether the breakpoint suspends execution (i.e.
`void`	`setEnabled(boolean enabled)` Controls whether this breakpoint is currently allowed to suspend execution (true by default).
`void`	`setIgnoreCount(int ignoreCount)` Changes the number of times the breakpoint must be executed before it hits (i.e.
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Method Detail
  - getKind
```
public Breakpoint.Kind getKind()
```
    Returns the kind of this breakpoint.
    
    Since:
    
    19.0
  - isDisposed
```
public boolean isDisposed()
```
    Returns:
    
    whether this breakpoint is permanently unable to affect execution
    
    Since:
    
    0.17
    
    See Also:
    
    Breakpoint.dispose()
  - isEnabled
```
public boolean isEnabled()
```
    Returns:
    
    whether this breakpoint is currently allowed to suspend execution (true by default)
    
    Since:
    
    0.9
    
    See Also:
    
    Breakpoint.setEnabled(boolean)
  - setEnabled
```
public void setEnabled(boolean enabled)
```
    Controls whether this breakpoint is currently allowed to suspend execution (true by default). This can be changed arbitrarily until breakpoint is disposed.
    When not modifiable, IllegalStateException is thrown.
    
    Parameters:
    
    enabled - whether this breakpoint should be allowed to suspend execution
    
    Since:
    
    0.9
  - isResolved
```
public boolean isResolved()
```
    Returns:
    
    whether at least one source has been loaded that contains a match for this breakpoint's location.
    
    Since:
    
    0.17
  - setCondition
```
public void setCondition(String expression)
```
    Assigns to this breakpoint a boolean expression whose evaluation will determine whether the breakpoint suspends execution (i.e. "hits"), null to remove any condition and always suspend.
    Breakpoints are by default unconditional.
    
    Evaluation: expressions are parsed and evaluated in the lexical context of the breakpoint's location. A conditional breakpoint that applies to multiple code locations will be parsed and evaluated separately for each location.
    
    Evaluation failure: when evaluation of a condition fails for any reason, including the return of a non-boolean value:
    - execution suspends, as if evaluation had returned true, and
    - a message is logged that can be retrieved while execution is suspended.
    When not modifiable, IllegalStateException is thrown.
    Parameters:
    
    expression - if non-null, a boolean expression, expressed in the guest language of the breakpoint's location.
    
    Since:
    
    0.9
    
    See Also:
    
    SuspendedEvent.getBreakpointConditionException(Breakpoint)
  - getCondition
```
public String getCondition()
```
    Returns the expression used to create the current breakpoint condition, null if no condition set.
    
    Since:
    
    0.20
  - dispose
```
public void dispose()
```
    Permanently prevents this breakpoint from affecting execution. When not modifiable, IllegalStateException is thrown.
    
    Since:
    
    0.9
  - isOneShot
```
public boolean isOneShot()
```
    Returns:
    
    whether this breakpoint disables itself after suspending execution, i.e. on first hit
    
    Since:
    
    0.9
  - getIgnoreCount
```
public int getIgnoreCount()
```
    Returns:
    
    the number of times breakpoint will be executed but not hit (i.e. suspend execution).
    
    Since:
    
    0.9
    
    See Also:
    
    Breakpoint.setIgnoreCount(int)
  - setIgnoreCount
```
public void setIgnoreCount(int ignoreCount)
```
    Changes the number of times the breakpoint must be executed before it hits (i.e. suspends execution).
    When a breakpoint condition evaluates to false:
    - execution is not suspended
    - it does not count as a hit
    - the remaining ignoreCount does not change.
    When not modifiable, IllegalStateException is thrown.
    Parameters:
    
    ignoreCount - number of breakpoint activations to ignore before it hits
    
    Since:
    
    0.9
  - getHitCount
```
public int getHitCount()
```
    Returns:
    
    the number of times this breakpoint has suspended execution
    
    Since:
    
    0.9
  - getLocationDescription
```
public String getLocationDescription()
```
    Returns:
    
    a description of this breakpoint's specified location
    
    Since:
    
    0.9
  - getSuspendAnchor
```
public SuspendAnchor getSuspendAnchor()
```
    Returns the suspended position within the guest language source location.
    
    Since:
    
    0.32
  - isModifiable
```
public boolean isModifiable()
```
    Test whether this breakpoint can be modified. When false, methods that change breakpoint state throw IllegalStateException.
    Unmodifiable breakpoints are created from installed breakpoints as read-only copies to be available to clients other than the one who installed the original breakpoint. Debugger.getBreakpoints() returns unmodifiable breakpoints, for instance.
    
    Returns:
    
    whether this breakpoint can be modified.
    
    Since:
    
    0.27
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
    
    Since:
    
    0.9
  - newBuilder
```
public static Breakpoint.Builder newBuilder(URI sourceUri)
```
    Creates a new breakpoint builder based on a URI location.
    
    Parameters:
    
    sourceUri - a URI to specify breakpoint location
    
    Since:
    
    0.17
  - newBuilder
```
public static Breakpoint.Builder newBuilder(Source source)
```
    Creates a new breakpoint builder based on a Source.
    
    Parameters:
    
    source - a Source to specify breakpoint location
    
    Since:
    
    0.17
  - newBuilder
```
public static Breakpoint.Builder newBuilder(SourceSection sourceSection)
```
    Creates a new breakpoint builder based on the textual region of a guest language source element.
    
    Parameters:
    
    sourceSection - a specification for guest language source element
    
    Since:
    
    0.17
  - newExceptionBuilder
```
public static Breakpoint.ExceptionBuilder newExceptionBuilder(boolean caught,
                                                              boolean uncaught)
```
    Creates a new exception breakpoint builder. The exception breakpoint can be set to intercept caught or uncaught exceptions, or both. At least one argument needs to be true. The builder creates breakpoint of EXCEPTION kind.
    
    Parameters:
    
    caught - true to intercept exceptions that are caught by guest language code.
    
    uncaught - true to intercept exceptions that are not caught by guest language code.
    
    Since:
    
    19.0

Class Breakpoint

Breakpoint lifetime

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getKind

isDisposed

isEnabled

setEnabled

isResolved

setCondition

getCondition

dispose

isOneShot

getIgnoreCount

setIgnoreCount

getHitCount

getLocationDescription

getSuspendAnchor

isModifiable

toString

newBuilder

newBuilder

newBuilder

newExceptionBuilder