# Class: com.pnfsoftware.jeb.core.units.UnitUtil

Utility methods for [units](IUnit).

## Static Method: buildFullyQualifiedCandidateUnitPath
- parameter: `candidateUnitName`, type: `java.lang.String`
- parameter: `parent`, type: `com.pnfsoftware.jeb.core.IUnitCreator`
- parameter: `includeArtifact`, type: `boolean`
- parameter: `separator`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Build the fully\-qualified path of a potential unit whose only the name is provided.
parameter: candidateUnitName: candidate unit name
parameter: parent: parent unit or artifact
parameter: includeArtifact: true to include the artifact name
parameter: separator: path separator
return: fully\-qualified candidate path

## Static Method: buildFullyQualifiedUnitPath
- parameter: `unit`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `includeArtifact`, type: `boolean`
- parameter: `separator`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Build a fully\-qualified unit path.
parameter: unit: unit
parameter: includeArtifact: true to include the artifact name
parameter: separator: path separator
return: fully\-qualified unit path

## Static Method: buildFullyQualifiedUnitPath
- parameter: `unit`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- return type: `java.lang.String`

Description: Build a unit path of the artifact name and its parent units, such as:`artifact > unit > unit > ... > unit`
parameter: unit: unit
return: fully\-qualified unit path

## Static Method: buildFullyQualifiedUnitPathList
- parameter: `unit`, type: `com.pnfsoftware.jeb.core.IUnitCreator`
- parameter: `includeArtifact`, type: `boolean`
- return type: `java.util.List<java.lang.String>`

Description: Build a fully\-qualified unit path as list of unit names.
parameter: unit: unit or artifact
parameter: includeArtifact: true to include the artifact name
return: path elements

## Static Method: debuggerProperty
- parameter: `engctx`, type: `com.pnfsoftware.jeb.core.IEnginesContext`
- parameter: `codeType`, type: `java.lang.String`
- parameter: `propertyName`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Generate a fully\-qualified property name used by a [decompiler unit](IDecompilerUnit).
parameter: engctx: JEB engines context
parameter: codeType: code unit type \(not a debugger unit\)
parameter: propertyName: simple property name
return: a fully\-qualified property name, or null if the property namespace cannot be found

## Static Method: decompilerProperty
- parameter: `engctx`, type: `com.pnfsoftware.jeb.core.IEnginesContext`
- parameter: `codeType`, type: `java.lang.String`
- parameter: `propertyName`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Generate a fully\-qualified property name used by a [decompiler unit](IDecompilerUnit).
parameter: engctx: JEB engines context
parameter: codeType: code unit type \(not a decompiler unit\)
parameter: propertyName: simple property name
return: a fully\-qualified property name, or null if the property namespace cannot be found

## Static Method: filterDescendants
- parameter: `base`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `maxDepth`, type: `int`
- parameter: `filter`, type: `com.pnfsoftware.jeb.core.IUnitFilter`
- return type: `java.util.List<com.pnfsoftware.jeb.core.units.IUnit>`

Description: Retrieve a list of descendants of the provided unit that pass the provided filter test and do not exceeded the maximum depth.
parameter: base: base unit
parameter: maxDepth: use \-1 to go as deep as possible
parameter: filter: optional unit filter
return: matching descendants

## Static Method: findAll
- parameter: `name`, type: `java.lang.String`
- parameter: `c`, type: `java.lang.Class<T>`
- parameter: `strict`, type: `boolean`
- return type: `java.util.List<T>`

Description: Retrieve matching units from all currently loaded projects.
parameter: name: optional unit name
parameter: c: optional unit type
parameter: strict: true for exact class matches
return: matching units
parameter: T: unit type

## Static Method: findAncestor
- parameter: `unit`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `c`, type: `java.lang.Class<T>`
- parameter: `strict`, type: `boolean`
- return type: `T`

Description: Find the closest ancestor of an [IUnit](IUnit) that matches a [Class](Class).
parameter: unit: a children element
parameter: c: the class to match. Can be an interface.
parameter: strict: if true, only units of the exact classtype will be returned
return: the closest ancestor that matches, or null if not found
parameter: T: ancestor type

## Static Method: findChild
- parameter: `base`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `name`, type: `java.lang.String`
- parameter: `c`, type: `java.lang.Class<T>`
- parameter: `strict`, type: `boolean`
- parameter: `index`, type: `int`
- return type: `T`

Description: Retrieve a child unit by name and type.
parameter: base: base unit
parameter: name: optional unit name
parameter: c: optional unit type
parameter: strict: true for exact class matches
parameter: index: result index
return: matching child, or null if none
parameter: T: unit type

## Static Method: findChildByFormatType
- parameter: `base`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `formatType`, type: `java.lang.String`
- parameter: `index`, type: `int`
- return type: `com.pnfsoftware.jeb.core.units.IUnit`

Description: Retrieve a child unit by format type.
parameter: base: base unit
parameter: formatType: wanted format type
parameter: index: result index
return: matching child, or null if none

## Static Method: findChildByName
- parameter: `base`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `name`, type: `java.lang.String`
- parameter: `index`, type: `int`
- return type: `com.pnfsoftware.jeb.core.units.IUnit`

Description: Retrieve a child unit by name.
parameter: base: base unit
parameter: name: wanted unit name
parameter: index: result index
return: matching child, or null if none

## Static Method: findChildByType
- parameter: `base`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `classtype`, type: `java.lang.Class<T>`
- parameter: `exactClasstype`, type: `boolean`
- parameter: `index`, type: `int`
- return type: `T`

Description: Retrieve a child unit by type.
parameter: base: base unit
parameter: classtype: wanted class type
parameter: exactClasstype: true for exact class matches
parameter: index: result index
return: matching child, or null if none
parameter: T: unit type

## Static Method: findChildren
- parameter: `base`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `name`, type: `java.lang.String`
- parameter: `c`, type: `java.lang.Class<T>`
- parameter: `strict`, type: `boolean`
- return type: `java.util.List<T>`

Description: Retrieve child units by name and type.
parameter: base: base unit
parameter: name: optional unit name
parameter: c: optional unit type
parameter: strict: true for exact class matches
return: matching children
parameter: T: unit type

## Static Method: findChildrenByFormatType
- parameter: `base`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `formatType`, type: `java.lang.String`
- return type: `java.util.List<com.pnfsoftware.jeb.core.units.IUnit>`

Description: Retrieve child units by format type.
parameter: base: base unit
parameter: formatType: wanted format type
return: matching children

## Static Method: findChildrenByName
- parameter: `base`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `name`, type: `java.lang.String`
- return type: `java.util.List<com.pnfsoftware.jeb.core.units.IUnit>`

Description: Retrieve child units by name.
parameter: base: base unit
parameter: name: wanted unit name
return: matching children

## Static Method: findChildrenByType
- parameter: `base`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `classtype`, type: `java.lang.Class<T>`
- parameter: `exactClasstype`, type: `boolean`
- return type: `java.util.List<T>`

Description: Retrieve child units by type.
parameter: base: base unit
parameter: classtype: wanted class type
parameter: exactClasstype: true for exact class matches
return: matching children
parameter: T: unit type

## Static Method: findDescendants
- parameter: `base`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `maxDepth`, type: `int`
- parameter: `name`, type: `java.lang.String`
- parameter: `classtype`, type: `java.lang.Class<T>`
- parameter: `exactClasstype`, type: `boolean`
- return type: `java.util.List<T>`

Description: Convenience function to find descendant units by type and/or name.
parameter: base: base unit
parameter: maxDepth: use \-1 to go as deep as possible
parameter: name: optional unit name
parameter: classtype: optional unit type
parameter: exactClasstype: true for exact class matches
return: matching descendants
parameter: T: unit type

## Static Method: findDescendants
- parameter: `base`, type: `com.pnfsoftware.jeb.core.ILiveArtifact`
- parameter: `level`, type: `int`
- parameter: `name`, type: `java.lang.String`
- parameter: `c`, type: `java.lang.Class<T>`
- parameter: `strict`, type: `boolean`
- return type: `java.util.List<T>`

Description: Retrieve descendant units of an artifact by name and type.
parameter: base: base artifact
parameter: level: maximum depth, or \-1 for no limit
parameter: name: optional unit name
parameter: c: optional unit type
parameter: strict: true for exact class matches
return: matching descendants
parameter: T: unit type

## Static Method: findDescendantsByFormatType
- parameter: `base`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `level`, type: `int`
- parameter: `formatType`, type: `java.lang.String`
- return type: `java.util.List<T>`

Description: Retrieve descendant units by format type.
parameter: base: base unit
parameter: level: maximum depth, or \-1 for no limit
parameter: formatType: wanted format type
return: matching descendants
parameter: T: unit type

## Static Method: findDescendantsByFormatType
- parameter: `base`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `formatType`, type: `java.lang.String`
- return type: `java.util.List<com.pnfsoftware.jeb.core.units.IUnit>`

Description: Retrieve descendant units by format type.
parameter: base: base unit
parameter: formatType: wanted format type
return: matching descendants

## Static Method: findDescendantsByName
- parameter: `base`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `maxDepth`, type: `int`
- parameter: `name`, type: `java.lang.String`
- return type: `java.util.List<com.pnfsoftware.jeb.core.units.IUnit>`

Description: Retrieve a list of descendant units of the provided unit that have the provided name.
parameter: base: base unit
parameter: maxDepth: use \-1 to go as deep as possible
parameter: name: wanted unit name
return: matching descendants

## Static Method: findDescendantsByName
- parameter: `base`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `name`, type: `java.lang.String`
- return type: `java.util.List<com.pnfsoftware.jeb.core.units.IUnit>`

Description: Retrieve descendant units by name.
parameter: base: base unit
parameter: name: wanted unit name
return: matching descendants

## Static Method: findDescendantsByType
- parameter: `base`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `maxDepth`, type: `int`
- parameter: `classtype`, type: `java.lang.Class<T>`
- parameter: `exactClasstype`, type: `boolean`
- return type: `java.util.List<T>`

Description: Retrieve a list of descendant units of the provided unit that are of the provided classtype \(exact or derived\) and do not exceeded the maximum depth.
parameter: base: base unit
parameter: maxDepth: use \-1 to go as deep as possible
parameter: classtype: wanted classtype
parameter: exactClasstype: if true, only units of the exact classtype will be returned
return: matching descendants
parameter: T: unit type

## Static Method: findDescendantsByType
- parameter: `base`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `classtype`, type: `java.lang.Class<T>`
- parameter: `exactClasstype`, type: `boolean`
- return type: `java.util.List<T>`

Description: Retrieve descendant units by type.
parameter: base: base unit
parameter: classtype: wanted class type
parameter: exactClasstype: true for exact class matches
return: matching descendants
parameter: T: unit type

## Static Method: findFirstChildByFormatType
- parameter: `base`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `formatType`, type: `java.lang.String`
- return type: `com.pnfsoftware.jeb.core.units.IUnit`

Description: Retrieve the first child unit by format type.
parameter: base: base unit
parameter: formatType: wanted format type
return: matching child, or null if none

## Static Method: findFirstChildByName
- parameter: `base`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `name`, type: `java.lang.String`
- return type: `com.pnfsoftware.jeb.core.units.IUnit`

Description: Retrieve the first child unit by name.
parameter: base: base unit
parameter: name: wanted unit name
return: matching child, or null if none

## Static Method: findFirstChildByType
- parameter: `base`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `classtype`, type: `java.lang.Class<T>`
- parameter: `exactClasstype`, type: `boolean`
- return type: `T`

Description: Retrieve the first child unit by type.
parameter: base: base unit
parameter: classtype: wanted class type
parameter: exactClasstype: true for exact class matches
return: matching child, or null if none
parameter: T: unit type

## Static Method: getUnitsFromPathList
- parameter: `prj`, type: `com.pnfsoftware.jeb.core.IRuntimeProject`
- parameter: `path`, type: `java.util.List<java.lang.String>`
- return type: `java.util.List<com.pnfsoftware.jeb.core.units.IUnit>`

Description: Retrieve the targets [IUnit](IUnit) from its path \(built from [#buildFullyQualifiedUnitPathList(IUnitCreator, boolean)](#buildFullyQualifiedUnitPathList(IUnitCreator, boolean)) for example\). Note that result target will be unique in most of the cases.
parameter: prj: runtime project
parameter: path: path elements
return: matching units

## Static Method: isAncestorOf
- parameter: `unit`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `expectedAncestor`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- return type: `boolean`

Description: Determine whether a unit is a descendant of another unit.
parameter: unit: candidate descendant
parameter: expectedAncestor: expected ancestor
return: true if the ancestor relationship exists

## Static Method: isAncestorOf
- parameter: `unit`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `expectedAncestor`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `strictAncestor`, type: `boolean`
- return type: `boolean`

Description: Determine whether a unit is a descendant of another unit.
parameter: unit: candidate descendant
parameter: expectedAncestor: expected ancestor
parameter: strictAncestor: true to require a strict ancestor
return: true if the ancestor relationship exists

## Static Method: isTopLevelUnit
- parameter: `unit`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- return type: `boolean`

Description: Determine whether a unit is directly attached to an artifact.
parameter: unit: unit
return: true if the unit is top\-level

## Static Method: logError
- parameter: `unit`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `address`, type: `java.lang.String`
- parameter: `recordNotification`, type: `boolean`
- parameter: `logger`, type: `com.pnfsoftware.jeb.util.logging.ILogger`
- parameter: `format`, type: `java.lang.String`
- parameter: `params`, type: `java.lang.Object[]`

Description: Log an error and optionally record a unit notification.
parameter: unit: optional unit
parameter: address: optional unit address
parameter: recordNotification: true to record a persistent notification
parameter: logger: logger
parameter: format: message format
parameter: params: format parameters

## Static Method: logException
- parameter: `unit`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `logger`, type: `com.pnfsoftware.jeb.util.logging.ILogger`
- parameter: `e`, type: `java.lang.Exception`

Description: Log an exception and optionally record a unit notification.
parameter: unit: optional unit
parameter: logger: logger
parameter: e: exception to log

## Static Method: logI
- parameter: `unit`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `address`, type: `java.lang.String`
- parameter: `logger`, type: `com.pnfsoftware.jeb.util.logging.ILogger`
- parameter: `format`, type: `java.lang.String`
- parameter: `params`, type: `java.lang.Object[]`

Description: Log an internal message.
parameter: unit: optional unit
parameter: address: optional unit address
parameter: logger: logger
parameter: format: message format
parameter: params: format parameters

## Static Method: logInfo
- parameter: `unit`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `address`, type: `java.lang.String`
- parameter: `recordNotification`, type: `boolean`
- parameter: `logger`, type: `com.pnfsoftware.jeb.util.logging.ILogger`
- parameter: `format`, type: `java.lang.String`
- parameter: `params`, type: `java.lang.Object[]`

Description: Log an informational message and optionally record a unit notification.
parameter: unit: optional unit
parameter: address: optional unit address
parameter: recordNotification: true to record a persistent notification
parameter: logger: logger
parameter: format: message format
parameter: params: format parameters

## Static Method: logTrace
- parameter: `unit`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `address`, type: `java.lang.String`
- parameter: `logger`, type: `com.pnfsoftware.jeb.util.logging.ILogger`
- parameter: `format`, type: `java.lang.String`
- parameter: `params`, type: `java.lang.Object[]`

Description: Log a trace message.
parameter: unit: optional unit
parameter: address: optional unit address
parameter: logger: logger
parameter: format: message format
parameter: params: format parameters

## Static Method: logWarn
- parameter: `unit`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `address`, type: `java.lang.String`
- parameter: `recordNotification`, type: `boolean`
- parameter: `logger`, type: `com.pnfsoftware.jeb.util.logging.ILogger`
- parameter: `format`, type: `java.lang.String`
- parameter: `params`, type: `java.lang.Object[]`

Description: Log a warning and optionally record a unit notification.
parameter: unit: optional unit
parameter: address: optional unit address
parameter: recordNotification: true to record a persistent notification
parameter: logger: logger
parameter: format: message format
parameter: params: format parameters

## Static Method: notifyGenericChange
- parameter: `unit`, type: `com.pnfsoftware.jeb.core.units.IUnit`

Description: Issue a generic [J#UnitChange](J#UnitChange) event to all listeners of the provided unit.
parameter: unit: a unit

## Static Method: retrieve
- parameter: `base`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `pathElements`, type: `java.lang.String[]`
- return type: `com.pnfsoftware.jeb.core.units.IUnit`

Description: Retrieve a unit rooted in the provided base, and whose relative path from that base consists of the provided path elements.
parameter: base: a root unit
parameter: pathElements: 1 or more sub\-unit names
return: the unit corresponding to the last path element, null if not found \- the unit may not         have been processed

## Static Method: retrieveProcessed
- parameter: `processIfUnprocessed`, type: `boolean`
- parameter: `base`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `pathElements`, type: `java.lang.String[]`
- return type: `com.pnfsoftware.jeb.core.units.IUnit`

Description: Retrieve a unit rooted in the provided base, and whose relative path from that base consists of the provided path elements. The returned unit is guaranteed to be processed.
parameter: processIfUnprocessed: attempt to process the unit if it is unprocessed
parameter: base: root unit
parameter: pathElements: sub\-unit names
return: a unit \(processed\) or null

## Static Method: unitProperty
- parameter: `ident`, type: `com.pnfsoftware.jeb.core.units.IUnitIdentifier`
- parameter: `propertyName`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Generate a fully\-qualified property name used by a [unit](IUnit).
parameter: ident: a unit identifier
parameter: propertyName: simple property name
return: a FQ name

## Static Method: unitProperty
- parameter: `unit`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `propertyName`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Generate a fully\-qualified property name used by a [unit](IUnit).
parameter: unit: a unit
parameter: propertyName: simple property name
return: a FQ name

## Static Method: unitProperty
- parameter: `engctx`, type: `com.pnfsoftware.jeb.core.IEnginesContext`
- parameter: `unitType`, type: `java.lang.String`
- parameter: `propertyName`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Generate a fully\-qualified property name used by a [unit](IUnit).
parameter: engctx: JEB engines context
parameter: unitType: unit type
parameter: propertyName: simple property name
return: a FQ name