Package com.pnfsoftware.jeb.core.units

Class UnitUtil

java.lang.Object
com.pnfsoftware.jeb.core.units.UnitUtil
public class UnitUtil extends Object
Utility methods for units.

  • Method Details

    • notifyGenericChange

      public static void notifyGenericChange(IUnit unit)
      Issue a generic J.UnitChange event to all listeners of the provided unit.
      Parameters:
      unit - a unit

    • logI

      public static void logI(IUnit unit, String address, ILogger logger, String format, Object... params)
      Log an internal message.
      Parameters:
      unit - optional unit
      address - optional unit address
      logger - logger
      format - message format
      params - format parameters

    • logTrace

      public static void logTrace(IUnit unit, String address, ILogger logger, String format, Object... params)
      Log a trace message.
      Parameters:
      unit - optional unit
      address - optional unit address
      logger - logger
      format - message format
      params - format parameters

    • logInfo

      public static void logInfo(IUnit unit, String address, boolean recordNotification, ILogger logger, String format, Object... params)
      Log an informational message and optionally record a unit notification.
      Parameters:
      unit - optional unit
      address - optional unit address
      recordNotification - true to record a persistent notification
      logger - logger
      format - message format
      params - format parameters

    • logWarn

      public static void logWarn(IUnit unit, String address, boolean recordNotification, ILogger logger, String format, Object... params)
      Log a warning and optionally record a unit notification.
      Parameters:
      unit - optional unit
      address - optional unit address
      recordNotification - true to record a persistent notification
      logger - logger
      format - message format
      params - format parameters

    • logError

      public static void logError(IUnit unit, String address, boolean recordNotification, ILogger logger, String format, Object... params)
      Log an error and optionally record a unit notification.
      Parameters:
      unit - optional unit
      address - optional unit address
      recordNotification - true to record a persistent notification
      logger - logger
      format - message format
      params - format parameters

    • logException

      public static void logException(IUnit unit, ILogger logger, Exception e)
      Log an exception and optionally record a unit notification.
      Parameters:
      unit - optional unit
      logger - logger
      e - exception to log

    • filterDescendants

      public static List<IUnit> filterDescendants(IUnit base, int maxDepth, IUnitFilter filter)
      Retrieve a list of descendants of the provided unit that pass the provided filter test and do not exceeded the maximum depth.
      Parameters:
      base - base unit
      maxDepth - use -1 to go as deep as possible
      filter - optional unit filter
      Returns:
      matching descendants

    • findDescendantsByType

      public static <T extends IUnit> List<T> findDescendantsByType(IUnit base, int maxDepth, Class<T> classtype, boolean exactClasstype)
      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.
      Type Parameters:
      T - unit type
      Parameters:
      base - base unit
      maxDepth - use -1 to go as deep as possible
      classtype - wanted classtype
      exactClasstype - if true, only units of the exact classtype will be returned
      Returns:
      matching descendants

    • findChildrenByType

      public static <T extends IUnit> List<T> findChildrenByType(IUnit base, Class<T> classtype, boolean exactClasstype)
      Retrieve child units by type.
      Type Parameters:
      T - unit type
      Parameters:
      base - base unit
      classtype - wanted class type
      exactClasstype - true for exact class matches
      Returns:
      matching children

    • findChildByType

      public static <T extends IUnit> T findChildByType(IUnit base, Class<T> classtype, boolean exactClasstype, int index)
      Retrieve a child unit by type.
      Type Parameters:
      T - unit type
      Parameters:
      base - base unit
      classtype - wanted class type
      exactClasstype - true for exact class matches
      index - result index
      Returns:
      matching child, or null if none

    • findFirstChildByType

      public static <T extends IUnit> T findFirstChildByType(IUnit base, Class<T> classtype, boolean exactClasstype)
      Retrieve the first child unit by type.
      Type Parameters:
      T - unit type
      Parameters:
      base - base unit
      classtype - wanted class type
      exactClasstype - true for exact class matches
      Returns:
      matching child, or null if none

    • findDescendantsByType

      public static <T extends IUnit> List<T> findDescendantsByType(IUnit base, Class<T> classtype, boolean exactClasstype)
      Retrieve descendant units by type.
      Type Parameters:
      T - unit type
      Parameters:
      base - base unit
      classtype - wanted class type
      exactClasstype - true for exact class matches
      Returns:
      matching descendants

    • findDescendantsByName

      public static List<IUnit> findDescendantsByName(IUnit base, int maxDepth, String name)
      Retrieve a list of descendant units of the provided unit that have the provided name.
      Parameters:
      base - base unit
      maxDepth - use -1 to go as deep as possible
      name - wanted unit name
      Returns:
      matching descendants

    • findDescendantsByName

      public static List<IUnit> findDescendantsByName(IUnit base, String name)
      Retrieve descendant units by name.
      Parameters:
      base - base unit
      name - wanted unit name
      Returns:
      matching descendants

    • findChildrenByName

      public static List<IUnit> findChildrenByName(IUnit base, String name)
      Retrieve child units by name.
      Parameters:
      base - base unit
      name - wanted unit name
      Returns:
      matching children

    • findChildByName

      public static IUnit findChildByName(IUnit base, String name, int index)
      Retrieve a child unit by name.
      Parameters:
      base - base unit
      name - wanted unit name
      index - result index
      Returns:
      matching child, or null if none

    • findFirstChildByName

      public static IUnit findFirstChildByName(IUnit base, String name)
      Retrieve the first child unit by name.
      Parameters:
      base - base unit
      name - wanted unit name
      Returns:
      matching child, or null if none

    • retrieve

      public static IUnit retrieve(IUnit base, String... pathElements)
      Retrieve a unit rooted in the provided base, and whose relative path from that base consists of the provided path elements.
      Parameters:
      base - a root unit
      pathElements - 1 or more sub-unit names
      Returns:
      the unit corresponding to the last path element, null if not found - the unit may not have been processed

    • retrieveProcessed

      public static IUnit retrieveProcessed(boolean processIfUnprocessed, IUnit base, String... pathElements)
      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.
      Parameters:
      processIfUnprocessed - attempt to process the unit if it is unprocessed
      base - root unit
      pathElements - sub-unit names
      Returns:
      a unit (processed) or null

    • findDescendants

      public static <T extends IUnit> List<T> findDescendants(IUnit base, int maxDepth, String name, Class<T> classtype, boolean exactClasstype)
      Convenience function to find descendant units by type and/or name.
      Type Parameters:
      T - unit type
      Parameters:
      base - base unit
      maxDepth - use -1 to go as deep as possible
      name - optional unit name
      classtype - optional unit type
      exactClasstype - true for exact class matches
      Returns:
      matching descendants

    • findChildren

      public static <T extends IUnit> List<T> findChildren(IUnit base, String name, Class<T> c, boolean strict)
      Retrieve child units by name and type.
      Type Parameters:
      T - unit type
      Parameters:
      base - base unit
      name - optional unit name
      c - optional unit type
      strict - true for exact class matches
      Returns:
      matching children

    • findChild

      public static <T extends IUnit> T findChild(IUnit base, String name, Class<T> c, boolean strict, int index)
      Retrieve a child unit by name and type.
      Type Parameters:
      T - unit type
      Parameters:
      base - base unit
      name - optional unit name
      c - optional unit type
      strict - true for exact class matches
      index - result index
      Returns:
      matching child, or null if none

    • findDescendants

      public static <T extends IUnit> List<T> findDescendants(ILiveArtifact base, int level, String name, Class<T> c, boolean strict)
      Retrieve descendant units of an artifact by name and type.
      Type Parameters:
      T - unit type
      Parameters:
      base - base artifact
      level - maximum depth, or -1 for no limit
      name - optional unit name
      c - optional unit type
      strict - true for exact class matches
      Returns:
      matching descendants

    • findAll

      public static <T extends IUnit> List<T> findAll(String name, Class<T> c, boolean strict)
      Retrieve matching units from all currently loaded projects.
      Type Parameters:
      T - unit type
      Parameters:
      name - optional unit name
      c - optional unit type
      strict - true for exact class matches
      Returns:
      matching units

    • findDescendantsByFormatType

      public static <T extends IUnit> List<T> findDescendantsByFormatType(IUnit base, int level, String formatType)
      Retrieve descendant units by format type.
      Type Parameters:
      T - unit type
      Parameters:
      base - base unit
      level - maximum depth, or -1 for no limit
      formatType - wanted format type
      Returns:
      matching descendants

    • findDescendantsByFormatType

      public static List<IUnit> findDescendantsByFormatType(IUnit base, String formatType)
      Retrieve descendant units by format type.
      Parameters:
      base - base unit
      formatType - wanted format type
      Returns:
      matching descendants

    • findChildrenByFormatType

      public static List<IUnit> findChildrenByFormatType(IUnit base, String formatType)
      Retrieve child units by format type.
      Parameters:
      base - base unit
      formatType - wanted format type
      Returns:
      matching children

    • findChildByFormatType

      public static IUnit findChildByFormatType(IUnit base, String formatType, int index)
      Retrieve a child unit by format type.
      Parameters:
      base - base unit
      formatType - wanted format type
      index - result index
      Returns:
      matching child, or null if none

    • findFirstChildByFormatType

      public static IUnit findFirstChildByFormatType(IUnit base, String formatType)
      Retrieve the first child unit by format type.
      Parameters:
      base - base unit
      formatType - wanted format type
      Returns:
      matching child, or null if none

    • findAncestor

      public static <T extends IUnitCreator> T findAncestor(IUnit unit, Class<T> c, boolean strict)
      Find the closest ancestor of an IUnit that matches a Class.
      Type Parameters:
      T - ancestor type
      Parameters:
      unit - a children element
      c - the class to match. Can be an interface.
      strict - if true, only units of the exact classtype will be returned
      Returns:
      the closest ancestor that matches, or null if not found

    • isAncestorOf

      public static boolean isAncestorOf(IUnit unit, IUnit expectedAncestor)
      Determine whether a unit is a descendant of another unit.
      Parameters:
      unit - candidate descendant
      expectedAncestor - expected ancestor
      Returns:
      true if the ancestor relationship exists

    • isAncestorOf

      public static boolean isAncestorOf(IUnit unit, IUnit expectedAncestor, boolean strictAncestor)
      Determine whether a unit is a descendant of another unit.
      Parameters:
      unit - candidate descendant
      expectedAncestor - expected ancestor
      strictAncestor - true to require a strict ancestor
      Returns:
      true if the ancestor relationship exists

    • buildFullyQualifiedCandidateUnitPath

      public static String buildFullyQualifiedCandidateUnitPath(String candidateUnitName, IUnitCreator parent, boolean includeArtifact, String separator)
      Build the fully-qualified path of a potential unit whose only the name is provided.
      Parameters:
      candidateUnitName - candidate unit name
      parent - parent unit or artifact
      includeArtifact - true to include the artifact name
      separator - path separator
      Returns:
      fully-qualified candidate path

    • buildFullyQualifiedUnitPath

      public static String buildFullyQualifiedUnitPath(IUnit unit, boolean includeArtifact, String separator)
      Build a fully-qualified unit path.
      Parameters:
      unit - unit
      includeArtifact - true to include the artifact name
      separator - path separator
      Returns:
      fully-qualified unit path

    • buildFullyQualifiedUnitPathList

      public static List<String> buildFullyQualifiedUnitPathList(IUnitCreator unit, boolean includeArtifact)
      Build a fully-qualified unit path as list of unit names.
      Parameters:
      unit - unit or artifact
      includeArtifact - true to include the artifact name
      Returns:
      path elements

    • buildFullyQualifiedUnitPath

      public static String buildFullyQualifiedUnitPath(IUnit unit)
      Build a unit path of the artifact name and its parent units, such as:artifact > unit > unit > ... > unit
      Parameters:
      unit - unit
      Returns:
      fully-qualified unit path

    • isTopLevelUnit

      public static boolean isTopLevelUnit(IUnit unit)
      Determine whether a unit is directly attached to an artifact.
      Parameters:
      unit - unit
      Returns:
      true if the unit is top-level

    • unitProperty

      public static String unitProperty(IUnitIdentifier ident, String propertyName)
      Generate a fully-qualified property name used by a unit.
      Parameters:
      ident - a unit identifier
      propertyName - simple property name
      Returns:
      a FQ name

    • unitProperty

      public static String unitProperty(IUnit unit, String propertyName)
      Generate a fully-qualified property name used by a unit.
      Parameters:
      unit - a unit
      propertyName - simple property name
      Returns:
      a FQ name

    • unitProperty

      public static String unitProperty(IEnginesContext engctx, String unitType, String propertyName)
      Generate a fully-qualified property name used by a unit.
      Parameters:
      engctx - JEB engines context
      unitType - unit type
      propertyName - simple property name
      Returns:
      a FQ name

    • decompilerProperty

      public static String decompilerProperty(IEnginesContext engctx, String codeType, String propertyName)
      Generate a fully-qualified property name used by a decompiler unit.
      Parameters:
      engctx - JEB engines context
      codeType - code unit type (not a decompiler unit)
      propertyName - simple property name
      Returns:
      a fully-qualified property name, or null if the property namespace cannot be found

    • debuggerProperty

      public static String debuggerProperty(IEnginesContext engctx, String codeType, String propertyName)
      Generate a fully-qualified property name used by a decompiler unit.
      Parameters:
      engctx - JEB engines context
      codeType - code unit type (not a debugger unit)
      propertyName - simple property name
      Returns:
      a fully-qualified property name, or null if the property namespace cannot be found

    • getUnitsFromPathList

      public static List<IUnit> getUnitsFromPathList(IRuntimeProject prj, List<String> path)
      Retrieve the targets IUnit from its path (built from buildFullyQualifiedUnitPathList(IUnitCreator, boolean) for example). Note that result target will be unique in most of the cases.
      Parameters:
      prj - runtime project
      path - path elements
      Returns:
      matching units