public interface

IUnit

implements IUnitCreator IUserDataSupport IEventSource
com.pnfsoftware.jeb.core.units.IUnit
Known Indirect Subclasses

Class Overview

Base interface for units.

Units parse input data (bytes or product of other units), and produce data and documents to be displayed by a client. Units may also produce and contain children. Children may be persisted (default) or transient. Top-level units (ie, those that are children of an artifact) are always persisted.

Implementors should extend one of the abstract classes that partially implement IUnit and derived interfaces, such as AbstractUnit. Specialized units, such as binary code parsers, have highly-specialized interfaces that clients take advantage of to display extra information and/or offer features specific to such units.

Implementation guidelines (non-exhaustive):

  • Constructors of IUnit objects should do as little processing as possible
  • Processing, such as the parsing or generation of intermediate abstractions, should be done in the process() method.
  • After processing, isProcessed() should return true
  • If processing cannot be done, process() should return false. An information message may be set to let the client know why the unit cannot be processed
  • Most methods can only be called after successful processing; calling them on a non-processed unit results in undefined behavior (and most likely, will raise an exception)
  • When unit internal state changes, units should issue an appropriate J.UnitXxx event.

See Also

Summary

Public Methods
abstract void addChild(IUnit unit, boolean persisted)
Add a child unit to this unit.
abstract void addChild(IUnit unit)
Register a child unit to this unit.
abstract void addChildUnit(IUnit unit)
Deprecated.
abstract boolean canBePersisted()
Determine if this unit can be persisted.
abstract void dispose()
Dispose of the resources used by this unit.
abstract IQuickStateObject generateQuickState()
Save the state of this unit (it may be a partial state).
abstract List<? extends IUnit> getChildren()
Retrieve a read-only list of all direct children units.
abstract List<IUnitContribution> getContributions()
Get the list of contributions attached to the unit.
abstract long getCreationTimestamp()
Get the date of creation of this unit.
abstract String getDescription()
Get a description string for that unit.
abstract Collection<IInput> getExtraInputs()
Get additional inputs.
abstract String getFormatType()
Mandatory unit type.
abstract IUnitFormatter getFormatter()
Retrieve a fresh formatter for that unit.
abstract byte[] getIconData()
The icon bytes representing units of such type.
abstract IInput getInput()
Get the primary input data for that unit, if there is some.
abstract List<IUnitInterpreter> getInterpreters()
Get the list of command interpreters attached to the unit.
abstract IUnitLock getLock()
Get the unit lock.
abstract String getName()
Get the unit name.
abstract String getNotes()
Get user-defined notes.
abstract IUnitNotificationManager getNotificationManager()
Get a reference to the notification manager.
abstract IUnitCreator getParent()
Retrieve the creator (or parent) of this unit.
abstract IArtifact getParentArtifact()
Retrieve the artifact from which this unit derive.
abstract IRuntimeProject getParentProject()
Retrieve the parent project that owns this unit.
abstract IPropertyDefinitionManager getPropertyDefinitionManager()
Retrieve the PDM used by this unit.
abstract IPropertyManager getPropertyManager()
Retrieve the PM used by this unit.
abstract String getRealName()
Retrieve the optional real unit name.
abstract String getStatus()
Get the status for the unit.
abstract long getUid()
Retrieve an identifier that uniquely identifies the unit within its project.
abstract IUnitProcessor getUnitProcessor()
Retrieve the unit processor used by this unit.
abstract void initializePropertyObjects(IUnitCreator parent, IUnitProcessor processor, IPropertyDefinitionManager pdm)
Initialize the property manager and property definition manager used by this unit.
abstract boolean isDisposed()
Indicate if the unit has been disposed
abstract boolean isProcessed()
Verify if the unit was successfully processed.
abstract boolean isStale()
Determine whether the unit was successfully processed, but is now considered to be stale (outdated content).
abstract boolean isTransientChild(IUnit unit)
Check if a child unit is transient.
abstract void notifyGenericChange()
Notify all listeners of a generic change, i.e.
abstract void postDeserialization(IRuntimeProject prj)
This method is called by the engines after a unit has been fully deserialized.
abstract boolean process()
Process the unit.
abstract void removeChild(IUnit unit)
Remove a direct child of the current unit.
abstract void setName(String name)
Set the unit name.
abstract void setNotes(String notes)
Set user-defined notes.
abstract void setParent(IUnitCreator parent)
Set the parent unit or artifact.
abstract void setRealName(String name)
Set the optional unit's real name.
abstract void setUnitProcessor(IUnitProcessor processor)
Set the unit processor.
[Expand]
Inherited Methods
From interface com.pnfsoftware.jeb.core.IUnitCreator
From interface com.pnfsoftware.jeb.core.IUserDataSupport
From interface com.pnfsoftware.jeb.util.events.IEventSource

Public Methods

public abstract void addChild (IUnit unit, boolean persisted)

Add a child unit to this unit. Implementations must check for duplicate and also notify clients by emitting the right event.

Parameters
unit the child unit
persisted true if the unit should be persisted upon project saving

public abstract void addChild (IUnit unit)

Register a child unit to this unit. The child unit is persisted. Same as addChild(child, true).

Parameters
unit the child unit

public abstract void addChildUnit (IUnit unit)

Deprecated. Please use addChild(IUnit) instead.

Parameters
unit the child unit

public abstract boolean canBePersisted ()

Determine if this unit can be persisted. This method can be used by parent units and client code to verify if a child unit can legally be persisted.

Returns
  • true if the unit can be persisted, false if the unit must not be persisted

public abstract void dispose ()

Dispose of the resources used by this unit.

public abstract IQuickStateObject generateQuickState ()

Save the state of this unit (it may be a partial state). Implementation of this method is optional.

Returns
  • a state object or null if unsupported

public abstract List<? extends IUnit> getChildren ()

Retrieve a read-only list of all direct children units.

Returns
  • the children or an empty list, never null

public abstract List<IUnitContribution> getContributions ()

Get the list of contributions attached to the unit.

public abstract long getCreationTimestamp ()

Get the date of creation of this unit.

Returns
  • the creation timestamp in milliseconds since the unix epoch

public abstract String getDescription ()

Get a description string for that unit.

The unit must be processed before calling this method.

Returns
  • a description string

public abstract Collection<IInput> getExtraInputs ()

Get additional inputs.

Returns
  • a collection of additional input objects (generally empty)

public abstract String getFormatType ()

Mandatory unit type. The type should be unique across all units. It should be the same as the identifier's type.

Returns
  • the non-null unit type

public abstract IUnitFormatter getFormatter ()

Retrieve a fresh formatter for that unit. Formatters are used to produce document outputs, that represent the unit in whole or in part.

The unit must be processed before calling this method.

Returns
  • a new formatter, never null

public abstract byte[] getIconData ()

The icon bytes representing units of such type. Typically, the data represents a 16x16 BMP or PNG image. Clients may use this data to represent labels for such units in a graphical way.

Returns
  • the BMP or PNG bytes of an icon

public abstract IInput getInput ()

Get the primary input data for that unit, if there is some. Usually, for top-level units, it will be the input of the parent artifact.

Returns
  • optional input object, may be null

public abstract List<IUnitInterpreter> getInterpreters ()

Get the list of command interpreters attached to the unit.

Returns
  • the interpreter, null if none

public abstract IUnitLock getLock ()

Get the unit lock.

public abstract String getName ()

Get the unit name.

Returns
  • the unit name

public abstract String getNotes ()

Get user-defined notes. The notes can be textual data of any sort.

Returns
  • the notes

public abstract IUnitNotificationManager getNotificationManager ()

Get a reference to the notification manager.

Returns
  • the notification manager, never null

public abstract IUnitCreator getParent ()

Retrieve the creator (or parent) of this unit. It can be a parent IUnit or an IArtifact, for top-level units.

Returns
  • the parent

public abstract IArtifact getParentArtifact ()

Retrieve the artifact from which this unit derive.

public abstract IRuntimeProject getParentProject ()

Retrieve the parent project that owns this unit.

public abstract IPropertyDefinitionManager getPropertyDefinitionManager ()

Retrieve the PDM used by this unit. For consistency, it is recommend that all units of a given type return equivalent PDMs.

Returns
  • the property definition manager

public abstract IPropertyManager getPropertyManager ()

Retrieve the PM used by this unit.

Returns
  • the property manager

public abstract String getRealName ()

Retrieve the optional real unit name.

Returns
  • potentially null

public abstract String getStatus ()

Get the status for the unit. Plugins should set a status if processing failed. Implementors must notify their listeners by issuing a UnitStatusChanged event.

Returns
  • a status string, used by clients to inform users about the status of this unit. null signifies that the unit is in an OK or unknown state

public abstract long getUid ()

Retrieve an identifier that uniquely identifies the unit within its project.

Returns
  • a strictly positive long integer

public abstract IUnitProcessor getUnitProcessor ()

Retrieve the unit processor used by this unit.

Returns
  • the processor

public abstract void initializePropertyObjects (IUnitCreator parent, IUnitProcessor processor, IPropertyDefinitionManager pdm)

Initialize the property manager and property definition manager used by this unit.

Code that needs access to the unit's property manager right after deserialization can safely do so after execution of this method.

Parameters
parent the parent unit or artifact
processor the processor
pdm the property definition manager for units of this type

public abstract boolean isDisposed ()

Indicate if the unit has been disposed

Returns
  • disposal status
See Also

public abstract boolean isProcessed ()

Verify if the unit was successfully processed.

Returns
  • true if the unit was successfully processed

public abstract boolean isStale ()

Determine whether the unit was successfully processed, but is now considered to be stale (outdated content). Re-processing is encouraged but not mandatory.

The result is irrelevant if isProcessed() is false.

Returns
  • whether the unit stale; this method should return false if isProcessed() returns false

public abstract boolean isTransientChild (IUnit unit)

Check if a child unit is transient. By default, children units are persisted.

Parameters
unit the child unit
Returns
  • true if the child is non-persisted

public abstract void notifyGenericChange ()

Notify all listeners of a generic change, i.e. the contents of this unit was modified, listeners and controllers should refresh the views representing this unit.

public abstract void postDeserialization (IRuntimeProject prj)

This method is called by the engines after a unit has been fully deserialized. Final repairs (eg, retrieving and re-connecting global objects that were not serialized) may be done by this method. The unit's project and engines are now accessible.

Parameters
prj the project to which this unit belongs

public abstract boolean process ()

Process the unit. Processing almost always involves parsing, eg, for a code disassembler unit, processing could mean disassembling machine code. This method is called by the unit producer, typically, those are:

  • a unit identifier who successfully identified input data, and who was later called by a processor
  • a parent unit doing the identification itself, and calling a child unit process() directly

Returns
  • true if processing is or was successful (in the latter case, process() should do nothing but return true), or false is processing failed. The unit should also notify clients by issuing a UnitProcessed event. If processing succeeded, subsequent calls to isProcessed() should return true.

public abstract void removeChild (IUnit unit)

Remove a direct child of the current unit.

Parameters
unit the unit removed

public abstract void setName (String name)

Set the unit name.

Parameters
name the unit name

public abstract void setNotes (String notes)

Set user-defined notes. The notes can be textual data of any sort.

Parameters
notes the notes

public abstract void setParent (IUnitCreator parent)

Set the parent unit or artifact.

Parameters
parent the parent

public abstract void setRealName (String name)

Set the optional unit's real name.

public abstract void setUnitProcessor (IUnitProcessor processor)

Set the unit processor. This method is called by the managing project or (engines) context.

Parameters
processor the unit processor