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

This method is deprecated.
use getInlineComment(String)

public abstract Map<String, String> getPrimaryComments ()

This method is deprecated.
use getInlineComments()

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

public abstract boolean setPrimaryComment (String address, String comment)

This method is deprecated.
use setInlineComment(String, String)