public interface

IInteractiveUnit

implements IAddressableUnit
com.pnfsoftware.jeb.core.units.IInteractiveUnit
Known Indirect Subclasses

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 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 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.
abstract boolean setComment(String address, String comment)
Set or delete the comment at a given address.
[Expand]
Inherited Methods
From interface com.pnfsoftware.jeb.core.IUnitCreator
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.

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

public abstract boolean setComment (String address, String comment)

Set or delete the comment at a given address.

Parameters
comment the new comment; null to remove any previous comment
Returns
  • success indicator