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
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.
-
Field Summary
Fields inherited from class com.pnfsoftware.jeb.core.events.JebEventSource
onEventCallCount
-
Constructor Summary
ConstructorsConstructorDescriptionAbstractUnit
(String formatType, String name, IUnit parent) Build a new child from parentIUnit
AbstractUnit
(String formatType, String name, IUnitProcessor unitProcessor, IUnitCreator parent, IPropertyDefinitionManager pdm) Initialize a new unit object. -
Method Summary
Modifier and TypeMethodDescriptionvoid
Sub-classes overriding this method must override related methods consistently.void
Sub-classes overriding this method must override related methods consistently.protected void
final void
addNotification
(IUnitNotification notification) boolean
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 thesuper
implementation last.protected void
finalize()
The default implementation returns null.Retrieve a map containing all key-value pairs of of custom unit data.Sub-classes overriding this method must override related methods consistently.Get the list of contributions attached to the unit.long
Get the date of creation of this unit.Retrieve a piece of custom unit data.Get a description string for that unit.Retrieve a fresh formatter for that unit.Mandatory unit type.byte[]
The icon bytes representing units of such type.Get the list of command interpreters attached to the unit.getLock()
The default implementation returns a pass-through lock that never locks.getName()
Get the unit name.getNotes()
Get user-defined notes.Get a reference to the notification manager.Retrieve the creator (or parent) of this unit.Retrieve the PDM used by this unit.Retrieve the PM used by this unit.Retrieve the optional real unit name.Get the status for the unit.long
getUid()
Retrieve an identifier that uniquely identifies the unit within itsproject
.Retrieve the unit processor used by this unit.boolean
void
initializePropertyObjects
(IUnitCreator parent, IUnitProcessor processor, IPropertyDefinitionManager pdm) Overrides are allowed.void
RESERVED FOR INTERNAL USE.boolean
final boolean
Indicate if the unit has been disposedboolean
Verify if the unit was successfully processed.boolean
isStale()
The default implementation returnsfalse
.boolean
isTransientChild
(IUnit unit) Sub-classes overriding this method must override related methods consistently.void
Log an error message using the current class logger, and optionally create a persistent unit notification as well.void
Log an exception using the current class logger.void
Log an information message using the current class logger, and optionally create a persistent unit notification as well.void
Log a trace message using the current class logger.void
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
To be overridden by subclasses if necessary.boolean
process()
The default implementation callsprocessInternal()
, and makes sure that a status string is set on error, or nullified on success.protected boolean
Plugins may override this method instead of the traditionalprocess()
.final void
removeChild
(IUnit unit) Sub-classes overriding this method must override related methods consistently.protected void
removeChild
(IUnit unit, boolean notify) boolean
protected boolean
void
Store a piece of custom unit data.void
Set the unit name.void
Set user-defined notes.void
setParent
(IUnitCreator parent) Set the parent unit or artifact.final void
setProcessed
(boolean processed) Mark the unit as processed and, if processed, notify the client.void
setProcessed
(boolean processed, boolean notify) Mark the unit as processed and, if processed, optionally notify clients by issuing aJ.UnitChange
event.void
setRealName
(String name) Set the optional unit's real name.final void
Set the plugin status.void
void
setUnitProcessor
(IUnitProcessor processor) Set the unit processor.toString()
Methods inherited from class com.pnfsoftware.jeb.core.events.JebEventSource
addListener, countListeners, getListeners, getParentSource, insertListener, notifyListeners, notifyListeners, notifyListeners, removeListener, setParentSource
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
Methods inherited from interface com.pnfsoftware.jeb.util.events.IEventSource
addListener, countListeners, getListeners, getParentSource, insertListener, notifyListeners, removeListener, setParentSource
Methods inherited from interface com.pnfsoftware.jeb.core.units.IUnit
getExtraInputs, getInput, getParentArtifact, getParentProject, notifyGenericChange
-
Constructor Details
-
AbstractUnit
Build a new child from parentIUnit
- Parameters:
formatType
- the mandatory format type, normally one provided by the identifiername
- the unit nameparent
- 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 identifiername
- the unit nameunitProcessor
- the unit processorparent
- the parent unit or artifact; if null, this unit cannot be attached to a project; practically, this field should never be nullpdm
- 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 interfaceIUnit
- Parameters:
parent
- the parent unit or artifactprocessor
- the processorpdm
- the property definition manager for units of this type
-
postDeserialization
To be overridden by subclasses if necessary. The default implementation does nothing.- Specified by:
postDeserialization
in interfaceIUnit
- Parameters:
prj
- the project to which this unit belongs
-
onPropertyChange
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
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 interfaceIUnit
- Returns:
- the property definition manager
-
getPropertyManager
Description copied from interface:IUnit
Retrieve the PM used by this unit.- Specified by:
getPropertyManager
in interfaceIUnit
- Returns:
- the property manager
-
getUid
public long getUid()Description copied from interface:IUnit
Retrieve an identifier that uniquely identifies the unit within itsproject
. -
getFormatType
Description copied from interface:IUnit
Mandatory unit type. The type should be unique across all units. It should be the same as theidentifier
'stype
.- Specified by:
getFormatType
in interfaceIUnit
- 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 interfaceIUnit
- Returns:
- the BMP or PNG bytes of an icon
-
setUnitProcessor
Description copied from interface:IUnit
Set the unit processor. This method is called by the managing project or (engines) context.- Specified by:
setUnitProcessor
in interfaceIUnit
- Parameters:
processor
- the unit processor
-
getUnitProcessor
Description copied from interface:IUnit
Retrieve the unit processor used by this unit.- Specified by:
getUnitProcessor
in interfaceIUnit
- Returns:
- the processor
-
getCreationTimestamp
public long getCreationTimestamp()Description copied from interface:IUnit
Get the date of creation of this unit.- Specified by:
getCreationTimestamp
in interfaceIUnit
- Returns:
- the creation timestamp in milliseconds since the unix epoch
-
getName
Description copied from interface:IUnit
Get the unit name.- Specified by:
getName
in interfaceIUnit
- Specified by:
getName
in interfaceIUnitCreator
- Returns:
- the unit name
-
setName
Description copied from interface:IUnit
Set the unit name. -
getRealName
Description copied from interface:IUnit
Retrieve the optional real unit name.- Specified by:
getRealName
in interfaceIUnit
- Returns:
- potentially null
-
setRealName
Description copied from interface:IUnit
Set the optional unit's real name.- Specified by:
setRealName
in interfaceIUnit
-
getNotes
Description copied from interface:IUnit
Get user-defined notes. The notes can be textual data of any sort. -
setNotes
Description copied from interface:IUnit
Set user-defined notes. The notes can be textual data of any sort. -
setParent
Description copied from interface:IUnit
Set the parent unit or artifact. -
getParent
Description copied from interface:IUnit
Retrieve the creator (or parent) of this unit. It can be a parentIUnit
or anIArtifact
, for top-level units.- Specified by:
getParent
in interfaceIUnit
- Specified by:
getParent
in interfaceIUnitCreator
- Returns:
- the parent
-
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 aJ.UnitStatusChanged
event. -
setStatus
Set the plugin status. This method also takes care of notifying listeners by issuing aJ.UnitStatusChanged
event.- Parameters:
status
- the new status
-
setStatus
-
getLock
The default implementation returns a pass-through lock that never locks. -
isProcessed
public boolean isProcessed()Description copied from interface:IUnit
Verify if the unit was successfully processed.- Specified by:
isProcessed
in interfaceIUnit
- Returns:
- true if the unit was successfully processed
-
isStale
public boolean isStale()The default implementation returnsfalse
.- Specified by:
isStale
in interfaceIUnit
- Returns:
- whether the unit
stale
; this method should return false ifIUnit.isProcessed()
returns false
-
setProcessed
public final void setProcessed(boolean processed) Mark the unit as processed and, if processed, notify the client. Same assetProcessed(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 aJ.UnitChange
event. Implementors wishing to override this method must also overrideisProcessed()
.- Parameters:
processed
-
-
process
public boolean process()The default implementation callsprocessInternal()
, and makes sure that a status string is set on error, or nullified on success. processInternal() is never called isisProcessed()
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 interfaceIUnit
- 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 toIUnit.isProcessed()
should return true.
-
processInternal
protected boolean processInternal()Plugins may override this method instead of the traditionalprocess()
. (If this method is overridden, implementors must NOT overrideprocess()
.) This method is called only ifisProcessed()
returnedfalse
.- Returns:
- success indicator
-
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 interfaceIUnit
- 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 interfaceIUnit
- Returns:
- true if the unit can be persisted, false if the unit must not be persisted
-
hasChildren
public boolean hasChildren() -
getChildren
Sub-classes overriding this method must override related methods consistently.- Specified by:
getChildren
in interfaceIUnit
- Returns:
- the children or an empty list, never null
-
addChild
Sub-classes overriding this method must override related methods consistently. -
addChild
Sub-classes overriding this method must override related methods consistently. -
addChild
-
isTransientChild
Sub-classes overriding this method must override related methods consistently.- Specified by:
isTransientChild
in interfaceIUnit
- 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 thesuper
implementation last. -
isDisposed
public final boolean isDisposed()Description copied from interface:IUnit
Indicate if the unit has been disposed- Specified by:
isDisposed
in interfaceIUnit
- Returns:
- disposal status
- See Also:
-
isDeserialized
public boolean isDeserialized() -
removeChild
Sub-classes overriding this method must override related methods consistently.- Specified by:
removeChild
in interfaceIUnit
- Parameters:
unit
- the unit removed
-
removeChild
-
setChild
-
setChild
-
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 interfaceIUnit
- Returns:
- a new formatter, never null
-
getNotificationManager
Description copied from interface:IUnit
Get a reference to the notification manager.- Specified by:
getNotificationManager
in interfaceIUnit
- Returns:
- the notification manager, never null
-
addNotification
-
getContributions
Description copied from interface:IUnit
Get the list of contributions attached to the unit.- Specified by:
getContributions
in interfaceIUnit
- Returns:
-
getInterpreters
Description copied from interface:IUnit
Get the list of command interpreters attached to the unit.- Specified by:
getInterpreters
in interfaceIUnit
- Returns:
- the interpreter, null if none
-
generateQuickState
The default implementation returns null.- Specified by:
generateQuickState
in interfaceIUnit
- Returns:
- a state object or null if unsupported
-
toString
-
logTrace
Log a trace message using the current class logger.- Parameters:
format
-params
-
-
logInfo
Log an information message using the current class logger, and optionally create a persistent unit notification as well.- Parameters:
recordNotification
-format
-params
-
-
logWarn
Log a warning message using the current class logger, and optionally create a persistent unit notification as well.- Parameters:
recordNotification
-format
-params
-
-
logError
Log an error message using the current class logger, and optionally create a persistent unit notification as well.- Parameters:
recordNotification
-format
-params
-
-
logException
Log an exception using the current class logger.- Parameters:
e
-
-
setData
Description copied from interface:IUserDataSupport
Store a piece of custom unit data.- Specified by:
setData
in interfaceIUserDataSupport
- Parameters:
key
- non-null keyvalue
- 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 areserializable
; 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
Description copied from interface:IUserDataSupport
Retrieve a piece of custom unit data.- Specified by:
getData
in interfaceIUserDataSupport
- 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
Description copied from interface:IUserDataSupport
Remove all pieces of custom unit data.- Specified by:
clearAllData
in interfaceIUserDataSupport
-
getAllData
Description copied from interface:IUserDataSupport
Retrieve a map containing all key-value pairs of of custom unit data.- Specified by:
getAllData
in interfaceIUserDataSupport
- Returns:
- a map
-
finalize
-