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 DomainObjects 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 DomainObjects 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 DomainObjects 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