Package ghidra.debug.api.tracermi

# Interface RemoteMethod

public interface RemoteMethod
A remote method registered by the back-end debugger.

Remote methods must describe the parameters names and types at a minimum. They should also provide a display name and description for the method itself and each of its parameters. These methods should not return a result. Instead, any "result" should be recorded into a trace. The invocation can result in an error, which is communicated by an exception that can carry only a message string. Choice few methods should return a result, for example, the `execute` method with output capture. That output generally does not belong in a trace, so the only way to communicate it back to the front end is to return it.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `ActionName`
  `action()`
  A string that hints at the UI action this method achieves.
  `static void`
  `checkType(String paramName, TraceObjectSchema.SchemaName schName, TraceObjectSchema sch, Object arg)`
  Check the type of an argument.
  `String`
  `description()`
  A description of the method.
  `String`
  `display()`
  A title to display in the UI for this action.
  `Icon`
  `icon()`
  The icon to display in menu's and in the prompt dialog.
  `default Object`
  `invoke(Map<String,Object> arguments)`
  Invoke the remote method and wait for its completion.
  `RemoteAsyncResult`
  `invokeAsync(Map<String,Object> arguments)`
  Invoke the remote method, getting a future result.
  `String`
  `name()`
  The name of the method.
  `String`
  `okText()`
  Text to display in the OK button of any prompt dialog.
  `Map<String,RemoteParameter>`
  `parameters()`
  The methods parameters.
  `TraceObjectSchema.SchemaName`
  `retType()`
  Get the schema for the return type.
  `default Trace`
  `validate(Map<String,Object> arguments)`
  Validate the given argument.

- ## Method Details

  - ### name

    String name()
    The name of the method.
    Returns:
      the name

  - ### action

    ActionName action()
    A string that hints at the UI action this method achieves.
    Returns:
      the action

  - ### display

    String display()
    A title to display in the UI for this action.
    Returns:
      the title

  - ### icon

    Icon icon()
    The icon to display in menu's and in the prompt dialog.
    Returns:
      the icon

  - ### okText

    String okText()
    Text to display in the OK button of any prompt dialog.
    Returns:
      the text

  - ### description

    String description()
    A description of the method.

    This is the text for tooltips or other information presented by actions whose purpose is to invoke this method. If the back-end command name is well known to its users, this text should include that name.

    Returns:
      the description

  - ### parameters

    Map<String,RemoteParameter> parameters()
    The methods parameters.

    Parameters are all keyword-style parameters. This returns a map of names to parameter descriptions.

    Returns:
      the parameter map

  - ### retType

    TraceObjectSchema.SchemaName retType()
    Get the schema for the return type. NOTE: Most methods should return void, i.e., either they succeed, or they throw/raise an error message. One notable exception is "execute," which may return the console output from executing a command. In most cases, the method should only cause an update to the trace database. That effect is its result.
    Returns:
      the schema name for the method's return type.

  - ### checkType

    static void checkType(String paramName, TraceObjectSchema.SchemaName schName, TraceObjectSchema sch, Object arg)
    Check the type of an argument.

    This is a hack, because `TraceObjectSchema` expects `TraceObject`, or a primitive. We instead need `TraceObject`. I'd add the method to the schema, except that trace stuff is not in its dependencies.

    Parameters:
      `paramName` - the name of the parameter
      `schName` - the name of the parameter's schema
      `sch` - the type of the parameter
      `arg` - the argument

  - ### validate

    default Trace validate(Map<String,Object> arguments)
    Validate the given argument.

    This method is for checking parameter sanity before they are marshalled to the back-end. This is called automatically during invocation. Clients can use this method to pre-test or validate in the UI, when invocation is not yet desired.

    Parameters:
      `arguments` - the arguments
    Returns:
      the trace if any object arguments were given, or null
    Throws:
      `IllegalArgumentException` - if the arguments are not valid

  - ### invokeAsync

    RemoteAsyncResult invokeAsync(Map<String,Object> arguments)
    Invoke the remote method, getting a future result.

    This invokes the method asynchronously. The returned objects is a `CompletableFuture`, whose getters are overridden to prevent blocking the Swing thread for more than 1 second. Use of this method is not recommended, if it can be avoided; however, you should not create a thread whose sole purpose is to invoke this method. UI actions that need to invoke a remote method should do so using this method, but they must be sure to handle errors using, e.g., using `CompletableFuture.exceptionally(Function)`, lest the actions fail silently.

    Parameters:
      `arguments` - the keyword arguments to the remote method
    Returns:
      the future result
    Throws:
      `IllegalArgumentException` - if the arguments are not valid

  - ### invoke

    default Object invoke(Map<String,Object> arguments)
    Invoke the remote method and wait for its completion.

    This method cannot be invoked from the Swing thread. This is to avoid locking up the user interface. If you are on the Swing thread, consider `invokeAsync(Map)` instead. You can chain the follow-up actions and then schedule any UI updates on the Swing thread using `AsyncUtils.SWING_EXECUTOR`.

    Parameters:
      `arguments` - the keyword arguments to the remote method
    Returns:
      the returned value
    Throws:
      `IllegalArgumentException` - if the arguments are not valid