Package ghidra.framework.data

Interface ContentHandler<T extends DomainObjectAdapter>

Type Parameters:
T - DomainObjectAdapter implementation class
All Superinterfaces:
ExtensionPoint
All Known Implementing Classes:
DataTypeArchiveContentHandler, DataTypeArchiveLinkContentHandler, DBContentHandler, DBWithUserDataContentHandler, FolderLinkContentHandler, LinkHandler, ProgramContentHandler, ProgramLinkContentHandler
public interface ContentHandler<T extends DomainObjectAdapter> extends ExtensionPoint
NOTE: ALL ContentHandler implementations MUST END IN "ContentHandler". If not, the ClassSearcher will not find them. ContentHandler defines an application interface for converting between a specific domain object implementation and folder item storage. This interface also defines a method which provides an appropriate icon corresponding to the content.

  • Field Details

  • Method Details

    • createFile

      long createFile(FileSystem fs, FileSystem userfs, String path, String name, DomainObject domainObject, TaskMonitor monitor) throws IOException, InvalidNameException, CancelledException
      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.
      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

    • getImmutableObject

      T getImmutableObject(FolderItem item, Object consumer, int version, int minChangeVersion, TaskMonitor monitor) throws IOException, CancelledException, VersionException
      Open a folder item for immutable use. If any changes are attempted on the returned object, an IllegalStateException state exception may be thrown.
      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.

    • getReadOnlyObject

      T getReadOnlyObject(FolderItem item, int version, boolean okToUpgrade, Object consumer, TaskMonitor monitor) throws IOException, VersionException, CancelledException
      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.
      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
      CancelledException - if operation is cancelled by user
      VersionException - if unable to handle file content due to version difference which could not be handled.

    • getDomainObject

      T getDomainObject(FolderItem item, FileSystem userfs, long checkoutId, boolean okToUpgrade, boolean okToRecover, Object consumer, TaskMonitor monitor) throws IOException, CancelledException, VersionException
      Open a folder item for update. Changes made to the returned object may be saved to the original folder item.
      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.

    • getChangeSet

      ChangeSet getChangeSet(FolderItem versionedFolderItem, int olderVersion, int newerVersion) throws VersionException, IOException
      Returns the object change data which includes changes made to the specified olderVersion through to the specified newerVersion.
      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

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

      boolean isPrivateContentType()
      Returns true if the content type is always private (i.e., can not be added to the versioned filesystem).
      Returns:
      true if private content type, else false

    • getContentType

      String getContentType()
      Returns a unique content-type identifier
      Returns:
      content type identifier for associated domain object(s).

    • getContentTypeDisplayString

      String getContentTypeDisplayString()
      A string that is meant to be presented to the user.
      Returns:
      user friendly content type for associated domain object(s).

    • getIcon

      Icon getIcon()
      Returns the Icon associated with this handlers content type.
      Returns:
      base icon to be used for a DomainFile with the associated content type.

    • getDefaultToolName

      String getDefaultToolName()
      Returns the name of the default tool/template that should be used to open this content type.
      Returns:
      associated default tool name for this content type

    • getDomainObjectClass

      Class<T> getDomainObjectClass()
      Returns domain object implementation class supported.
      Returns:
      implementation class for the associated DomainObjectAdapter implementation.

    • getLinkHandler

      default LinkHandler<?> getLinkHandler()
      If linking is supported return an instanceof the appropriate LinkHandler.
      Returns:
      corresponding link handler or null if not supported.

    • canResetDBSourceFile

      default boolean canResetDBSourceFile()
      Determine if this content handler supports the use of resetDBSourceFile(FolderItem, DomainObjectAdapterDB) .

      A versioned domain object open for update may have its underlying database reset to the latest buffer file version:

      1. The resetDBSourceFile(FolderItem, DomainObjectAdapterDB) method is invoked (synchronized on filesystem) to reset the underlying database source file and and any corresponding change sets held by the specified domain object to the latest version,
      2. afterwhich the caller must invalidate the domain object instance which will clear all caches and generate a DomainObjectEvent.RESTORED event.
      Returns:
      true if this content handler supports DB source file replacement, else false

    • resetDBSourceFile

      default void resetDBSourceFile(FolderItem item, DomainObjectAdapterDB domainObj) throws IOException
      Reset the database for the specified domain object to its latest buffer file version. It is very important that the specified folder item matches the item which was used to originally open the specified domain object. This method should be invoked with a filesystem lock.

      Following the invocation of this method, the specified domain object should be invalidated without a filesystem lock.

      Parameters:
      item - local versioned database folder item currently checked-out. An error will be thrown if not an instanceof LocalDatabaseItem. This should always be the case for an item which has just processed a versioning action with a retained checkout (e.g., checkin, merge, add-to-version-control).
      domainObj - domain object which is currently open for update
      Throws:
      IOException - if an IO error occurs
      IllegalArgumentException - if invalid or unsupported arguments are provided