JShell (JShell API)

java.lang.Object
- jdk.jshell.JShell

All Implemented Interfaces:

java.lang.AutoCloseable
```
public abstract class JShell
extends java.lang.Object
implements java.lang.AutoCloseable
```
The JShell evaluation state engine. This is the central class in the JShell API. A JShell instance holds the evolving compilation and execution state. The state is changed with the instance methods eval(String), drop(PersistentSnippet) and addToClasspath(String). The majority of methods query the state. A JShell instance also allows registering for events with onSnippetEvent(Consumer) and onShutdown(Consumer), which are unregistered with unsubscribe(Subscription). Access to the source analysis utilities is via sourceCodeAnalysis(). When complete the instance should be closed to free resources -- close().
An instance of JShell is created with JShell.create().
This class is not thread safe, except as noted, all access should be through a single thread.

See Also:

jdk.jshell

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`JShell.Builder` Builder for `JShell` instances.
`class`	`JShell.Subscription` Subscription is a token for referring to subscriptions so they can be unsubscribed.

Constructor Summary

Constructors
Constructor and Description

JShell()

Constructors
Constructor and Description
`JShell()`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`abstract void`	`addToClasspath(java.lang.String path)` The specified path is added to the end of the classpath used in eval().
`static JShell.Builder`	`builder()` Factory method for `JShell.Builder` which, in-turn, is used for creating instances of `JShell`.
`abstract void`	`close()` Close this state engine.
`static JShell`	`create()` Create a new JShell state engine.
`abstract java.util.List<javax.tools.Diagnostic<java.lang.String>>`	`diagnostics(Snippet snippet)` Return the diagnostics of the most recent evaluation of the snippet.
`abstract java.util.List<SnippetEvent>`	`drop(PersistentSnippet snippet)` Remove a declaration from the state.
`abstract java.util.List<SnippetEvent>`	`eval(java.lang.String input)` Evaluate the input String, including definition and/or execution, if applicable.
`abstract java.util.List<MethodSnippet>`	`methods()` Returns the active method snippets.
`abstract JShell.Subscription`	`onShutdown(java.util.function.Consumer<JShell> listener)` Register a callback to be called when this JShell instance terminates.
`abstract JShell.Subscription`	`onSnippetEvent(java.util.function.Consumer<SnippetEvent> listener)` Register a callback to be called when the Status of a snippet changes.
`abstract java.util.List<Snippet>`	`snippets()` Return all snippets.
`abstract SourceCodeAnalysis`	`sourceCodeAnalysis()` Access to source code analysis functionality.
`abstract Snippet.Status`	`status(Snippet snippet)` Return the status of the snippet.
`abstract void`	`stop()` Attempt to stop currently running evaluation.
`abstract java.util.List<TypeDeclSnippet>`	`types()` Returns the active type declaration (class, interface, annotation type, and enum) snippets.
`abstract java.util.List<java.lang.String>`	`unresolvedDependencies(DeclarationSnippet snippet)` For `RECOVERABLE_DEFINED` or `RECOVERABLE_NOT_DEFINED` declarations, the names of current unresolved dependencies for the snippet.
`abstract void`	`unsubscribe(JShell.Subscription token)` Unsubscribe from a callback subscription.
`abstract java.util.List<VarSnippet>`	`variables()` Returns the active variable snippets.
`abstract java.lang.String`	`varValue(VarSnippet snippet)` Get the current value of a variable.

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

- Constructor Detail
  - JShell
```
public JShell()
```
- Method Detail
  - create
```
public static JShell create()
```
    Create a new JShell state engine. That is, create an instance of JShell.
    Equivalent to JShell.builder().build().
    
    Returns:
    
    an instance of JShell.
  - builder
```
public static JShell.Builder builder()
```
    Factory method for JShell.Builder which, in-turn, is used for creating instances of JShell. Create a default instance of JShell with JShell.builder().build(). For more construction options see JShell.Builder.
    
    Returns:
    
    an instance of Builder.
    
    See Also:
    
    JShell.Builder
  - sourceCodeAnalysis
```
public abstract SourceCodeAnalysis sourceCodeAnalysis()
```
    Access to source code analysis functionality. An instance of JShell will always return the same SourceCodeAnalysis instance from sourceCodeAnalysis().
    
    Returns:
    
    an instance of SourceCodeAnalysis which can be used for source analysis such as completion detection and completion suggestions.
  - eval
```
public abstract java.util.List<SnippetEvent> eval(java.lang.String input)
                                           throws java.lang.IllegalStateException
```
    Evaluate the input String, including definition and/or execution, if applicable. The input is checked for errors, unless the errors can be deferred (as is the case with some unresolvedDependencies references), errors will abort evaluation. The input should be exactly one complete snippet of source code, that is, one expression, statement, variable declaration, method declaration, class declaration, or import. To break arbitrary input into individual complete snippets, use SourceCodeAnalysis.analyzeCompletion(String).
    For imports, the import is added. Classes, interfaces. methods, and variables are defined. The initializer of variables, statements, and expressions are executed. The modifiers public, protected, private, static, and final are not allowed on op-level declarations and are ignored with a warning. Synchronized, native, abstract, and default top-level methods are not allowed and are errors. If a previous definition of a declaration is overwritten then there will be an event showing its status changed to OVERWRITTEN, this will not occur for dropped, rejected, or already overwritten declarations.
    The execution environment is out of process. If the evaluated code causes the execution environment to terminate, this JShell instance will be closed but the calling process and VM remain valid.
    
    Parameters:
    
    input - The input String to evaluate
    
    Returns:
    
    the list of events directly or indirectly caused by this evaluation.
    
    Throws:
    
    java.lang.IllegalStateException - if this JShell instance is closed.
    
    See Also:
    
    SourceCodeAnalysis.analyzeCompletion(String), onShutdown(java.util.function.Consumer)
  - stop
```
public abstract void stop()
```
    Attempt to stop currently running evaluation. When called while the eval(java.lang.String) method is running and the user's code being executed, an attempt will be made to stop user's code. Note that typically this method needs to be called from a different thread than the one running the eval method.
    If the eval(java.lang.String) method is not running, does nothing.
    The attempt to stop the user's code may fail in some case, which may include when the execution is blocked on an I/O operation, or when the user's code is catching the ThreadDeath exception.
  - drop
```
public abstract java.util.List<SnippetEvent> drop(PersistentSnippet snippet)
                                           throws java.lang.IllegalStateException
```
    Remove a declaration from the state.
    
    Parameters:
    
    snippet - The snippet to remove
    
    Returns:
    
    The list of events from updating declarations dependent on the dropped snippet.
    
    Throws:
    
    java.lang.IllegalStateException - if this JShell instance is closed.
    
    java.lang.IllegalArgumentException - if the snippet is not associated with this JShell instance.
  - varValue
```
public abstract java.lang.String varValue(VarSnippet snippet)
                                   throws java.lang.IllegalStateException
```
    Get the current value of a variable.
    
    Parameters:
    
    snippet - the variable Snippet whose value is queried.
    
    Returns:
    
    the current value of the variable referenced by snippet.
    
    Throws:
    
    java.lang.IllegalStateException - if this JShell instance is closed.
    
    java.lang.IllegalArgumentException - if the snippet is not associated with this JShell instance.
    
    java.lang.IllegalArgumentException - if the variable's status is anything but Snippet.Status.VALID.
  - addToClasspath
```
public abstract void addToClasspath(java.lang.String path)
```
    The specified path is added to the end of the classpath used in eval(). Note that the unnamed package is not accessible from the package in which eval() code is placed.
    
    Parameters:
    
    path - the path to add to the classpath.
  - close
```
public abstract void close()
```
    Close this state engine. Frees resources. Should be called when this state engine is no longer needed.
    
    Specified by:
    
    close in interface java.lang.AutoCloseable
  - snippets
```
public abstract java.util.List<Snippet> snippets()
                                          throws java.lang.IllegalStateException
```
    Return all snippets.
    
    Returns:
    
    the snippets for all current snippets in id order.
    
    Throws:
    
    java.lang.IllegalStateException - if this JShell instance is closed.
  - variables
```
public abstract java.util.List<VarSnippet> variables()
                                              throws java.lang.IllegalStateException
```
    Returns the active variable snippets. This convenience method is equivalent to snippets() filtered for status(snippet).isActive && snippet.kind() == Kind.VARIABLE and cast to VarSnippet.
    
    Returns:
    
    the active declared variables.
    
    Throws:
    
    java.lang.IllegalStateException - if this JShell instance is closed.
  - methods
```
public abstract java.util.List<MethodSnippet> methods()
                                               throws java.lang.IllegalStateException
```
    Returns the active method snippets. This convenience method is equivalent to snippets() filtered for status(snippet).isActive && snippet.kind() == Kind.METHOD and cast to MethodSnippet.
    
    Returns:
    
    the active declared methods.
    
    Throws:
    
    java.lang.IllegalStateException - if this JShell instance is closed.
  - types
```
public abstract java.util.List<TypeDeclSnippet> types()
                                               throws java.lang.IllegalStateException
```
    Returns the active type declaration (class, interface, annotation type, and enum) snippets. This convenience method is equivalent to snippets() filtered for status(snippet).isActive && snippet.kind() == Kind.TYPE_DECL and cast to TypeDeclSnippet.
    
    Returns:
    
    the active declared type declarations.
    
    Throws:
    
    java.lang.IllegalStateException - if this JShell instance is closed.
  - status
```
public abstract Snippet.Status status(Snippet snippet)
```
    Return the status of the snippet. This is updated either because of an explicit eval() call or an automatic update triggered by a dependency.
    
    Parameters:
    
    snippet - the Snippet to look up
    
    Returns:
    
    the status corresponding to this snippet
    
    Throws:
    
    java.lang.IllegalStateException - if this JShell instance is closed.
    
    java.lang.IllegalArgumentException - if the snippet is not associated with this JShell instance.
  - unresolvedDependencies
```
public abstract java.util.List<java.lang.String> unresolvedDependencies(DeclarationSnippet snippet)
```
    For RECOVERABLE_DEFINED or RECOVERABLE_NOT_DEFINED declarations, the names of current unresolved dependencies for the snippet. The returned value of this method, for a given method may change when an eval() or drop() of another snippet causes an update of a dependency.
    
    Parameters:
    
    snippet - the declaration Snippet to look up
    
    Returns:
    
    the list of symbol names that are currently unresolvedDependencies.
    
    Throws:
    
    java.lang.IllegalStateException - if this JShell instance is closed.
    
    java.lang.IllegalArgumentException - if the snippet is not associated with this JShell instance.
  - diagnostics
```
public abstract java.util.List<javax.tools.Diagnostic<java.lang.String>> diagnostics(Snippet snippet)
```
    Return the diagnostics of the most recent evaluation of the snippet. The evaluation can either because of an explicit eval() call or an automatic update triggered by a dependency.
    
    Parameters:
    
    snippet - the Snippet to look up
    
    Returns:
    
    the diagnostics corresponding to this snippet. This does not include unresolvedDependencies references reported in unresolvedDependencies().
    
    Throws:
    
    java.lang.IllegalStateException - if this JShell instance is closed.
    
    java.lang.IllegalArgumentException - if the snippet is not associated with this JShell instance.
  - onSnippetEvent
```
public abstract JShell.Subscription onSnippetEvent(java.util.function.Consumer<SnippetEvent> listener)
                                            throws java.lang.IllegalStateException
```
    Register a callback to be called when the Status of a snippet changes. Each call adds a new subscription.
    
    Parameters:
    
    listener - Action to perform when the Status changes.
    
    Returns:
    
    A token which can be used to unsubscribe this subscription.
    
    Throws:
    
    java.lang.IllegalStateException - if this JShell instance is closed.
  - onShutdown
```
public abstract JShell.Subscription onShutdown(java.util.function.Consumer<JShell> listener)
                                        throws java.lang.IllegalStateException
```
    Register a callback to be called when this JShell instance terminates. This occurs either because the client process has ended (e.g. called System.exit(0)) or the connection has been shutdown, as by close(). Each call adds a new subscription.
    
    Parameters:
    
    listener - Action to perform when the state terminates.
    
    Returns:
    
    A token which can be used to unsubscribe this subscription.
    
    Throws:
    
    java.lang.IllegalStateException - if this JShell instance is closed
  - unsubscribe
```
public abstract void unsubscribe(JShell.Subscription token)
```
    Unsubscribe from a callback subscription.
    
    Parameters:
    
    token - The token corresponding to the subscription to be unsubscribed.

Class JShell

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

JShell

Method Detail

create

builder

sourceCodeAnalysis

eval

stop

drop

varValue

addToClasspath

close

snippets

variables

methods

types

status

unresolvedDependencies

diagnostics

onSnippetEvent

onShutdown

unsubscribe