- All Implemented Interfaces:
AutoCloseable
JShell
instance holds the evolving compilation and
execution state. The state is changed with the instance methods
eval(String)
,
drop(Snippet)
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.
- Since:
- 9
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic class
Builder forJShell
instances.class
Subscription is a token for referring to subscriptions so they can be unsubscribed. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addToClasspath
(String path) The specified path is added to the end of the classpath used in eval().static JShell.Builder
builder()
Factory method forJShell.Builder
which, in-turn, is used for creating instances ofJShell
.void
close()
Close this state engine.static JShell
create()
Create a new JShell state engine.diagnostics
(Snippet snippet) Return the diagnostics of the most recent evaluation of the snippet.Remove a declaration from the state.Evaluate the input String, including definition and/or execution, if applicable.imports()
Returns the active import snippets.methods()
Returns the active method snippets.onShutdown
(Consumer<JShell> listener) Register a callback to be called when this JShell instance terminates.onSnippetEvent
(Consumer<SnippetEvent> listener) Register a callback to be called when the Status of a snippet changes.snippets()
Return all snippets.Access to source code analysis functionality.Return the status of the snippet.void
stop()
Attempt to stop currently running evaluation.types()
Returns the active type declaration (class, interface, annotation type, and enum) snippets.unresolvedDependencies
(DeclarationSnippet snippet) ForRECOVERABLE_DEFINED
orRECOVERABLE_NOT_DEFINED
declarations, the names of current unresolved dependencies for the snippet.void
unsubscribe
(JShell.Subscription token) Cancel a callback subscription.Returns the active variable snippets.varValue
(VarSnippet snippet) Get the current value of a variable.
-
Method Details
-
create
Create a new JShell state engine. That is, create an instance ofJShell
.Equivalent to
JShell.builder()
.build()
.- Returns:
- an instance of
JShell
. - Throws:
IllegalStateException
- if theJShell
instance could not be created.
-
builder
Factory method forJShell.Builder
which, in-turn, is used for creating instances ofJShell
. Create a default instance ofJShell
withJShell.builder().build()
. For more construction options seeJShell.Builder
.- Returns:
- an instance of
Builder
. - See Also:
-
sourceCodeAnalysis
Access to source code analysis functionality. An instance ofJShell
will always return the sameSourceCodeAnalysis
instance fromsourceCodeAnalysis()
.- Returns:
- an instance of
SourceCodeAnalysis
which can be used for source analysis such as completion detection and completion suggestions.
-
eval
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.
If execution environment is out of process, as is the default case, then 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:
IllegalStateException
- if thisJShell
instance is closed.- See Also:
-
drop
Remove a declaration from the state. That is, if the snippet is an active persistent snippet, remove the snippet and update the JShell evaluation state accordingly. For all active snippets, change the status toDROPPED
.- Parameters:
snippet
- The snippet to remove- Returns:
- The list of events from updating declarations dependent on the dropped snippet.
- Throws:
IllegalStateException
- if thisJShell
instance is closed.IllegalArgumentException
- if the snippet is not associated with thisJShell
instance.
-
addToClasspath
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 whicheval(String)
code is placed.- Parameters:
path
- the path to add to the classpath.- Throws:
IllegalStateException
- if thisJShell
instance is closed.
-
stop
public void stop()Attempt to stop currently running evaluation. When called while theeval(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 theeval
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. -
close
public void close()Close this state engine. Frees resources. Should be called when this state engine is no longer needed.- Specified by:
close
in interfaceAutoCloseable
-
snippets
Return all snippets.- Returns:
- the snippets for all current snippets in id order.
-
variables
Returns the active variable snippets. This convenience method is equivalent tosnippets()
filtered forstatus(snippet).isActive()
&& snippet.kind() == Kind.VARIABLE
and cast toVarSnippet
.- Returns:
- the active declared variables.
-
methods
Returns the active method snippets. This convenience method is equivalent tosnippets()
filtered forstatus(snippet).isActive()
&& snippet.kind() == Kind.METHOD
and cast to MethodSnippet.- Returns:
- the active declared methods.
-
types
Returns the active type declaration (class, interface, annotation type, and enum) snippets. This convenience method is equivalent tosnippets()
filtered forstatus(snippet).isActive()
&& snippet.kind() == Kind.TYPE_DECL
and cast to TypeDeclSnippet.- Returns:
- the active declared type declarations.
-
imports
Returns the active import snippets. This convenience method is equivalent tosnippets()
filtered forstatus(snippet).isActive()
&& snippet.kind() == Kind.IMPORT
and cast to ImportSnippet.- Returns:
- the active declared import declarations.
-
status
Return the status of the snippet. This is updated either because of an expliciteval()
call or an automatic update triggered by a dependency.- Parameters:
snippet
- theSnippet
to look up- Returns:
- the status corresponding to this snippet
- Throws:
IllegalStateException
- if thisJShell
instance is closed.IllegalArgumentException
- if the snippet is not associated with thisJShell
instance.
-
diagnostics
Return the diagnostics of the most recent evaluation of the snippet. The evaluation can either because of an expliciteval()
call or an automatic update triggered by a dependency.- Parameters:
snippet
- theSnippet
to look up- Returns:
- the diagnostics corresponding to this snippet. This does not
include unresolvedDependencies references reported in
unresolvedDependencies()
. - Throws:
IllegalStateException
- if thisJShell
instance is closed.IllegalArgumentException
- if the snippet is not associated with thisJShell
instance.
-
unresolvedDependencies
ForRECOVERABLE_DEFINED
orRECOVERABLE_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 aneval()
ordrop()
of another snippet causes an update of a dependency.- Parameters:
snippet
- the declarationSnippet
to look up- Returns:
- a stream of symbol names that are currently unresolvedDependencies.
- Throws:
IllegalStateException
- if thisJShell
instance is closed.IllegalArgumentException
- if the snippet is not associated with thisJShell
instance.
-
varValue
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:
IllegalStateException
- if thisJShell
instance is closed.IllegalArgumentException
- if the snippet is not associated with thisJShell
instance.IllegalArgumentException
- if the variable's status is anything butSnippet.Status.VALID
.
-
onSnippetEvent
public JShell.Subscription onSnippetEvent(Consumer<SnippetEvent> listener) throws 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:
IllegalStateException
- if thisJShell
instance is closed.
-
onShutdown
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:
IllegalStateException
- if this JShell instance is closed
-
unsubscribe
Cancel a callback subscription.- Parameters:
token
- The token corresponding to the subscription to be unsubscribed.
-