public class

WrapperUnit

extends Object
implements IUnit IWrap<T>
java.lang.Object
   ↳ com.pnfsoftware.jeb.core.units.impl.WrapperUnit<T extends com.pnfsoftware.jeb.core.units.IUnit>
Known Direct Subclasses

Class Overview

Simple wrapper (decorator) unit that delegates its job to the provided IUnit. This decorator allows the additions of output documents as well as a customization of the unit's format type using the IUnitProvider. For other changes in the IUnit, it is required to extend this class.

Summary

Public Constructors
WrapperUnit(T unit, IUnitProvider provider)
Public Methods
void addChild(IUnit unit, boolean persisted)
Add a child unit to this unit.
void addChild(IUnit unit)
Register a child unit to this unit.
void addChildUnit(IUnit unit)
Deprecated.
void addListener(IEventListener listener)
Register a listener.
boolean canBePersisted()
Determine if this unit can be persisted.
void clearAllData(Object key)
Remove all pieces of custom unit data.
int countListeners()
Get the numbers of objects listening to this event source.
void dispose()
Dispose of the resources used by this unit.
IQuickStateObject generateQuickState()
Save the state of this unit (it may be a partial state).
Map<Object, Object> getAllData()
Retrieve a map containing all key-value pairs of of custom unit data.
List<? extends IUnit> getChildren()
Retrieve a read-only list of all direct children units.
List<IUnitContribution> getContributions()
Get the list of contributions attached to the unit.
long getCreationTimestamp()
Get the date of creation of this unit.
Object getData(Object key)
Retrieve a piece of custom unit data.
String getDescription()
Get a description string for that unit.
String getFormatType()
Mandatory unit type.
IUnitFormatter getFormatter()
Retrieve a fresh formatter for that unit.
byte[] getIconData()
The icon bytes representing units of such type.
List<IUnitInterpreter> getInterpreters()
Get the list of command interpreters attached to the unit.
List<? extends IEventListener> getListeners()
Get a copy of the list of listeners.
IUnitLock getLock()
Get the unit lock.
String getName()
Get the unit name.
String getNotes()
Get user-defined notes.
IUnitNotificationManager getNotificationManager()
Get a reference to the notification manager.
IUnitCreator getParent()
Retrieve the creator (or parent) of this unit.
IEventSource getParentSource()
Get the parent source.
IPropertyDefinitionManager getPropertyDefinitionManager()
Retrieve the PDM used by this unit.
IPropertyManager getPropertyManager()
Retrieve the PM used by this unit.
String getRealName()
Retrieve the optional real unit name.
String getStatus()
Get the status for the unit.
long getUid()
Retrieve an identifier that uniquely identifies the unit within its project.
IUnitProcessor getUnitProcessor()
Retrieve the unit processor used by this unit.
T getWrap()
Return the wrapped IUnit
void initializePropertyObjects(IUnitCreator parent, IUnitProcessor processor, IPropertyDefinitionManager pdm)
Initialize the property manager and property definition manager used by this unit.
void insertListener(int index, IEventListener listener)
Register a listener.
boolean isDisposed()
Indicate if the unit has been disposed
boolean isProcessed()
Verify if the unit was successfully processed.
boolean isStale()
Determine whether the unit was successfully processed, but is now considered to be stale (outdated content).
boolean isTransientChild(IUnit unit)
Check if a child unit is transient.
void notifyListeners(IEvent e)
Notify listeners that an event has occurred.
void postDeserialization(IRuntimeProject prj)
This method is called by the engines after a unit has been fully deserialized.
boolean process()
Process the unit.
void removeChild(IUnit unit)
Remove a direct child of the current unit.
void removeListener(IEventListener listener)
Unregister a listener.
void setData(Object key, Object value, boolean persist)
Store a piece of custom unit data.
void setName(String name)
Set the unit name.
void setNotes(String notes)
Set user-defined notes.
void setParent(IUnitCreator parent)
Set the parent unit or artifact.
void setParentSource(IEventSource parentSource)
Set a parent source.
void setRealName(String name)
Set the optional unit's real name.
void setUnitProcessor(IUnitProcessor unitProcessor)
Set the unit processor.
[Expand]
Inherited Methods
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.IUnit
From interface com.pnfsoftware.jeb.corei.IWrap
From interface com.pnfsoftware.jeb.util.events.IEventSource

Public Constructors

public WrapperUnit (T unit, IUnitProvider provider)

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

Public Methods

public 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 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 void addChildUnit (IUnit unit)

Deprecated. Please use addChild(IUnit) instead.

Parameters
unit the child unit

public void addListener (IEventListener listener)

Register a listener. The listener is appended to the existing list of listeners. The implementor may allow duplicates.

Parameters
listener a listener of events generated by this source

public 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 void clearAllData (Object key)

Remove all pieces of custom unit data.

public int countListeners ()

Get the numbers of objects listening to this event source.

Returns
  • the number of listeners

public void dispose ()

Dispose of the resources used by this unit.

public 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 Map<Object, Object> getAllData ()

Retrieve a map containing all key-value pairs of of custom unit data.

Returns
  • a map

public List<? extends IUnit> getChildren ()

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

Returns
  • the children or an empty list, never null

public List<IUnitContribution> getContributions ()

Get the list of contributions attached to the unit.

public long getCreationTimestamp ()

Get the date of creation of this unit.

Returns
  • the creation timestamp in milliseconds since the unix epoch

public Object getData (Object key)

Retrieve a piece of custom unit data.

Parameters
key non-null key
Returns
  • value (null may indicate that the key-value pair is not present or that the stored value is null)

public String getDescription ()

Get a description string for that unit.

The unit must be processed before calling this method.

Returns
  • a description string

public 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 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 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 List<IUnitInterpreter> getInterpreters ()

Get the list of command interpreters attached to the unit.

Returns
  • the interpreter, null if none

public List<? extends IEventListener> getListeners ()

Get a copy of the list of listeners.

public IUnitLock getLock ()

Get the unit lock.

public String getName ()

Get the unit name.

Returns
  • the unit name

public String getNotes ()

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

Returns
  • the notes

public IUnitNotificationManager getNotificationManager ()

Get a reference to the notification manager.

Returns
  • the notification manager, never null

public 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 IEventSource getParentSource ()

Get the parent source.

Returns
  • the parent source, or null if none

public 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 IPropertyManager getPropertyManager ()

Retrieve the PM used by this unit.

Returns
  • the property manager

public String getRealName ()

Retrieve the optional real unit name.

Returns
  • potentially null

public 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 long getUid ()

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

Returns
  • a strictly positive long integer

public IUnitProcessor getUnitProcessor ()

Retrieve the unit processor used by this unit.

Returns
  • the processor

public T getWrap ()

Return the wrapped IUnit

Returns

public 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 void insertListener (int index, IEventListener listener)

Register a listener. The implementor may allow duplicates.

Parameters
index insertion point
listener a listener of events generated by this source

public boolean isDisposed ()

Indicate if the unit has been disposed

Returns
  • disposal status

public boolean isProcessed ()

Verify if the unit was successfully processed.

Returns
  • true if the unit was successfully processed

public 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 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 void notifyListeners (IEvent e)

Notify listeners that an event has occurred.

Parameters
e the event to be propagated

public 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 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 void removeChild (IUnit unit)

Remove a direct child of the current unit.

Parameters
unit the unit removed

public void removeListener (IEventListener listener)

Unregister a listener. If the implementor allows duplicates in addListener(), it should deal with those consistently.

Parameters
listener the listener to be removed

public void setData (Object key, Object value, boolean persist)

Store a piece of custom unit data.

Parameters
key non-null key
value optional value (may be null)
persist if false, the piece of data is transient and will not be persisted to disk when saving the project to a JEB database; if true, the piece of data will be persisted, in which case, user of this method must ensure that both key and value are serializable; if unsure, it is recommended to either not persist the data, or if persistence is a requirement, use only key/value types that are guaranteed to be persisted, such as any basic types (String, boxed primitive types, primitive types, arrays or lists of those, etc.)

public void setName (String name)

Set the unit name.

Parameters
name the unit name

public void setNotes (String notes)

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

Parameters
notes the notes

public void setParent (IUnitCreator parent)

Set the parent unit or artifact.

Parameters
parent the parent

public void setParentSource (IEventSource parentSource)

Set a parent source.

Parameters
parentSource the optional parent source

public void setRealName (String name)

Set the optional unit's real name.

public void setUnitProcessor (IUnitProcessor unitProcessor)

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

Parameters
unitProcessor the unit processor