public class JShell extends Object implements AutoCloseable
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.
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.
|
Modifier and Type | Method and Description |
---|---|
void |
addToClasspath(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 . |
void |
close()
Close this state engine.
|
static JShell |
create()
Create a new JShell state engine.
|
Stream<Diag> |
diagnostics(Snippet snippet)
Return the diagnostics of the most recent evaluation of the snippet.
|
List<SnippetEvent> |
drop(PersistentSnippet snippet)
Remove a declaration from the state.
|
List<SnippetEvent> |
eval(String input)
Evaluate the input String, including definition and/or execution, if
applicable.
|
Stream<ImportSnippet> |
imports()
Returns the active import snippets.
|
Stream<MethodSnippet> |
methods()
Returns the active method snippets.
|
JShell.Subscription |
onShutdown(Consumer<JShell> listener)
Register a callback to be called when this JShell instance terminates.
|
JShell.Subscription |
onSnippetEvent(Consumer<SnippetEvent> listener)
Register a callback to be called when the Status of a snippet changes.
|
Stream<Snippet> |
snippets()
Return all snippets.
|
SourceCodeAnalysis |
sourceCodeAnalysis()
Access to source code analysis functionality.
|
Snippet.Status |
status(Snippet snippet)
Return the status of the snippet.
|
void |
stop()
Attempt to stop currently running evaluation.
|
Stream<TypeDeclSnippet> |
types()
Returns the active type declaration (class, interface, annotation type, and enum) snippets.
|
Stream<String> |
unresolvedDependencies(DeclarationSnippet snippet)
For
RECOVERABLE_DEFINED or
RECOVERABLE_NOT_DEFINED
declarations, the names of current unresolved dependencies for
the snippet. |
void |
unsubscribe(JShell.Subscription token)
Cancel a callback subscription.
|
Stream<VarSnippet> |
variables()
Returns the active variable snippets.
|
String |
varValue(VarSnippet snippet)
Get the current value of a variable.
|
public static JShell create()
JShell
.
Equivalent to JShell.builder()
.build()
.
JShell
.public static JShell.Builder builder()
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
.Builder
.JShell.Builder
public SourceCodeAnalysis sourceCodeAnalysis()
JShell
will always return the same
SourceCodeAnalysis
instance from
sourceCodeAnalysis()
.SourceCodeAnalysis
which can be used for source analysis such as completion detection and
completion suggestions.public List<SnippetEvent> eval(String input) throws IllegalStateException
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.
input
- The input String to evaluateIllegalStateException
- if this JShell
instance is closed.SourceCodeAnalysis.analyzeCompletion(String)
,
onShutdown(java.util.function.Consumer)
public List<SnippetEvent> drop(PersistentSnippet snippet) throws IllegalStateException
snippet
- The snippet to removeIllegalStateException
- if this JShell
instance is closed.IllegalArgumentException
- if the snippet is not associated with
this JShell
instance.public void addToClasspath(String path)
eval(String)
code is placed.path
- the path to add to the classpath.public void stop()
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.
public void close()
close
in interface AutoCloseable
public Stream<Snippet> snippets() throws IllegalStateException
IllegalStateException
- if this JShell instance is closed.public Stream<VarSnippet> variables() throws IllegalStateException
snippets()
filtered for
status(snippet).isActive()
&& snippet.kind() == Kind.VARIABLE
and cast to VarSnippet
.IllegalStateException
- if this JShell instance is closed.public Stream<MethodSnippet> methods() throws IllegalStateException
snippets()
filtered for
status(snippet).isActive()
&& snippet.kind() == Kind.METHOD
and cast to MethodSnippet.IllegalStateException
- if this JShell instance is closed.public Stream<TypeDeclSnippet> types() throws IllegalStateException
snippets()
filtered for
status(snippet).isActive()
&& snippet.kind() == Kind.TYPE_DECL
and cast to TypeDeclSnippet.IllegalStateException
- if this JShell instance is closed.public Stream<ImportSnippet> imports() throws IllegalStateException
snippets()
filtered for
status(snippet).isActive()
&& snippet.kind() == Kind.IMPORT
and cast to ImportSnippet.IllegalStateException
- if this JShell instance is closed.public Snippet.Status status(Snippet snippet)
eval()
call or
an automatic update triggered by a dependency.snippet
- the Snippet
to look upIllegalStateException
- if this JShell
instance is closed.IllegalArgumentException
- if the snippet is not associated with
this JShell
instance.public Stream<Diag> diagnostics(Snippet snippet)
eval()
call or
an automatic update triggered by a dependency.snippet
- the Snippet
to look upunresolvedDependencies()
.IllegalStateException
- if this JShell
instance is closed.IllegalArgumentException
- if the snippet is not associated with
this JShell
instance.public Stream<String> unresolvedDependencies(DeclarationSnippet snippet)
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.snippet
- the declaration Snippet
to look upIllegalStateException
- if this JShell
instance is closed.IllegalArgumentException
- if the snippet is not associated with
this JShell
instance.public String varValue(VarSnippet snippet) throws IllegalStateException
snippet
- the variable Snippet whose value is queried.IllegalStateException
- if this JShell
instance is closed.IllegalArgumentException
- if the snippet is not associated with
this JShell
instance.IllegalArgumentException
- if the variable's status is anything but
Snippet.Status.VALID
.public JShell.Subscription onSnippetEvent(Consumer<SnippetEvent> listener) throws IllegalStateException
listener
- Action to perform when the Status changes.IllegalStateException
- if this JShell
instance is closed.public JShell.Subscription onShutdown(Consumer<JShell> listener) throws IllegalStateException
listener
- Action to perform when the state terminates.IllegalStateException
- if this JShell instance is closedpublic void unsubscribe(JShell.Subscription token)
token
- The token corresponding to the subscription to be unsubscribed.
Copyright © 2015, 2016, Oracle and/or its affiliates. All rights reserved.
DRAFT 9-internal+0-2016-08-10-220919.robert.dev