Package ghidra.features.bsim.query.description

# Class ExecutableRecord

java.lang.Object
ghidra.features.bsim.query.description.ExecutableRecord

All Implemented Interfaces:
  `Comparable<ExecutableRecord>`

public class ExecutableRecord extends Object implements Comparable<ExecutableRecord>
Metadata about a specific executable, as stored in a BSim database There are two basic varieties: Normal executables, which can be viewed as a container of functions where each function has a body and an address (and a corresponding feature vector) Library executables, which contains functions that can only be identified by name and have no body (or corresponding feature vector)

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `ExecutableRecord.Update`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `ALREADY_STORED`
  `static final int`
  `CATEGORIES_SET`
  `static final Date`
  `EMPTY_DATE`
  `static final int`
  `LIBRARY`
  `static final int`
  `METADATA_ARCH`
  `static final int`
  `METADATA_COMP`
  `static final int`
  `METADATA_DATE`
  `static final int`
  `METADATA_LIBR`
  `static final int`
  `METADATA_NAME`
  `static final int`
  `METADATA_PATH`
  `static final int`
  `METADATA_REPO`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `ExecutableRecord(String md5)`
  Constructor for searching within a DescriptionManager
  ``
  `ExecutableRecord(String enm, String arc, RowKey id)`
  Constructor for a "library" executable
  ``
  `ExecutableRecord(String md5, String execName, String compilerName, String architecture, Date date, RowKey id, String repo, String path)`
  Construct a normal (non-library) record.
  ``
  `ExecutableRecord(String md5, String enm, String cnm, String arc, Date dt, List<CategoryRecord> uc, RowKey id, String repo, String pth)`
  Construct a normal (non-library) record.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static String`
  `calcLibraryMd5Placeholder(String enm, String arc)`
  Generate a placeholder md5 string for a library executable based just on its name and architecture
  `boolean`
  `categoriesAreSet()`
  `protected void`
  `cloneCategories(ExecutableRecord op2)`
  `boolean`
  `compareCategory(ExecutableRecord op2)`
  Compare the set of categories that -this- and -op2- belong to
  `int`
  `compareMetadata(ExecutableRecord o)`
  Compare just the metadata portion (names and versions) of two ExecutableRecords We do NOT compare categories as these may not have been read into the object yet
  `int`
  `compareTo(ExecutableRecord o)`
  `boolean`
  `diffForUpdate(ExecutableRecord.Update res, ExecutableRecord fromDB)`
  Assuming this is a (possibly) updated variant of another executable metadata record Prepare an Update record describing the difference between the two records
  `boolean`
  `equals(Object obj)`
  `List<CategoryRecord>`
  `getAllCategories()`
  `String`
  `getArchitecture()`
  `List<String>`
  `getCategory(String type)`
  Return the executable's settings for a specific category type
  `Date`
  `getDate()`
  `String`
  `getExeCategoryAlphabetic(String type)`
  Get all the category settings of a specific type in alphabetic order.
  `String`
  `getMd5()`
  `String`
  `getNameCompiler()`
  `String`
  `getNameExec()`
  `String`
  `getPath()`
  `String`
  `getRepository()`
  `RowKey`
  `getRowId()`
  `String`
  `getURLString()`
  `int`
  `getXrefIndex()`
  `boolean`
  `hasCategory(String type, String value)`
  Determine if an executable has been set with a specific category value
  `int`
  `hashCode()`
  `boolean`
  `isAlreadyStored()`
  `boolean`
  `isLibrary()`
  `static boolean`
  `isLibraryHash(String md5)`
  Identify whether an md5 string is a placeholder hash (as generated by `calcLibraryMd5Placeholder(java.lang.String, java.lang.String)`)
  `String`
  `printRaw()`
  Get the formatted raw executable metadata as a string
  `static ExecutableRecord`
  `restoreXml(XmlPullParser parser, DescriptionManager man)`
  Build a new `ExecutableRecord` by deserializing from an XML stream
  `void`
  `saveXml(Writer fwrite)`
  Serialize this executable (meta-data) to an XML stream
  `protected void`
  `setAlreadyStored()`
  `protected void`
  `setCategory(List<CategoryRecord> cats)`
  `protected void`
  `setRepository(String repo, String newpath)`
  Set the repository and path Strings for an executable, replacing any previous setting.
  `protected void`
  `setRowId(RowKey i)`
  `protected void`
  `setXrefIndex(int val)`
  `String`
  `toString()`

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### EMPTY_DATE

    public static final Date EMPTY_DATE

  - ### ALREADY_STORED

    public static final int ALREADY_STORED
    See Also:
      - Constant Field Values

  - ### LIBRARY

    public static final int LIBRARY
    See Also:
      - Constant Field Values

  - ### CATEGORIES_SET

    public static final int CATEGORIES_SET
    See Also:
      - Constant Field Values

  - ### METADATA_NAME

    public static final int METADATA_NAME
    See Also:
      - Constant Field Values

  - ### METADATA_ARCH

    public static final int METADATA_ARCH
    See Also:
      - Constant Field Values

  - ### METADATA_COMP

    public static final int METADATA_COMP
    See Also:
      - Constant Field Values

  - ### METADATA_DATE

    public static final int METADATA_DATE
    See Also:
      - Constant Field Values

  - ### METADATA_REPO

    public static final int METADATA_REPO
    See Also:
      - Constant Field Values

  - ### METADATA_PATH

    public static final int METADATA_PATH
    See Also:
      - Constant Field Values

  - ### METADATA_LIBR

    public static final int METADATA_LIBR
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### ExecutableRecord

    protected ExecutableRecord(String md5)
    Constructor for searching within a DescriptionManager
    Parameters:
      `md5` - is hash of executable being searched for

  - ### ExecutableRecord

    public ExecutableRecord(String md5, String execName, String compilerName, String architecture, Date date, RowKey id, String repo, String path)
    Construct a normal (non-library) record. Fill-in all fields except categories. Categories are marked as NOT set
    Parameters:
      `md5` - is the md5 checksum
      `execName` - is the executable name
      `compilerName` - is the compiler name
      `architecture` - is the processor architecture
      `date` - is the date of ingest (may be null)
      `id` - is the row id of the record
      `repo` - is the repository containing the executable (may be null)
      `path` - is the path to the executable (may be null)

  - ### ExecutableRecord

    public ExecutableRecord(String md5, String enm, String cnm, String arc, Date dt, List<CategoryRecord> uc, RowKey id, String repo, String pth)
    Construct a normal (non-library) record. Fill-in all fields.
    Parameters:
      `md5` - is the md5 checksum
      `enm` - is the executable name
      `cnm` - is the compiler name
      `arc` - is the architecture
      `dt` - is the date of ingest (may be null)
      `uc` - is the categories (may be null, categories are considered SET regardless)
      `id` - is the row id of the record
      `repo` - is the repository containing the executable (may be null)
      `pth` - is the path to the executable (may be null)

  - ### ExecutableRecord

    public ExecutableRecord(String enm, String arc, RowKey id)
    Constructor for a "library" executable
    Parameters:
      `enm` - is the name of the library
      `arc` - is the architecture for functions in the library
      `id` - is the database (row) id of the record (may be null)

- ## Method Details

  - ### calcLibraryMd5Placeholder

    public static String calcLibraryMd5Placeholder(String enm, String arc)
    Generate a placeholder md5 string for a library executable based just on its name and architecture
    Parameters:
      `enm` - is the name of the library
      `arc` - is the architecture
    Returns:
      the placeholder md5 String

  - ### setRepository

    protected void setRepository(String repo, String newpath)
    Set the repository and path Strings for an executable, replacing any previous setting. Truncate any trailing slash.
    Parameters:
      `repo` - is (URL) string indicating which repository contains this executable
      `newpath` - is the path, relative to the repository, to the executable
    Throws:
      `IllegalArgumentException` - if invalid repo URL specified

  - ### setRowId

    protected void setRowId(RowKey i)

  - ### setAlreadyStored

    protected void setAlreadyStored()

  - ### setXrefIndex

    protected void setXrefIndex(int val)

  - ### setCategory

    protected void setCategory(List<CategoryRecord> cats)

  - ### cloneCategories

    protected void cloneCategories(ExecutableRecord op2)

  - ### getAllCategories

    public List<CategoryRecord> getAllCategories()
    Returns:
      the list of `CategoryRecord`s associated with this executable

  - ### getCategory

    public List<String> getCategory(String type)
    Return the executable's settings for a specific category type
    Parameters:
      `type` - is the category type
    Returns:
      the list of settings with this type (or null)

  - ### hasCategory

    public boolean hasCategory(String type, String value)
    Determine if an executable has been set with a specific category value
    Parameters:
      `type` - is the type of category to check
      `value` - is the value to check for
    Returns:
      true if the executable has that value, false otherwise

  - ### getMd5

    public String getMd5()
    Returns:
      the MD5 hash of the executable

  - ### getNameExec

    public String getNameExec()
    Returns:
      the name of the executable

  - ### getArchitecture

    public String getArchitecture()
    Returns:
      the architecture associated with the executable

  - ### getNameCompiler

    public String getNameCompiler()
    Returns:
      the name of the compiler that built this executable

  - ### getDate

    public Date getDate()
    Returns:
      the date this executable was ingested into the database

  - ### getRepository

    public String getRepository()
    Returns:
      the URL of the repository containing this executable

  - ### getPath

    public String getPath()
    Returns:
      the (repository relative) path to the executable

  - ### isLibrary

    public boolean isLibrary()
    Returns:
      true if this executable is a "library" (functions identified only by name)

  - ### isAlreadyStored

    public boolean isAlreadyStored()
    Returns:
      true if this database record has already been stored in the database

  - ### categoriesAreSet

    public boolean categoriesAreSet()
    Returns:
      true if categories have been queried in (does not mean that it has any categories)

  - ### getURLString

    public String getURLString()
    Returns:
      the fully formed URL to this executable or null

  - ### getExeCategoryAlphabetic

    public String getExeCategoryAlphabetic(String type)
    Get all the category settings of a specific type in alphabetic order. Multiple values are returned in a single String separated by ','
    Parameters:
      `type` - is the type of category to retrieve
    Returns:
      the concatenated list of settings

  - ### getRowId

    public RowKey getRowId()
    Returns:
      the database (row) id of this executable object

  - ### getXrefIndex

    public int getXrefIndex()
    Returns:
      the internal cross-referencing index for this executable

  - ### saveXml

    public void saveXml(Writer fwrite) throws IOException
    Serialize this executable (meta-data) to an XML stream
    Parameters:
      `fwrite` - is the XML stream
    Throws:
      `IOException` - if there are I/O errors writing to the stream

  - ### isLibraryHash

    public static boolean isLibraryHash(String md5)
    Identify whether an md5 string is a placeholder hash (as generated by `calcLibraryMd5Placeholder(java.lang.String, java.lang.String)`)
    Parameters:
      `md5` - is the md5 string
    Returns:
      true if it is a placeholder, false otherwise

  - ### restoreXml

    public static ExecutableRecord restoreXml(XmlPullParser parser, DescriptionManager man) throws LSHException
    Build a new `ExecutableRecord` by deserializing from an XML stream
    Parameters:
      `parser` - is the XML parser
      `man` - is the DescriptionManager that should hold the new executable
    Returns:
      the new ExecutableRecord
    Throws:
      `LSHException` - if there are inconsistencies in the XML description

  - ### equals

    public boolean equals(Object obj)
    Overrides:
      `equals` in class `Object`

  - ### hashCode

    public int hashCode()
    Overrides:
      `hashCode` in class `Object`

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`

  - ### compareTo

    public int compareTo(ExecutableRecord o)
    Specified by:
      `compareTo` in interface `Comparable<ExecutableRecord>`

  - ### compareMetadata

    public int compareMetadata(ExecutableRecord o)
    Compare just the metadata portion (names and versions) of two ExecutableRecords We do NOT compare categories as these may not have been read into the object yet
    Parameters:
      `o` - is ExecutableRecord to compare with this
    Returns:
      bit vector with a 1 bit for every field that differs

  - ### compareCategory

    public boolean compareCategory(ExecutableRecord op2)
    Compare the set of categories that -this- and -op2- belong to
    Parameters:
      `op2` - is executable to compare with this
    Returns:
      true if the categories are exactly the same

  - ### diffForUpdate

    public boolean diffForUpdate(ExecutableRecord.Update res, ExecutableRecord fromDB)
    Assuming this is a (possibly) updated variant of another executable metadata record Prepare an Update record describing the difference between the two records
    Parameters:
      `res` - is the Update record to fill in
      `fromDB` - is the other ExecutableRecord metadata
    Returns:
      true if overall there has been an update

  - ### printRaw

    public String printRaw()
    Get the formatted raw executable metadata as a string
    Returns:
      formatted metadata