# Class RemoteExecutionControl

java.lang.Object
jdk.jshell.execution.DirectExecutionControl
jdk.jshell.execution.RemoteExecutionControl

All Implemented Interfaces:
  `AutoCloseable, ExecutionControl`

public class RemoteExecutionControl extends DirectExecutionControl implements ExecutionControl
The remote agent runs in the execution process (separate from the main JShell process). This agent loads code over a socket from the main JShell process, executes the code, and other misc, Specialization of `DirectExecutionControl` which adds stop support controlled by an external process. Designed to work with `JdiDefaultExecutionControl`.

Since:
  9

- ## Nested Class Summary

  ### Nested classes/interfaces declared in interface ExecutionControl

  `ExecutionControl.ClassBytecodes, ExecutionControl.ClassInstallException, ExecutionControl.EngineTerminationException, ExecutionControl.ExecutionControlException, ExecutionControl.InternalException, ExecutionControl.NotImplementedException, ExecutionControl.ResolutionException, ExecutionControl.RunException, ExecutionControl.StoppedException, ExecutionControl.UserException`
  Modifier and Type
  Interface
  Description
  `static final class`
  `ExecutionControl.ClassBytecodes`
  Bundles class name with class bytecodes.
  `static class`
  `ExecutionControl.ClassInstallException`
  A class install (load or redefine) encountered a problem.
  `static class`
  `ExecutionControl.EngineTerminationException`
  Unbidden execution engine termination has occurred.
  `static class`
  `ExecutionControl.ExecutionControlException`
  The abstract base of all `ExecutionControl` exceptions.
  `static class`
  `ExecutionControl.InternalException`
  An internal problem has occurred.
  `static class`
  `ExecutionControl.NotImplementedException`
  The command is not implemented.
  `static class`
  `ExecutionControl.ResolutionException`
  An exception indicating that a `DeclarationSnippet` with unresolved references has been encountered.
  `static class`
  `ExecutionControl.RunException`
  The abstract base of of exceptions specific to running user code.
  `static class`
  `ExecutionControl.StoppedException`
  An exception indicating that an `ExecutionControl.invoke(java.lang.String, java.lang.String)` (or theoretically a `ExecutionControl.varValue(java.lang.String, java.lang.String)`) has been interrupted by a `ExecutionControl.stop()`.
  `static class`
  `ExecutionControl.UserException`
  A 'normal' user exception occurred.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `RemoteExecutionControl()`
  Create an instance using the default class loading.
  `RemoteExecutionControl(LoaderDelegate loaderDelegate)`
  Creates an instance, delegating loader operations to the specified delegate.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `clientCodeEnter()`
  Marks entry into user code.
  `static void`
  `main(String[] args)`
  Launch the agent, connecting to the JShell-core over the socket specified in the command-line argument.
  `void`
  `redefine(ExecutionControl.ClassBytecodes[] cbcs)`
  Redefine processing on the remote end is only to register the redefined classes
  `String`
  `varValue(String className, String varName)`
  Returns the value of a variable.

  ### Methods declared in class DirectExecutionControl

  `addToClasspath, classesRedefined, clientCodeLeave, close, extensionCommand, findClass, invoke, invoke, load, stop, throwConvertedInvocationException, throwConvertedOtherException, valueString`
  Modifier and Type
  Method
  Description
  `void`
  `addToClasspath(String cp)`
  Adds the path to the execution class path.
  `protected void`
  `classesRedefined(ExecutionControl.ClassBytecodes[] cbcs)`
  Notify that classes have been redefined.
  `protected void`
  `clientCodeLeave()`
  Marks departure from user code.
  `void`
  `close()`
  Shuts down this execution engine.
  `Object`
  `extensionCommand(String command, Object arg)`
  Run a non-standard command (or a standard command from a newer version).
  `protected Class<?>`
  `findClass(String name)`
  Finds the class with the specified binary name.
  `protected String`
  `invoke(Method doitMethod)`
  Invoke the specified "doit-method", a static method with no parameters.
  `String`
  `invoke(String className, String methodName)`
  Invokes an executable Snippet by calling a method on the specified wrapper class.
  `void`
  `load(ExecutionControl.ClassBytecodes[] cbcs)`
  Attempts to load new classes.
  `void`
  `stop()`
  Interrupts a running invoke.
  `protected String`
  `throwConvertedInvocationException(Throwable cause)`
  Converts incoming exceptions in user code into instances of subtypes of `ExecutionControl.ExecutionControlException` and throws the converted exception.
  `protected String`
  `throwConvertedOtherException(Throwable ex)`
  Converts incoming exceptions in agent code into instances of subtypes of `ExecutionControl.ExecutionControlException` and throws the converted exception.
  `protected static String`
  `valueString(Object value)`
  Converts the `Object` value from `ExecutionControl.invoke(String, String)` or `ExecutionControl.varValue(String, String)` to `String`.

  ### Methods declared in class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`
  Modifier and Type
  Method
  Description
  `protected Object`
  `clone()`
  Creates and returns a copy of this object.
  `boolean`
  `equals(Object obj)`
  Indicates whether some other object is "equal to" this one.
  `protected void`
  `finalize()`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Finalization is deprecated and subject to removal in a future release.
  `final Class<?>`
  `getClass()`
  Returns the runtime class of this `Object`.
  `int`
  `hashCode()`
  Returns a hash code value for this object.
  `final void`
  `notify()`
  Wakes up a single thread that is waiting on this object's monitor.
  `final void`
  `notifyAll()`
  Wakes up all threads that are waiting on this object's monitor.
  `String`
  `toString()`
  Returns a string representation of the object.
  `final void`
  `wait()`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
  `final void`
  `wait(long timeoutMillis)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
  `final void`
  `wait(long timeoutMillis, int nanos)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

- ## Constructor Details

  - ### RemoteExecutionControl

    public RemoteExecutionControl(LoaderDelegate loaderDelegate)
    Creates an instance, delegating loader operations to the specified delegate.
    Parameters:
      `loaderDelegate` - the delegate to handle loading classes

  - ### RemoteExecutionControl

    public RemoteExecutionControl()
    Create an instance using the default class loading.

- ## Method Details

  - ### main

    public static void main(String[] args) throws Exception
    Launch the agent, connecting to the JShell-core over the socket specified in the command-line argument.
    Parameters:
      `args` - standard command-line arguments, expectation is the socket number is the only argument
    Throws:
      `Exception` - any unexpected exception

  - ### redefine

    public void redefine(ExecutionControl.ClassBytecodes[] cbcs) throws ExecutionControl.ClassInstallException, ExecutionControl.NotImplementedException, ExecutionControl.EngineTerminationException
    Redefine processing on the remote end is only to register the redefined classes
    Specified by:
      `redefine` in interface `ExecutionControl`
    Parameters:
      `cbcs` - the class name and bytecodes to redefine
    Throws:
      `ExecutionControl.ClassInstallException` - exception occurred redefining the classes, some or all were not redefined
      `ExecutionControl.NotImplementedException` - if not implemented
      `ExecutionControl.EngineTerminationException` - the execution engine has terminated

  - ### varValue

    public String varValue(String className, String varName) throws ExecutionControl.RunException, ExecutionControl.EngineTerminationException, ExecutionControl.InternalException
    Description copied from interface: `ExecutionControl`
    Returns the value of a variable.
    Specified by:
      `varValue` in interface `ExecutionControl`
    Overrides:
      `varValue` in class `DirectExecutionControl`
    Parameters:
      `className` - the name of the wrapper class of the variable
      `varName` - the name of the variable
    Returns:
      the value of the variable
    Throws:
      `ExecutionControl.UserException` - formatting the value raised a user exception
      `ExecutionControl.ResolutionException` - formatting the value attempted to directly or indirectly invoke an unresolved snippet
      `ExecutionControl.StoppedException` - if the formatting the value was canceled by `ExecutionControl.stop()`
      `ExecutionControl.EngineTerminationException` - the execution engine has terminated
      `ExecutionControl.InternalException` - an internal problem occurred
      `ExecutionControl.RunException`

  - ### clientCodeEnter

    protected void clientCodeEnter()
    Description copied from class: `DirectExecutionControl`
    Marks entry into user code.
    Overrides:
      `clientCodeEnter` in class `DirectExecutionControl`