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.

  • 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