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.

  • Field Details

    • URL_METADATA_KEY

      public static final String URL_METADATA_KEY
      Legacy linkPath metadata key for database storage
      See Also:

  • 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.