Package ghidra.app.util.opinion

# Class Loaded<T extends DomainObject>

java.lang.Object
ghidra.app.util.opinion.Loaded<T>

Type Parameters:
  `T` - The type of `DomainObject` that was loaded

All Implemented Interfaces:
  `AutoCloseable`

Direct Known Subclasses:
  `LoadedOpen`

public class Loaded<T extends DomainObject> extends Object implements AutoCloseable
A loaded `DomainObject` produced by a `Loader`. In addition to storing the loaded `DomainObject`, it also stores the `Loader`'s desired name and project folder path for the loaded `DomainObject`, should it get saved to a project.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected DomainFile`
  `domainFile`
  `protected final T`
  `domainObject`
  `protected FSRL`
  `fsrl`
  `protected Object`
  `loadedConsumer`
  `protected boolean`
  `mirrorFsLayout`
  `protected final String`
  `name`
  `protected Project`
  `project`
  `protected String`
  `projectRootPath`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Loaded(T domainObject, Loader.ImporterSettings settings)`
  Creates a new `Loaded` object.
  `Loaded(T domainObject, String name, FSRL fsrl, Project project, String projectRootPath, boolean mirrorFsLayout, Object consumer)`
  Creates a new `Loaded` object.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `apply(Consumer<T> operation)`
  Safely applies the given operation to the loaded `DomainObject` without the need to worry about resource management
  `boolean`
  `check(Predicate<T> predicate)`
  Safely tests the given predicate on the loaded `DomainObject` without the need to worry about resource management
  `void`
  `close()`
  Closes this `Loaded` `DomainObject` and releases the reference on the object consuming it.
  `T`
  `getDomainObject()`
  Deprecated, for removal: This API element is subject to removal in a future version.
  This class's internal `DomainObject` is now cleaned up with the `close()` method.
  `T`
  `getDomainObject(Object consumer)`
  Gets the loaded `DomainObject`.
  `Class<? extends DomainObject>`
  `getDomainObjectType()`
  Gets the loaded `DomainObject`'s type
  `String`
  `getName()`
  Gets the name of the loaded `DomainObject`.
  `Project`
  `getProject()`
  Gets the `Project` this will get saved to during a `save(TaskMonitor)` operation
  `String`
  `getProjectFolderPath()`
  Gets the project folder path this will get saved to during a `save(TaskMonitor)` operation.
  `DomainFile`
  `getSavedDomainFile()`
  Gets the loaded `DomainObject`'s associated `DomainFile` that was `saved`
  `void`
  `release(Object consumer)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Use `close()` instead
  `DomainFile`
  `save(TaskMonitor monitor)`
  Saves the loaded `DomainObject` to the given `Project` at this object's project folder path, using this object's name.
  `void`
  `setProjectFolderPath(String projectRootPath)`
  Sets the project folder path this will get saved to during a `save(TaskMonitor)` operation.
  `String`
  `toString()`

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

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

- ## Field Details

  - ### domainObject

    protected final T extends DomainObject domainObject

  - ### name

    protected final String name

  - ### fsrl

    protected FSRL fsrl

  - ### project

    protected Project project

  - ### projectRootPath

    protected String projectRootPath

  - ### mirrorFsLayout

    protected boolean mirrorFsLayout

  - ### loadedConsumer

    protected Object loadedConsumer

  - ### domainFile

    protected DomainFile domainFile

- ## Constructor Details

  - ### Loaded

    public Loaded(T domainObject, String name, FSRL fsrl, Project project, String projectRootPath, boolean mirrorFsLayout, Object consumer)
    Creates a new `Loaded` object.

    This object needs to be `closed` when done with it.

    Parameters:
      `domainObject` - The loaded `DomainObject`
      `name` - The name of the loaded `DomainObject`. Path information that appears at the beginning the name will be appended to the `projectRootPath` during a `operation`.
      `fsrl` - The `FSRL` of the loaded `DomainObject`
      `project` - If not `null`, the project this will get saved to during a `save(TaskMonitor)` operation
      `projectRootPath` - The project folder path that all `Loaded` `DomainObject`s will be `saved` relative to. If `null`, "/" will be used.
      `mirrorFsLayout` - True if the filesystem layout should be mirrored when `saving`; otherwise, false
      `consumer` - A reference to the object "consuming" the returned `Loaded` `DomainObject`, used to ensure the underlying `DomainObject` is only closed when every consumer is done with it (see `close()`). NOTE: Wrapping a `DomainObject` in a `Loaded` transfers responsibility of releasing the given `DomainObject` to this `Loaded`'s `close()` method.

  - ### Loaded

    public Loaded(T domainObject, Loader.ImporterSettings settings)
    Creates a new `Loaded` object.

    This object needs to be `closed` when done with it.

    Parameters:
      `domainObject` - The loaded `DomainObject`
      `settings` - The `Loader.ImporterSettings`.

- ## Method Details

  - ### getDomainObject

    public T getDomainObject(Object consumer)
    Gets the loaded `DomainObject`.

    NOTE: The given It is the responsibility of the caller to properly `release` it when done. This `DomainObject.release(Object)` does not replace the requirement to `close()` the `Loaded` object when done.

    Parameters:
      `consumer` - A new reference to the object "consuming" the returned `DomainObject`, used to ensure the underlying `DomainObject` is only released when every consumer is done with it (see `DomainObject.release(Object)`). NOTE: This method adds the given consumer to the returned `DomainObject`, requiring an explicit `DomainObject.release(Object)` to be called on the return value (this `Loaded` must also still be `closed`).
    Returns:
      The loaded `DomainObject`

  - ### getDomainObject

    @Deprecated(since="12.0", forRemoval=true) public T getDomainObject()
    Deprecated, for removal: This API element is subject to removal in a future version.
    This class's internal `DomainObject` is now cleaned up with the `close()` method. If the `DomainObject` needs to be retrieved from this class, instead use `getDomainObject(Object)` and independently clean up the new reference with a separate call to `DomainObject.release(Object)`.
    Gets the loaded `DomainObject` with unsafe resource management. Temporarily exists to provide backwards compatibility.
    Returns:
      The loaded `DomainObject`

  - ### getDomainObjectType

    public Class<? extends DomainObject> getDomainObjectType()
    Gets the loaded `DomainObject`'s type
    Returns:
      the loaded `DomainObject`'s type

  - ### apply

    public void apply(Consumer<T> operation)
    Safely applies the given operation to the loaded `DomainObject` without the need to worry about resource management
    Parameters:
      `operation` - The operation to apply to the loaded `DomainObject`

  - ### check

    public boolean check(Predicate<T> predicate)
    Safely tests the given predicate on the loaded `DomainObject` without the need to worry about resource management
    Parameters:
      `predicate` - The predicate to test
    Returns:
      The result of the test

  - ### getName

    public String getName()
    Gets the name of the loaded `DomainObject`. If a `save(TaskMonitor)` occurs, this will attempted to be used for the resulting `DomainFile`'s name.
    Returns:
      the name of the loaded `DomainObject`

  - ### getProject

    public Project getProject()
    Gets the `Project` this will get saved to during a `save(TaskMonitor)` operation
    Returns:
      The `Project` this will get saved to during a `save(TaskMonitor)` operation (could be null)

  - ### getProjectFolderPath

    public String getProjectFolderPath()
    Gets the project folder path this will get saved to during a `save(TaskMonitor)` operation.

    NOTE: The returned path will always end with a "/".

    Returns:
      the project folder path

  - ### setProjectFolderPath

    public void setProjectFolderPath(String projectRootPath)
    Sets the project folder path this will get saved to during a `save(TaskMonitor)` operation.
    Parameters:
      `projectRootPath` - The project folder path that all `Loaded` `DomainObject`s will be saved relative to. If `null`, "/" will be used.

  - ### save

    public DomainFile save(TaskMonitor monitor) throws CancelledException, ClosedException, IOException, InvalidNameException
    Saves the loaded `DomainObject` to the given `Project` at this object's project folder path, using this object's name.

    If a `DomainFile` already exists with the same desired name and project folder path, the desired name will get a counter value appended to it to avoid a naming conflict. Therefore, it should not be assumed that the returned `DomainFile` will have the same name as a call to `getName()`.

    Parameters:
      `monitor` - A cancelable task monitor
    Returns:
      The `DomainFile` where the save happened
    Throws:
      `CancelledException` - if the operation was cancelled
      `ClosedException` - if the loaded `DomainObject` was already closed
      `IOException` - If there was an IO-related error, a project wasn't specified, an invalid name was specified, or it was already successfully saved and still exists
      `InvalidNameException` - if saving with an invalid name

  - ### getSavedDomainFile

    public DomainFile getSavedDomainFile() throws FileNotFoundException
    Gets the loaded `DomainObject`'s associated `DomainFile` that was `saved`
    Returns:
      The loaded `DomainObject`'s associated saved `DomainFile`, or null if was not saved
    Throws:
      `FileNotFoundException` - If the loaded `DomainObject` was saved but the associated `DomainFile` no longer exists
    See Also:
      - `save(TaskMonitor)`

  - ### release

    @Deprecated(since="12.0", forRemoval=true) public void release(Object consumer)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use `close()` instead
    Unsafely notifies the loaded `DomainObject` that the specified consumer is no longer using it. Temporarily exists to provide backwards compatibility.
    Parameters:
      `consumer` - the consumer

  - ### close

    public void close()
    Closes this `Loaded` `DomainObject` and releases the reference on the object consuming it.

    NOTE: Any `DomainObject`s obtained via `getDomainObject(Object)` must still be explicitly `released` after calling this method, since they were obtained with their own consumers.

    Specified by:
      `close` in interface `AutoCloseable`

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`