# Interface: com.pnfsoftware.jeb.core.units.IUnit Base interface for `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](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](J) event. - ## Method: addChild - parameter: `unit`, type: `com.pnfsoftware.jeb.core.units.IUnit` Description: Register a child unit to this unit. The child unit is persisted. Same as [addChild\(child, true\)](#addChild(IUnit, boolean)). parameter: unit: the child unit ## Method: addChild - parameter: `unit`, type: `com.pnfsoftware.jeb.core.units.IUnit` - parameter: `persisted`, type: `boolean` Description: Add a child unit to this unit. Implementations must check for duplicate and also notify clients by emitting the right event. parameter: unit: the child unit parameter: persisted: true if the unit should be persisted upon project saving ## Method: canBePersisted - return type: `boolean` Description: 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. return: true if the unit can be persisted, false if the unit must not be persisted ## Method: dispose Description: Dispose of the resources used by this unit. ## Method: execprvfunc - parameter: `code`, type: `int` - parameter: `param`, type: `java.lang.Object` - return type: `boolean` Description: Private functions. External client code should not use this method. parameter: code: function code parameter: param: function parameter return: execution result ## Method: generateQuickState - return type: `com.pnfsoftware.jeb.core.units.IQuickStateObject` Description: Save the state of this unit \(it may be a partial state\). Implementation of this method is optional. return: a state object or null if unsupported ## Method: getChildren - return type: `java.util.List` Description: Retrieve a read\-only list of all direct children units. return: the children or an empty list, never null ## Method: getContributions - return type: `java.util.List` Description: Get the list of contributions attached to the unit. return: the contributions, null or empty if none ## Method: getCreationTimestamp - return type: `long` Description: Get the date of creation of this unit. return: the creation timestamp in milliseconds since the unix epoch ## Method: getDescription - return type: `java.lang.String` Description: Get a description string for that unit. The unit must be processed before calling this method. return: a description string ## Method: getExtraInputs - return type: `java.util.Collection` Description: Get additional inputs. return: a collection of additional input objects \(generally empty\) ## Method: getFormatType - return type: `java.lang.String` Description: Mandatory unit type. The type should be unique across all units. It should be the same as the [identifier](IUnitIdentifier)'s [type](IUnitIdentifier#getFormatType()). return: the non\-null unit type ## Method: getFormatter - return type: `com.pnfsoftware.jeb.core.output.IUnitFormatter` Description: 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. return: a new formatter, never null ## Method: getIconData - return type: `byte[]` Description: 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. return: the BMP or PNG bytes of an icon ## Method: getInput - return type: `com.pnfsoftware.jeb.core.input.IInput` Description: Get the primary input data for that unit, if there is some. Usually, for top\-level units, it will be the input of the parent [artifact](IArtifact). return: optional input object, may be null ## Method: getInterpreters - return type: `java.util.List` Description: Get the list of command interpreters attached to the unit. return: the interpreter, null if none ## Method: getLock - return type: `com.pnfsoftware.jeb.core.units.IUnitLock` Description: Get the unit lock. return: the unit lock ## Method: getName - return type: `java.lang.String` Description: Get the unit name. return: the unit name ## Method: getNotes - return type: `java.lang.String` Description: Get user\-defined notes. The notes can be textual data of any sort. return: the notes ## Method: getNotificationManager - return type: `com.pnfsoftware.jeb.core.units.IUnitNotificationManager` Description: Get a reference to the notification manager. return: the notification manager, never null ## Method: getParent - return type: `com.pnfsoftware.jeb.core.IUnitCreator` Description: Retrieve the creator \(or parent\) of this unit. It can be a parent [IUnit](IUnit) or an [IArtifact](IArtifact), for top\-level units. return: the parent ## Method: getParentArtifact - return type: `com.pnfsoftware.jeb.core.IArtifact` Description: Retrieve the artifact from which this unit derive. return: the parent artifact, or null if the unit is not attached to an artifact ## Method: getParentProject - return type: `com.pnfsoftware.jeb.core.IRuntimeProject` Description: Retrieve the parent [project](IRuntimeProject) that owns this unit. return: the parent project, or null if the unit is not attached to a project ## Method: getPropertyDefinitionManager - return type: `com.pnfsoftware.jeb.core.properties.IPropertyDefinitionManager` Description: Retrieve the PDM used by this unit. For consistency, it is recommend that all units of a given type return equivalent PDMs. return: the property definition manager ## Method: getPropertyManager - return type: `com.pnfsoftware.jeb.core.properties.IPropertyManager` Description: Retrieve the PM used by this unit. return: the property manager ## Method: getRealName - return type: `java.lang.String` Description: Retrieve the optional real unit name. return: potentially null ## Method: getStatus - return type: `java.lang.String` Description: Get the status for the unit. Plugins should set a status if processing failed. Implementors must notify their listeners by issuing a [J#UnitStatusChanged](J#UnitStatusChanged) event. return: 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 ## Method: getUid - return type: `long` Description: Retrieve an identifier that uniquely identifies the unit within its [project](IRuntimeProject). return: a strictly positive long integer ## Method: getUnitProcessor - return type: `com.pnfsoftware.jeb.core.units.IUnitProcessor` Description: Retrieve the unit processor used by this unit. return: the processor ## Method: initializePropertyObjects - parameter: `parent`, type: `com.pnfsoftware.jeb.core.IUnitCreator` - parameter: `processor`, type: `com.pnfsoftware.jeb.core.units.IUnitProcessor` - parameter: `pdm`, type: `com.pnfsoftware.jeb.core.properties.IPropertyDefinitionManager` Description: 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. parameter: parent: the parent unit or artifact parameter: processor: the processor parameter: pdm: the property definition manager for units of this type ## Method: isDisposed - return type: `boolean` Description: Indicate if the unit has been disposed see also: #dispose() return: disposal status ## Method: isProcessed - return type: `boolean` Description: Verify if the unit was successfully processed. return: true if the unit was successfully processed ## Method: isStale - return type: `boolean` Description: Determine whether the unit was successfully processed, but is now considered to be stale \(outdated content\). [Re\-processing](#process()) is encouraged but not mandatory. The result is irrelevant if [#isProcessed()](#isProcessed()) is `false`. return: whether the unit `stale`; this method should return false if [#isProcessed()](#isProcessed()) returns false ## Method: isTransientChild - parameter: `unit`, type: `com.pnfsoftware.jeb.core.units.IUnit` - return type: `boolean` Description: Check if a child unit is transient. By default, children units are persisted. parameter: unit: the child unit return: true if the child is non\-persisted ## Method: notifyGenericChange Description: Notify all listeners of a [generic change](J#UnitChange), i.e. the contents of this unit was modified, listeners and controllers should refresh the views representing this unit. ## Method: postDeserialization - parameter: `prj`, type: `com.pnfsoftware.jeb.core.IRuntimeProject` Description: 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. parameter: prj: the project to which this unit belongs ## Method: process - return type: `boolean` Description: 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 - return: 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](J#UnitProcessed) event. If processing succeeded, subsequent calls to [#isProcessed()](#isProcessed()) should return true. ## Method: removeChild - parameter: `unit`, type: `com.pnfsoftware.jeb.core.units.IUnit` Description: Remove a direct child of the current unit. parameter: unit: the unit removed ## Method: setName - parameter: `name`, type: `java.lang.String` Description: Set the unit name. parameter: name: 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 ## Method: setNotes - parameter: `notes`, type: `java.lang.String` Description: Set user\-defined notes. The notes can be textual data of any sort. parameter: notes: the notes ## Method: setParent - parameter: `parent`, type: `com.pnfsoftware.jeb.core.IUnitCreator` Description: Set the parent unit or artifact. parameter: parent: the parent ## Method: setRealName - parameter: `name`, type: `java.lang.String` Description: Set the optional unit's real name. parameter: name: optional real name ## Method: setUnitProcessor - parameter: `processor`, type: `com.pnfsoftware.jeb.core.units.IUnitProcessor` Description: Set the unit processor. This method is called by the managing project or \(engines\) context. parameter: processor: the unit processor