# Interface: com.pnfsoftware.jeb.core.units.IInteractiveUnit 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](ICodeUnit) for example, offers getXxx methods to retrieve items\). ## Method: addressToLocation - parameter: `address`, type: `java.lang.String` - return type: `com.pnfsoftware.jeb.core.input.IInputLocation` Description: 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](IBinaryUnit). Note: The addressing scheme is unit specific, and defined by the plugin developer. Addresses should not start with the reserved '@' prefix. parameter: address: mandatory address return: the location, null if none, error, or not supported ## Method: canExecuteAction - parameter: `actionContext`, type: `com.pnfsoftware.jeb.core.actions.ActionContext` - return type: `boolean` Description: Verify if an action can be executed. Clients must call this method before attempting to call [prepareExecution](#prepareExecution(ActionContext, IActionData)) or [executeAction](#executeAction(ActionContext, IActionData)). parameter: actionContext: location context for the action return: true ## Method: executeAction - parameter: `actionContext`, type: `com.pnfsoftware.jeb.core.actions.ActionContext` - parameter: `actionData`, type: `com.pnfsoftware.jeb.core.actions.IActionData` - return type: `boolean` Description: Execute an action. On success, the plugin should notify listeners if the unit contents has changed, by issuing a [J#UnitChange](J#UnitChange) event. parameter: actionContext: location context for the action parameter: actionData: data for the action return: true if the execution was successful. Upon successful execution, actionData will contain plugin\-set post\-execution data ## Method: executeAction - parameter: `actionContext`, type: `com.pnfsoftware.jeb.core.actions.ActionContext` - parameter: `actionData`, type: `com.pnfsoftware.jeb.core.actions.IActionData` - parameter: `notify`, type: `boolean` - return type: `boolean` Description: 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](J#UnitChange) after the unit has received that series of modification. parameter: actionContext: context for the action parameter: actionData: data for the action parameter: notify: true to notify clients if the action was successfully executed and the unit contents has changed return: action success indicator ## Method: getAddressActions - parameter: `address`, type: `java.lang.String` - return type: `java.util.List` Description: 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. parameter: address: the target address return: the list of actions see also: Actions ## Method: getCommentManager - return type: `com.pnfsoftware.jeb.core.units.impl.AbstractCommentManager` Description: Get the comment manager. This method is optional. **When the unit is disposed, this method must return null.** The default implementation returns null. return: a comment manager, or null if the unit does not have one ## Method: getFullComment - parameter: `address`, type: `java.lang.String` - return type: `java.lang.String` Description: This convenience method is used to generate the full string comment attached to the provided address. parameter: address: mandatory address return: the full comment, or null if none ## Method: getFullComments - return type: `java.util.Map` Description: This convenience method is used to generate a map of full string comments held by the units. return: a map of "address: full comment" value pairs ## Method: getGlobalActions - return type: `java.util.List` Description: Provide a list of actions that may be executed globally. return: the list of actions ## Method: getInlineComment - parameter: `address`, type: `java.lang.String` - return type: `java.lang.String` Description: Retrieve the primary comment at a given address. The default implementation returns null. parameter: address: mandatory address return: the comment, null if none ## Method: getInlineComments - return type: `java.util.Map` Description: Retrieve all primary comments. The default implementation returns an empty map. return: a map of "address: comment" value pairs ## Method: getItemActions - parameter: `id`, type: `long` - return type: `java.util.List` Description: 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. parameter: id: the target item identifier return: the list of actions ## Method: getMetadataManager - return type: `com.pnfsoftware.jeb.core.units.IMetadataManager` Description: 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](AbstractInteractiveUnit) or [AbstractInteractiveBinaryUnit](AbstractInteractiveBinaryUnit) do offer a [default metadata manager](MetadataManager). return: the manager, null if none ## Method: locationToAddress - parameter: `location`, type: `com.pnfsoftware.jeb.core.input.IInputLocation` - return type: `java.lang.String` Description: 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. parameter: location: mandatory location return: the address, null if none, error, or not supported ## Method: prepareExecution - parameter: `actionContext`, type: `com.pnfsoftware.jeb.core.actions.ActionContext` - parameter: `actionData`, type: `com.pnfsoftware.jeb.core.actions.IActionData` - return type: `boolean` Description: Prepare the execution of an action. Clients must call this method before attempting to call [executeAction](#executeAction(ActionContext, IActionData)). parameter: actionContext: location context for the action parameter: actionData: data for the action return: true if the preparation was successful, and the action may be executed. Upon successful preparation, actionData will contain plugin\-set pre\-execution data ## Method: setInlineComment - parameter: `address`, type: `java.lang.String` - parameter: `comment`, type: `java.lang.String` - return type: `boolean` Description: Set or delete the primary comment at a given address. The default implementation returns false. parameter: address: mandatory address parameter: comment: the new comment; null to remove any previous comment return: success indicator