Package ghidra.app.util.opinion

# Class AbstractProgramLoader

java.lang.Object
ghidra.app.util.opinion.AbstractProgramLoader

All Implemented Interfaces:
  `Loader`, `ExtensionPoint`, `Comparable<Loader>`

Direct Known Subclasses:
  `AbstractLibrarySupportLoader`, `AbstractProgramWrapperLoader`, `BinaryLoader`, `IntelHexLoader`, `MotorolaHexLoader`, `XmlLoader`

public abstract class AbstractProgramLoader extends Object implements Loader
An abstract `Loader` that provides a framework to conveniently load `Program`s. Subclasses are responsible for the actual load.

This `Loader` provides a couple processor-related options, as all `Program`s will have a processor associated with them.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `ANCHOR_LABELS_OPTION_NAME`
  `static final String`
  `APPLY_LABELS_OPTION_NAME`

  ### Fields inherited from interface ghidra.app.util.opinion.Loader

  `COMMAND_LINE_ARG_PREFIX, OPTIONS_PROJECT_SAVE_STATE_KEY`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AbstractProgramLoader()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected String`
  `concatenatePaths(String... pathElements)`
  Concatenates the given path elements to form a single path.
  `protected void`
  `createDefaultMemoryBlocks(Program program, Language language, MessageLog log)`
  Creates default memory blocks for the given `Program`.
  `protected Program`
  `createProgram(ByteProvider provider, String domainFileName, Address imageBase, String executableFormatName, Language language, CompilerSpec compilerSpec, Object consumer)`
  Creates a `Program` with the specified attributes.
  `protected String`
  `generateBlockName(Program program, boolean isOverlay, AddressSpace space)`
  Generates a block name.
  `List<Option>`
  `getDefaultOptions(ByteProvider provider, LoadSpec loadSpec, DomainObject domainObject, boolean isLoadIntoProgram)`
  Gets the default `Loader` options.
  `protected LanguageService`
  `getLanguageService()`
  Gets the `Loader`'s language service.
  `final LoadResults<? extends DomainObject>`
  `load(ByteProvider provider, String loadedName, Project project, String projectFolderPath, LoadSpec loadSpec, List<Option> options, MessageLog messageLog, Object consumer, TaskMonitor monitor)`
  Loads bytes in a particular format as a new `Loaded` `DomainObject`.
  `final void`
  `loadInto(ByteProvider provider, LoadSpec loadSpec, List<Option> options, MessageLog messageLog, Program program, TaskMonitor monitor)`
  Loads bytes into the specified `Program`.
  `protected abstract List<Loaded<Program>>`
  `loadProgram(ByteProvider provider, String loadedName, Project project, String projectFolderPath, LoadSpec loadSpec, List<Option> options, MessageLog log, Object consumer, TaskMonitor monitor)`
  Loads bytes in a particular format as a new `Loaded` `Program`.
  `protected abstract void`
  `loadProgramInto(ByteProvider provider, LoadSpec loadSpec, List<Option> options, MessageLog messageLog, Program program, TaskMonitor monitor)`
  Loads program bytes into the specified `Program`.
  `static void`
  `markAsFunction(Program program, String name, Address funcStart)`
  Mark this address as a function by creating a one byte function.
  `protected void`
  `postLoadCleanup(boolean success)`
  This gets called as the final step of the load process.
  `protected void`
  `postLoadProgramFixups(List<Loaded<Program>> loadedPrograms, Project project, List<Option> options, MessageLog messageLog, TaskMonitor monitor)`
  This gets called after the given list of `loaded programs`s is finished loading.
  `protected final void`
  `release(List<Loaded<Program>> loadedPrograms, Object consumer)`
  Releases the given consumer from each of the provided `loaded programs`
  `static void`
  `setProgramProperties(Program prog, ByteProvider provider, String executableFormatName)`
  Sets a program's Executable Path, Executable Format, MD5, SHA256, and FSRL properties.
  `protected boolean`
  `shouldApplyProcessorLabelsByDefault()`
  Returns whether or not processor labels should be applied by default.
  `String`
  `validateOptions(ByteProvider provider, LoadSpec loadSpec, List<Option> options, Program program)`
  Validates the `Loader`'s options and returns null if all options are valid; otherwise, an error message describing the problem is returned.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface ghidra.app.util.opinion.Loader

  `compareTo, findSupportedLoadSpecs, getName, getPreferredFileName, getTier, getTierPriority, loadsIntoNewFolder, supportsLoadIntoProgram, supportsLoadIntoProgram`

- ## Field Details

  - ### APPLY_LABELS_OPTION_NAME

    public static final String APPLY_LABELS_OPTION_NAME
    See Also:
      - Constant Field Values

  - ### ANCHOR_LABELS_OPTION_NAME

    public static final String ANCHOR_LABELS_OPTION_NAME
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### AbstractProgramLoader

    public AbstractProgramLoader()

- ## Method Details

  - ### loadProgram

    protected abstract List<Loaded<Program>> loadProgram(ByteProvider provider, String loadedName, Project project, String projectFolderPath, LoadSpec loadSpec, List<Option> options, MessageLog log, Object consumer, TaskMonitor monitor) throws IOException, LoadException, CancelledException
    Loads bytes in a particular format as a new `Loaded` `Program`. Multiple `Program`s may end up getting created, depending on the nature of the format.

    Note that when the load completes, the returned `Loaded` `Program`s are not saved to a project. That is the responsibility of the caller (see `Loaded.save(Project, MessageLog, TaskMonitor)`).

    It is also the responsibility of the caller to release the returned `Loaded` `Program`s with `Loaded.release(Object)` when they are no longer needed.

    Parameters:
      `provider` - The bytes to load.
      `loadedName` - A suggested name for the primary `Loaded` `Program`. This is just a suggestion, and a `Loader` implementation reserves the right to change it. The `Loaded` `Program`s should be queried for their true names using `Loaded.getName()`.
      `project` - The `Project`. Loaders can use this to take advantage of existing `DomainFolder`s and `DomainFile`s to do custom behaviors such as loading libraries. Could be null if there is no project.
      `projectFolderPath` - A suggested project folder path for the `Loaded` `Program`s. This is just a suggestion, and a `Loader` implementation reserves the right to change it for each `Loaded` result. The `Loaded` `Program`s should be queried for their true project folder paths using `Loaded.getProjectFolderPath()`.
      `loadSpec` - The `LoadSpec` to use during load.
      `options` - The load options.
      `log` - The message log.
      `consumer` - A consumer object for generated `Program`s.
      `monitor` - A task monitor.
    Returns:
      A `List` of one or more `Loaded` `Program`s (created but not saved).
    Throws:
      `LoadException` - if the load failed in an expected way.
      `IOException` - if there was an IO-related problem loading.
      `CancelledException` - if the user cancelled the load.

  - ### loadProgramInto

    protected abstract void loadProgramInto(ByteProvider provider, LoadSpec loadSpec, List<Option> options, MessageLog messageLog, Program program, TaskMonitor monitor) throws IOException, LoadException, CancelledException
    Loads program bytes into the specified `Program`. This method will not create any new `Program`s. It is only for adding to an existing `Program`.

    NOTE: The loading that occurs in this method will automatically be done in a transaction.

    Parameters:
      `provider` - The bytes to load into the `Program`.
      `loadSpec` - The `LoadSpec` to use during load.
      `options` - The load options.
      `messageLog` - The message log.
      `program` - The `Program` to load into.
      `monitor` - A cancelable task monitor.
    Throws:
      `LoadException` - if the load failed in an expected way.
      `IOException` - if there was an IO-related problem loading.
      `CancelledException` - if the user cancelled the load.

  - ### load

    public final LoadResults<? extends DomainObject> load(ByteProvider provider, String loadedName, Project project, String projectFolderPath, LoadSpec loadSpec, List<Option> options, MessageLog messageLog, Object consumer, TaskMonitor monitor) throws IOException, CancelledException, VersionException, LoadException
    Description copied from interface: `Loader`
    Loads bytes in a particular format as a new `Loaded` `DomainObject`. Multiple `DomainObject`s may end up getting created, depending on the nature of the format. The `Loaded` `DomainObject`s are bundled together in a `LoadResults` object which provides convenience methods to operate on the entire group of `Loaded` `DomainObject`s.

    Note that when the load completes, the returned `Loaded` `DomainObject`s are not saved to a project. That is the responsibility of the caller (see `LoadResults.save(Project, Object, MessageLog, TaskMonitor)`).

    It is also the responsibility of the caller to release the returned `Loaded` `DomainObject`s with `LoadResults.release(Object)` when they are no longer needed.

    Specified by:
      `load` in interface `Loader`
    Parameters:
      `provider` - The bytes to load.
      `loadedName` - A suggested name for the primary `Loaded` `DomainObject`. This is just a suggestion, and a `Loader` implementation reserves the right to change it. The `LoadResults` should be queried for their true names using `Loaded.getName()`.
      `project` - The `Project`. Loaders can use this to take advantage of existing `DomainFolder`s and `DomainFile`s to do custom behaviors such as loading libraries. Could be null if there is no project.
      `projectFolderPath` - A suggested project folder path for the `Loaded` `DomainObject`s. This is just a suggestion, and a `Loader` implementation reserves the right to change it for each `Loaded` result. The `LoadResults` should be queried for their true project folder paths using `Loaded.getProjectFolderPath()`.
      `loadSpec` - The `LoadSpec` to use during load.
      `options` - The load options.
      `messageLog` - The message log.
      `consumer` - A consumer object for generated `DomainObject`s.
      `monitor` - A task monitor.
    Returns:
      The `LoadResults` which contains one or more `Loaded` `DomainObject`s (created but not saved).
    Throws:
      `LoadException` - if the load failed in an expected way
      `IOException` - if there was an IO-related problem loading.
      `CancelledException` - if the user cancelled the load.
      `VersionException` - if the load process tried to open an existing `DomainFile` which was created with a newer or unsupported version of Ghidra

  - ### loadInto

    public final void loadInto(ByteProvider provider, LoadSpec loadSpec, List<Option> options, MessageLog messageLog, Program program, TaskMonitor monitor) throws IOException, LoadException, CancelledException
    Description copied from interface: `Loader`
    Loads bytes into the specified `Program`. This method will not create any new `Program`s. It is only for adding to an existing `Program`.
    Specified by:
      `loadInto` in interface `Loader`
    Parameters:
      `provider` - The bytes to load into the `Program`.
      `loadSpec` - The `LoadSpec` to use during load.
      `options` - The load options.
      `messageLog` - The message log.
      `program` - The `Program` to load into.
      `monitor` - A cancelable task monitor.
    Throws:
      `LoadException` - if the load failed in an expected way.
      `IOException` - if there was an IO-related problem loading.
      `CancelledException` - if the user cancelled the load.

  - ### getDefaultOptions

    public List<Option> getDefaultOptions(ByteProvider provider, LoadSpec loadSpec, DomainObject domainObject, boolean isLoadIntoProgram)
    Description copied from interface: `Loader`
    Gets the default `Loader` options.
    Specified by:
      `getDefaultOptions` in interface `Loader`
    Parameters:
      `provider` - The bytes of the thing being loaded.
      `loadSpec` - The `LoadSpec`.
      `domainObject` - The `DomainObject` being loaded.
      `isLoadIntoProgram` - True if the load is adding to an existing `DomainObject`; otherwise, false.
    Returns:
      A list of the `Loader`'s default options.

  - ### validateOptions

    public String validateOptions(ByteProvider provider, LoadSpec loadSpec, List<Option> options, Program program)
    Description copied from interface: `Loader`
    Validates the `Loader`'s options and returns null if all options are valid; otherwise, an error message describing the problem is returned.
    Specified by:
      `validateOptions` in interface `Loader`
    Parameters:
      `provider` - The bytes of the thing being loaded.
      `loadSpec` - The proposed `LoadSpec`.
      `options` - The list of `Option`s to validate.
      `program` - existing program if the loader is adding to an existing program. If it is a fresh import, then this will be null.
    Returns:
      null if all `Option`s are valid; otherwise, an error message describing the problem is returned.

  - ### postLoadProgramFixups

    protected void postLoadProgramFixups(List<Loaded<Program>> loadedPrograms, Project project, List<Option> options, MessageLog messageLog, TaskMonitor monitor) throws CancelledException, IOException
    This gets called after the given list of `loaded programs`s is finished loading. It provides subclasses an opportunity to do follow-on actions to the load.
    Parameters:
      `loadedPrograms` - The `loaded programs` to be fixed up.
      `project` - The `Project` to load into. Could be null if there is no project.
      `options` - The load options.
      `messageLog` - The message log.
      `monitor` - A cancelable task monitor.
    Throws:
      `IOException` - if there was an IO-related problem loading.
      `CancelledException` - if the user cancelled the load.

  - ### postLoadCleanup

    protected void postLoadCleanup(boolean success)
    This gets called as the final step of the load process. Subclasses may override it to ensure any resources they created can be cleaned up after the load finishes.

    NOTE: Subclasses should not use this method to release any `Program`s they created when failure occurs. That should be done by the subclass as soon as it detects failure has occurred.

    Parameters:
      `success` - True if the load completed successfully; otherwise, false

  - ### shouldApplyProcessorLabelsByDefault

    protected boolean shouldApplyProcessorLabelsByDefault()
    Returns whether or not processor labels should be applied by default. Most loaders will not need to override this method because they will not want the labels applied by default.
    Returns:
      Whether or not processor labels should be applied by default.

  - ### concatenatePaths

    protected String concatenatePaths(String... pathElements)
    Concatenates the given path elements to form a single path. Empty and null path elements are ignored.
    Parameters:
      `pathElements` - The path elements to append to one another
    Returns:
      A single path consisting of the given path elements appended together

  - ### generateBlockName

    protected String generateBlockName(Program program, boolean isOverlay, AddressSpace space)
    Generates a block name.
    Parameters:
      `program` - The `Program` for the block.
      `isOverlay` - true if the block is an overlay; use "ov" in the name.
      `space` - The `AddressSpace` for the block.
    Returns:
      The generated block name.

  - ### createProgram

    protected Program createProgram(ByteProvider provider, String domainFileName, Address imageBase, String executableFormatName, Language language, CompilerSpec compilerSpec, Object consumer) throws IOException
    Creates a `Program` with the specified attributes.
    Parameters:
      `provider` - The bytes that will make up the `Program`.
      `domainFileName` - The name for the DomainFile that will store the `Program`.
      `imageBase` - The image base address of the `Program`.
      `executableFormatName` - The file format name of the `Program`. Typically this will be the `Loader` name.
      `language` - The `Language` of the `Program`.
      `compilerSpec` - The `CompilerSpec` of the `Program`.
      `consumer` - A consumer object for the `Program` generated.
    Returns:
      The newly created `Program`.
    Throws:
      `IOException` - if there was an IO-related problem with creating the `Program`.

  - ### setProgramProperties

    public static void setProgramProperties(Program prog, ByteProvider provider, String executableFormatName) throws IOException
    Sets a program's Executable Path, Executable Format, MD5, SHA256, and FSRL properties.

    Parameters:
      `prog` - `Program` (with active transaction)
      `provider` - `ByteProvider` that the program was created from
      `executableFormatName` - executable format string
    Throws:
      `IOException` - if error reading from ByteProvider

  - ### createDefaultMemoryBlocks

    protected void createDefaultMemoryBlocks(Program program, Language language, MessageLog log)
    Creates default memory blocks for the given `Program`.
    Parameters:
      `program` - The `Program` to create default memory blocks for.
      `language` - The `Program`s `Language`.
      `log` - The log to use during memory block creation.

  - ### markAsFunction

    public static void markAsFunction(Program program, String name, Address funcStart)
    Mark this address as a function by creating a one byte function. The single byte body function is picked up by the function analyzer, disassembled, and the body fixed. Marking the function this way keeps disassembly and follow on analysis out of the loaders.
    Parameters:
      `program` - the program
      `name` - name of function, null if name not known
      `funcStart` - starting address of the function

  - ### getLanguageService

    protected LanguageService getLanguageService()
    Gets the `Loader`'s language service.

    The default behavior of this method is to return the `DefaultLanguageService`.

    Returns:
      The `Loader`'s language service.

  - ### release

    protected final void release(List<Loaded<Program>> loadedPrograms, Object consumer)
    Releases the given consumer from each of the provided `loaded programs`
    Parameters:
      `loadedPrograms` - A list of `loaded programs` which are no longer being used
      `consumer` - The consumer that was marking the `Program`s as being used