Package ghidra.framework.store.local

Class LocalFileSystem

java.lang.Object
ghidra.framework.store.local.LocalFileSystem
All Implemented Interfaces:
FileSystem
Direct Known Subclasses:
IndexedLocalFileSystem, MangledLocalFileSystem
public abstract class LocalFileSystem extends Object implements FileSystem
LocalFileSystem provides access to FolderItem's which exist within a File-based directory structure. Although FolderItem caching is highly recommended, it is not provided by this implementation and should be provided by an encompassing set of folder/file objects.

A LocalFileSystem may optionally support version control of its FolderItem's. When versioned, FolderItem's must be checked-out to create new versions. When not versioned, the check-out mechanism is not used.

FileSystemListener's will only be notified of changes made by the associated LocalFileSystem instance. For this reason, it is important that proper measures are taken to prevent concurrent modification of the underlying files/directories by another instance or by any other means.

  • Field Details

    • HIDDEN_DIR_PREFIX_CHAR

      public static final char HIDDEN_DIR_PREFIX_CHAR
      Hidden directory name prefix. Should only be prepended to an escaped base-name.
      See Also:

    • HIDDEN_DIR_PREFIX

      public static final String HIDDEN_DIR_PREFIX

    • HIDDEN_ITEM_PREFIX

      public static final String HIDDEN_ITEM_PREFIX
      Hidden item name prefix.
      See Also:

    • root

      protected final File root

    • isVersioned

      protected final boolean isVersioned

    • readOnly

      protected final boolean readOnly

    • eventManager

      protected final FileSystemEventManager eventManager

  • Constructor Details

    • LocalFileSystem

      protected LocalFileSystem(String rootPath, boolean isVersioned, boolean readOnly, boolean enableAsyncronousDispatching) throws FileNotFoundException
      Constructor.
      Parameters:
      rootPath - root path directory.
      isVersioned - if true item versioning will be enabled.
      readOnly - if true modifications within this file-system will not be allowed and result in an ReadOnlyException
      enableAsyncronousDispatching - if true a separate dispatch thread will be used to notify listeners. If false, blocking notification will be performed.
      Throws:
      FileNotFoundException - if specified rootPath does not exist

    • LocalFileSystem

      protected LocalFileSystem()
      Constructor for an empty read-only file-system.

  • Method Details

    • getLocalFileSystem

      public static LocalFileSystem getLocalFileSystem(String rootPath, boolean create, boolean isVersioned, boolean readOnly, boolean enableAsyncronousDispatching) throws IOException
      Construct a local filesystem for existing data
      Parameters:
      rootPath - filesystem root directory (the directory must exist and must not have any contents if create is true)
      create - true if creating new filesystem from the empty directory at rootPath
      isVersioned - true if creating a versioned filesystem
      readOnly - true if file system is read-only (ignored if create is true).
      enableAsyncronousDispatching - true if async event dispatching should be performed
      Returns:
      local filesystem
      Throws:
      FileNotFoundException - if specified rootPath does not exist
      IOException - if error occurs while reading/writing index files

    • getUserName

      public String getUserName()
      Description copied from interface: FileSystem
      Get user name associated with this filesystem. In the case of a remote filesystem this will correspond to the name used during login/authentication. A null value may be returned if user name unknown.
      Specified by:
      getUserName in interface FileSystem
      Returns:
      user name used to authenticate or null if not-applicable

    • cleanupAfterConstruction

      protected void cleanupAfterConstruction()

    • setAssociatedRepositoryLogger

      public void setAssociatedRepositoryLogger(RepositoryLogger repositoryLogger)
      Associate file system with a specific repository logger
      Parameters:
      repositoryLogger - repository logger (may be null)

    • log

      protected void log(LocalFolderItem item, String msg, String user)

    • setValidationRequired

      public static void setValidationRequired()
      If set, the state of folder item resources will be continually refreshed. This is required if multiple instances exist for a single item. The default is disabled. This feature should be enabled for testing only since it may have a significant performance impact. This does not provide locking which may be required for a shared environment (e.g., checkin locking is only managed by a single instance).

    • isRefreshRequired

      public static boolean isRefreshRequired()
      Returns:
      true if folder item resources must be refreshed.
      See Also:

    • isVersioned

      public boolean isVersioned()
      Description copied from interface: FileSystem
      Returns true if the file-system requires check-outs when modifying folder items..
      Specified by:
      isVersioned in interface FileSystem
      Returns:
      true if the file-system requires check-outs when modifying folder items.

    • isOnline

      public boolean isOnline()
      Description copied from interface: FileSystem
      Returns true if file-system is on-line..
      Specified by:
      isOnline in interface FileSystem
      Returns:
      true if file-system is on-line.

    • isReadOnly

      public boolean isReadOnly()
      Description copied from interface: FileSystem
      Returns true if file-system is read-only..
      Specified by:
      isReadOnly in interface FileSystem
      Returns:
      true if file-system is read-only.

    • findItemStorage

      protected abstract LocalFileSystem.ItemStorage findItemStorage(String folderPath, String itemName) throws FileNotFoundException
      Find an existing storage location
      Parameters:
      folderPath - folder path of item
      itemName - item name
      Returns:
      storage location. A non-null value does not guarantee that the associated item actually exists.
      Throws:
      FileNotFoundException - if existing storage allocation not found

    • allocateItemStorage

      protected abstract LocalFileSystem.ItemStorage allocateItemStorage(String folderPath, String itemName) throws IOException, InvalidNameException
      Allocate a new storage location
      Parameters:
      folderPath - folder path of item
      itemName - item name
      Returns:
      storage location
      Throws:
      DuplicateFileException - if item path has previously been allocated
      IOException - if invalid path/item name specified
      InvalidNameException - if folderPath or itemName contains invalid characters

    • deallocateItemStorage

      protected abstract void deallocateItemStorage(String folderPath, String itemName) throws IOException
      Deallocate item storage
      Parameters:
      folderPath - folder path of item
      itemName - item name
      Throws:
      IOException - if an IO error occurs

    • getItemNames

      public abstract String[] getItemNames(String folderPath, boolean includeHiddenFiles) throws IOException
      Throws:
      IOException

    • getItemNames

      public String[] getItemNames(String folderPath) throws IOException
      Description copied from interface: FileSystem
      Returns a list of the folder item names contained in the given folder..
      Specified by:
      getItemNames in interface FileSystem
      Parameters:
      folderPath - the path of the folder.
      Returns:
      a list of the folder item names contained in the given folder.
      Throws:
      IOException - if an IO error occurs

    • getItem

      public LocalFolderItem getItem(String folderPath, String name) throws IOException
      Description copied from interface: FileSystem
      Returns the FolderItem in the given folder with the given name
      Specified by:
      getItem in interface FileSystem
      Parameters:
      folderPath - the folder path containing the item.
      name - the name of the item.
      Returns:
      the FolderItem with the given folderPath and name, or null if it doesn't exist.
      Throws:
      IOException - if IO error occurs.

    • fileIdChanged

      protected void fileIdChanged(ItemPropertyFile propertyFile, String oldFileId) throws IOException
      Notification that FileID has been changed within propertyFile
      Parameters:
      propertyFile - item property file
      oldFileId - old FileId
      Throws:
      IOException - if an IO error occurs

    • getItem

      public LocalFolderItem getItem(String fileID) throws IOException, UnsupportedOperationException
      Description copied from interface: FileSystem
      Returns the FolderItem specified by its unique File-ID
      Specified by:
      getItem in interface FileSystem
      Parameters:
      fileID - the items unique file ID
      Returns:
      the FolderItem with the given folderPath and name, or null if it doesn't exist.
      Throws:
      IOException - if IO error occurs.
      UnsupportedOperationException - if file-system does not support this operation

    • getItems

      public LocalFolderItem[] getItems(String folderPath) throws IOException
      Description copied from interface: FileSystem
      Returns a list of the folder items contained in the given folder.
      Specified by:
      getItems in interface FileSystem
      Parameters:
      folderPath - the path of the folder.
      Returns:
      a list of folder items. Null items may exist if index contained item name while storage was not found. An UnknownFolderItem may be returned if unsupported item storage encountered.
      Throws:
      IOException - if an IO error occurs

    • isSupportedItemType

      public boolean isSupportedItemType(FolderItem folderItem)
      Description copied from interface: FileSystem
      Determine if the specified folder item is supported by this filesystem's interface and storage. This method primarily exists to determine if a remote server can support the specified content. This can come into play as new storage formats are added to a LocalFileSystem but may not be supported by a connected RemoteFileSystem.
      Specified by:
      isSupportedItemType in interface FileSystem
      Parameters:
      folderItem - folder item
      Returns:
      true if folder item storage is supported

    • createDatabase

      public LocalDatabaseItem createDatabase(String parentPath, String name, String fileID, BufferFile bufferFile, String comment, String contentType, boolean resetDatabaseId, TaskMonitor monitor, String user) throws InvalidNameException, IOException, CancelledException
      Description copied from interface: FileSystem
      Create a new database item within the specified parent folder using the contents of the specified BufferFile.
      Specified by:
      createDatabase in interface FileSystem
      Parameters:
      parentPath - folder path of parent
      name - new database name
      fileID - file ID to be associated with new database or null
      bufferFile - data source
      comment - version comment (used for versioned file system only)
      contentType - application defined content type
      resetDatabaseId - if true database ID will be reset for new Database
      monitor - allows the database copy to be monitored and cancelled.
      user - name of user creating item (required for versioned item)
      Returns:
      new DatabaseItem
      Throws:
      InvalidNameException - if the name does not have all alphanumerics
      IOException - if an IO error occurs.
      CancelledException - if cancelled by monitor

    • createTemporaryDatabase

      public LocalDatabaseItem createTemporaryDatabase(String parentPath, String name, String fileID, BufferFile bufferFile, String contentType, boolean resetDatabaseId, TaskMonitor monitor) throws InvalidNameException, IOException, CancelledException
      Throws:
      InvalidNameException
      IOException
      CancelledException

    • createDatabase

      public LocalManagedBufferFile createDatabase(String parentPath, String name, String fileID, String contentType, int bufferSize, String user, String projectPath) throws InvalidNameException, IOException
      Description copied from interface: FileSystem
      Create a new empty database item within the specified parent folder. If this is a versioned file-system, the associated item is checked-out. The resulting checkoutId can be obtained from the returned buffer file.
      Specified by:
      createDatabase in interface FileSystem
      Parameters:
      parentPath - folder path of parent
      name - new database name
      fileID - file ID to be associated with new database or null
      contentType - application defined content type
      bufferSize - buffer size. If copying an existing BufferFile, the buffer size must be the same as the source file.
      user - name of user creating item (required for versioned item)
      projectPath - path of project in which database is checked-out (required for versioned item)
      Returns:
      an empty BufferFile open for read-write.
      Throws:
      InvalidNameException - if the name has illegal characters.
      IOException - if an IO error occurs.

    • createDataFile

      public LocalDataFileItem createDataFile(String parentPath, String name, InputStream istream, String comment, String contentType, TaskMonitor monitor) throws InvalidNameException, IOException, CancelledException
      Description copied from interface: FileSystem
      Creates a new empty data file within the specified parent folder.
      Specified by:
      createDataFile in interface FileSystem
      Parameters:
      parentPath - folder path of parent
      name - new data file name
      istream - source data
      comment - version comment (used for versioned file system only)
      contentType - application defined content type
      monitor - progress monitor (used for cancel support, progress not used since length of input stream is unknown)
      Returns:
      new data file
      Throws:
      InvalidNameException - if the name has illegal characters.
      IOException - if an IO error occurs.
      CancelledException - if cancelled by monitor

    • createTextDataItem

      public LocalTextDataItem createTextDataItem(String parentPath, String name, String fileID, String contentType, String textData, String comment, String user) throws InvalidNameException, IOException
      Description copied from interface: FileSystem
      Creates a new text data file within the specified parent folder.
      Specified by:
      createTextDataItem in interface FileSystem
      Parameters:
      parentPath - folder path of parent
      name - new data file name
      fileID - file ID to be associated with new file or null
      contentType - application defined content type
      textData - text data (required)
      comment - file comment (may be null, only used if versioning is enabled)
      user - name of user creating item (required for local versioned item)
      Returns:
      new data file
      Throws:
      InvalidNameException - if the name has illegal characters.
      IOException - if an IO error occurs.

    • createFile

      public LocalDatabaseItem createFile(String parentPath, String name, File packedFile, TaskMonitor monitor, String user) throws InvalidNameException, IOException, CancelledException
      Description copied from interface: FileSystem
      Creates a new file item from a packed file. The content/item type must be determined from the input stream.
      Specified by:
      createFile in interface FileSystem
      Parameters:
      parentPath - folder path of parent
      name - new data file name
      packedFile - packed file data
      monitor - progress monitor (used for cancel support, progress not used since length of input stream is unknown)
      user - name of user creating item (required for versioned item)
      Returns:
      new item
      Throws:
      InvalidNameException - if the name has illegal characters. all alphanumerics
      IOException - if an IO error occurs.
      CancelledException - if cancelled by monitor

    • moveItem

      public void moveItem(String folderPath, String name, String newFolderPath, String newName) throws IOException, InvalidNameException
      Description copied from interface: FileSystem
      Moves the specified item to a new folder.
      Specified by:
      moveItem in interface FileSystem
      Parameters:
      folderPath - path of folder containing the item.
      name - name of the item to be moved.
      newFolderPath - path of folder where item is to be moved to.
      newName - new item name to be applied
      Throws:
      IOException - if an IO error occurs.
      InvalidNameException - if the newName is invalid

    • folderExists

      public abstract boolean folderExists(String folderPath)
      Description copied from interface: FileSystem
      Returns true if the folder specified by the path exists.
      Specified by:
      folderExists in interface FileSystem
      Parameters:
      folderPath - the name of the folder to check for existence.
      Returns:
      true if the folder exists.

    • fileExists

      public boolean fileExists(String folderPath, String name)
      Description copied from interface: FileSystem
      Returns true if the file exists.
      Specified by:
      fileExists in interface FileSystem
      Parameters:
      folderPath - the folderPath of the folder that may contain the file.
      name - the name of the file to check for existence.
      Returns:
      true if the file exists

    • addFileSystemListener

      public void addFileSystemListener(FileSystemListener listener)
      Description copied from interface: FileSystem
      Adds a file system listener to be notified of file system changes.
      Specified by:
      addFileSystemListener in interface FileSystem
      Parameters:
      listener - the listener to be added.

    • removeFileSystemListener

      public void removeFileSystemListener(FileSystemListener listener)
      Description copied from interface: FileSystem
      Removes a file system listener from being notified of file system changes.
      Specified by:
      removeFileSystemListener in interface FileSystem
      Parameters:
      listener - file system listener

    • getMaxNameLength

      public abstract int getMaxNameLength()
      Returns:
      the maximum name length permitted for folders or items.

    • testValidName

      public void testValidName(String name, boolean isPath) throws InvalidNameException
      Validate a folder/item name or path.
      Parameters:
      name - folder or item name
      isPath - if true name represents full path
      Throws:
      InvalidNameException - if name is invalid

    • isValidNameCharacter

      public static boolean isValidNameCharacter(char c)
      Parameters:
      c - character to check
      Returns:
      true if c is a valid character within the FileSystem.

    • deleteEmptyVersionedFolders

      protected void deleteEmptyVersionedFolders(String folderPath)
      Remove the directory which corresponds to the specified folder path if it is empty. If folder directory is removed, this method is invoked recursively for parent folder path which may also be removed if it is empty. This method is intended for use with a versioned file system which only retains folders if they contain one or more items or sub-folders.
      Parameters:
      folderPath - folder path

    • itemDeleted

      protected void itemDeleted(String folderPath, String itemName) throws IOException
      Notify the filesystem that the property file and associated data files for an item have been removed from the filesystem.
      Parameters:
      folderPath - folder path of item
      itemName - item name
      Throws:
      IOException - if an IO error occurs

    • getPath

      public static final String getPath(String parentPath, String name)
      Returns the full path for a named folder or item within a parent folder
      Parameters:
      parentPath - full parent path
      name - child folder or item name
      Returns:
      pathname

    • getParentPath

      public static final String getParentPath(String path)
      Returns the full parent path for a specific folder or item path
      Parameters:
      path - full path of folder or item
      Returns:
      parent path or null if "/" path was specified

    • getName

      public static final String getName(String path)
      Returns the name for a specific folder or item path
      Parameters:
      path - full path of folder or item
      Returns:
      parent path or null if "/" path was specified

    • isShared

      public boolean isShared()
      Description copied from interface: FileSystem
      Returns true if this file system is shared.
      Specified by:
      isShared in interface FileSystem
      Returns:
      true if this file system is shared

    • dispose

      public void dispose()
      Description copied from interface: FileSystem
      Cleanup and release resources
      Specified by:
      dispose in interface FileSystem

    • checkDisposed

      protected void checkDisposed() throws IOException
      Check to see if file-system has been disposed.
      Throws:
      IOException - if file-system has been disposed

    • migrationInProgress

      public boolean migrationInProgress()

    • isHiddenDirName

      public static final boolean isHiddenDirName(String name)
      Determines if the specified storage directory name corresponds to a hidden directory (includes both system and application hidden directories).
      Parameters:
      name - directory name as it appears on storage file system.
      Returns:
      true if name is a hidden name, else false

    • escapeHiddenDirPrefixChars

      public static final String escapeHiddenDirPrefixChars(String name)
      Escape hidden prefix chars in name
      Parameters:
      name - name to be escaped
      Returns:
      escaped name

    • unescapeHiddenDirPrefixChars

      public static final String unescapeHiddenDirPrefixChars(String name)
      Unescape a non-hidden directory name
      Parameters:
      name - name to be unescaped
      Returns:
      unescaped name or null if name is a hidden name