Package ghidra.framework.data

# Class DefaultProjectData

java.lang.Object
ghidra.framework.data.DefaultProjectData

All Implemented Interfaces:
  `ProjectData`, `Iterable<DomainFile>`

Direct Known Subclasses:
  `TransientProjectData`

public class DefaultProjectData extends Object implements ProjectData
Helper class to manage files within a project.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `INDEXED_DATA_FOLDER_NAME`
  `static final String`
  `MANGLED_DATA_FOLDER_NAME`
  `static final String`
  `OWNER`
  `static final String`
  `PORT_NUMBER`
  `static final String`
  `REPOSITORY_NAME`
  `static final String`
  `SERVER_NAME`
  `static final String`
  `USER_FOLDER_NAME`
  `static final String`
  `VERSIONED_FOLDER_NAME`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DefaultProjectData(ProjectLocator localStorageLocator, boolean isInWritableProject, boolean resetOwner)`
  Constructor for existing projects.
  `DefaultProjectData(ProjectLocator localStorageLocator, RepositoryAdapter repository, boolean isInWritableProject)`
  Constructor for a new project.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addDomainFolderChangeListener(DomainFolderChangeListener l)`
  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 newRepository, TaskMonitor monitor)`
  Convert a local project to a shared project.
  `protected void`
  `dispose()`
  Immediately dispose this project data store instance.
  `List<DomainFile>`
  `findCheckedOutFiles(TaskMonitor monitor)`
  Find all project files which are currently checked-out
  `void`
  `findOpenFiles(List<DomainFile> list)`
  Finds all changed 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()`
  `String`
  `getOwner()`
  Returns the owner of the project that is associated with this DefaultProjectData.
  `FileSystem`
  `getPrivateFileSystem()`
  `File`
  `getProjectDir()`
  `TaskMonitor`
  `getProjectDisposalMonitor()`
  Get monitor which will be cancelled if project is closed
  `ProjectLocator`
  `getProjectLocator()`
  Returns the projectLocator for the this ProjectData.
  `RepositoryAdapter`
  `getRepository()`
  Return the repository for this project data.
  `GhidraFolder`
  `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.
  `static String`
  `getUserDataFilename(String associatedFileID)`
  Returns the standard user data filename associated with the specified file ID.
  `boolean`
  `hasInvalidCheckouts(List<DomainFile> checkoutList, RepositoryAdapter newRepository, TaskMonitor monitor)`
  Determine if any domain files listed does not correspond to a checkout in the specified newRespository.
  `boolean`
  `isClosed()`
  `boolean`
  `isDisposed()`
  `static boolean`
  `isLocked(ProjectLocator locator)`
  Determine if the specified project location currently has a write lock.
  `String`
  `makeValidName(String name)`
  Transform the specified name into an acceptable folder or file item name.
  `static Properties`
  `readProjectProperties(File projectDir)`
  Read the contents of the project properties file to include the following values if relavent: "OWNER", "SERVER", "REPOSITORY_NAME", "PORT_NUMBER"
  `void`
  `refresh(boolean force)`
  Sync the Domain folder/file structure with the underlying file structure.
  `void`
  `releaseDomainFiles(Object consumer)`
  `void`
  `removeDomainFolderChangeListener(DomainFolderChangeListener l)`
  Removes the listener to be notified of folder and file changes.
  `void`
  `removeFromIndex(String fileID)`
  Remove specified fileID from index.
  `void`
  `testValidName(String name, boolean isPath)`
  Validate a folder/item name or path.
  `void`
  `updateFileIndex(GhidraFileData fileData)`
  Update the file index for the specified file data
  `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 class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

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

  `forEach, spliterator`

  ### Methods inherited from interface ghidra.framework.model.ProjectData

  `iterator`

- ## Field Details

  - ### MANGLED_DATA_FOLDER_NAME

    public static final String MANGLED_DATA_FOLDER_NAME
    See Also:
      - Constant Field Values

  - ### INDEXED_DATA_FOLDER_NAME

    public static final String INDEXED_DATA_FOLDER_NAME
    See Also:
      - Constant Field Values

  - ### USER_FOLDER_NAME

    public static final String USER_FOLDER_NAME
    See Also:
      - Constant Field Values

  - ### VERSIONED_FOLDER_NAME

    public static final String VERSIONED_FOLDER_NAME
    See Also:
      - Constant Field Values

  - ### SERVER_NAME

    public static final String SERVER_NAME
    See Also:
      - Constant Field Values

  - ### PORT_NUMBER

    public static final String PORT_NUMBER
    See Also:
      - Constant Field Values

  - ### REPOSITORY_NAME

    public static final String REPOSITORY_NAME
    See Also:
      - Constant Field Values

  - ### OWNER

    public static final String OWNER
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### DefaultProjectData

    public DefaultProjectData(ProjectLocator localStorageLocator, boolean isInWritableProject, boolean resetOwner) throws NotOwnerException, IOException, LockException
    Constructor for existing projects.
    Parameters:
      `localStorageLocator` - the location of the project
      `isInWritableProject` - true if project content is writable, false if project is read-only
      `resetOwner` - true to reset the project owner
    Throws:
      `IOException` - if an i/o error occurs
      `NotOwnerException` - if inProject is true and user is not owner
      `LockException` - if `isInWritableProject` is true and unable to establish project write lock (i.e., project in-use)
      `FileNotFoundException` - if project directory not found

  - ### DefaultProjectData

    public DefaultProjectData(ProjectLocator localStorageLocator, RepositoryAdapter repository, boolean isInWritableProject) throws IOException, LockException
    Constructor for a new project.
    Parameters:
      `localStorageLocator` - the location of the project
      `repository` - a repository if this is a shared project or null if it is a private project
      `isInWritableProject` - true if project content is writable, false if project is read-only
    Throws:
      `IOException` - if an i/o error occurs
      `LockException` - if `isInWritableProject` is true and unable to establish project lock (i.e., project in-use)

- ## Method Details

  - ### readProjectProperties

    public static Properties readProjectProperties(File projectDir)
    Read the contents of the project properties file to include the following values if relavent: "OWNER", "SERVER", "REPOSITORY_NAME", "PORT_NUMBER"
    Parameters:
      `projectDir` - project directory (*.rep)
    Returns:
      project properties or null if invalid project directory specified

  - ### isLocked

    public static boolean isLocked(ProjectLocator locator)
    Determine if the specified project location currently has a write lock.
    Parameters:
      `locator` - project storage locator
    Returns:
      true if project data current has write-lock else false

  - ### getMaxNameLength

    public int getMaxNameLength()
    Specified by:
      `getMaxNameLength` in interface `ProjectData`
    Returns:
      the maximum name length permitted for folders or items.

  - ### testValidName

    public void testValidName(String name, boolean isPath) throws InvalidNameException
    Description copied from interface: `ProjectData`
    Validate a folder/item name or path.
    Specified by:
      `testValidName` in interface `ProjectData`
    Parameters:
      `name` - folder or item name
      `isPath` - if true name represents full path
    Throws:
      `InvalidNameException` - if name is invalid

  - ### getUser

    public User getUser()
    Description copied from interface: `ProjectData`
    Returns User object associated with remote repository or null if a remote repository is not used.
    Specified by:
      `getUser` in interface `ProjectData`
    Returns:
      current remote user identity or null

  - ### getLocalStorageClass

    public Class<? extends LocalFileSystem> getLocalStorageClass()
    Specified by:
      `getLocalStorageClass` in interface `ProjectData`
    Returns:
      local storage implementation class

  - ### getOwner

    public String getOwner()
    Returns the owner of the project that is associated with this DefaultProjectData. A value of null indicates an old multiuser project.
    Returns:
      the owner of the project

  - ### getRootFolder

    public GhidraFolder getRootFolder()
    Description copied from interface: `ProjectData`
    Returns the root folder of the project.
    Specified by:
      `getRootFolder` in interface `ProjectData`
    Returns:
      root `DomainFolder` within project.

  - ### getFolder

    public DomainFolder getFolder(String path)
    Description copied from interface: `ProjectData`
    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 `ProjectData.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 `"/"`.

    Specified by:
      `getFolder` in interface `ProjectData`
    Parameters:
      `path` - the absolute path of a domain folder within the project.
    Returns:
      domain folder or null if folder not found

  - ### getFolder

    public DomainFolder getFolder(String path, DomainFolderFilter filter)
    Description copied from interface: `ProjectData`
    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 `"/"`.

    Specified by:
      `getFolder` in interface `ProjectData`
    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

    public int getFileCount()
    Description copied from interface: `ProjectData`
    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.
    Specified by:
      `getFileCount` in interface `ProjectData`
    Returns:
      number of project files or -1 if unknown.

  - ### getFile

    public DomainFile getFile(String path)
    Description copied from interface: `ProjectData`
    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 `ProjectData.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 `"/"`.

    Specified by:
      `getFile` in interface `ProjectData`
    Parameters:
      `path` - the absolute path of domain file within the project.
    Returns:
      domain file or null if file not found

  - ### getFile

    public DomainFile getFile(String path, DomainFileFilter filter)
    Description copied from interface: `ProjectData`
    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 `"/"`.

    Specified by:
      `getFile` in interface `ProjectData`
    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

  - ### getFileByID

    public DomainFile getFileByID(String fileID)
    Description copied from interface: `ProjectData`
    Get domain file specified by its unique fileID. Link following is not performed.
    Specified by:
      `getFileByID` in interface `ProjectData`
    Parameters:
      `fileID` - domain file ID
    Returns:
      domain file or null if file not found

  - ### releaseDomainFiles

    public void releaseDomainFiles(Object consumer)

  - ### findOpenFiles

    public void findOpenFiles(List<DomainFile> list)
    Finds all changed domain files and appends them to the specified list.
    Specified by:
      `findOpenFiles` in interface `ProjectData`
    Parameters:
      `list` - the list to receive the changed domain files

  - ### getProjectLocator

    public ProjectLocator getProjectLocator()
    Description copied from interface: `ProjectData`
    Returns the projectLocator for the this ProjectData.
    Specified by:
      `getProjectLocator` in interface `ProjectData`
    Returns:
      project locator object

  - ### addDomainFolderChangeListener

    public void addDomainFolderChangeListener(DomainFolderChangeListener l)
    Description copied from interface: `ProjectData`
    Adds a listener that will be notified when any folder or file changes in the project.
    Specified by:
      `addDomainFolderChangeListener` in interface `ProjectData`
    Parameters:
      `l` - the listener to be notified of folder and file changes.

  - ### removeDomainFolderChangeListener

    public void removeDomainFolderChangeListener(DomainFolderChangeListener l)
    Description copied from interface: `ProjectData`
    Removes the listener to be notified of folder and file changes.
    Specified by:
      `removeDomainFolderChangeListener` in interface `ProjectData`
    Parameters:
      `l` - the listener to be removed.

  - ### getPrivateFileSystem

    public FileSystem getPrivateFileSystem()

  - ### getRepository

    public RepositoryAdapter getRepository()
    Description copied from interface: `ProjectData`
    Return the repository for this project data.
    Specified by:
      `getRepository` in interface `ProjectData`
    Returns:
      null if the project is not associated with a repository

  - ### refresh

    public void refresh(boolean force)
    Description copied from interface: `ProjectData`
    Sync the Domain folder/file structure with the underlying file structure.
    Specified by:
      `refresh` in interface `ProjectData`
    Parameters:
      `force` - if true all folders will be visited and refreshed, if false only those folders previously visited will be refreshed.

  - ### convertProjectToShared

    public void convertProjectToShared(RepositoryAdapter newRepository, TaskMonitor monitor) throws IOException, CancelledException
    Description copied from interface: `ProjectData`
    Convert a local project to a shared project. NOTE: The project should be closed and then reopened after this method is called.
    Specified by:
      `convertProjectToShared` in interface `ProjectData`
    Parameters:
      `newRepository` - 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

    public void updateRepositoryInfo(RepositoryAdapter newRepository, boolean force, TaskMonitor monitor) throws IOException, CancelledException
    Description copied from interface: `ProjectData`
    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.
    Specified by:
      `updateRepositoryInfo` in interface `ProjectData`
    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

  - ### hasInvalidCheckouts

    public boolean hasInvalidCheckouts(List<DomainFile> checkoutList, RepositoryAdapter newRepository, TaskMonitor monitor) throws IOException, CancelledException
    Determine if any domain files listed does not correspond to a checkout in the specified newRespository.
    Specified by:
      `hasInvalidCheckouts` in interface `ProjectData`
    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

  - ### findCheckedOutFiles

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

  - ### getSharedProjectURL

    public URL getSharedProjectURL()
    Description copied from interface: `ProjectData`
    Generate a repository URL which corresponds to this project data if applicable. Local private projects will return null;
    Specified by:
      `getSharedProjectURL` in interface `ProjectData`
    Returns:
      repository URL which corresponds to this project data or null if not applicable.

  - ### getLocalProjectURL

    public URL getLocalProjectURL()
    Description copied from interface: `ProjectData`
    Generate a local URL which corresponds to this project data if applicable. Remote transient project data will return null;
    Specified by:
      `getLocalProjectURL` in interface `ProjectData`
    Returns:
      local URL which corresponds to this project data or null if not applicable.

  - ### getUserDataFilename

    public static String getUserDataFilename(String associatedFileID)
    Returns the standard user data filename associated with the specified file ID.
    Parameters:
      `associatedFileID` - the file id
    Returns:
      user data filename

  - ### makeValidName

    public String makeValidName(String name)
    Description copied from interface: `ProjectData`
    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.
    Specified by:
      `makeValidName` in interface `ProjectData`
    Parameters:
      `name` - original name to be sanitized
    Returns:
      valid name or "unknown" if no valid characters exist within name provided

  - ### getProjectDir

    public File getProjectDir()

  - ### isClosed

    public boolean isClosed()

  - ### isDisposed

    public boolean isDisposed()

  - ### close

    public void close()
    Description copied from interface: `ProjectData`
    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.
    Specified by:
      `close` in interface `ProjectData`

  - ### dispose

    protected void dispose()
    Immediately dispose this project data store instance. If this project has an associated `RepositoryAdapter` it will be disconnected as well. This method should generally not be used directly when there may be open `DomainObject` instances which may rely on an associated server connection. The `Object.clone()` method should be used when open `DomainObject` instances may exist and should be allowed to persist until they are closed.

  - ### updateFileIndex

    public void updateFileIndex(GhidraFileData fileData)
    Update the file index for the specified file data
    Parameters:
      `fileData` - file data

  - ### removeFromIndex

    public void removeFromIndex(String fileID)
    Remove specified fileID from index.
    Parameters:
      `fileID` - the file ID

  - ### getProjectDisposalMonitor

    public TaskMonitor getProjectDisposalMonitor()
    Get monitor which will be cancelled if project is closed
    Returns:
      cancel monitor