Package ghidra.framework.model

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 a project folder. A domain folder is an immutable reference to a folder contained within a project. Provided the corresponding path exists within the project it may continue to be used to create and access its files and sub-folders. The state of a folder object does not track name/parent changes made to the referenced project file. An up-to-date instance may be obtained from ProjectData.getFolder(String) or may be returned by any method used to move or rename it. The project data object for the active Project may be obtained via Project.getProjectData().

Link Files

Link files may exist or be created within a folder. See DomainFile for more information.

Obtaining the folder which corresponds to a linked-folder is done indirectly via a link file. There are different ways to arrive on a linked-folder:

  1. Obtained directly via a folder request by path, or
  2. discovered by the presence of a link file which corresponds to a linked-folder.

Example #1, where folder path is known (external links will be followed): 

    DomainFolder folder = projectData.getFolder("/A/B/linkedFolder");
    if (folder != null) {
       if (folder.isLinked())
          LinkedDomainFolder linkedFolder = (LinkedDomainFolder) folder;
          // linkedFolder behaves the same as a normal folder
       }
       DomainFile[] files = folder.getFiles();
    }

Example #2, where we locate via a link file: 


    DomainFile file = ...
    LinkFileInfo linkInfo = file.getLinkInfo();
    if (linkInfo != null && linkInfo.isFolderLink()) {
       LinkStatus status = linkInfo.getLinkStatus(null);
       if (status != LinkStatus.INTERNAL) {
          return; // Only consider internally linked-folder, skip broken or external link
       }
       LinkedDomainFolder linkedFolder = linkInfo.getLinkedFolder();
       if (linkedFolder != null) {    
          DomainFile[] files = linkedFolder.getFiles();
       }
    }

The utility method ProjectDataUtils.descendantFiles(DomainFolder, DomainFileFilter) may also come in handy to iterate over folder contents while restricting treatment of linked content.

  • 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

      DomainFolder setName(String newName) throws InvalidNameException, IOException
      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

    • isSame

      boolean isSame(DomainFolder folder)
      Returns true if the given folder is the same as this folder based on path and underlying project/repository. Unlike the Object.equals(Object) check, this method handles cases where the folder provided may correspond to another project instance which is considered the same as the project that this folder is contained within.
      Parameters:
      folder - the potential same or descendant folder to check
      Returns:
      true if the given folder is the same or a child of this folder or one of its descendants.

    • isSameOrAncestor

      boolean isSameOrAncestor(DomainFolder folder)
      Returns true if the given folder is the same or a child of this folder or one of its descendants based on path and underlying project/repository. Unlike the Object.equals(Object) check, this method handles cases where the folder provided may correspond to another project instance which is considered the same as the project that this folder is contained within.
      Parameters:
      folder - the potential same or descendant folder to check
      Returns:
      true if the given folder is the same or a child of this folder or one of its descendants.

    • 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. Folder link-files are ignored.
      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

      DomainFile createFile(String name, DomainObject obj, TaskMonitor monitor) throws InvalidNameException, IOException, CancelledException
      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.

    • createLinkFile

      DomainFile createLinkFile(ProjectData sourceProjectData, String pathname, boolean makeRelative, String linkFilename, LinkHandler<?> lh) throws IOException
      Create a link-file within this folder which references the specified file or folder pathname within the project specified by sourceProjectData. The link-file may correspond to various types of content (e.g., Program, Trace, Folder, etc.) based upon the specified LinkHandler instance.
      Parameters:
      sourceProjectData - referenced content project data within which specified path exists. If this differ's from this folder's project a Ghidra URL will be used, otherwise and internal link path reference will be used.
      pathname - an absolute path of project folder or file within the specified source project data (a Ghidra URL is not permitted)
      makeRelative - if true, and this file is contained within the same active ProjectData instance as newParent, an internal-project relative path link-file will be created.
      linkFilename - name of link-file to be created within this folder. NOTE: This name may be modified to ensure uniqueness within this folder.
      lh - link-file handler used to create specific link-file (see derived implementations of LinkHandler and their public static INSTANCE.
      Returns:
      newly created link-file
      Throws:
      IOException - if IO error occurs during link creation

    • createLinkFile

      DomainFile createLinkFile(String ghidraUrl, String linkFilename, LinkHandler<?> lh) throws IOException
      Create an external link-file within this folder which references the specified ghidraUrl and whose content is defined by the specified lh instance.
      Parameters:
      ghidraUrl - a Ghidra URL which corresponds to a file or a folder based on the designated lh instance. Only rudimentary URL checks are performed.
      linkFilename - name of link-file to be created within this folder. NOTE: This name may be modified to ensure uniqueness within this folder.
      lh - link-file handler used to create specific link-file (see derived implementations of LinkHandler and their public static INSTANCE.
      Returns:
      newly created link-file
      Throws:
      IOException - if IO error occurs during link creation

    • 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

      DomainFolder copyTo(DomainFolder newParent, TaskMonitor monitor) throws IOException, CancelledException
      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, boolean relative) throws IOException
      Copy this folder into the newParent folder as a folder-link. A folder-link references another folder without actually copying all of its children. If this folder is associated with a temporary transient project (i.e., not a locally managed project) the generated link will refer to the this folder with a Ghidra URL. If this folder is contained within the same active ProjectData instance as newParent an internal link reference will be made.
      Parameters:
      newParent - new parent folder where link-file is to be created
      relative - if true, and this folder is contained within the same active ProjectData instance as newParent, an internal-project relative path folder-link will be created.
      Returns:
      newly created domain file which is a folder-link (i.e., link-file).
      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 which directly corresponds to a folder-link file. While this method is useful for identify a linked-folder root, in some cases it may be preferrable to simply check for instanceof LinkedDomainFolder which applies to the linked-folder root as well as its child sub-folders.
      Returns:
      true if folder corresponds to a linked-folder, else false.