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 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 GFile lookup(GFile baseDir, String path, boolean followSymlinks, Comparator<String> nameComp) throws IOException
      Throws:
      IOException

    • lookup

      protected ghidra.formats.gfilesystem.FileSystemIndexHelper.FileData<METADATATYPE> lookup(ghidra.formats.gfilesystem.FileSystemIndexHelper.FileData<METADATATYPE> baseDir, String[] nameparts, int maxpart, boolean createIfMissing, boolean followSymlinks, 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

    • splitPath

      protected String[] splitPath(String path)

    • 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