Package ghidra.framework.model

# Interface DomainFile

All Superinterfaces:
  `Comparable<DomainFile>`

All Known Subinterfaces:
  `LinkedDomainFile`

All Known Implementing Classes:
  `DomainFileProxy`, `GhidraFile`

public interface DomainFile extends Comparable<DomainFile>
`DomainFile` provides a storage interface for a project file. A domain file provides an immutable reference to a stored file contained within a project. The state of a file object does not track name/parent changes made to the referenced project file. An up-to-date object may be obtained from `ProjectData.getFile(String)`, `ProjectData.getFileByID(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 project where the methods `isLink()` and `getLinkInfo()` may be used to obtain more details about a link and in the case of a linked-folder can facilitate obtainining the referenced `LinkedGhidraFolder`. This information object can also be used to determine if the referenced file or folder is external to this file's project.

A link-file can become "broken" if its reference has one of the following conditions occur:

1. A referenced internal file or folder does not exist, or
2. the nature/content-type of the referenced file does not match the designated type when the link was created, or
3. the link has a circular reference path within this file's project.

The method `LinkFileInfo.getLinkStatus(java.util.function.Consumer)` may be used to determine if a link is "broken". Use of a broken link may result in an IOException or other failure. The domain object for a file-link (e.g., ProgramLink) may be obtained in the same manner as a normal file (e.g., `getDomainObject(Object, boolean, boolean, TaskMonitor)`. However, as with any file it is recommended that `getDomainObjectClass()` first be used to ensure the file corresponds to the expected/supported content type.

NOTE: Using external links to shared projects or repositories may result in required authentication; which in headless situations may be limited by the active authentication handler (see `LinkFileInfo.isExternalLink()` and `LinkFileInfo.getLinkStatus(java.util.function.Consumer)` for more details).

Link files can facilitate a link to either a folder or another file of a specific content type within a Ghidra project. Here's why someone might choose to use them:

- File Organization: links allow users to organize files and folders in a way that makes sense for their workflow without duplicating data. A single file can appear to exist in multiple locations without taking up additional space.
- Dynamic Updates: If the original file or folder is modified, the changes are automatically reflected wherever the link is used, ensuring consistency without manual updates.
- Shared Resources: links can be used to establish shortcuts to files stored in different repositories, projects or directories, enabling easy access without navigating deeply nested folder structures or replicating stored data.
- System Configuration: links can be used to link different versions of programs or libraries without changing paths.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `DEFAULT_VERSION`
  Use with getDomainObject to request the default version.
  `static final String`
  `READ_ONLY_PROPERTY`
  Event property name for Read-only setting.
  `static final Icon`
  `UNSUPPORTED_FILE_ICON`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addToVersionControl(String comment, boolean keepCheckedOut, TaskMonitor monitor)`
  Adds this private file to version control.
  `boolean`
  `canAddToRepository()`
  Returns true if this private file may be added to the associated repository.
  `boolean`
  `canCheckin()`
  Returns true if this file may be checked-in to the associated repository.
  `boolean`
  `canCheckout()`
  Returns true if this file may be checked-out from the associated repository.
  `boolean`
  `canMerge()`
  Returns true if this file can be merged with the current versioned file.
  `boolean`
  `canRecover()`
  Prior to invoking getDomainObject, this method can be used to determine if unsaved changes can be recovered on the next open.
  `boolean`
  `canSave()`
  Return whether this domain object can be saved (i.e., updated/overwritten).
  `default void`
  `checkin(CheckinHandler checkinHandler, boolean okToUpgrade, TaskMonitor monitor)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  use alternative `checkin(CheckinHandler, TaskMonitor)` method since okToUpgrade cannot be respected and is ignored.
  `void`
  `checkin(CheckinHandler checkinHandler, TaskMonitor monitor)`
  Performs check in to associated repository.
  `boolean`
  `checkout(boolean exclusive, TaskMonitor monitor)`
  Checkout this file for update.
  `DomainFile`
  `copyTo(DomainFolder newParent, TaskMonitor monitor)`
  Copy this file into the newParent folder as a private file.
  `DomainFile`
  `copyToAsLink(DomainFolder newParent, boolean relative)`
  Copy this file into the newParent folder as a file-link.
  `DomainFile`
  `copyVersionTo(int version, DomainFolder destFolder, TaskMonitor monitor)`
  Copy a specific version of this file to the specified destFolder.
  `void`
  `delete()`
  Delete the entire database for this file, including any version files.
  `void`
  `delete(int version)`
  Deletes a specific version of a file from the versioned filesystem.
  `boolean`
  `exists()`
  Check for existence of domain file.
  `ChangeSet`
  `getChangesByOthersSinceCheckout()`
  Returns changes made to versioned file by others since checkout was performed.
  `ItemCheckoutStatus[]`
  `getCheckouts()`
  Get a list of checkouts by all users for the associated versioned file.
  `ItemCheckoutStatus`
  `getCheckoutStatus()`
  Get checkout status associated with a versioned file.
  `List<?>`
  `getConsumers()`
  Get the list of consumers (Objects) for this domain file.
  `String`
  `getContentType()`
  Returns content-type string for this file
  `DomainObject`
  `getDomainObject(Object consumer, boolean okToUpgrade, boolean okToRecover, TaskMonitor monitor)`
  Opens and returns the current domain object.
  `Class<? extends DomainObject>`
  `getDomainObjectClass()`
  Returns the underlying Class for the domain object in this domain file.
  `String`
  `getFileID()`
  Returns a unique file-ID if one has been established or null.
  `Icon`
  `getIcon(boolean disabled)`
  Get the state based Icon image for the domain file based upon its content class.
  `DomainObject`
  `getImmutableDomainObject(Object consumer, int version, TaskMonitor monitor)`
  Returns a new DomainObject that cannot be changed or saved to its original file.
  `long`
  `getLastModifiedTime()`
  Get a long value representing the time when the data was last modified.
  `int`
  `getLatestVersion()`
  Return the latest version
  `LinkFileInfo`
  `getLinkInfo()`
  If this file is a `link-file` the link information will be returned.
  `URL`
  `getLocalProjectURL(String ref)`
  Get a local Ghidra URL for this domain file if available within the associated non-transient local project.
  `Map<String,String>`
  `getMetadata()`
  Returns an ordered map containing the metadata that has been associated with the corresponding domain object.
  `String`
  `getName()`
  Get the name of this project file
  `DomainObject`
  `getOpenedDomainObject(Object consumer)`
  Returns the domainObject for this DomainFile only if it is already open.
  `DomainFolder`
  `getParent()`
  Get the parent domain folder for this domain file.
  `String`
  `getPathname()`
  Returns the full path name to this file
  `ProjectLocator`
  `getProjectLocator()`
  Returns the local storage location for the project that this DomainFile belongs to.
  `DomainObject`
  `getReadOnlyDomainObject(Object consumer, int version, TaskMonitor monitor)`
  Returns a "read-only" version of the domain object.
  `URL`
  `getSharedProjectURL(String ref)`
  Get a remote Ghidra URL for this domain file if available within an associated shared project repository.
  `int`
  `getVersion()`
  Return either the latest version if the file is not checked-out or the version that was checked-out or a specific version that was requested.
  `Version[]`
  `getVersionHistory()`
  Returns list of all available versions.
  `boolean`
  `isBusy()`
  Returns true if the domain object in this domain file exists and has an open transaction.
  `boolean`
  `isChanged()`
  Return whether the domain object in this domain file has changed.
  `boolean`
  `isCheckedOut()`
  Returns true if this is a checked-out file.
  `boolean`
  `isCheckedOutExclusive()`
  Returns true if this a checked-out file with exclusive access.
  `boolean`
  `isHijacked()`
  Returns true if the file is versioned but a private copy also exists.
  `boolean`
  `isInWritableProject()`
  Returns true if this file is in a writable project.
  `boolean`
  `isLatestVersion()`
  Returns true if this file represents the latest version of the associated domain object.
  `boolean`
  `isLink()`
  Determine if this file is a link-file which corresponds to either a file or folder link.
  `boolean`
  `isLinkingSupported()`
  Determine if this file's content type supports linking.
  `boolean`
  `isOpen()`
  Returns true if there is an open domainObject for this file.
  `boolean`
  `isReadOnly()`
  Returns whether this file is explicitly marked as read-only.
  `boolean`
  `isVersioned()`
  Return true if this is a versioned database, else false
  `long`
  `length()`
  Returns the length of this domain file.
  `void`
  `merge(boolean okToUpgrade, TaskMonitor monitor)`
  Performs merge from current version of versioned file into local checked-out file.
  `boolean`
  `modifiedSinceCheckout()`
  Returns true if this is a checked-out file which has been modified since it was checked-out.
  `DomainFile`
  `moveTo(DomainFolder newParent)`
  Move this file into the newParent folder.
  `void`
  `packFile(File file, TaskMonitor monitor)`
  Pack domain file into specified file.
  `void`
  `save(TaskMonitor monitor)`
  Save the `DomainObject` associated with this file.
  `DomainFile`
  `setName(String newName)`
  Set the name on this domain file.
  `void`
  `setReadOnly(boolean state)`
  Sets the object to read-only.
  `boolean`
  `takeRecoverySnapshot()`
  If the file has an updatable domain object with unsaved changes, generate a recovery snapshot.
  `void`
  `terminateCheckout(long checkoutId)`
  Forcefully terminate a checkout for the associated versioned file.
  `void`
  `undoCheckout(boolean keep)`
  Undo "checked-out" file.
  `void`
  `undoCheckout(boolean keep, boolean force)`
  Undo "checked-out" file.

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

  `compareTo`

- ## Field Details

  - ### UNSUPPORTED_FILE_ICON

    static final Icon UNSUPPORTED_FILE_ICON

  - ### DEFAULT_VERSION

    static final int DEFAULT_VERSION
    Use with getDomainObject to request the default version. The default version is the private file or check-out file if one exists, or the latest version from the version controlled file system.
    See Also:
      - Constant Field Values

  - ### READ_ONLY_PROPERTY

    static final String READ_ONLY_PROPERTY
    Event property name for Read-only setting.
    See Also:
      - Constant Field Values

- ## Method Details

  - ### getName

    String getName()
    Get the name of this project file
    Returns:
      the name

  - ### exists

    boolean exists()
    Check for existence of domain file.
    Returns:
      true if file exists. A proxy domain file will always return false.

  - ### getFileID

    String getFileID()
    Returns a unique file-ID if one has been established or null. Examples which may result in null ID:
    - Very old project file which pre-dates introduction of file ID, or
    - Remote versioned file with lost connection
    Returns:
      the file-ID or null if failed to obtain ID.

  - ### setName

    DomainFile setName(String newName) throws InvalidNameException, IOException
    Set the name on this domain file.
    Parameters:
      `newName` - domain file name
    Returns:
      renamed domain file (the original DomainFile object becomes invalid since it is immutable)
    Throws:
      `InvalidNameException` - if newName contains illegal characters
      `DuplicateFileException` - if a file named newName already exists in this files domain folder.
      `FileInUseException` - if this file is in-use / checked-out.
      `IOException` - if an IO or access error occurs.

  - ### getPathname

    String getPathname()
    Returns the full path name to this file
    Returns:
      the path name

  - ### getSharedProjectURL

    URL getSharedProjectURL(String ref)
    Get a remote Ghidra URL for this domain file if available within an associated shared project repository. A null value will be returned if shared file does not exist and may also be returned if shared repository is not connected or a connection error occurs.
    Parameters:
      `ref` - reference within a file, may be null. NOTE: such reference interpretation is specific to a domain object and tooling with limited support.
    Returns:
      remote Ghidra URL for this file or null

  - ### getLocalProjectURL

    URL getLocalProjectURL(String ref)
    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.
    Parameters:
      `ref` - reference within a file, may be null. NOTE: such reference interpretation is specific to a domain object and tooling with limited support.
    Returns:
      local Ghidra URL for this file or null if transient or not applicable

  - ### getProjectLocator

    ProjectLocator getProjectLocator()
    Returns the local storage location for the project that this DomainFile belongs to.
    Returns:
      the location

  - ### getContentType

    String getContentType()
    Returns content-type string for this file
    Returns:
      the file content type or a reserved content type `ContentHandler.MISSING_CONTENT` or `ContentHandler.UNKNOWN_CONTENT`.

  - ### getDomainObjectClass

    Class<? extends DomainObject> getDomainObjectClass()
    Returns the underlying Class for the domain object in this domain file.
    Returns:
      the class or null if does not correspond to a domain object.

  - ### getParent

    DomainFolder getParent()
    Get the parent domain folder for this domain file.
    Returns:
      the parent

  - ### getChangesByOthersSinceCheckout

    ChangeSet getChangesByOthersSinceCheckout() throws VersionException, IOException
    Returns changes made to versioned file by others since checkout was performed. NOTE: This method is unable to cope with version issues which may require an upgrade.
    Returns:
      change set or null
    Throws:
      `VersionException` - latest version was created with a different version of software which prevents rapid determination of change set.
      `IOException` - if a folder item access error occurs or change set was produced by newer version of software and can not be read

  - ### getDomainObject

    DomainObject getDomainObject(Object consumer, boolean okToUpgrade, boolean okToRecover, TaskMonitor monitor) throws VersionException, IOException, CancelledException
    Opens and returns the current domain object. If the domain object is already opened, then the existing open domain object is returned.
    Parameters:
      `consumer` - consumer of the domain object which is responsible for releasing it after use. When all the consumers using the domain object release it, then the object is closed and its resources released.
      `okToUpgrade` - if true, allows the system to upgrade out of data domain objects to be in compliance with the current version of Ghidra. A Version exception will be thrown if the domain object cannot be upgraded OR okToUpgrade is false and the domain object is out of date.
      `okToRecover` - if true, allows the system to recover unsaved file changes which resulted from a crash. If false, any existing recovery data will be deleted. This flag is only relevant if project is open for update (isInProject) and the file can be opened for update.
      `monitor` - permits monitoring of open progress.
    Returns:
      an open domain object can be modified and saved. (Not read-only)
    Throws:
      `VersionException` - if the domain object could not be read due to a version format change. If okToUpgrade is true, then a VersionException indicates that the domain object cannot be upgraded to the current format. If okToUpgrade is false, then the VersionException only means the object is not in the current format - it may or may not be possible to upgrade.
      `IOException` - if an IO or access error occurs.
      `CancelledException` - if monitor cancelled operation

  - ### getOpenedDomainObject

    DomainObject getOpenedDomainObject(Object consumer)
    Returns the domainObject for this DomainFile only if it is already open.
    Parameters:
      `consumer` - the consumer that will use the object.
    Returns:
      the already opened domainObject or null if it is not currently open.

  - ### getReadOnlyDomainObject

    DomainObject getReadOnlyDomainObject(Object consumer, int version, TaskMonitor monitor) throws VersionException, IOException, CancelledException
    Returns a "read-only" version of the domain object. "Read-only" means that the domain object cannot be saved back into its original domain object. It can still be modified and saved to a new domain file. The domain object will be assigned a temporary domain file that will not allow a "save" operation. The user must do a "save as" to a new filename.
    Parameters:
      `consumer` - consumer of the domain object which is responsible for releasing it after use.
      `version` - the domain object version requested. DEFAULT_VERSION should be specified to open the current version.
      `monitor` - permits monitoring of open progress.
    Returns:
      a new domain object that is disassociated from its original domain file.
    Throws:
      `VersionException` - if the domain object could not be read due to a version format change.
      `FileNotFoundException` - if the stored file/version was not found.
      `IOException` - if an IO or access error occurs.
      `CancelledException` - if monitor cancelled operation

  - ### getImmutableDomainObject

    DomainObject getImmutableDomainObject(Object consumer, int version, TaskMonitor monitor) throws VersionException, IOException, CancelledException
    Returns a new DomainObject that cannot be changed or saved to its original file. NOTE: The use of this method should generally be avoided since it can't handle version changes that may have occured and require a data upgrade (e.g., DB schema change).
    Parameters:
      `consumer` - consumer of the domain object which is responsible for releasing it after use.
      `version` - the domain object version requested. DEFAULT_VERSION should be specified to open the current version.
      `monitor` - permits monitoring of open progress.
    Returns:
      a new domain object that is disassociated from its original domain file and cannot be modified
    Throws:
      `VersionException` - if the domain object could not be read due to a version format change.
      `FileNotFoundException` - if the stored file/version was not found.
      `IOException` - if an IO or access error occurs.
      `CancelledException` - if monitor cancelled operation

  - ### save

    void save(TaskMonitor monitor) throws IOException, CancelledException
    Save the `DomainObject` associated with this file.
    Parameters:
      `monitor` - monitor for the task that is doing the save on the file
    Throws:
      `FileInUseException` - if the file is open for update by someone else, or a transient-read is in progress.
      `IOException` - if an IO error occurs.
      `CancelledException` - if monitor cancelled operation

  - ### canSave

    boolean canSave()
    Return whether this domain object can be saved (i.e., updated/overwritten).
    Returns:
      true if the user is the owner AND the file is in the active project AND the file is not read-only.

  - ### canRecover

    boolean canRecover()
    Prior to invoking getDomainObject, this method can be used to determine if unsaved changes can be recovered on the next open.
    Returns:
      true if recovery data exists.

  - ### takeRecoverySnapshot

    boolean takeRecoverySnapshot() throws IOException
    If the file has an updatable domain object with unsaved changes, generate a recovery snapshot.
    Returns:
      true if snapshot successful or not needed, false if file is busy which prevents snapshot, or snapshot was cancelled.
    Throws:
      `IOException` - if there is an exception saving the snapshot

  - ### isInWritableProject

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

  - ### getLastModifiedTime

    long getLastModifiedTime()
    Get a long value representing the time when the data was last modified.
    Returns:
      the time

  - ### getIcon

    Icon getIcon(boolean disabled)
    Get the state based Icon image for the domain file based upon its content class.
    Parameters:
      `disabled` - true if the icon return should be rendered as not enabled
    Returns:
      image icon

  - ### isCheckedOut

    boolean isCheckedOut()
    Returns true if this is a checked-out file.
    Returns:
      true if checked-out

  - ### isCheckedOutExclusive

    boolean isCheckedOutExclusive()
    Returns true if this a checked-out file with exclusive access.
    Returns:
      true if checked-out exclusively

  - ### modifiedSinceCheckout

    boolean modifiedSinceCheckout()
    Returns true if this is a checked-out file which has been modified since it was checked-out.
    Returns:
      true if modified since check-out

  - ### canCheckout

    boolean canCheckout()
    Returns true if this file may be checked-out from the associated repository. User's with read-only repository access will not have checkout ability.
    Returns:
      true if can checkout

  - ### canCheckin

    boolean canCheckin()
    Returns true if this file may be checked-in to the associated repository. Note: this does not take into consideration cases where the file is currently in-use which may cause a failure if a checkin is attempted.
    Returns:
      true if a check-in can be attempted (i.e., file is checked-out with changes), else false

  - ### canMerge

    boolean canMerge()
    Returns true if this file can be merged with the current versioned file. Note: this does not take into consideration cases where the file is currently in-use which may cause a failure if a merge is attempted.
    Returns:
      true if a merge can be attempted (i.e., file is checked-out and a newer version exists), else false

  - ### canAddToRepository

    boolean canAddToRepository()
    Returns true if this private file may be added to the associated repository. Note: this does not take into consideration cases where the file is currently in-use which may cause a failure if add to repository is attempted.
    Returns:
      true if add to the repository can be attempted (i.e., file in active project is not versioned or hijacked)

  - ### setReadOnly

    void setReadOnly(boolean state) throws IOException
    Sets the object to read-only. This method may only be invoked for private files (i.e., not versioned).
    Parameters:
      `state` - if true file will be read-only and may not be updated, if false the file may be updated.
    Throws:
      `IOException` - if an IO error occurs.

  - ### isReadOnly

    boolean isReadOnly()
    Returns whether this file is explicitly marked as read-only. This method is only supported by the local file system and does not apply to a versioned file that is not checked-out. A versioned file that is not checked-out will always return false, while a `DomainFileProxy` will always return true. From a framework point of view a read-only file can never be changed.
    Returns:
      true if this file is marked read-only

  - ### isVersioned

    boolean isVersioned()
    Return true if this is a versioned database, else false
    Returns:
      true if versioned

  - ### isHijacked

    boolean isHijacked()
    Returns true if the file is versioned but a private copy also exists.
    Returns:
      true if hijacked

  - ### getLatestVersion

    int getLatestVersion()
    Return the latest version
    Returns:
      the version

  - ### isLatestVersion

    boolean isLatestVersion()
    Returns true if this file represents the latest version of the associated domain object.
    Returns:
      true if the latest version

  - ### getVersion

    int getVersion()
    Return either the latest version if the file is not checked-out or the version that was checked-out or a specific version that was requested.
    Returns:
      the version

  - ### getVersionHistory

    Version[] getVersionHistory() throws IOException
    Returns list of all available versions.
    Returns:
      the versions
    Throws:
      `IOException` - if there is an exception getting the history

  - ### addToVersionControl

    void addToVersionControl(String comment, boolean keepCheckedOut, TaskMonitor monitor) throws IOException, CancelledException
    Adds this private file to version control.
    Parameters:
      `comment` - new version comment
      `keepCheckedOut` - if true, the file will be initially checked-out. This option will be ignored if file is currently open in which case file will remain checked-out.
      `monitor` - progress monitor
    Throws:
      `FileInUseException` - if this file is in-use.
      `IOException` - if an IO or access error occurs. Also if file is not private.
      `CancelledException` - if the monitor cancelled the operation

  - ### checkout

    boolean checkout(boolean exclusive, TaskMonitor monitor) throws IOException, CancelledException
    Checkout this file for update. If this file is already private, this method does nothing.
    Parameters:
      `exclusive` - if true an exclusive checkout will be requested
      `monitor` - progress monitor
    Returns:
      true if checkout successful, false if an exclusive checkout was not possible due to other users having checkouts of this file. A request for a non-exclusive checkout will never return false.
    Throws:
      `IOException` - if an IO or access error occurs.
      `CancelledException` - if task monitor cancelled operation.

  - ### checkin

    void checkin(CheckinHandler checkinHandler, TaskMonitor monitor) throws IOException, VersionException, CancelledException
    Performs check in to associated repository. File must be checked-out and modified since checkout.
    Parameters:
      `checkinHandler` - provides user input data to complete checkin process. The keep-checked-out option supplied by this handler will be ignored if file is currently open in which case file will remain checked-out.
      `monitor` - the TaskMonitor.
    Throws:
      `IOException` - if an IO or access error occurs
      `VersionException` - if unable to handle domain object version in versioned filesystem. We are unable to upgrade since this would only occur if checkout is not exclusive.
      `CancelledException` - if task monitor cancelled operation

  - ### checkin

    @Deprecated(since="11.1", forRemoval=true) default void checkin(CheckinHandler checkinHandler, boolean okToUpgrade, TaskMonitor monitor) throws IOException, VersionException, CancelledException
    Deprecated, for removal: This API element is subject to removal in a future version.
    use alternative `checkin(CheckinHandler, TaskMonitor)` method since okToUpgrade cannot be respected and is ignored. Upgrade cannot be performed during checkin.
    Performs check in to associated repository. File must be checked-out and modified since checkout.
    Parameters:
      `checkinHandler` - provides user input data to complete checkin process. This keep-checked-out option supplied by this handler will be ignored and forced true if file is currently open.
      `okToUpgrade` - if true an upgrade will be performed if needed (ignored)
      `monitor` - the TaskMonitor.
    Throws:
      `IOException` - if an IO or access error occurs
      `VersionException` - if unable to handle domain object version in versioned filesystem. If okToUpgrade was false, check exception to see if it can be upgraded sometime after doing a checkout.
      `CancelledException` - if task monitor cancelled operation

  - ### merge

    void merge(boolean okToUpgrade, TaskMonitor monitor) throws IOException, VersionException, CancelledException
    Performs merge from current version of versioned file into local checked-out file.
    Parameters:
      `okToUpgrade` - if true an upgrade will be performed if needed
      `monitor` - task monitor
    Throws:
      `IOException` - if an IO or access error occurs
      `VersionException` - if unable to handle domain object version in versioned filesystem. If okToUpgrade was false, check exception to see if it can be upgraded
      `CancelledException` - if task monitor cancelled operation

  - ### undoCheckout

    void undoCheckout(boolean keep) throws IOException
    Undo "checked-out" file. The original repository file is restored.
    Parameters:
      `keep` - if true, the private database will be renamed with a .keep extension.
    Throws:
      `NotConnectedException` - if shared project and not connected to repository
      `FileInUseException` - if this file is in-use.
      `IOException` - if file is not checked-out or an IO / access error occurs.

  - ### undoCheckout

    void undoCheckout(boolean keep, boolean force) throws IOException
    Undo "checked-out" file. The original repository file is restored.
    Parameters:
      `keep` - if true, the private database will be renamed with a .keep extension.
      `force` - if not connected to the repository the local checkout file will be removed. Warning: forcing undo checkout will leave a stale checkout in place for the associated repository if not connected.
    Throws:
      `NotConnectedException` - if shared project and not connected to repository and force is false
      `FileInUseException` - if this file is in-use / checked-out.
      `IOException` - thrown if file is not checked-out or an IO / access error occurs.

  - ### terminateCheckout

    void terminateCheckout(long checkoutId) throws IOException
    Forcefully terminate a checkout for the associated versioned file. The user must be the owner of the checkout or have administrator privilege on the versioned filesystem (i.e., repository).
    Parameters:
      `checkoutId` - checkout ID
    Throws:
      `IOException` - if an IO or access error occurs

  - ### getCheckouts

    ItemCheckoutStatus[] getCheckouts() throws IOException
    Get a list of checkouts by all users for the associated versioned file.
    Returns:
      list of checkouts
    Throws:
      `IOException` - if an IO or access error occurs

  - ### getCheckoutStatus

    ItemCheckoutStatus getCheckoutStatus() throws IOException
    Get checkout status associated with a versioned file.
    Returns:
      checkout status or null if not checked-out to current associated project.
    Throws:
      `IOException` - if an IO or access error occurs

  - ### delete

    void delete() throws IOException
    Delete the entire database for this file, including any version files.
    Throws:
      `FileInUseException` - if this file is in-use / checked-out.
      `UserAccessException` - if the user does not have permission to delete the file.
      `IOException` - if an IO or access error occurs.

  - ### delete

    void delete(int version) throws IOException
    Deletes a specific version of a file from the versioned filesystem.
    Parameters:
      `version` - specific version to be deleted. The version must either be the oldest or latest, or -1 which will attempt to remove all versions. When deleting the latest version, this method could take a long time to return since the previous version must be reconstructed within the versioned filesystem.
    Throws:
      `IOException` - if an IO error occurs, including the inability to delete a version because this item is checked-out, the user does not have permission, or the specified version is not the oldest or latest.

  - ### moveTo

    DomainFile moveTo(DomainFolder newParent) throws IOException
    Move this file into the newParent folder.
    Parameters:
      `newParent` - new parent folder within the same project
    Returns:
      the newly relocated domain file (the original DomainFile object becomes invalid since it is immutable)
    Throws:
      `DuplicateFileException` - if a file with the same name already exists in newParent folder.
      `FileInUseException` - if this file is in-use / checked-out.
      `IOException` - if an IO or access error occurs.

  - ### copyTo

    DomainFile copyTo(DomainFolder newParent, TaskMonitor monitor) throws IOException, CancelledException
    Copy this file into the newParent folder as a private file.
    Parameters:
      `newParent` - new parent folder
      `monitor` - task monitor
    Returns:
      newly created domain file
    Throws:
      `FileInUseException` - if this file is in-use / checked-out.
      `IOException` - if an IO or access error occurs.
      `CancelledException` - if task monitor cancelled operation.

  - ### copyVersionTo

    DomainFile copyVersionTo(int version, DomainFolder destFolder, TaskMonitor monitor) throws IOException, CancelledException
    Copy a specific version of this file to the specified destFolder.
    Parameters:
      `version` - version to copy
      `destFolder` - destination parent folder
      `monitor` - task monitor
    Returns:
      the copied file
    Throws:
      `IOException` - if an IO or access error occurs.
      `CancelledException` - if task monitor cancelled operation.

  - ### copyToAsLink

    DomainFile copyToAsLink(DomainFolder newParent, boolean relative) throws IOException
    Copy this file into the newParent folder as a file-link. A file-link references another file without actually copying all of its content. If this file is associated with a temporary transient project (i.e., not a locally managed project) the generated link will refer to the this file with a Ghidra URL. If this file is contained within the same active `ProjectData` instance as `newParent` an internal link reference will be made.
    Parameters:
      `newParent` - new parent folder
      `relative` - if true, and this file is contained within the same active `ProjectData` instance as `newParent`, an internal-project relative path file-link will be created.
    Returns:
      newly created domain file or null if content type does not support link use.
    Throws:
      `IOException` - if an IO or access error occurs.

  - ### isLinkingSupported

    boolean isLinkingSupported()
    Determine if this file's content type supports linking.
    Returns:
      true if linking is supported, else false.

  - ### getConsumers

    List<?> getConsumers()
    Get the list of consumers (Objects) for this domain file.
    Returns:
      true if linking is supported allowing a link-file to be created which references this file, else false.

  - ### isChanged

    boolean isChanged()
    Return whether the domain object in this domain file has changed.
    Returns:
      true if changed

  - ### isOpen

    boolean isOpen()
    Returns true if there is an open domainObject for this file.
    Returns:
      true if open

  - ### isBusy

    boolean isBusy()
    Returns true if the domain object in this domain file exists and has an open transaction.
    Returns:
      true if busy

  - ### packFile

    void packFile(File file, TaskMonitor monitor) throws IOException, CancelledException
    Pack domain file into specified file. Specified file will be overwritten if it already exists.
    Parameters:
      `file` - destination file
      `monitor` - the task monitor
    Throws:
      `IOException` - if there is an exception packing the file
      `CancelledException` - if monitor cancels operation

  - ### getMetadata

    Map<String,String> getMetadata()
    Returns an ordered map containing the metadata that has been associated with the corresponding domain object. The map contains key,value pairs and are ordered by their insertion order.
    Returns:
      a map containing the metadata that has been associated with the corresponding domain object.

  - ### length

    long length() throws IOException
    Returns the length of this domain file. This size is the minimum disk space used for storing this file, but does not account for additional storage space used to track changes, etc.
    Returns:
      file length
    Throws:
      `IOException` - if IO or access error occurs

  - ### isLink

    boolean isLink()
    Determine if this file is a link-file which corresponds to either a file or folder link. See `getLinkInfo()` to obtain link information.

    If the link-file is a `folder-link` the method `LinkFileInfo.getLinkedFolder()` can be used to get the linked domain folder where the resulting folder's `DomainFolder.isLinked()` indicates that it was the result of following a folder-link.

    The associated link path/URL may be obtained with `LinkFileInfo.getLinkPath()`.

    The content type (see `getContentType()` of a link-file will differ from that of the linked object (e.g., "LinkedProgram" vs "Program"). It is highly recommended that the `getDomainObjectClass()` method be used instead since it will return the same value for a normal file or link-file that corresponds to the same `DomainObject` implementation.

    The `DomainObject` referenced by a link-file may be opened using `getReadOnlyDomainObject(Object, int, TaskMonitor)`. The `getDomainObject(Object, boolean, boolean, TaskMonitor)` method may also be used to obtain a read-only instance. These methods should not be used on a folder-link since an `UnsupportedOperationException` will be thrown.

    Returns:
      true if link file else false for a normal domain file

  - ### getLinkInfo

    LinkFileInfo getLinkInfo()
    If this file is a `link-file` the link information will be returned.
    Returns:
      link information or null if this is not a link-file