Package ghidra.formats.gfilesystem

# Class FileSystemIndexHelper<METADATATYPE>

java.lang.Object
ghidra.formats.gfilesystem.FileSystemIndexHelper<METADATATYPE>

Type Parameters:
  `METADATATYPE` - the filesystem specific native file object that the user of this class wants to be able to correlate with Ghidra `GFile` instances.

public class FileSystemIndexHelper<METADATATYPE> extends Object
A helper class used by GFilesystem implementors to track mappings between GFile instances and the underlying container filesystem's native file objects.

Threadsafe (methods are synchronized).

This class also provides filename 'unique-ifying' (per directory) where an auto-incrementing number will be added to a file's filename if it is not unique in the directory.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected Map<GFile,Map<String,ghidra.formats.gfilesystem.FileSystemIndexHelper.FileData<METADATATYPE>>>`
  `directoryToListing`
  `protected Map<Long,ghidra.formats.gfilesystem.FileSystemIndexHelper.FileData<METADATATYPE>>`
  `fileIndexToEntryMap`
  `protected Map<GFile,ghidra.formats.gfilesystem.FileSystemIndexHelper.FileData<METADATATYPE>>`
  `fileToEntryMap`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `FileSystemIndexHelper(GFileSystem fs, FSRLRoot fsFSRL)`
  Creates a new `FileSystemIndexHelper` for the specified `GFileSystem`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `clear()`
  Removes all file info from this index.
  `protected GFileImpl`
  `createNewFile(GFile parentFile, String name, boolean isDirectory, long size, METADATATYPE metadata)`
  Creates a new GFile instance, using per-filesystem custom logic.
  `GFile`
  `getFileByIndex(long fileIndex)`
  Gets the GFile instance that was associated with the filesystem file index.
  `int`
  `getFileCount()`
  Number of files in this index.
  `List<GFile>`
  `getListing(GFile directory)`
  Mirrors `GFileSystem.getListing(GFile)` interface.
  `METADATATYPE`
  `getMetadata(GFile f)`
  Gets the opaque filesystem specific blob that was associated with the specified file.
  `GFile`
  `getRootDir()`
  Gets the root `GFile` object for this filesystem index.
  `protected ghidra.formats.gfilesystem.FileSystemIndexHelper.FileData<METADATATYPE>`
  `lookup(ghidra.formats.gfilesystem.FileSystemIndexHelper.FileData<METADATATYPE> baseDir, String[] nameparts, int maxpart, boolean createIfMissing, Comparator<String> nameComp)`
  `GFile`
  `lookup(GFile baseDir, String path, Comparator<String> nameComp)`
  Mirrors `GFileSystem.lookup(String)` interface, with additional parameters to control the lookup.
  `GFile`
  `lookup(String path)`
  Mirrors `GFileSystem.lookup(String)` interface.
  `protected ghidra.formats.gfilesystem.FileSystemIndexHelper.FileData<METADATATYPE>`
  `lookupFileInDir(Map<String,ghidra.formats.gfilesystem.FileSystemIndexHelper.FileData<METADATATYPE>> dirContents, String filename, Comparator<String> nameComp)`
  `protected GFile`
  `lookupParent(String[] nameparts, Comparator<String> nameComp)`
  Walks a list of names of directories in nameparts (stopping prior to the last element) starting at the root of the filesystem and returns the final directory.
  `protected ghidra.formats.gfilesystem.FileSystemIndexHelper.FileData<METADATATYPE>`
  `resolveSymlinkPath(ghidra.formats.gfilesystem.FileSystemIndexHelper.FileData<METADATATYPE> baseDir, String path, int depth, StringBuilder symlinkPathDebug, Comparator<String> nameComp)`
  `GFile`
  `resolveSymlinks(GFile file)`
  If supplied file is a symlink, converts the supplied file into the targeted file, otherwise just returns the original file.
  `void`
  `setMetadata(GFile f, METADATATYPE metaData)`
  Sets the associated metadata blob for the specified file.
  `GFile`
  `storeFile(String path, long fileIndex, boolean isDirectory, long length, METADATATYPE metadata)`
  Creates and stores a file entry into in-memory indexes.
  `GFile`
  `storeFileWithParent(String filename, GFile parent, long fileIndex, boolean isDirectory, long length, METADATATYPE metadata)`
  Creates and stores a file entry into in-memory indexes.
  `GFile`
  `storeSymlink(String path, long fileIndex, String symlinkPath, long length, METADATATYPE metadata)`
  Creates and stores a file entry that is a symlink into in-memory indexes.
  `GFile`
  `storeSymlinkWithParent(String filename, GFile parent, long fileIndex, String symlinkPath, long length, METADATATYPE metadata)`
  Creates and stores a file entry that is a symlink into in-memory indexes.
  `String`
  `toString()`
  `void`
  `updateFSRL(GFile file, FSRL newFSRL)`
  Updates the FSRL of a file already in the index.

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

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

- ## Field Details

  - ### fileToEntryMap

    protected Map<GFile,ghidra.formats.gfilesystem.FileSystemIndexHelper.FileData<METADATATYPE>> fileToEntryMap

  - ### fileIndexToEntryMap

    protected Map<Long,ghidra.formats.gfilesystem.FileSystemIndexHelper.FileData<METADATATYPE>> fileIndexToEntryMap

  - ### directoryToListing

    protected Map<GFile,Map<String,ghidra.formats.gfilesystem.FileSystemIndexHelper.FileData<METADATATYPE>>> directoryToListing

- ## Constructor Details

  - ### FileSystemIndexHelper

    public FileSystemIndexHelper(GFileSystem fs, FSRLRoot fsFSRL)
    Creates a new `FileSystemIndexHelper` for the specified `GFileSystem`.

    A "root" directory GFile will be auto-created for the filesystem.

    Parameters:
      `fs` - the `GFileSystem` that this index will be for.
      `fsFSRL` - the `fsrl` of the filesystem itself. (this parameter is explicitly passed here so there is no possibility of trying to call back to the fs's `GFileSystem.getFSRL()` on a half-constructed filesystem.)

- ## Method Details

  - ### getRootDir

    public GFile getRootDir()
    Gets the root `GFile` object for this filesystem index.
    Returns:
      root `GFile` object.

  - ### clear

    public void clear()
    Removes all file info from this index.

  - ### getFileCount

    public int getFileCount()
    Number of files in this index.
    Returns:
      number of file in this index

  - ### getMetadata

    public METADATATYPE getMetadata(GFile f)
    Gets the opaque filesystem specific blob that was associated with the specified file.
    Parameters:
      `f` - `GFile` to look for
    Returns:
      Filesystem specific blob associated with the specified file, or null if not found

  - ### setMetadata

    public void setMetadata(GFile f, METADATATYPE metaData) throws IOException
    Sets the associated metadata blob for the specified file.
    Parameters:
      `f` - GFile to update
      `metaData` - new metadata blob
    Throws:
      `IOException` - if unknown file

  - ### getFileByIndex

    public GFile getFileByIndex(long fileIndex)
    Gets the GFile instance that was associated with the filesystem file index.
    Parameters:
      `fileIndex` - index of the file in its filesystem
    Returns:
      the associated GFile instance, or null if not found

  - ### getListing

    public List<GFile> getListing(GFile directory)
    Mirrors `GFileSystem.getListing(GFile)` interface.
    Parameters:
      `directory` - `GFile` directory to get the list of child files that have been added to this index, null means root directory
    Returns:
      `List` of GFile files that are in the specified directory, never null

  - ### lookup

    public GFile lookup(String path)
    Mirrors `GFileSystem.lookup(String)` interface.
    Parameters:
      `path` - path and filename of a file to find
    Returns:
      `GFile` instance or null if no file was added to the index at that path

  - ### lookup

    public GFile lookup(GFile baseDir, String path, Comparator<String> nameComp)
    Mirrors `GFileSystem.lookup(String)` interface, with additional parameters to control the lookup.
    Parameters:
      `baseDir` - optional starting directory to perform lookup
      `path` - path and filename of a file to find
      `nameComp` - optional `Comparator` that compares file names. Suggested values are `String::compareTo` or `String::compareToIgnoreCase` or `null` (also exact).
    Returns:
      `GFile` instance or null if no file was added to the index at that path

  - ### lookup

    protected ghidra.formats.gfilesystem.FileSystemIndexHelper.FileData<METADATATYPE> lookup(ghidra.formats.gfilesystem.FileSystemIndexHelper.FileData<METADATATYPE> baseDir, String[] nameparts, int maxpart, boolean createIfMissing, Comparator<String> nameComp)

  - ### resolveSymlinkPath

    protected ghidra.formats.gfilesystem.FileSystemIndexHelper.FileData<METADATATYPE> resolveSymlinkPath(ghidra.formats.gfilesystem.FileSystemIndexHelper.FileData<METADATATYPE> baseDir, String path, int depth, StringBuilder symlinkPathDebug, Comparator<String> nameComp) throws IOException
    Throws:
      `IOException`

  - ### resolveSymlinks

    public GFile resolveSymlinks(GFile file) throws IOException
    If supplied file is a symlink, converts the supplied file into the targeted file, otherwise just returns the original file.
    Parameters:
      `file` - `GFile` to convert
    Returns:
      symlink targeted `GFile`, or original file it not a symlink, or null if symlink path was invalid or reached outside the bounds of this file system
    Throws:
      `IOException` - if symlinks are nested too deeply

  - ### storeFile

    public GFile storeFile(String path, long fileIndex, boolean isDirectory, long length, METADATATYPE metadata)
    Creates and stores a file entry into in-memory indexes.

    The string path will be normalized to forward slashes before being split into directory components.

    Filenames that are not unique in their directory will have a "[nnn]" suffix added to the resultant GFile name, where nnn is the file's order of occurrence in the container file.

    Parameters:
      `path` - string path and filename of the file being added to the index. Back slashes are normalized to forward slashes
      `fileIndex` - the filesystem specific unique index for this file, or -1 if not available
      `isDirectory` - boolean true if the new file is a directory
      `length` - number of bytes in the file or -1 if not known or directory
      `metadata` - opaque blob that will be stored and associated with the new GFile instance
    Returns:
      new GFile instance

  - ### storeFileWithParent

    public GFile storeFileWithParent(String filename, GFile parent, long fileIndex, boolean isDirectory, long length, METADATATYPE metadata)
    Creates and stores a file entry into in-memory indexes.

    Use this when you already know the parent directory GFile object.

    Filenames that are not unique in their directory will have a "[nnn]" suffix added to the resultant GFile name, where nnn is the file's order of occurrence in the container file.

    Parameters:
      `filename` - the new file's name
      `parent` - the new file's parent directory
      `fileIndex` - the filesystem specific unique index for this file, or -1 if not available
      `isDirectory` - boolean true if the new file is a directory
      `length` - number of bytes in the file or -1 if not known or directory
      `metadata` - opaque blob that will be stored and associated with the new GFile instance
    Returns:
      new GFile instance

  - ### storeSymlink

    public GFile storeSymlink(String path, long fileIndex, String symlinkPath, long length, METADATATYPE metadata)
    Creates and stores a file entry that is a symlink into in-memory indexes.

    The string path will be normalized to forward slashes before being split into directory components.

    Filenames that are not unique in their directory will have a "[nnn]" suffix added to the resultant GFile name, where nnn is the file's order of occurrence in the container file.

    Parameters:
      `path` - string path and filename of the file being added to the index. Back slashes are normalized to forward slashes
      `fileIndex` - the filesystem specific unique index for this file, or -1 if not available
      `symlinkPath` - destination of the symlink
      `length` - number of bytes in the file or -1 if not known or directory
      `metadata` - opaque blob that will be stored and associated with the new GFile instance
    Returns:
      new GFile instance

  - ### storeSymlinkWithParent

    public GFile storeSymlinkWithParent(String filename, GFile parent, long fileIndex, String symlinkPath, long length, METADATATYPE metadata)
    Creates and stores a file entry that is a symlink into in-memory indexes.

    Use this when you already know the parent directory GFile object.

    Filenames that are not unique in their directory will have a "[nnn]" suffix added to the resultant GFile name, where nnn is the file's order of occurrence in the container file.

    Parameters:
      `filename` - the new file's name
      `parent` - the new file's parent directory
      `fileIndex` - the filesystem specific unique index for this file, or -1 if not available
      `symlinkPath` - destination of the symlink
      `length` - number of bytes in the file or -1 if not known or directory
      `metadata` - opaque blob that will be stored and associated with the new GFile instance
    Returns:
      new GFile instance

  - ### lookupParent

    protected GFile lookupParent(String[] nameparts, Comparator<String> nameComp)
    Walks a list of names of directories in nameparts (stopping prior to the last element) starting at the root of the filesystem and returns the final directory.

    Directories in a path that have not been encountered before (ie. a file's path references a directory that hasn't been mentioned yet as its own file entry) will have a stub entry GFile created for them if createIfMissing is true.

    Superfluous slashes in the original filename (ie. name/sub//subafter_extra_slash) will be represented as empty string elements in the nameparts array and will be skipped as if they were not there.

    Parameters:
      `nameparts` - String[] containing the elements of a path for them
      `nameComp` - optional comparator that will compare names, usually case-sensitive vs case insensitive
    Returns:
      GFile that represents the parent directory

  - ### lookupFileInDir

    protected ghidra.formats.gfilesystem.FileSystemIndexHelper.FileData<METADATATYPE> lookupFileInDir(Map<String,ghidra.formats.gfilesystem.FileSystemIndexHelper.FileData<METADATATYPE>> dirContents, String filename, Comparator<String> nameComp)

  - ### createNewFile

    protected GFileImpl createNewFile(GFile parentFile, String name, boolean isDirectory, long size, METADATATYPE metadata)
    Creates a new GFile instance, using per-filesystem custom logic.
    Parameters:
      `parentFile` - the parent file of the new instance. Never null.
      `name` - the name of the file
      `isDirectory` - is this is file or directory?
      `size` - length of the file data
      `metadata` - filesystem specific BLOB that may have data that this method needs to create the new GFile instance. Can be null if this method is being called to create a missing directory that was referenced in a filename.
    Returns:
      new GFileImpl instance

  - ### updateFSRL

    public void updateFSRL(GFile file, FSRL newFSRL)
    Updates the FSRL of a file already in the index.
    Parameters:
      `file` - current `GFile`
      `newFSRL` - the new FSRL the new file will be given

  - ### toString

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