Package ghidra.framework.data

# Class LinkHandler<T extends DomainObjectAdapterDB>

java.lang.Object
ghidra.framework.data.LinkHandler<T>

Type Parameters:
  `T` - `URLLinkObject` implementation class

All Implemented Interfaces:
  `ContentHandler<T>`, `ExtensionPoint`

Direct Known Subclasses:
  `DataTypeArchiveLinkContentHandler`, `DBTraceLinkContentHandler`, `FolderLinkContentHandler`, `ProgramLinkContentHandler`

public abstract class LinkHandler<T extends DomainObjectAdapterDB> extends Object implements ContentHandler<T>
NOTE: ALL ContentHandler implementations MUST END IN "ContentHandler". If not, the ClassSearcher will not find them. `LinkHandler` defines an application interface for handling domain files which are shortcut links to another supported content type.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `LinkHandler.LinkStatus`
  `LinkHandler.LinkStatus` provides a link evaluation for its ulimate type or if it is considered broken.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final Icon`
  `LINK_ICON`
  16x16 link icon where link is placed in lower-left corner
  `static final String`
  `URL_METADATA_KEY`
  Legacy linkPath metadata key for database storage

  ### Fields inherited from interface ghidra.framework.data.ContentHandler

  `MISSING_CONTENT, UNKNOWN_CONTENT`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `LinkHandler()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final long`
  `createFile(FileSystem fs, FileSystem userfs, String path, String name, DomainObject domainObject, TaskMonitor monitor)`
  Creates a new folder item within a specified file-system.
  `protected final void`
  `createLink(String linkPath, LocalFileSystem fs, String folderPath, String linkFilename)`
  Create a link file using the specified URL
  `static DomainFile`
  `followInternalLinkage(DomainFile file, Consumer<LinkHandler.LinkStatus> statusConsumer, Consumer<String> errorConsumer)`
  Follow the internal linkage, if any, for the specified file.
  `static String`
  `getAbsoluteLinkPath(DomainFile linkFile)`
  Get the Ghidra URL or absolute normalized link-path from a link file.
  `final ChangeSet`
  `getChangeSet(FolderItem versionedFolderItem, int olderVersion, int newerVersion)`
  Returns the object change data which includes changes made to the specified olderVersion through to the specified newerVersion.
  `final T`
  `getDomainObject(FolderItem item, FileSystem userfs, long checkoutId, boolean okToUpgrade, boolean okToRecover, Object consumer, TaskMonitor monitor)`
  Open a folder item for update.
  `abstract Icon`
  `getIcon()`
  Get the base icon for this link-file which does not include the link overlay icon.
  `T`
  `getImmutableObject(FolderItem item, Object consumer, int version, int minChangeVersion, TaskMonitor monitor)`
  Open a folder item for immutable use.
  `static LinkHandler.LinkStatus`
  `getLinkFileStatus(DomainFile file, Consumer<String> errorConsumer)`
  Determine the link status for the specified `link-file`.
  `LinkHandler<?>`
  `getLinkHandler()`
  If linking is supported return an instanceof the appropriate `LinkHandler`.
  `static URL`
  `getLinkURL(DomainFile linkFile)`
  Get the link URL which corresponds to the specified link file's link-path.
  `final DomainObjectMergeManager`
  `getMergeManager(DomainObject resultsObj, DomainObject sourceObj, DomainObject originalObj, DomainObject latestObj)`
  Get an instance of a suitable merge manager to be used during the merge of a Versioned object which has been modified by another user since it was last merged or checked-out.
  `final T`
  `getReadOnlyObject(FolderItem item, int version, boolean okToUpgrade, Object consumer, TaskMonitor monitor)`
  Open a folder item for read-only use.
  `final boolean`
  `isPrivateContentType()`
  Returns true if the content type is always private (i.e., can not be added to the versioned filesystem).

  ### Methods inherited from class java.lang.Object

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

  ### Methods inherited from interface ghidra.framework.data.ContentHandler

  `canResetDBSourceFile, getContentType, getContentTypeDisplayString, getDefaultToolName, getDomainObjectClass, resetDBSourceFile`

- ## Field Details

  - ### URL_METADATA_KEY

    public static final String URL_METADATA_KEY
    Legacy linkPath metadata key for database storage
    See Also:
      - Constant Field Values

  - ### LINK_ICON

    public static final Icon LINK_ICON
    16x16 link icon where link is placed in lower-left corner

- ## Constructor Details

  - ### LinkHandler

    public LinkHandler()

- ## Method Details

  - ### getLinkHandler

    public LinkHandler<?> getLinkHandler()
    Description copied from interface: `ContentHandler`
    If linking is supported return an instanceof the appropriate `LinkHandler`.
    Specified by:
      `getLinkHandler` in interface `ContentHandler<T extends DomainObjectAdapterDB>`
    Returns:
      corresponding link handler or null if not supported.

  - ### createLink

    protected final void createLink(String linkPath, LocalFileSystem fs, String folderPath, String linkFilename) throws IOException, InvalidNameException
    Create a link file using the specified URL
    Parameters:
      `linkPath` - link path or Ghidra URL.
      `fs` - filesystem where link file should be created
      `folderPath` - folder path which should contain link file
      `linkFilename` - link filename
    Throws:
      `IOException` - if an IO error occurs
      `InvalidNameException` - if invalid folderPath or linkFilename specified

  - ### createFile

    public final long createFile(FileSystem fs, FileSystem userfs, String path, String name, DomainObject domainObject, TaskMonitor monitor) throws IOException, InvalidNameException, CancelledException
    Description copied from interface: `ContentHandler`
    Creates a new folder item within a specified file-system. If fs is versioned, the resulting item is marked as checked-out within the versioned file-system. The specified domainObj will become associated with the newly created database.
    Specified by:
      `createFile` in interface `ContentHandler<T extends DomainObjectAdapterDB>`
    Parameters:
      `fs` - the file system in which to create the folder item
      `userfs` - file system which contains associated user data
      `path` - the path of the folder item
      `name` - the name of the new folder item
      `domainObject` - the domain object to store in the newly created folder item
      `monitor` - the monitor that allows the user to cancel
    Returns:
      checkout ID for new item
    Throws:
      `IOException` - if an IO error occurs or an unsupported `domainObject` implementation is specified.
      `InvalidNameException` - if the specified name contains invalid characters
      `CancelledException` - if the user cancels

  - ### getDomainObject

    public final T getDomainObject(FolderItem item, FileSystem userfs, long checkoutId, boolean okToUpgrade, boolean okToRecover, Object consumer, TaskMonitor monitor) throws IOException, CancelledException, VersionException
    Description copied from interface: `ContentHandler`
    Open a folder item for update. Changes made to the returned object may be saved to the original folder item.
    Specified by:
      `getDomainObject` in interface `ContentHandler<T extends DomainObjectAdapterDB>`
    Parameters:
      `item` - stored folder item
      `userfs` - file system which contains associated user data
      `checkoutId` - an appropriate checout ID required to update the specified folder item.
      `okToUpgrade` - if true a version upgrade to the content will be done if necessary.
      `okToRecover` - if true an attempt to recover any unsaved changes resulting from a crash will be attempted.
      `consumer` - consumer of the returned object
      `monitor` - cancelable task monitor
    Returns:
      updateable domain object
    Throws:
      `IOException` - if an IO or folder item access error occurs
      `CancelledException` - if operation is cancelled by user
      `VersionException` - if unable to handle file content due to version difference which could not be handled.

  - ### getReadOnlyObject

    public final T getReadOnlyObject(FolderItem item, int version, boolean okToUpgrade, Object consumer, TaskMonitor monitor) throws IOException, VersionException, CancelledException
    Description copied from interface: `ContentHandler`
    Open a folder item for read-only use. While changes are permitted on the returned object, the original folder item may not be overwritten / updated.
    Specified by:
      `getReadOnlyObject` in interface `ContentHandler<T extends DomainObjectAdapterDB>`
    Parameters:
      `item` - stored folder item
      `version` - version of the stored folder item to be opened. DomainFile.DEFAULT_VERSION should be specified when not opening a specific file version.
      `okToUpgrade` - if true a version upgrade to the content will be done if necessary.
      `consumer` - consumer of the returned object
      `monitor` - the monitor that allows the user to cancel
    Returns:
      read-only domain object
    Throws:
      `IOException` - if an IO or folder item access error occurs
      `VersionException` - if unable to handle file content due to version difference which could not be handled.
      `CancelledException` - if operation is cancelled by user

  - ### getImmutableObject

    public T getImmutableObject(FolderItem item, Object consumer, int version, int minChangeVersion, TaskMonitor monitor) throws IOException, CancelledException, VersionException
    Description copied from interface: `ContentHandler`
    Open a folder item for immutable use. If any changes are attempted on the returned object, an IllegalStateException state exception may be thrown.
    Specified by:
      `getImmutableObject` in interface `ContentHandler<T extends DomainObjectAdapterDB>`
    Parameters:
      `item` - stored folder item
      `consumer` - consumer of the returned object
      `version` - version of the stored folder item to be opened. DomainFile.DEFAULT_VERSION (-1) should be specified when not opening a specific file version.
      `minChangeVersion` - the minimum version which should be included in the change set for the returned object. A value of -1 indicates the default change set.
      `monitor` - the monitor that allows the user to cancel
    Returns:
      immutable domain object
    Throws:
      `IOException` - if an IO or folder item access error occurs
      `CancelledException` - if operation is cancelled by user
      `VersionException` - if unable to handle file content due to version difference which could not be handled.

  - ### getChangeSet

    public final ChangeSet getChangeSet(FolderItem versionedFolderItem, int olderVersion, int newerVersion) throws VersionException, IOException
    Description copied from interface: `ContentHandler`
    Returns the object change data which includes changes made to the specified olderVersion through to the specified newerVersion.
    Specified by:
      `getChangeSet` in interface `ContentHandler<T extends DomainObjectAdapterDB>`
    Parameters:
      `versionedFolderItem` - versioned folder item
      `olderVersion` - the older version number
      `newerVersion` - the newer version number
    Returns:
      the set of changes that were made
    Throws:
      `VersionException` - if a database version change prevents reading of data.
      `IOException` - if an IO or folder item access error occurs or change set was produced by newer version of software and can not be read

  - ### getMergeManager

    public final DomainObjectMergeManager getMergeManager(DomainObject resultsObj, DomainObject sourceObj, DomainObject originalObj, DomainObject latestObj)
    Description copied from interface: `ContentHandler`
    Get an instance of a suitable merge manager to be used during the merge of a Versioned object which has been modified by another user since it was last merged or checked-out.
    Specified by:
      `getMergeManager` in interface `ContentHandler<T extends DomainObjectAdapterDB>`
    Parameters:
      `resultsObj` - object to which merge results should be written
      `sourceObj` - object which contains user's changes to be merged
      `originalObj` - object which corresponds to checked-out version state
      `latestObj` - object which corresponds to latest version with which the sourceObj must be merged.
    Returns:
      merge manager

  - ### isPrivateContentType

    public final boolean isPrivateContentType()
    Description copied from interface: `ContentHandler`
    Returns true if the content type is always private (i.e., can not be added to the versioned filesystem).
    Specified by:
      `isPrivateContentType` in interface `ContentHandler<T extends DomainObjectAdapterDB>`
    Returns:
      true if private content type, else false

  - ### getIcon

    public abstract Icon getIcon()
    Get the base icon for this link-file which does not include the link overlay icon.
    Specified by:
      `getIcon` in interface `ContentHandler<T extends DomainObjectAdapterDB>`
    Returns:
      base icon to be used for a `DomainFile` with the associated content type.

  - ### getLinkURL

    public static URL getLinkURL(DomainFile linkFile) throws IOException
    Get the link URL which corresponds to the specified link file's link-path. If link-path was originally specified as an internal path it will be transformed into a URL. See `DomainFile.isLink()`.
    Parameters:
      `linkFile` - link-file domain file which may correspond to a linked-folder or file.
    Returns:
      link URL or null if invalid link-URL or a non-link-file is specified
    Throws:
      `IOException` - if linkFile has an invalid relative link-path that failed to normalize

  - ### getAbsoluteLinkPath

    public static String getAbsoluteLinkPath(DomainFile linkFile) throws IOException
    Get the Ghidra URL or absolute normalized link-path from a link file. Path normalization eliminates any path element of "./" or "../". A local folder-link path will always end with a "/" path separator. Path normalization is not performed on Ghidra URLs.
    Parameters:
      `linkFile` - link file
    Returns:
      Ghidra URL or absolute normalized link-path from a link file
    Throws:
      `IOException` - if linkFile has an invalid relative link-path that failed to normalize

  - ### getLinkFileStatus

    public static LinkHandler.LinkStatus getLinkFileStatus(DomainFile file, Consumer<String> errorConsumer)
    Determine the link status for the specified `link-file`. If a status is `LinkHandler.LinkStatus.BROKEN` and an `errorConsumer` has been specified the error details will be reported.
    Parameters:
      `file` - domain file
      `errorConsumer` - broken link error consumer (may be null)
    Returns:
      link status

  - ### followInternalLinkage

    public static DomainFile followInternalLinkage(DomainFile file, Consumer<LinkHandler.LinkStatus> statusConsumer, Consumer<String> errorConsumer)
    Follow the internal linkage, if any, for the specified file. Any broken linkage details will be reported to the specified `errorConsumer`.
    Parameters:
      `file` - domain file to be checked
      `statusConsumer` - link status consumer (required)
      `errorConsumer` - broken link error consumer (may be null)
    Returns:
      the final `DomainFile` within the same project or null if file specified was not a link-file. A broken link will return the last valid link-file in chain.