Interface IUnit
- All Superinterfaces:
IEventSource
,IUnitCreator
,IUserDataSupport
- All Known Subinterfaces:
IAddressableUnit
,IApkUnit
,IArchiveUnit
,IBinaryUnit
,ICertificateUnit
,ICodeObjectUnit
,ICodeUnit
,IDalvikDebuggerUnit
,IDartAotUnit
,IDebuggerUnit
,IDecompilerUnit
,IDexDecompilerUnit
,IDexUnit
,IDuplicatedUnit
,IELFUnit
,IInteractiveUnit
,IJavaSourceUnit
,IJsonUnit
,INativeCodeUnit<InsnType>
,INativeDebuggerUnit
,INativeDecompilerUnit<InsnType>
,INativeSourceUnit
,IPECOFFUnit
,IS7Unit
,ISourceUnit
,IXApkUnit
,IXmlUnit
- All Known Implementing Classes:
AbstractBinaryUnit
,AbstractCodeObjectUnit
,AbstractCodeUnit
,AbstractInteractiveBinaryUnit
,AbstractInteractiveUnit
,AbstractUnit
,BinaryWrapperUnit
,ContainerUnit
,DataContainerUnit
,FileContainerUnit
,InteractiveWrapperUnit
,LazyDataContainerUnit
,UnknownBinaryUnit
,WrapperUnit
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.
-
Method Summary
Modifier and TypeMethodDescriptionvoid
Register a child unit to this unit.void
Add a child unit to this unit.boolean
Determine if this unit can be persisted.void
dispose()
Dispose of the resources used by this unit.Save the state of this unit (it may be a partial state).Retrieve a read-only list of all direct children units.Get the list of contributions attached to the unit.long
Get the date of creation of this unit.Get a description string for that unit.default Collection<IInput>
Get additional inputs.Retrieve a fresh formatter for that unit.Mandatory unit type.byte[]
The icon bytes representing units of such type.default IInput
getInput()
Get the primary input data for that unit, if there is some.Get the list of command interpreters attached to the unit.getLock()
Get the unit lock.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.default IArtifact
Retrieve the artifact from which this unit derive.default IRuntimeProject
Retrieve the parentproject
that owns 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.void
initializePropertyObjects
(IUnitCreator parent, IUnitProcessor processor, IPropertyDefinitionManager pdm) Initialize the property manager and property definition manager used by this unit.boolean
Indicate if the unit has been disposedboolean
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.default void
Notify all listeners of ageneric change
, i.e.void
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
Set the unit name.void
Set user-defined notes.void
setParent
(IUnitCreator parent) Set the parent unit or artifact.void
setRealName
(String name) Set the optional unit's real name.void
setUnitProcessor
(IUnitProcessor processor) Set the unit processor.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.IUserDataSupport
clearAllData, getAllData, getData, setData
-
Method Details
-
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 parentartifact
.- Specified by:
getInput
in interfaceIUnitCreator
- Returns:
- optional input object, may be null
-
getExtraInputs
Get additional inputs.- Returns:
- a collection of additional input objects (generally empty)
-
getParentProject
Retrieve the parentproject
that owns this unit.- Returns:
-
getParentArtifact
Retrieve the artifact from which this unit derive.- Returns:
-
getPropertyDefinitionManager
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
-
getPropertyManager
IPropertyManager getPropertyManager()Retrieve the PM used by this unit.- Returns:
- the property manager
-
getUid
long getUid()Retrieve an identifier that uniquely identifies the unit within itsproject
.- Returns:
- a strictly positive long integer
-
getFormatType
String getFormatType()Mandatory unit type. The type should be unique across all units. It should be the same as theidentifier
'stype
.- Returns:
- the non-null unit type
-
getIconData
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
-
getUnitProcessor
IUnitProcessor getUnitProcessor()Retrieve the unit processor used by this unit.- Returns:
- the processor
-
getCreationTimestamp
long getCreationTimestamp()Get the date of creation of this unit.- Returns:
- the creation timestamp in milliseconds since the unix epoch
-
getName
String getName()Get the unit name.- Specified by:
getName
in interfaceIUnitCreator
- Returns:
- the unit name
-
setName
Set the unit name.- Parameters:
name
- the unit name
-
getRealName
String getRealName()Retrieve the optional real unit name.- Returns:
- potentially null
-
setRealName
Set the optional unit's real name.- Parameters:
name
-
-
getNotes
String getNotes()Get user-defined notes. The notes can be textual data of any sort.- Returns:
- the notes
-
setNotes
Set user-defined notes. The notes can be textual data of any sort.- Parameters:
notes
- the notes
-
getParent
IUnitCreator getParent()Retrieve the creator (or parent) of this unit. It can be a parentIUnit
or anIArtifact
, for top-level units.- Specified by:
getParent
in interfaceIUnitCreator
- Returns:
- the parent
-
process
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
J.UnitProcessed
event. If processing succeeded, subsequent calls toisProcessed()
should return true.
-
getStatus
String getStatus()Get the status for the unit. Plugins should set a status if processing failed. Implementors must notify their listeners by issuing aJ.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
-
isProcessed
boolean isProcessed()Verify if the unit was successfully processed.- Returns:
- true if the unit was successfully processed
-
isStale
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()
isfalse
.- Returns:
- whether the unit
stale
; this method should return false ifisProcessed()
returns false
-
canBePersisted
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
-
getChildren
Retrieve a read-only list of all direct children units.- Returns:
- the children or an empty list, never null
-
addChild
Register a child unit to this unit. The child unit is persisted. Same asaddChild(child, true)
.- Parameters:
unit
- the child unit
-
addChild
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 unitpersisted
- true if the unit should be persisted upon project saving
-
isTransientChild
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
-
removeChild
Remove a direct child of the current unit.- Parameters:
unit
- the unit removed
-
dispose
void dispose()Dispose of the resources used by this unit. -
isDisposed
boolean isDisposed()Indicate if the unit has been disposed- Returns:
- disposal status
- See Also:
-
getDescription
String getDescription()Get a description string for that unit.The unit must be processed before calling this method.
- Returns:
- a description string
-
getFormatter
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
-
getNotificationManager
IUnitNotificationManager getNotificationManager()Get a reference to the notification manager.- Returns:
- the notification manager, never null
-
setUnitProcessor
Set the unit processor. This method is called by the managing project or (engines) context.- Parameters:
processor
- the unit processor
-
initializePropertyObjects
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 artifactprocessor
- the processorpdm
- the property definition manager for units of this type
-
postDeserialization
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
-
setParent
Set the parent unit or artifact.- Parameters:
parent
- the parent
-
getInterpreters
List<IUnitInterpreter> getInterpreters()Get the list of command interpreters attached to the unit.- Returns:
- the interpreter, null if none
-
getContributions
List<IUnitContribution> getContributions()Get the list of contributions attached to the unit.- Returns:
-
generateQuickState
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
-
getLock
IUnitLock getLock()Get the unit lock.- Returns:
-
notifyGenericChange
default void notifyGenericChange()Notify all listeners of ageneric change
, i.e. the contents of this unit was modified, listeners and controllers should refresh the views representing this unit.
-