IInteractiveUnit
implements IAddressableUnit| com.pnfsoftware.jeb.core.units.IInteractiveUnit |
 Known Indirect Subclasses
AbstractCodeUnit,
AbstractInteractiveBinaryUnit,
AbstractInteractiveUnit,
ICodeUnit,
IDalvikDebuggerUnit,
IDebuggerUnit,
IDecompilerUnit,
IDexDecompilerUnit,
IDexUnit,
IJavaSourceUnit,
INativeCodeUnit<InsnType extends IInstruction>,
INativeDebuggerUnit,
INativeDecompilerUnit<InsnType extends IInstruction>,
INativeSourceUnit,
ISourceUnit,
InteractiveWrapperUnit
|
Class Overview
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).
Summary
| Public Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| abstract IInputLocation |
addressToLocation(String address)
Convert a unit-specific address to location information relative to the input.
| ||||||||||
| abstract boolean |
canExecuteAction(ActionContext actionContext)
Verify if an action can be executed.
| ||||||||||
| abstract 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.
| ||||||||||
| abstract boolean |
executeAction(ActionContext actionContext, IActionData actionData)
Execute an action.
| ||||||||||
| abstract List<Integer> |
getAddressActions(String address)
Provide a list of actions that may be executed at the given address.
| ||||||||||
| abstract AbstractCommentManager<?, ?> |
getCommentManager()
Get the comment manager.
| ||||||||||
| abstract String |
getFullComment(String address)
This convenience method is used to generate the full string comment attached to the provided
address.
| ||||||||||
| abstract Map<String, String> |
getFullComments()
This convenience method is used to generate a map of full string comments held by the units.
| ||||||||||
| abstract List<Integer> |
getGlobalActions()
Provide a list of actions that may be executed globally.
| ||||||||||
| abstract String |
getInlineComment(String address)
Retrieve the primary comment at a given address.
| ||||||||||
| abstract Map<String, String> |
getInlineComments()
Retrieve all primary comments.
| ||||||||||
| abstract List<Integer> |
getItemActions(long id)
Provide a list of actions that may be executed on the item with the given id.
| ||||||||||
| abstract IMetadataManager |
getMetadataManager()
Get a reference to the metadata manager for this unit.
| ||||||||||
| abstract String |
getPrimaryComment(String address)
This method is deprecated.
use
getInlineComment(String)
| ||||||||||
| abstract Map<String, String> |
getPrimaryComments()
This method is deprecated.
use
getInlineComments()
| ||||||||||
| abstract String |
locationToAddress(IInputLocation location)
Convert a location relative to the input to a unit-specific address.
| ||||||||||
| abstract boolean |
prepareExecution(ActionContext actionContext, IActionData actionData)
Prepare the execution of an action.
| ||||||||||
| abstract boolean |
setInlineComment(String address, String comment)
Set or delete the primary comment at a given address.
| ||||||||||
| abstract boolean |
setPrimaryComment(String address, String comment)
This method is deprecated.
use
setInlineComment(String, String)
| ||||||||||
|
[Expand]
Inherited Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
From interface
com.pnfsoftware.jeb.core.IUnitCreator
| |||||||||||
|
From interface
com.pnfsoftware.jeb.core.IUserDataSupport
| |||||||||||
|
From interface
com.pnfsoftware.jeb.core.units.IAddressableUnit
| |||||||||||
|
From interface
com.pnfsoftware.jeb.core.units.IUnit
| |||||||||||
|
From interface
com.pnfsoftware.jeb.util.events.IEventSource
| |||||||||||
Public Methods
public abstract 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
public abstract 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
public abstract 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
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
public abstract 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 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
public abstract 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
public abstract 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
public abstract String getFullComment (String address)
This convenience method is used to generate the full string comment attached to the provided address.
Returns
- may be null
public abstract Map<String, String> getFullComments ()
This convenience method is used to generate a map of full string comments held by the units.
public abstract List<Integer> getGlobalActions ()
Provide a list of actions that may be executed globally.
Returns
- the list of actions
public abstract 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
public abstract Map<String, String> getInlineComments ()
Retrieve all primary comments. The default implementation returns an empty map.
Returns
- a map of "address: comment" value pairs
public abstract 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
public abstract 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
public abstract String getPrimaryComment (String address)
public abstract Map<String, String> getPrimaryComments ()
public abstract 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
public abstract 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
public abstract boolean setInlineComment (String address, String comment)
Set or delete the primary comment at a given address. The default implementation returns false.
Parameters
| comment | the new comment; null to remove any previous comment |
|---|
Returns
- success indicator