Interface DomainFolder

All Superinterfaces:
Comparable<DomainFolder>
All Known Subinterfaces:
LinkedDomainFolder
All Known Implementing Classes:
GhidraFolder, LinkedGhidraFolder, RootGhidraFolder

public interface DomainFolder extends Comparable<DomainFolder>
DomainFolder provides a storage interface for project folders. A DomainFolder is an immutable reference to a folder contained within a project. The state of a DomainFolder object does not track name/parent changes made to the referenced project folder.
  • Field Details

    • OPEN_FOLDER_ICON

      static final Icon OPEN_FOLDER_ICON
    • CLOSED_FOLDER_ICON

      static final Icon CLOSED_FOLDER_ICON
    • SEPARATOR

      static final String SEPARATOR
      Character used to separate folder and item names within a path string.
      See Also:
    • COPY_SUFFIX

      static final String COPY_SUFFIX
      Name extension to add when attempting to avoid a duplicate name.
      See Also:
  • Method Details

    • getName

      String getName()
      Return this folder's name.
      Returns:
      the name
    • setName

      Set the name on this domain folder.
      Parameters:
      newName - domain folder name
      Returns:
      renamed domain file (the original DomainFolder object becomes invalid since it is immutable)
      Throws:
      InvalidNameException - if newName contains illegal characters
      DuplicateFileException - if a folder named newName already exists in this files domain folder.
      FileInUseException - if any file within this folder or its descendants is in-use / checked-out.
      IOException - thrown if an IO or access error occurs.
    • getProjectLocator

      ProjectLocator getProjectLocator()
      Returns the local storage location for the project that this DomainFolder belongs to.
      Returns:
      the locator
    • getProjectData

      ProjectData getProjectData()
      Returns the project data
      Returns:
      the project data
    • getPathname

      String getPathname()
      Returns the full path name to this folder
      Returns:
      the path name
    • getSharedProjectURL

      URL getSharedProjectURL()
      Get a remote Ghidra URL for this domain folder if available within an associated shared project repository. URL path will end with "/". A null value will be returned if shared folder does not exist and may also be returned if shared repository is not connected or a connection error occurs.
      Returns:
      remote Ghidra URL for this folder or null
    • getLocalProjectURL

      URL getLocalProjectURL()
      Get a local Ghidra URL for this domain file if available within the associated non-transient local project. A null value will be returned if project is transient.
      Returns:
      local Ghidra URL for this folder or null if transient or not applicable
    • isInWritableProject

      boolean isInWritableProject()
      Returns true if this file is in a writable project.
      Returns:
      true if writable
    • getParent

      DomainFolder getParent()
      Return parent folder or null if this DomainFolder is the root folder.
      Returns:
      the parent
    • getFolders

      DomainFolder[] getFolders()
      Get DomainFolders in this folder. This may return cached information and does not force a full refresh.
      Returns:
      list of sub-folders
    • getFolder

      DomainFolder getFolder(String name)
      Return the folder for the given name.
      Parameters:
      name - of folder to retrieve
      Returns:
      folder or null if there is no folder by the given name.
    • getFile

      DomainFile getFile(String name)
      Get the domain file in this folder with the given name.
      Parameters:
      name - name of file in this folder to retrieve
      Returns:
      domain file or null if there is no domain file in this folder with the given name.
    • isEmpty

      boolean isEmpty()
      Determine if this folder contains any sub-folders or domain files.
      Returns:
      true if this folder is empty.
    • getFiles

      DomainFile[] getFiles()
      Get all domain files in this folder. This may return cached information and does not force a full refresh.
      Returns:
      list of domain files
    • createFile

      Add a domain object to this folder.
      Parameters:
      name - domain file name
      obj - domain object to be stored
      monitor - progress monitor
      Returns:
      domain file created as a result of adding the domain object to this folder
      Throws:
      DuplicateFileException - thrown if the file name already exists
      InvalidNameException - if name is an empty string or if it contains characters other than alphanumerics.
      IOException - if IO or access error occurs
      CancelledException - if the user cancels the create.
    • createFile

      DomainFile createFile(String name, File packFile, TaskMonitor monitor) throws InvalidNameException, IOException, CancelledException
      Add a new domain file to this folder.
      Parameters:
      name - domain file name
      packFile - packed file containing domain file data
      monitor - progress monitor
      Returns:
      domain file created as a result of adding the domain object to this folder
      Throws:
      DuplicateFileException - thrown if the file name already exists
      InvalidNameException - if name is an empty string or if it contains characters other than alphanumerics.
      IOException - if IO or access error occurs
      CancelledException - if the user cancels the create.
    • createFolder

      DomainFolder createFolder(String folderName) throws InvalidNameException, IOException
      Create a subfolder within this folder.
      Parameters:
      folderName - sub-folder name
      Returns:
      the new folder
      Throws:
      DuplicateFileException - if a folder by this name already exists
      InvalidNameException - if name is an empty string of if it contains characters other than alphanumerics.
      IOException - if IO or access error occurs
    • delete

      void delete() throws IOException
      Deletes this folder, if empty, from the local filesystem
      Throws:
      IOException - if IO or access error occurs
      FolderNotEmptyException - Thrown if this folder is not empty.
    • moveTo

      DomainFolder moveTo(DomainFolder newParent) throws IOException
      Move this folder into the newParent folder. If connected to a repository this moves both private and repository folders/files. If not connected, only private folders/files are moved.
      Parameters:
      newParent - new parent folder within the same project
      Returns:
      the newly relocated folder (the original DomainFolder object becomes invalid since it is immutable)
      Throws:
      DuplicateFileException - if a folder with the same name already exists in newParent folder.
      FileInUseException - if this folder or one of its descendants contains a file which is in-use / checked-out.
      IOException - thrown if an IO or access error occurs.
    • copyTo

      Copy this folder into the newParent folder.
      Parameters:
      newParent - new parent folder
      monitor - the task monitor
      Returns:
      the new copied folder
      Throws:
      DuplicateFileException - if a folder or file by this name already exists in the newParent folder
      IOException - thrown if an IO or access error occurs.
      CancelledException - if task monitor cancelled operation.
    • copyToAsLink

      DomainFile copyToAsLink(DomainFolder newParent) throws IOException
      Create a new link-file in the specified newParent which will reference this folder (i.e., linked-folder). Restrictions:
      • Specified newParent must reside within a different project since internal linking is not currently supported.
      If this folder is associated with a temporary transient project (i.e., not a locally managed project) the generated link will refer to the remote folder with a remote Ghidra URL, otherwise a local project storage path will be used.
      Parameters:
      newParent - new parent folder where link-file is to be created
      Returns:
      newly created domain file (i.e., link-file) or null if link use not supported.
      Throws:
      IOException - if an IO or access error occurs.
    • setActive

      void setActive()
      Allows the framework to react to a request to make this folder the "active" one.
    • isLinked

      default boolean isLinked()
      Determine if this folder corresponds to a linked-folder.
      Returns:
      true if folder corresponds to a linked-folder, else false.