public abstract class

AbstractUnit

extends JebEventSource
implements IUnit
java.lang.Object
   ↳ com.pnfsoftware.jeb.core.events.JebEventSource
     ↳ com.pnfsoftware.jeb.core.units.AbstractUnit
Known Direct Subclasses
Known Indirect Subclasses

Class Overview

Skeleton implementation for an IUnit. It is highly recommended that plugins extend this class or one of the its subclasses instead of implementing IUnit entirely.

Implementors must implement their own constructor; the default constructor is used for deserialization only. Example of a typical unit constructor: 

 public DerivedClass(String name, IUnitProcessor unitProcessor, IUnitCreator parent,
         IPropertyDefinitionManager pdm) {
     super(..., name, unitProcessor, parent, pdm);
     ...
 }

Notes on persistence:

  • By default, canBePersisted() returns true.
  • This class persist the non-transient children units only.
  • The formatter allows storing of persisted and transient presentation. Refer to IUnitFormatter for more information.
  • Derived classes that wish to implement custom persistence should implement a custom serialization methods.

Summary

[Expand]
Inherited Fields
From class com.pnfsoftware.jeb.core.events.JebEventSource
Public Constructors
AbstractUnit(String formatType, String name, IUnit parent)
Build a new child from parent IUnit
AbstractUnit(String formatType, String name, IUnitProcessor unitProcessor, IUnitCreator parent, IPropertyDefinitionManager pdm)
Initialize a new unit object.
Public Methods
void addChild(IUnit unit, boolean persisted)
Sub-classes overriding this method must override related methods consistently.
void addChild(IUnit unit)
Sub-classes overriding this method must override related methods consistently.
void addChildUnit(IUnit unit)
Sub-classes overriding this method must override related methods consistently.
final void addNotification(IUnitNotification notification)
boolean canBePersisted()
Determine if this unit can be persisted.
void clearAllData(Object key)
Remove all pieces of custom unit data.
void dispose()
Sub-classes overriding this method must call the super implementation last.
IQuickStateObject generateQuickState()
The default implementation returns null.
Map<Object, Object> getAllData()
Retrieve a map containing all key-value pairs of of custom unit data.
List<? extends IUnit> getChildren()
Sub-classes overriding this method must override related methods consistently.
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.
IUnitLock getLock()
The default implementation returns a pass-through lock that never locks.
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.
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.
boolean hasChildren()
void initializePropertyObjects(IUnitCreator parent, IUnitProcessor processor, IPropertyDefinitionManager pdm)
Overrides are allowed.
synchronized void internalSwapChildren()
RESERVED FOR INTERNAL USE.
boolean isDeserialized()
final boolean isDisposed()
Indicate if the unit has been disposed
boolean isProcessed()
Verify if the unit was successfully processed.
boolean isStale()
The default implementation returns false.
boolean isTransientChild(IUnit unit)
Sub-classes overriding this method must override related methods consistently.
void logError(boolean recordNotification, String format, Object... params)
Log an error message using the current class logger, and optionally create a persistent unit notification as well.
void logException(Exception e)
Log an exception using the current class logger.
void logInfo(boolean recordNotification, String format, Object... params)
Log an information message using the current class logger, and optionally create a persistent unit notification as well.
void logTrace(String format, Object... params)
Log a trace message using the current class logger.
void logWarn(boolean recordNotification, String format, Object... params)
Log a warning message using the current class logger, and optionally create a persistent unit notification as well.
void onPropertyChange(String fqPropertyName)
This method is called when a project property is changed.
void postDeserialization(IRuntimeProject prj)
To be overridden by subclasses if necessary.
boolean process()
The default implementation calls processInternal(), and makes sure that a status string is set on error, or nullified on success.
final void removeChild(IUnit unit)
Sub-classes overriding this method must override related methods consistently.
boolean setChild(IUnit oldUnit, IUnit newUnit)
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 setProcessed(boolean processed, boolean notify)
Mark the unit as processed and, if processed, optionally notify clients by issuing a UnitChange event.
final void setProcessed(boolean processed)
Mark the unit as processed and, if processed, notify the client.
void setRealName(String name)
Set the optional unit's real name.
void setStatus(String status, boolean notify)
final void setStatus(String status)
Set the plugin status.
void setUnitProcessor(IUnitProcessor processor)
Set the unit processor.
String toString()
Protected Methods
void addChild(IUnit unit, boolean persisted, boolean notify)
void finalize()
boolean processInternal()
Plugins may override this method instead of the traditional process().
void removeChild(IUnit unit, boolean notify)
boolean setChild(IUnit oldUnit, IUnit newUnit, boolean notify)
[Expand]
Inherited Methods
From class com.pnfsoftware.jeb.core.events.JebEventSource
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.util.events.IEventSource

Public Constructors

public AbstractUnit (String formatType, String name, IUnit parent)

Build a new child from parent IUnit

Parameters
formatType the mandatory format type, normally one provided by the identifier
name the unit name
parent the parent unit

public AbstractUnit (String formatType, String name, IUnitProcessor unitProcessor, IUnitCreator parent, IPropertyDefinitionManager pdm)

Initialize a new unit object.

The PDM is provided by the IUnitIdentifier (if created from there). Else, it can be provided manually by the caller. If pdm is null, an unattached PDM will be created with no property and a region name matching the unit formatType.

Parameters
formatType the mandatory format type, normally one provided by the identifier
name the unit name
unitProcessor the unit processor
parent the parent unit or artifact; if null, this unit cannot be attached to a project; practically, this field should never be null
pdm optional an optional property definition manager

Public Methods

public void addChild (IUnit unit, boolean persisted)

Sub-classes overriding this method must override related methods consistently.

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

public void addChild (IUnit unit)

Sub-classes overriding this method must override related methods consistently.

Parameters
unit the child unit

public void addChildUnit (IUnit unit)

Sub-classes overriding this method must override related methods consistently.

Parameters
unit the child unit

public final void addNotification (IUnitNotification notification)

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 void dispose ()

Sub-classes overriding this method must call the super implementation last.

public IQuickStateObject generateQuickState ()

The default implementation returns null.

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

Sub-classes overriding this method must override related methods consistently.

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 IUnitLock getLock ()

The default implementation returns a pass-through lock that never locks.

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 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 boolean hasChildren ()

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

Overrides are allowed. If so, super.initializePropertyObjects() must be called first.

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

public synchronized void internalSwapChildren ()

RESERVED FOR INTERNAL USE.

public boolean isDeserialized ()

public final 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 ()

The default implementation returns false.

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

public boolean isTransientChild (IUnit unit)

Sub-classes overriding this method must override related methods consistently.

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

public void logError (boolean recordNotification, String format, Object... params)

Log an error message using the current class logger, and optionally create a persistent unit notification as well.

public void logException (Exception e)

Log an exception using the current class logger.

public void logInfo (boolean recordNotification, String format, Object... params)

Log an information message using the current class logger, and optionally create a persistent unit notification as well.

public void logTrace (String format, Object... params)

Log a trace message using the current class logger.

public void logWarn (boolean recordNotification, String format, Object... params)

Log a warning message using the current class logger, and optionally create a persistent unit notification as well.

public void onPropertyChange (String fqPropertyName)

This method is called when a project property is changed. The default implementation does nothing: Implementors may safely override. Note that project-wide properties are being tracked, not solely those defined by the current unit's identifier.

public void postDeserialization (IRuntimeProject prj)

To be overridden by subclasses if necessary. The default implementation does nothing.

Parameters
prj the project to which this unit belongs

public boolean process ()

The default implementation calls processInternal(), and makes sure that a status string is set on error, or nullified on success. processInternal() is never called is isProcessed() returns true.

Plugins may decide to override this method, if they need finer control over processing (we recommend overriding processInternal(); in that case, processInternal() should be ignored.

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

Sub-classes overriding this method must override related methods consistently.

Parameters
unit the unit removed

public boolean setChild (IUnit oldUnit, IUnit newUnit)

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 setProcessed (boolean processed, boolean notify)

Mark the unit as processed and, if processed, optionally notify clients by issuing a UnitChange event. Implementors wishing to override this method must also override isProcessed().

public final void setProcessed (boolean processed)

Mark the unit as processed and, if processed, notify the client. Same as setProcessed(processed, true).

public void setRealName (String name)

Set the optional unit's real name.

public void setStatus (String status, boolean notify)

public final void setStatus (String status)

Set the plugin status. This method also takes care of notifying listeners by issuing a UnitStatusChanged event.

Parameters
status the new status

public void setUnitProcessor (IUnitProcessor processor)

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

Parameters
processor the unit processor

public String toString ()

Protected Methods

protected void addChild (IUnit unit, boolean persisted, boolean notify)

protected void finalize ()

Throws
Throwable

protected boolean processInternal ()

Plugins may override this method instead of the traditional process(). (If this method is overridden, implementors must NOT override process().) This method is called only if isProcessed() returned false.

Returns
  • success indicator

protected void removeChild (IUnit unit, boolean notify)

protected boolean setChild (IUnit oldUnit, IUnit newUnit, boolean notify)