Package ghidra.debug.api.tracermi

# Interface TraceRmiLaunchOffer

public interface TraceRmiLaunchOffer
An offer to launch a program with a given mechanism

Typically each offer is configured with the program it's going to launch, and knows how to work a specific connector and platform to obtain a target executing the program's image. The mechanisms may vary wildly from platform to platform.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static interface`
  `TraceRmiLaunchOffer.LaunchConfigurator`
  Callbacks for custom configuration when launching a program
  `static final record`
  `TraceRmiLaunchOffer.LaunchResult`
  The result of launching a program
  `static enum`
  `TraceRmiLaunchOffer.PromptMode`
  `static enum`
  `TraceRmiLaunchOffer.RelPrompt`
  When programmatically customizing launch configuration, describes callback timing relative to prompting the user.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `String`
  `getConfigName()`
  A name so that this offer can be recognized later
  `String`
  `getDescription()`
  Get an HTML description of the connector
  `default HelpLocation`
  `getHelpLocation()`
  Get the location for additional help about this specific offer
  `Icon`
  `getIcon()`
  Get the icon displayed in the UI for this offer
  `default String`
  `getMenuGroup()`
  Get the menu group for the offer
  `default String`
  `getMenuOrder()`
  Controls the position in the menu (within its group) of the entry
  `default List<String>`
  `getMenuPath()`
  Get the menu path subordinate to "Debugger.Debug [imagePath]" for this offer.
  `Map<String,LaunchParameter<?>>`
  `getParameters()`
  Get the parameter descriptions for the launcher
  `String`
  `getTitle()`
  Get the text displayed in the quick-launch drop-down menu.
  `LaunchParameter<?>`
  `imageParameter()`
  If present, get the parameter via which this offer expects to receive the current program
  `default TraceRmiLaunchOffer.LaunchResult`
  `launchProgram(TaskMonitor monitor)`
  Launch the program using the offered mechanism
  `TraceRmiLaunchOffer.LaunchResult`
  `launchProgram(TaskMonitor monitor, TraceRmiLaunchOffer.LaunchConfigurator configurator)`
  Launch the program using the offered mechanism
  `default boolean`
  `requiresImage()`
  Check if this offer requires an open program
  `default boolean`
  `supportsImage()`
  Check if this offer presents a parameter for the open program

- ## Method Details

  - ### launchProgram

    TraceRmiLaunchOffer.LaunchResult launchProgram(TaskMonitor monitor, TraceRmiLaunchOffer.LaunchConfigurator configurator)
    Launch the program using the offered mechanism
    Parameters:
      `monitor` - a monitor for progress and cancellation
      `configurator` - the configuration callback
    Returns:
      the launch result

  - ### launchProgram

    default TraceRmiLaunchOffer.LaunchResult launchProgram(TaskMonitor monitor)
    Launch the program using the offered mechanism
    Parameters:
      `monitor` - a monitor for progress and cancellation
    Returns:
      the launch result

  - ### getConfigName

    String getConfigName()
    A name so that this offer can be recognized later

    The name is saved to configuration files, so that user preferences and priorities can be memorized. The opinion will generate each offer fresh each time, so it's important that the "same offer" have the same configuration name. Note that the name cannot depend on the program name, but can depend on the model factory and program language and/or compiler spec. This name cannot contain semicolons (`;`).

    Returns:
      the configuration name

  - ### getIcon

    Icon getIcon()
    Get the icon displayed in the UI for this offer

    Please take care when overriding this that the icon still clearly indicates the target will be executed. Changing it, e.g., to the same icon as "Step" would be an unwelcome prank. A more reasonable choice would be the standard `"icon.debugger"` plus an overlay, or the branding of the underlying technology, e.g., QEMU or GDB.

    Returns:
      the icon

  - ### getMenuPath

    default List<String> getMenuPath()
    Get the menu path subordinate to "Debugger.Debug [imagePath]" for this offer.

    By default, this is just the title, i.e., the same as in the quick-launch drop-down menu. A package that introduces a large number of offers should override this method to organize them. A general rule of thumb is "no more than seven." Except at the level immediately under "Debug [imagePath]," no more than seven items should be presented to the user. In some cases, it may be more appropriate to group things using `menu groups` rather than sub menus.

    Organization is very much a matter of taste, but consider that you are cooperating with other packages to populate the launcher menu. The top level is especially contentious, but sub menus, if named appropriately, are presumed to belong to a single package.

    Returns:
      the path

  - ### getTitle

    String getTitle()
    Get the text displayed in the quick-launch drop-down menu.

    No two offers should ever have the same title, even if they appear in different sub-menus. Otherwise, the user cannot distinguish the offers in the quick-launch drop-down menu.

    Returns:
      the menu title

  - ### getDescription

    String getDescription()
    Get an HTML description of the connector
    Returns:
      the description

  - ### getMenuGroup

    default String getMenuGroup()
    Get the menu group for the offer

    Especially for entries immediately under to "Debugger.Debug [imagePath]", specifies the menu group. A package that introduces a large number of offers should instead consider `sub menus`.

    Returns:
      the menu group

  - ### getMenuOrder

    default String getMenuOrder()
    Controls the position in the menu (within its group) of the entry

    The menus will always be presented in the same order, barring any changes to the plugins or launcher properties. Groups are alphabetized and visually separated. Then sub groups are alphabetized, but not visually separated. Finally, offers are alphabetized by their final path element, usually the title.

    The order of entries in the quick-launch drop-down menu is always most-recently to least-recently used. An entry that has never been used does not appear in the quick launch menu.

    Returns:
      the sub-group name for ordering in the menu

  - ### getHelpLocation

    default HelpLocation getHelpLocation()
    Get the location for additional help about this specific offer

    The default is just the entry on Trace RMI launchers in general.

    Returns:
      the location

  - ### getParameters

    Map<String,LaunchParameter<?>> getParameters()
    Get the parameter descriptions for the launcher
    Returns:
      the parameters

  - ### imageParameter

    LaunchParameter<?> imageParameter()
    If present, get the parameter via which this offer expects to receive the current program
    Returns:
      the parameter, or null

  - ### supportsImage

    default boolean supportsImage()
    Check if this offer presents a parameter for the open program
    Returns:
      true if present

  - ### requiresImage

    default boolean requiresImage()
    Check if this offer requires an open program
    Returns:
      true if required