Package com.pnfsoftware.jeb.core.units.impl

Class InteractiveWrapperUnit

java.lang.Object

com.pnfsoftware.jeb.core.units.impl.WrapperUnit<IInteractiveUnit>

com.pnfsoftware.jeb.core.units.impl.InteractiveWrapperUnit

All Implemented Interfaces:

IUnitCreator, IUserDataSupport, IAddressableUnit, IInteractiveUnit, IUnit, com.pnfsoftware.jeb.corei.IWrap<IInteractiveUnit>, IEventSource

@Ser
public class InteractiveWrapperUnit
extends WrapperUnit<IInteractiveUnit>
implements IInteractiveUnit

Simple wrapper (decorator) for IInteractiveUnit.

Constructor Summary

Constructors

Constructor	Description
InteractiveWrapperUnit(IInteractiveUnit unit, IUnitProvider provider)

Method Summary

Modifier and Type	Method	Description
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.
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.

Methods inherited from class com.pnfsoftware.jeb.core.units.impl.WrapperUnit

addChild, addChild, addListener, canBePersisted, clearAllData, countListeners, dispose, generateQuickState, getAllData, getChildren, getContributions, getCreationTimestamp, getData, getDescription, getFormatter, getFormatType, getIconData, getInterpreters, getListeners, getLock, getName, getNotes, getNotificationManager, getParent, getParentSource, getPropertyDefinitionManager, getPropertyManager, getRealName, getStatus, getUid, getUnitProcessor, getWrap, initializePropertyObjects, insertListener, isDisposed, isProcessed, isStale, isTransientChild, notifyListeners, postDeserialization, process, removeChild, removeListener, setData, setName, setNotes, setParent, setParentSource, setRealName, setUnitProcessor

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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

getCanonicalAddress, getWellKnownAddresses

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

getCommentManager, getFullComment, getFullComments

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

addChild, addChild, canBePersisted, dispose, execprvfunc, 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

Constructor Details

InteractiveWrapperUnit

public InteractiveWrapperUnit(IInteractiveUnit unit,
 IUnitProvider provider)

Parameters:

unit - IUnit to be delegated

provider - provider that extends the unit behavior

Method Details

addressToLocation

public IInputLocation addressToLocation(String address)

Description copied from interface: IInteractiveUnit

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.

Specified by:

addressToLocation in interface IInteractiveUnit

Parameters:

address - mandatory address

Returns:

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

canExecuteAction

public boolean canExecuteAction(ActionContext actionContext)

Description copied from interface: IInteractiveUnit

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

Specified by:

canExecuteAction in interface IInteractiveUnit

Parameters:

actionContext - location context for the action

Returns:

true

executeAction

public boolean executeAction(ActionContext actionContext,
 IActionData actionData)

Description copied from interface: IInteractiveUnit

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

Specified by:

executeAction in interface IInteractiveUnit

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

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

Description copied from interface: IInteractiveUnit

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.

Specified by:

executeAction in interface IInteractiveUnit

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

getAddressActions

public List<Integer> getAddressActions(String address)

Description copied from interface: IInteractiveUnit

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.

Specified by:

getAddressActions in interface IInteractiveUnit

Parameters:

address - the target address

Returns:

the list of actions

See Also:

• Actions

getMetadataManager

public IMetadataManager getMetadataManager()

Description copied from interface: IInteractiveUnit

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.

Specified by:

getMetadataManager in interface IInteractiveUnit

Returns:

the manager, null if none

getAddressLabel

public String getAddressLabel(String address)

Description copied from interface: IAddressableUnit

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

Specified by:

getAddressLabel in interface IAddressableUnit

Parameters:

address - mandatory address

Returns:

the label, null if none

getAddressLabels

public Map<String,String> getAddressLabels()

Description copied from interface: IAddressableUnit

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

Specified by:

getAddressLabels in interface IAddressableUnit

Returns:

a map of "address: label" value pairs

getAddressOfItem

public String getAddressOfItem(long id)

Description copied from interface: IAddressableUnit

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.

Specified by:

getAddressOfItem in interface IAddressableUnit

Parameters:

id - the item id

Returns:

an address best representing or matching the provided item, null otherwise

getRelatedItems

public List<Long> getRelatedItems(long id)

Description copied from interface: IAddressableUnit

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

Specified by:

getRelatedItems in interface IAddressableUnit

Parameters:

id - an item id

Returns:

a list of related items (not containing the provided id), may be empty - never null

getInlineComment

public String getInlineComment(String address)

Description copied from interface: IInteractiveUnit

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

Specified by:

getInlineComment in interface IInteractiveUnit

Parameters:

address - mandatory address

Returns:

the comment, null if none

getInlineComments

public Map<String,String> getInlineComments()

Description copied from interface: IInteractiveUnit

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

Specified by:

getInlineComments in interface IInteractiveUnit

Returns:

a map of "address: comment" value pairs

setInlineComment

public boolean setInlineComment(String address,
 String comment)

Description copied from interface: IInteractiveUnit

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

Specified by:

setInlineComment in interface IInteractiveUnit

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

Returns:

success indicator

getItemObject

public Object getItemObject(long id)

Description copied from interface: IAddressableUnit

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.

Specified by:

getItemObject in interface IAddressableUnit

Parameters:

id - the item id

Returns:

an object, whose type is defined by contract, potentially null

getGlobalActions

public List<Integer> getGlobalActions()

Description copied from interface: IInteractiveUnit

Provide a list of actions that may be executed globally.

Specified by:

getGlobalActions in interface IInteractiveUnit

Returns:

the list of actions

getItemActions

public List<Integer> getItemActions(long id)

Description copied from interface: IInteractiveUnit

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.

Specified by:

getItemActions in interface IInteractiveUnit

Parameters:

id - the target item identifier

Returns:

the list of actions

isValidAddress

public boolean isValidAddress(String address)

Description copied from interface: IAddressableUnit

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

Specified by:

isValidAddress in interface IAddressableUnit

Returns:

getItemAtAddress

public long getItemAtAddress(String address)

Description copied from interface: IAddressableUnit

Attempt to determine the best item for a given address. Implementors may return 0 if a conversion is deemed impossible, inaccurate or irrelevant.

Specified by:

getItemAtAddress in interface IAddressableUnit

Parameters:

address - the address

Returns:

an item best representing or matching the provided address, 0 otherwise

locationToAddress

public String locationToAddress(IInputLocation location)

Description copied from interface: IInteractiveUnit

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.

Specified by:

locationToAddress in interface IInteractiveUnit

Parameters:

location - mandatory location

Returns:

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

prepareExecution

public boolean prepareExecution(ActionContext actionContext,
 IActionData actionData)

Description copied from interface: IInteractiveUnit

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

Specified by:

prepareExecution in interface IInteractiveUnit

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