JShell (Java SE 15 & JDK 15) (original) (raw)

All Implemented Interfaces:

[AutoCloseable](../../../java.base/java/lang/AutoCloseable.html "interface in java.lang")

public class JShell extends Object implements 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 methodseval(String),drop(Snippet) andaddToClasspath(String). The majority of methods query the state. A JShell instance also allows registering for events withonSnippetEvent(Consumer) and onShutdown(Consumer), which are unregistered withunsubscribe(Subscription). Access to the source analysis utilities is viasourceCodeAnalysis(). When complete the instance should be closed to free resources --close().

An instance of JShell is created withJShell.create().

This class is not thread safe, except as noted, all access should be through a single thread.

Since:

9

• Nested Class Summary

Nested Classes

• Method Summary

Methods declared in class java.lang.Object

[clone](../../../java.base/java/lang/Object.html#clone%28%29), [equals](../../../java.base/java/lang/Object.html#equals%28java.lang.Object%29), [finalize](../../../java.base/java/lang/Object.html#finalize%28%29), [getClass](../../../java.base/java/lang/Object.html#getClass%28%29), [hashCode](../../../java.base/java/lang/Object.html#hashCode%28%29), [notify](../../../java.base/java/lang/Object.html#notify%28%29), [notifyAll](../../../java.base/java/lang/Object.html#notifyAll%28%29), [toString](../../../java.base/java/lang/Object.html#toString%28%29), [wait](../../../java.base/java/lang/Object.html#wait%28%29), [wait](../../../java.base/java/lang/Object.html#wait%28long%29), [wait](../../../java.base/java/lang/Object.html#wait%28long,int%29)

• Method Details

  • create

  Create a new JShell state engine. That is, create an instance of JShell.
  Equivalent to JShell.builder().build().
  Returns:
  an instance of JShell.
  Throws:
  [IllegalStateException](../../../java.base/java/lang/IllegalStateException.html "class in java.lang") - if the JShell instance could not be created.

  • builder

  Factory method for JShell.Builder which, in-turn, is used for creating instances of JShell. Create a default instance of JShell withJShell.builder().build(). For more construction options see JShell.Builder.
  Returns:
  an instance of Builder.
  See Also:
  JShell.Builder

  • sourceCodeAnalysis

  Access to source code analysis functionality. An instance of JShell 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, useSourceCodeAnalysis.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](../../../java.base/java/lang/IllegalStateException.html "class in java.lang") - if this JShell instance is closed.
  See Also:
  SourceCodeAnalysis.analyzeCompletion(String), onShutdown(java.util.function.Consumer)

  • drop

  Remove a declaration from the state. That is, if the snippet is anactive 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](../../../java.base/java/lang/IllegalStateException.html "class in java.lang") - if this JShell instance is closed.
  [IllegalArgumentException](../../../java.base/java/lang/IllegalArgumentException.html "class in java.lang") - if the snippet is not associated with this JShell instance.

  • addToClasspath

  public void addToClasspath​(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 whicheval(String) code is placed.
  Parameters:
  path - the path to add to the classpath.
  Throws:
  [IllegalStateException](../../../java.base/java/lang/IllegalStateException.html "class in java.lang") - if this JShell instance is closed.

  • stop

  public 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.

  • close

  public void close()
  Close this state engine. Frees resources. Should be called when this state engine is no longer needed.
  Specified by:
  [close](../../../java.base/java/lang/AutoCloseable.html#close%28%29) in interface [AutoCloseable](../../../java.base/java/lang/AutoCloseable.html "interface in java.lang")

  • 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 to snippets() filtered forstatus(snippet).isActive() && snippet.kind() == Kind.VARIABLE and cast to VarSnippet.
  Returns:
  the active declared variables.

  • methods

  Returns the active method snippets. This convenience method is equivalent to snippets() 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 to snippets() 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 to snippets() 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 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:
  [IllegalStateException](../../../java.base/java/lang/IllegalStateException.html "class in java.lang") - if this JShell instance is closed.
  [IllegalArgumentException](../../../java.base/java/lang/IllegalArgumentException.html "class in java.lang") - if the snippet is not associated with this JShell instance.

  • diagnostics

  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:
  [IllegalStateException](../../../java.base/java/lang/IllegalStateException.html "class in java.lang") - if this JShell instance is closed.
  [IllegalArgumentException](../../../java.base/java/lang/IllegalArgumentException.html "class in java.lang") - if the snippet is not associated with this JShell instance.

  • unresolvedDependencies

  For RECOVERABLE_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() or drop() of another snippet causes an update of a dependency.
  Parameters:
  snippet - the declaration Snippet to look up
  Returns:
  a stream of symbol names that are currently unresolvedDependencies.
  Throws:
  [IllegalStateException](../../../java.base/java/lang/IllegalStateException.html "class in java.lang") - if this JShell instance is closed.
  [IllegalArgumentException](../../../java.base/java/lang/IllegalArgumentException.html "class in java.lang") - if the snippet is not associated with this JShell 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](../../../java.base/java/lang/IllegalStateException.html "class in java.lang") - if this JShell instance is closed.
  [IllegalArgumentException](../../../java.base/java/lang/IllegalArgumentException.html "class in java.lang") - if the snippet is not associated with this JShell instance.
  [IllegalArgumentException](../../../java.base/java/lang/IllegalArgumentException.html "class in java.lang") - if the variable's status is anything butSnippet.Status.VALID.

  • onSnippetEvent

  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](../../../java.base/java/lang/IllegalStateException.html "class in java.lang") - if this JShell 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](../../../java.base/java/lang/IllegalStateException.html "class in java.lang") - if this JShell instance is closed

  • unsubscribe

  Cancel a callback subscription.
  Parameters:
  token - The token corresponding to the subscription to be unsubscribed.