Package com.pnfsoftware.jeb.core.units

Class AbstractUnit

java.lang.Object
com.pnfsoftware.jeb.core.events.JebEventSource
com.pnfsoftware.jeb.core.units.AbstractUnit
All Implemented Interfaces:
IUnitCreator, IUserDataSupport, IUnit, IEventSource
Direct Known Subclasses:
AbstractBinaryUnit, AbstractInteractiveUnit, ContainerUnit
@Ser public abstract class AbstractUnit extends JebEventSource implements IUnit
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.

  • Constructor Details

    • AbstractUnit

      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

    • AbstractUnit

      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 desired unit name; if null or blank, a name will be auto-generated; slashes and back-slashes will be replaced by underscores; leading and trailing WSP characters will be removed
      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

  • Method Details

    • initializePropertyObjects

      public void initializePropertyObjects(IUnitCreator parent, IUnitProcessor processor, IPropertyDefinitionManager pdm)
      Overrides are allowed. If so, super.initializePropertyObjects() must be called first.
      Specified by:
      initializePropertyObjects in interface IUnit
      Parameters:
      parent - the parent unit or artifact
      processor - the processor
      pdm - the property definition manager for units of this type

    • postDeserialization

      public void postDeserialization(IRuntimeProject prj)
      To be overridden by subclasses if necessary. The default implementation does nothing.
      Specified by:
      postDeserialization in interface IUnit
      Parameters:
      prj - the project to which this unit belongs

    • onPropertyChange

      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.

    • getPropertyDefinitionManager

      public IPropertyDefinitionManager getPropertyDefinitionManager()
      Description copied from interface: IUnit
      Retrieve the PDM used by this unit. For consistency, it is recommend that all units of a given type return equivalent PDMs.
      Specified by:
      getPropertyDefinitionManager in interface IUnit
      Returns:
      the property definition manager

    • getPropertyManager

      public IPropertyManager getPropertyManager()
      Description copied from interface: IUnit
      Retrieve the PM used by this unit.
      Specified by:
      getPropertyManager in interface IUnit
      Returns:
      the property manager

    • getUid

      public long getUid()
      Description copied from interface: IUnit
      Retrieve an identifier that uniquely identifies the unit within its project.
      Specified by:
      getUid in interface IUnit
      Returns:
      a strictly positive long integer

    • getFormatType

      public String getFormatType()
      Description copied from interface: IUnit
      Mandatory unit type. The type should be unique across all units. It should be the same as the identifier's type.
      Specified by:
      getFormatType in interface IUnit
      Returns:
      the non-null unit type

    • getIconData

      public byte[] getIconData()
      Description copied from interface: IUnit
      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.
      Specified by:
      getIconData in interface IUnit
      Returns:
      the BMP or PNG bytes of an icon

    • setUnitProcessor

      public void setUnitProcessor(IUnitProcessor processor)
      Description copied from interface: IUnit
      Set the unit processor. This method is called by the managing project or (engines) context.
      Specified by:
      setUnitProcessor in interface IUnit
      Parameters:
      processor - the unit processor

    • getUnitProcessor

      public IUnitProcessor getUnitProcessor()
      Description copied from interface: IUnit
      Retrieve the unit processor used by this unit.
      Specified by:
      getUnitProcessor in interface IUnit
      Returns:
      the processor

    • getCreationTimestamp

      public long getCreationTimestamp()
      Description copied from interface: IUnit
      Get the date of creation of this unit.
      Specified by:
      getCreationTimestamp in interface IUnit
      Returns:
      the creation timestamp in milliseconds since the unix epoch

    • getName

      public String getName()
      Description copied from interface: IUnit
      Get the unit name.
      Specified by:
      getName in interface IUnit
      Specified by:
      getName in interface IUnitCreator
      Returns:
      the unit name

    • setName

      public void setName(String newName)
      Description copied from interface: IUnit
      Set the unit name.
      Specified by:
      setName in interface IUnit
      Parameters:
      newName - the desired new name; if null or blank, a name will be auto-generated; slashes and back-slashes will be replaced by underscores; leading and trailing WSP characters will be removed

    • getRealName

      public String getRealName()
      Description copied from interface: IUnit
      Retrieve the optional real unit name.
      Specified by:
      getRealName in interface IUnit
      Returns:
      potentially null

    • setRealName

      public void setRealName(String name)
      Description copied from interface: IUnit
      Set the optional unit's real name.
      Specified by:
      setRealName in interface IUnit

    • getNotes

      public String getNotes()
      Description copied from interface: IUnit
      Get user-defined notes. The notes can be textual data of any sort.
      Specified by:
      getNotes in interface IUnit
      Returns:
      the notes

    • setNotes

      public void setNotes(String notes)
      Description copied from interface: IUnit
      Set user-defined notes. The notes can be textual data of any sort.
      Specified by:
      setNotes in interface IUnit
      Parameters:
      notes - the notes

    • setParent

      public void setParent(IUnitCreator parent)
      Description copied from interface: IUnit
      Set the parent unit or artifact.
      Specified by:
      setParent in interface IUnit
      Parameters:
      parent - the parent

    • getParent

      public IUnitCreator getParent()
      Description copied from interface: IUnit
      Retrieve the creator (or parent) of this unit. It can be a parent IUnit or an IArtifact, for top-level units.
      Specified by:
      getParent in interface IUnit
      Specified by:
      getParent in interface IUnitCreator
      Returns:
      the parent

    • getStatus

      public String getStatus()
      Description copied from interface: IUnit
      Get the status for the unit. Plugins should set a status if processing failed. Implementors must notify their listeners by issuing a J.UnitStatusChanged event.
      Specified by:
      getStatus in interface IUnit
      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

    • setStatus

      public final void setStatus(String status)
      Set the plugin status. This method also takes care of notifying listeners by issuing a J.UnitStatusChanged event.
      Parameters:
      status - the new status

    • setStatus

      public void setStatus(String status, boolean notify)

    • getLock

      public IUnitLock getLock()
      The default implementation returns a pass-through lock that never locks.
      Specified by:
      getLock in interface IUnit
      Returns:

    • isProcessed

      public boolean isProcessed()
      Description copied from interface: IUnit
      Verify if the unit was successfully processed.
      Specified by:
      isProcessed in interface IUnit
      Returns:
      true if the unit was successfully processed

    • isStale

      public boolean isStale()
      The default implementation returns false.
      Specified by:
      isStale in interface IUnit
      Returns:
      whether the unit stale; this method should return false if IUnit.isProcessed() returns false

    • setProcessed

      public final void setProcessed(boolean processed)
      Mark the unit as processed and, if processed, notify the client. Same as setProcessed(processed, true).
      Parameters:
      processed -

    • setProcessed

      public void setProcessed(boolean processed, boolean notify)
      Mark the unit as processed and, if processed, optionally notify clients by issuing a J.UnitChange event. Implementors wishing to override this method must also override isProcessed().
      Parameters:
      processed -

    • process

      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.

      Specified by:
      process in interface IUnit
      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 J.UnitProcessed event. If processing succeeded, subsequent calls to IUnit.isProcessed() should return true.

    • processInternal

      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

    • getDescription

      public String getDescription()
      Description copied from interface: IUnit
      Get a description string for that unit.

      The unit must be processed before calling this method.

      Specified by:
      getDescription in interface IUnit
      Returns:
      a description string

    • canBePersisted

      public boolean canBePersisted()
      Description copied from interface: IUnit
      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.
      Specified by:
      canBePersisted in interface IUnit
      Returns:
      true if the unit can be persisted, false if the unit must not be persisted

    • hasChildren

      public boolean hasChildren()

    • getChildren

      public List<? extends IUnit> getChildren()
      Sub-classes overriding this method must override related methods consistently.
      Specified by:
      getChildren in interface IUnit
      Returns:
      the children or an empty list, never null

    • addChild

      public void addChild(IUnit unit)
      Sub-classes overriding this method must override related methods consistently.
      Specified by:
      addChild in interface IUnit
      Parameters:
      unit - the child unit

    • addChild

      public void addChild(IUnit unit, boolean persisted)
      Sub-classes overriding this method must override related methods consistently.
      Specified by:
      addChild in interface IUnit
      Parameters:
      unit - the child unit
      persisted - true if the unit should be persisted upon project saving

    • addChild

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

    • isTransientChild

      public boolean isTransientChild(IUnit unit)
      Sub-classes overriding this method must override related methods consistently.
      Specified by:
      isTransientChild in interface IUnit
      Parameters:
      unit - the child unit
      Returns:
      true if the child is non-persisted

    • internalSwapChildren

      public void internalSwapChildren()
      RESERVED FOR INTERNAL USE.

    • dispose

      public void dispose()
      Sub-classes overriding this method must call the super implementation last.
      Specified by:
      dispose in interface IUnit

    • isDisposed

      public final boolean isDisposed()
      Description copied from interface: IUnit
      Indicate if the unit has been disposed
      Specified by:
      isDisposed in interface IUnit
      Returns:
      disposal status
      See Also:

    • isDeserialized

      public boolean isDeserialized()

    • removeChild

      public final void removeChild(IUnit unit)
      Sub-classes overriding this method must override related methods consistently.
      Specified by:
      removeChild in interface IUnit
      Parameters:
      unit - the unit removed

    • removeChild

      protected void removeChild(IUnit unit, boolean notify)

    • setChild

      public boolean setChild(IUnit oldUnit, IUnit newUnit)

    • setChild

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

    • getFormatter

      public IUnitFormatter getFormatter()
      Description copied from interface: IUnit
      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.

      Specified by:
      getFormatter in interface IUnit
      Returns:
      a new formatter, never null

    • getNotificationManager

      public IUnitNotificationManager getNotificationManager()
      Description copied from interface: IUnit
      Get a reference to the notification manager.
      Specified by:
      getNotificationManager in interface IUnit
      Returns:
      the notification manager, never null

    • addNotification

      public final void addNotification(IUnitNotification notification)

    • getContributions

      public List<IUnitContribution> getContributions()
      Description copied from interface: IUnit
      Get the list of contributions attached to the unit.
      Specified by:
      getContributions in interface IUnit
      Returns:

    • getInterpreters

      public List<IUnitInterpreter> getInterpreters()
      Description copied from interface: IUnit
      Get the list of command interpreters attached to the unit.
      Specified by:
      getInterpreters in interface IUnit
      Returns:
      the interpreter, null if none

    • generateQuickState

      public IQuickStateObject generateQuickState()
      The default implementation returns null.
      Specified by:
      generateQuickState in interface IUnit
      Returns:
      a state object or null if unsupported

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • logTrace

      public void logTrace(String format, Object... params)
      Log a trace message using the current class logger.
      Parameters:
      format -
      params -

    • logInfo

      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.
      Parameters:
      recordNotification -
      format -
      params -

    • logWarn

      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.
      Parameters:
      recordNotification -
      format -
      params -

    • logError

      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.
      Parameters:
      recordNotification -
      format -
      params -

    • logException

      public void logException(Exception e)
      Log an exception using the current class logger.
      Parameters:
      e -

    • setData

      public void setData(Object key, Object value, boolean persist)
      Description copied from interface: IUserDataSupport
      Store a piece of custom unit data.
      Specified by:
      setData in interface IUserDataSupport
      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.)

    • getData

      public Object getData(Object key)
      Description copied from interface: IUserDataSupport
      Retrieve a piece of custom unit data.
      Specified by:
      getData in interface IUserDataSupport
      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)

    • clearAllData

      public void clearAllData(Object key)
      Description copied from interface: IUserDataSupport
      Remove all pieces of custom unit data.
      Specified by:
      clearAllData in interface IUserDataSupport

    • getAllData

      public Map<Object,Object> getAllData()
      Description copied from interface: IUserDataSupport
      Retrieve a map containing all key-value pairs of of custom unit data.
      Specified by:
      getAllData in interface IUserDataSupport
      Returns:
      a map

    • finalize

      protected void finalize() throws Throwable
      Overrides:
      finalize in class Object
      Throws:
      Throwable