public class

InteractiveWrapperUnit

extends WrapperUnit<T extends IUnit>
implements IInteractiveUnit
java.lang.Object
   ↳ com.pnfsoftware.jeb.core.units.impl.WrapperUnit<T extends com.pnfsoftware.jeb.core.units.IUnit>
     ↳ com.pnfsoftware.jeb.core.units.impl.InteractiveWrapperUnit

Class Overview

Simple wrapper (decorator) for IInteractiveUnit.

Summary

Public Constructors
InteractiveWrapperUnit(IInteractiveUnit unit, IUnitProvider provider)
Public Methods
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, boolean notify)
Execute an action and optionally notify clients if the action was executed successfully and modified the unit contents.
boolean executeAction(ActionContext actionContext, IActionData actionData)
Execute an action.
List<Integer> getAddressActions(String address)
Provide a list of actions that may be executed at the given address.
String getAddressLabel(String address)
Retrieve the label at a given address.
Map<String, String> getAddressLabels()
Retrieve all labels.
String getAddressOfItem(long id)
Attempt to determine the best address for a given item.
List<Integer> getGlobalActions()
Provide a list of actions that may be executed globally.
String getInlineComment(String address)
Retrieve the primary comment at a given address.
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.
long getItemAtAddress(String address)
Attempt to determine the best item for a given address.
Object getItemObject(long id)
Optionally provide an object associated with the given item.
IMetadataManager getMetadataManager()
Get a reference to the metadata manager for this unit.
List<Long> getRelatedItems(long id)
Retrieve items related to the provided item id.
boolean isValidAddress(String address)
Determine if the provided address is a valid address for this unit.
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.
boolean setInlineComment(String address, String comment)
Set or delete the primary comment at a given address.
[Expand]
Inherited Methods
From class com.pnfsoftware.jeb.core.units.impl.WrapperUnit
From class java.lang.Object
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.IInteractiveUnit
From interface com.pnfsoftware.jeb.core.units.IUnit
From interface com.pnfsoftware.jeb.corei.IWrap
From interface com.pnfsoftware.jeb.util.events.IEventSource

Public Constructors

public InteractiveWrapperUnit (IInteractiveUnit unit, IUnitProvider provider)

Parameters
unit IUnit to be delegated
provider provider that extends the unit behavior

Public Methods

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

public String getAddressLabel (String address)

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

Parameters
address mandatory address
Returns
  • the label, null if none

public Map<String, String> getAddressLabels ()

Retrieve all labels. The default implementation returns an empty map.

Returns
  • a map of "address: label" value pairs

public 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 List<Integer> getGlobalActions ()

Provide a list of actions that may be executed globally.

Returns
  • the list of actions

public 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 Map<String, String> getInlineComments ()

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

Returns
  • a map of "address: comment" value pairs

public 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 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 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 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 List<Long> getRelatedItems (long id)

Retrieve items related to the provided item id. The definition and context of 'relation' is implementation dependent.

Parameters
id an item id
Returns
  • a list of related items (not containing the provided id), may be empty - never null

public boolean isValidAddress (String address)

Determine if the provided address is a valid address for this unit.

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