Package com.pnfsoftware.jeb.core.units

Interface IInteractiveUnit

All Superinterfaces:

IAddressableUnit, IEventSource, IUnit, IUnitCreator, IUserDataSupport

All Known Subinterfaces:

ICodeUnit, IDalvikDebuggerUnit, IDebuggerUnit, IDecompilerUnit, IDexDecompilerUnit, IDexUnit, IJavaSourceUnit, INativeCodeUnit<InsnType>, INativeDebuggerUnit, INativeDecompilerUnit<InsnType>, INativeSourceUnit, ISourceUnit

All Known Implementing Classes:

AbstractCodeUnit, AbstractInteractiveBinaryUnit, AbstractInteractiveUnit, InteractiveWrapperUnit

@Ser
public interface IInteractiveUnit
extends IAddressableUnit

Interactive units are addressable units that offer clients the ability to execute actions on their contents.

Plugins returning interactive documents (such as a text document with actionable items) will most likely want to implement this interface.

Well-known actions as well as classes to hold well-known action data are located in the com.pnfsoftware.jeb.core.actions.

Internal: there is currently no getAllItems()-like method that would provide a comprehensive list of items produced by an interactive unit. Derived classes may choose to provide such a method, or methods returning subsets of a unit's list of items (ICodeUnit for example, offers getXxx methods to retrieve items).

Method Summary

Modifier and Type	Method	Description
default IInputLocation	addressToLocation(String address)	Convert a unit-specific address to location information relative to the input.
boolean	canExecuteAction(ActionContext actionContext)	Verify if an action can be executed.
boolean	executeAction(ActionContext actionContext, IActionData actionData)	Execute an action.
boolean	executeAction(ActionContext actionContext, IActionData actionData, boolean notify)	Execute an action and optionally notify clients if the action was executed successfully and modified the unit contents.
List<Integer>	getAddressActions(String address)	Provide a list of actions that may be executed at the given address.
default AbstractCommentManager<?,?>	getCommentManager()	Get the comment manager.
default String	getFullComment(String address)	This convenience method is used to generate the full string comment attached to the provided address.
default Map<String,String>	getFullComments()	This convenience method is used to generate a map of full string comments held by the units.
List<Integer>	getGlobalActions()	Provide a list of actions that may be executed globally.
default String	getInlineComment(String address)	Retrieve the primary comment at a given address.
default Map<String,String>	getInlineComments()	Retrieve all primary comments.
List<Integer>	getItemActions(long id)	Provide a list of actions that may be executed on the item with the given id.
IMetadataManager	getMetadataManager()	Get a reference to the metadata manager for this unit.
default String	locationToAddress(IInputLocation location)	Convert a location relative to the input to a unit-specific address.
boolean	prepareExecution(ActionContext actionContext, IActionData actionData)	Prepare the execution of an action.
default boolean	setInlineComment(String address, String comment)	Set or delete the primary comment at a given address.

Methods inherited from interface com.pnfsoftware.jeb.core.units.IAddressableUnit

getAddressLabel, getAddressLabels, getAddressOfItem, getCanonicalAddress, getItemAtAddress, getItemObject, getRelatedItems, getWellKnownAddresses, isValidAddress

Methods inherited from interface com.pnfsoftware.jeb.util.events.IEventSource

addListener, countListeners, getListeners, getParentSource, insertListener, notifyListeners, removeListener, setParentSource

Methods inherited from interface com.pnfsoftware.jeb.core.units.IUnit

addChild, addChild, canBePersisted, dispose, generateQuickState, getChildren, getContributions, getCreationTimestamp, getDescription, getExtraInputs, getFormatter, getFormatType, getIconData, getInput, getInterpreters, getLock, getName, getNotes, getNotificationManager, getParent, getParentArtifact, getParentProject, getPropertyDefinitionManager, getPropertyManager, getRealName, getStatus, getUid, getUnitProcessor, initializePropertyObjects, isDisposed, isProcessed, isStale, isTransientChild, notifyGenericChange, postDeserialization, process, removeChild, setName, setNotes, setParent, setRealName, setUnitProcessor

Methods inherited from interface com.pnfsoftware.jeb.core.IUserDataSupport

clearAllData, getAllData, getData, setData

Method Details

getGlobalActions

List<Integer> getGlobalActions()

Provide a list of actions that may be executed globally.

Returns:

the list of actions

getItemActions

List<Integer> getItemActions(long id)

Provide a list of actions that may be executed on the item with the given id. Global actions should not be returned by this method, even though they may be executed on the given (or any) item id as well.

Parameters:

id - the target item identifier

Returns:

the list of actions

getAddressActions

List<Integer> getAddressActions(String address)

Provide a list of actions that may be executed at the given address. Global actions should not be returned by this method, even though they may be executed on the given (or any) address as well.

Parameters:

address - the target address

Returns:

the list of actions

See Also:

• Actions

addressToLocation

default IInputLocation addressToLocation(String address)

Convert a unit-specific address to location information relative to the input. The default implementation returns null.

Example: the location information could contain an (offset, size) tuple if the input is a sequence of bytes, such as for IBinaryUnit.

Note: The addressing scheme is unit specific, and defined by the plugin developer. Addresses should not start with the reserved '@' prefix.

Parameters:

address - mandatory address

Returns:

the location, null if none, error, or not supported

locationToAddress

default String locationToAddress(IInputLocation location)

Convert a location relative to the input to a unit-specific address. The default implementation returns null.

Note: The addressing scheme is unit specific, and defined by the plugin developer. Addresses should not start with the reserved '@' prefix.

Parameters:

location - mandatory location

Returns:

the address, null if none, error, or not supported

canExecuteAction

boolean canExecuteAction(ActionContext actionContext)

Verify if an action can be executed. Clients must call this method before attempting to call prepareExecution or executeAction.

Parameters:

actionContext - location context for the action

Returns:

true

prepareExecution

boolean prepareExecution(ActionContext actionContext,
 IActionData actionData)

Prepare the execution of an action. Clients must call this method before attempting to call executeAction.

Parameters:

actionContext - location context for the action

actionData - data for the action

Returns:

true if the preparation was successful, and the action may be executed. Upon successful preparation, actionData will contain plugin-set pre-execution data

executeAction

boolean executeAction(ActionContext actionContext,
 IActionData actionData)

Execute an action. On success, the plugin should notify listeners if the unit contents has changed, by issuing a J.UnitChange event.

Parameters:

actionContext - location context for the action

actionData - data for the action

Returns:

true if the execution was successful. Upon successful execution, actionData will contain plugin-set post-execution data

executeAction

boolean executeAction(ActionContext actionContext,
 IActionData actionData,
 boolean notify)

Execute an action and optionally notify clients if the action was executed successfully and modified the unit contents.

Note: setting `notify` to false can be handy when executing many actions in a short time span (which could result in many events being generated). However, since clients will not be notified that the unit has changed, it is good practice for code to manually issue a single J.UnitChange after the unit has received that series of modification.

Parameters:

actionContext - context for the action

actionData - data for the action

notify - true to notify clients if the action was successfully executed and the unit contents has changed

Returns:

action success indicator

getInlineComments

default Map<String,String> getInlineComments()

Retrieve all primary comments. The default implementation returns an empty map.

Returns:

a map of "address: comment" value pairs

getInlineComment

default String getInlineComment(String address)

Retrieve the primary comment at a given address. The default implementation returns null.

Parameters:

address - mandatory address

Returns:

the comment, null if none

setInlineComment

default boolean setInlineComment(String address,
 String comment)

Set or delete the primary comment at a given address. The default implementation returns false.

Parameters:

address -

comment - the new comment; null to remove any previous comment

Returns:

success indicator

getCommentManager

default AbstractCommentManager<?,?> getCommentManager()

Get the comment manager. This method is optional. When the unit is disposed, this method must return null. The default implementation returns null.

Returns:

a comment manager, or null if the unit does not have one

getFullComment

default String getFullComment(String address)

This convenience method is used to generate the full string comment attached to the provided address.

Parameters:

address -

Returns:

may be null

getFullComments

default Map<String,String> getFullComments()

This convenience method is used to generate a map of full string comments held by the units.

Returns:

getMetadataManager

IMetadataManager getMetadataManager()

Get a reference to the metadata manager for this unit. The metadata manager is optional; units may decide to not provide one. Units inheriting from AbstractInteractiveUnit or AbstractInteractiveBinaryUnit do offer a default metadata manager.

Returns:

the manager, null if none