IInteractiveUnit
implements IUnit| com.pnfsoftware.jeb.core.units.IInteractiveUnit |
 Known Indirect Subclasses
|
Class Overview
Interactive units are 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)
Execute an action.
| ||||||||||
| 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 List<Integer> |
getAddressActions(String address)
Provide a list of actions that may be executed at the given address.
| ||||||||||
| abstract String |
getAddressLabel(String address)
Retrieve the label at a given address.
| ||||||||||
| abstract Map<String, String> |
getAddressLabels()
Retrieve all labels.
| ||||||||||
| abstract String |
getAddressOfItem(long id)
Attempt to determine the best address for a given item.
| ||||||||||
| abstract String |
getComment(String address)
Retrieve the comment at a given address.
| ||||||||||
| abstract Map<String, String> |
getComments()
Retrieve all comments.
| ||||||||||
| abstract List<Integer> |
getGlobalActions()
Provide a list of actions that may be executed globally.
| ||||||||||
| abstract List<Integer> |
getItemActions(long id)
Provide a list of actions that may be executed on the item with the given id.
| ||||||||||
| abstract long |
getItemAtAddress(String address)
Attempt to determine the best item for a given address.
| ||||||||||
| abstract Object |
getItemObject(long id)
Optionally provide an object associated with the given item.
| ||||||||||
| abstract IMetadataManager |
getMetadataManager()
Get a reference to the metadata manager for this unit.
| ||||||||||
| 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.
| ||||||||||
|
[Expand]
Inherited Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
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.
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)
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 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 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 String getAddressLabel (String address)
Retrieve the label at a given address.
Parameters
| address | mandatory address |
|---|
Returns
- the comment, null if none
public abstract Map<String, String> getAddressLabels ()
Retrieve all labels.
Returns
- a map of "address: label" value pairs
public abstract String getAddressOfItem (long id)
Attempt to determine the best address for a given item. Implementors may return null if a conversion is deemed impossible, inaccurate or irrelevant.
Clients use this method to provide navigation capability, for example, jumping from an item to the master (main) related item, that would be located at the resulting address.
Plugin developers are recommended to implement this method.
Parameters
| id | the item id |
|---|
Returns
- an address best representing or matching the provided item, null otherwise
public abstract String getComment (String address)
Retrieve the comment at a given address.
Parameters
| address | mandatory address |
|---|
Returns
- the comment, null if none
public abstract Map<String, String> getComments ()
Retrieve all comments.
Returns
- a map of "address: comment" value pairs
public abstract List<Integer> getGlobalActions ()
Provide a list of actions that may be executed globally.
Returns
- the list of actions
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 long getItemAtAddress (String address)
Attempt to determine the best item for a given address. Implementors may return 0 if a conversion is deemed impossible, inaccurate or irrelevant.
Parameters
| address | the address |
|---|
Returns
- an item best representing or matching the provided address, 0 otherwise
public abstract Object getItemObject (long id)
Optionally provide an object associated with the given item. This method may return null, an opaque object, or an object defined by the contract of the implementing object or sub-interface. The SPI of sub-interfaces should specify the item id formats, if any, as well as types and semantics associated with the objects returned by this method.
Parameters
| id | the item id |
|---|
Returns
- an object, whose type is defined by contract, potentially null
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 locationToAddress (IInputLocation location)
Convert a location relative to the input to a unit-specific address.
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