Package ghidra.app.util.opinion

Class LoadResults<T extends DomainObject>

java.lang.Object

ghidra.app.util.opinion.LoadResults<T>

Type Parameters:

T - The type of DomainObjects that were loaded

All Implemented Interfaces:

AutoCloseable, Iterable<Loaded<T>>

public class LoadResults<T extends DomainObject>
extends Object
implements Iterable<Loaded<T>>, AutoCloseable

The result of a Loader.load(ghidra.app.util.opinion.Loader.ImporterSettings). Provides convenient access to and operations on the underlying Loaded DomainObjects that got loaded.

Constructor Summary

Constructors

Constructor	Description
LoadResults(Loaded<T> loaded)	Creates a new LoadResults that contains the given Loaded DomainObject.
LoadResults(List<Loaded<T>> loadedList)	Creates a new LoadResults that contains the given non-empty List of Loaded DomainObjects.

Method Summary

Modifier and Type	Method	Description
void	close()	Closes this LoadResults and releases the reference on the object consuming it.
List<Loaded<T>>	getNonPrimary()	Gets the "non-primary" Loaded DomainObjects, whose meaning is defined by each Loader implementation
Loaded<T>	getPrimary()	Gets the "primary" Loaded DomainObject, whose meaning is defined by each Loader implementation
T	getPrimaryDomainObject()	Deprecated, for removal: This API element is subject to removal in a future version. This class's internal DomainObjects are now cleaned up with the close() method.
T	getPrimaryDomainObject(Object consumer)	Gets the "primary" DomainObject, whose meaning is defined by each Loader implementation.
Iterator<Loaded<T>>	iterator()
void	release(Object consumer)	Deprecated, for removal: This API element is subject to removal in a future version. Use close() instead
void	release(Object consumer, Predicate<? super Loaded<T>> filter)	Deprecated, for removal: This API element is subject to removal in a future version. Use close() instead
void	releaseNonPrimary(Object consumer)	Deprecated, for removal: This API element is subject to removal in a future version. Use getNonPrimary() and Loaded.close() on the List elements instead
void	save(TaskMonitor monitor)	Saves each Loaded DomainObject to the given Project.
int	size()	Gets the number of Loaded DomainObjects in this LoadResults.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Constructor Details

LoadResults

public LoadResults(List<Loaded<T>> loadedList)
            throws IllegalArgumentException

Creates a new LoadResults that contains the given non-empty List of Loaded DomainObjects. The first entry in the List is assumed to be the primary Loaded DomainObject.

This object needs to be closed when done with it.

Parameters:

loadedList - A List of Loaded DomainObjects

Throws:

IllegalArgumentException - if the provided List is null or empty

LoadResults

public LoadResults(Loaded<T> loaded)

Creates a new LoadResults that contains the given Loaded DomainObject. This Loaded DomainObject is assumed to be the primary Loaded DomainObject.

Parameters:

loaded - The Loaded DomainObject

Method Details

getPrimary

public Loaded<T> getPrimary()

Gets the "primary" Loaded DomainObject, whose meaning is defined by each Loader implementation

Returns:

The "primary" Loaded DomainObject

getNonPrimary

public List<Loaded<T>> getNonPrimary()

Gets the "non-primary" Loaded DomainObjects, whose meaning is defined by each Loader implementation

Returns:

The "non-primary" Loaded DomainObjects

getPrimaryDomainObject

public T getPrimaryDomainObject(Object consumer)

Gets the "primary" DomainObject, whose meaning is defined by each Loader implementation.

NOTE: 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 LoadResults 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 entire LoadResults must also still be closed).

Returns:

The "primary" DomainObject

getPrimaryDomainObject

@Deprecated(since="12.0",
            forRemoval=true)
public T getPrimaryDomainObject()

Deprecated, for removal: This API element is subject to removal in a future version.

This class's internal DomainObjects are now cleaned up with the close() method. If the primary DomainObject needs to be retrieved from this class, instead use getPrimaryDomainObject(Object) and independently clean up the new reference with a separate call to DomainObject.release(Object).

Gets the "primary" loaded DomainObject, whose meaning is defined by each Loader implementation. Unsafe resource management is used. Temporarily exists to provide backwards compatibility.

Returns:

The "primary" DomainObject

size

public int size()

Gets the number of Loaded DomainObjects in this LoadResults. The size will always be greater than 0.

Returns:

The number of Loaded DomainObjects in this LoadResults

save

public void save(TaskMonitor monitor)
          throws CancelledException,
IOException,
InvalidNameException

Saves each Loaded DomainObject to the given Project.

Parameters:

monitor - A cancelable task monitor

Throws:

CancelledException - if the operation was cancelled

IOException - If there was a problem saving. A thrown exception may result in only some of the Loaded elements being saved. It is the responsibility of the caller to clean things up appropriately.

InvalidNameException - if saving with an invalid name

See Also:

• Loaded.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 all of the Loaded DomainObjects that the specified consumer is no longer using them. Temporarily exists to provide backwards compatibility.

Parameters:

consumer - the consumer

release

@Deprecated(since="12.0",
            forRemoval=true)
public void release(Object consumer,
 Predicate<? super Loaded<T>> filter)

Deprecated, for removal: This API element is subject to removal in a future version.

Use close() instead

Unsafely notifies the filtered Loaded DomainObjects that the specified consumer is no longer using them. Temporarily exists to provide backwards compatibility.

Parameters:

consumer - the consumer

filter - a filter to apply to the Loaded DomainObjects prior to the release

releaseNonPrimary

@Deprecated(since="12.0",
            forRemoval=true)
public void releaseNonPrimary(Object consumer)

Deprecated, for removal: This API element is subject to removal in a future version.

Use getNonPrimary() and Loaded.close() on the List elements instead

Notify the non-primary Loaded DomainObjects that the specified consumer is no longer using them. When the last consumer invokes this method, the non-primary Loaded DomainObjects will be closed and will become invalid.

Parameters:

consumer - the consumer

close

public void close()

Closes this LoadResults and releases the reference on the object consuming it.

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

Specified by:

close in interface AutoCloseable

iterator

public Iterator<Loaded<T>> iterator()

Specified by:

iterator in interface Iterable<T extends DomainObject>