Package ghidra.framework.model

# Interface ProjectData

All Superinterfaces:
  `Iterable<DomainFile>`

All Known Implementing Classes:
  `DefaultProjectData`, `TransientProjectData`

public interface ProjectData extends Iterable<DomainFile>
The ProjectData interface provides access to all the data files and folders in a project.

NOTE: Iterating over this project data instance will ignore all link-files. If links should be handled please instantiate `ProjectDataUtils.descendantFiles(DomainFolder, DomainFileFilter)` with a suitable `DomainFileFilter`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addDomainFolderChangeListener(DomainFolderChangeListener listener)`
  Adds a listener that will be notified when any folder or file changes in the project.
  `void`
  `close()`
  Initiate disposal of this project data object.
  `void`
  `convertProjectToShared(RepositoryAdapter repository, TaskMonitor monitor)`
  Convert a local project to a shared project.
  `List<DomainFile>`
  `findCheckedOutFiles(TaskMonitor monitor)`
  Find all project files which are currently checked-out to this project
  `void`
  `findOpenFiles(List<DomainFile> list)`
  Finds all open domain files and appends them to the specified list.
  `DomainFile`
  `getFile(String path)`
  Get domain file specified by an absolute data path.
  `DomainFile`
  `getFile(String path, DomainFileFilter filter)`
  Get domain file specified by an absolute data path which satisfies the specified filter.
  `DomainFile`
  `getFileByID(String fileID)`
  Get domain file specified by its unique fileID.
  `int`
  `getFileCount()`
  Get the approximate number of files contained within the project.
  `DomainFolder`
  `getFolder(String path)`
  Get domain folder specified by an absolute data path.
  `DomainFolder`
  `getFolder(String path, DomainFolderFilter filter)`
  Get domain folder specified by an absolute data path.
  `URL`
  `getLocalProjectURL()`
  Generate a local URL which corresponds to this project data if applicable.
  `Class<? extends LocalFileSystem>`
  `getLocalStorageClass()`
  `int`
  `getMaxNameLength()`
  `ProjectLocator`
  `getProjectLocator()`
  Returns the projectLocator for the this ProjectData.
  `RepositoryAdapter`
  `getRepository()`
  Return the repository for this project data.
  `DomainFolder`
  `getRootFolder()`
  Returns the root folder of the project.
  `URL`
  `getSharedProjectURL()`
  Generate a repository URL which corresponds to this project data if applicable.
  `User`
  `getUser()`
  Returns User object associated with remote repository or null if a remote repository is not used.
  `boolean`
  `hasInvalidCheckouts(List<DomainFile> checkoutList, RepositoryAdapter newRepository, TaskMonitor monitor)`
  Determine if any domain files listed do not correspond to a checkout in the specified newRespository prior to invoking `updateRepositoryInfo(RepositoryAdapter, boolean, TaskMonitor)`.
  `default Iterator<DomainFile>`
  `iterator()`
  Return a `DomainFile` iterator over all non-link files within this project data store.
  `String`
  `makeValidName(String name)`
  Transform the specified name into an acceptable folder or file item name.
  `void`
  `refresh(boolean force)`
  Sync the Domain folder/file structure with the underlying file structure.
  `void`
  `removeDomainFolderChangeListener(DomainFolderChangeListener listener)`
  Removes the listener to be notified of folder and file changes.
  `void`
  `testValidName(String name, boolean isPath)`
  Validate a folder/item name or path.
  `void`
  `updateRepositoryInfo(RepositoryAdapter newRepository, boolean force, TaskMonitor monitor)`
  Update the repository for this project; the server may have changed or a different repository is being used.

  ### Methods inherited from interface java.lang.Iterable

  `forEach, spliterator`

- ## Method Details

  - ### getLocalStorageClass

    Class<? extends LocalFileSystem> getLocalStorageClass()
    Returns:
      local storage implementation class

  - ### getRootFolder

    DomainFolder getRootFolder()
    Returns the root folder of the project.
    Returns:
      root `DomainFolder` within project.

  - ### getFolder

    DomainFolder getFolder(String path)
    Get domain folder specified by an absolute data path. All internal folder-links will be followed. All path elements must refer to a valid internal non-conflicting folder or folder-link. Internal folder-links will be resolved to their corresponding linked-folder.

    External links are not followed. If external links should be followed the `getFolder(String, DomainFolderFilter)` method should be used with an appropriate filter.

    NOTE: Absolute paths do not include the project name which may be shown in the project data tree in place of the root folder node `"/"`.

    Parameters:
      `path` - the absolute path of a domain folder within the project.
    Returns:
      domain folder or null if folder not found

  - ### getFolder

    DomainFolder getFolder(String path, DomainFolderFilter filter)
    Get domain folder specified by an absolute data path. If path refers to a non-conflicting folder-link the specified filter will determine if it should be followed to the linked-folder. All folder path elements must satisfy the filter restrictions.

    NOTE: Absolute paths do not include the project name which may be shown in the project data tree in place of the root folder node `"/"`.

    Parameters:
      `path` - the absolute path of a domain folder within the project.
      `filter` - domain folder filter which constrains returned folder and following of folder-links.
    Returns:
      domain folder or null if folder not found

  - ### getFileCount

    int getFileCount()
    Get the approximate number of files contained within the project. The number may be reduced if not connected to the shared repository. Only the newer indexed file-system supports this capability, a value of -1 will be returned for older projects utilizing the mangled file-system or if an IO Error occurs. An approximate number is provided since the two underlying file systems are consulted separately and the local private file-system does not distinguish between checked-out files and private files. This number is currently intended as a rough sizing number to disable certain features when very large projects are in use. Generally the larger of the two file counts will be returned.
    Returns:
      number of project files or -1 if unknown.

  - ### getFile

    DomainFile getFile(String path)
    Get domain file specified by an absolute data path. All internal folder-links will be followed. The returned file may be a link-file and `DomainFile.getLinkInfo()` result and/or `DomainFile.getDomainObjectClass()` / `DomainFile.getContentType()` should be checked if needed.

    External links are not followed. If external links should be followed the `getFile(String, DomainFileFilter)` method should be used with an appropriate filter.

    NOTE: Absolute path does not include the project name which may be shown in the project data tree in place of the root folder node `"/"`.

    Parameters:
      `path` - the absolute path of domain file within the project.
    Returns:
      domain file or null if file not found

  - ### getFile

    DomainFile getFile(String path, DomainFileFilter filter)
    Get domain file specified by an absolute data path which satisfies the specified filter. If permitted by the filter the returned file may be a link-file. This may occur if filter constrains based upon `DomainFile.getDomainObjectClass()` instead of `DomainFile.getContentType()`. `DomainFile.getLinkInfo()` result can be checked if needed.

    NOTE: Absolute path does not include the project name which may be shown in the project data tree in place of the root folder node `"/"`.

    Parameters:
      `path` - the absolute path of domain file within the project.
      `filter` - domain file filter which constrains returned file and following of folder-links and file-links.
    Returns:
      domain file or null if file not found

  - ### findOpenFiles

    void findOpenFiles(List<DomainFile> list)
    Finds all open domain files and appends them to the specified list.
    Parameters:
      `list` - the list to receive the open domain files

  - ### findCheckedOutFiles

    List<DomainFile> findCheckedOutFiles(TaskMonitor monitor) throws IOException, CancelledException
    Find all project files which are currently checked-out to this project
    Parameters:
      `monitor` - task monitor (no progress updates)
    Returns:
      list of current checkout files
    Throws:
      `IOException` - if IO error occurs
      `CancelledException` - if task cancelled

  - ### hasInvalidCheckouts

    boolean hasInvalidCheckouts(List<DomainFile> checkoutList, RepositoryAdapter newRepository, TaskMonitor monitor) throws IOException, CancelledException
    Determine if any domain files listed do not correspond to a checkout in the specified newRespository prior to invoking `updateRepositoryInfo(RepositoryAdapter, boolean, TaskMonitor)`.
    Parameters:
      `checkoutList` - project domain files to check
      `newRepository` - repository to check against before updating
      `monitor` - task monitor
    Returns:
      true if one or more files are not valid checkouts in newRepository
    Throws:
      `IOException` - if IO error occurs
      `CancelledException` - if task cancelled

  - ### getFileByID

    DomainFile getFileByID(String fileID)
    Get domain file specified by its unique fileID. Link following is not performed.
    Parameters:
      `fileID` - domain file ID
    Returns:
      domain file or null if file not found

  - ### makeValidName

    String makeValidName(String name)
    Transform the specified name into an acceptable folder or file item name. Only an individual folder or file name should be specified, since any separators will be stripped-out. NOTE: Uniqueness of name within the intended target folder is not considered.
    Parameters:
      `name` - original name to be sanitized
    Returns:
      valid name or "unknown" if no valid characters exist within name provided

  - ### getProjectLocator

    ProjectLocator getProjectLocator()
    Returns the projectLocator for the this ProjectData.
    Returns:
      project locator object

  - ### addDomainFolderChangeListener

    void addDomainFolderChangeListener(DomainFolderChangeListener listener)
    Adds a listener that will be notified when any folder or file changes in the project.
    Parameters:
      `listener` - the listener to be notified of folder and file changes.

  - ### removeDomainFolderChangeListener

    void removeDomainFolderChangeListener(DomainFolderChangeListener listener)
    Removes the listener to be notified of folder and file changes.
    Parameters:
      `listener` - the listener to be removed.

  - ### refresh

    void refresh(boolean force)
    Sync the Domain folder/file structure with the underlying file structure.
    Parameters:
      `force` - if true all folders will be visited and refreshed, if false only those folders previously visited will be refreshed.

  - ### getUser

    User getUser()
    Returns User object associated with remote repository or null if a remote repository is not used.
    Returns:
      current remote user identity or null

  - ### getRepository

    RepositoryAdapter getRepository()
    Return the repository for this project data.
    Returns:
      null if the project is not associated with a repository

  - ### convertProjectToShared

    void convertProjectToShared(RepositoryAdapter repository, TaskMonitor monitor) throws IOException, CancelledException
    Convert a local project to a shared project. NOTE: The project should be closed and then reopened after this method is called.
    Parameters:
      `repository` - the repository that the project will be associated with.
      `monitor` - task monitor
    Throws:
      `IOException` - thrown if files under version control are still checked out, or if there was a problem accessing the filesystem
      `CancelledException` - if the conversion was cancelled while versioned files were being converted to private files.

  - ### updateRepositoryInfo

    void updateRepositoryInfo(RepositoryAdapter newRepository, boolean force, TaskMonitor monitor) throws IOException, CancelledException
    Update the repository for this project; the server may have changed or a different repository is being used. Any existing checkout which is not recognized/valid by newRepository will be terminated and a local .keep file created. NOTE: The project should be closed and then reopened after this method is called.
    Parameters:
      `newRepository` - new repository to use
      `force` - if true any existing local checkout which is not recognized/valid for newRepository will be forceably terminated if offline with old repository.
      `monitor` - task monitor
    Throws:
      `IOException` - thrown if files are still checked out, or if there was a problem accessing the filesystem
      `CancelledException` - if the user canceled the update

  - ### close

    void close()
    Initiate disposal of this project data object. Any files already open will delay disposal until they are closed. NOTE: This should only be invoked by the controlling object which created/opened this instance to avoid premature disposal.

  - ### getMaxNameLength

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

  - ### testValidName

    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

  - ### getSharedProjectURL

    URL getSharedProjectURL()
    Generate a repository URL which corresponds to this project data if applicable. Local private projects will return null;
    Returns:
      repository URL which corresponds to this project data or null if not applicable.

  - ### getLocalProjectURL

    URL getLocalProjectURL()
    Generate a local URL which corresponds to this project data if applicable. Remote transient project data will return null;
    Returns:
      local URL which corresponds to this project data or null if not applicable.

  - ### iterator

    default Iterator<DomainFile> iterator()
    Return a `DomainFile` iterator over all non-link files within this project data store. If links should be followed use an appropropriate static method from `ProjectDataUtils`.
    Specified by:
      `iterator` in interface `Iterable<DomainFile>`
    Returns:
      domain file iterator