APIs for CAS Journaling

This extension to the CAS interface provides APIs to enable
tracking of CAS operations by component and APIs to access
the logged information.

When journaling is enabled, the following information related to CAS
operations will be logged:
1) Calling sequence of component As.
2) For each AE, a list of newly created feature structures (FSs) and a list of changes to pre-existing FSs.
3) For each AE, a list of added, deleted, and reindexed FSs in each index repository.

The Journal class obtained from the CAS provides accessed to the above information.
Although this initial proposal is based on the requirements for provenance tracking
as described here, the APIs are intended to be general and support any application that wants
to visualize or track CAS operations.

The proposed extension to the CAS interface and the new Journal interface are shown below:

Issues that needs discussion:

1) use of FS ids as a handle to FeatureStructure objects.
The proposed APIs return arrays of FS ids. Currently there are only LowLevelCAS APIs to
get a FeatureStructure object from a FS id.

2) should Journaling be enabled via a global setting ?

CAS Interface extension

/**
   * Gets an array of <code>Journal</code> objects one for each component that processed this
   * CAS.
   * The <code>Journal</code> object provides access to the  CAS and IndexRepository
   * updates made by a specific analysis component.
   *
   * @return Journal object
   */
  Journal[] getJournal();

  /**
   * Enable or disable journaling.
   *
   * Note: this method may only be called from an application. Calling it from an annotator
   * will trigger a runtime exception.   *
   * @param enable
   *
   */
  void enableJournaling(boolean enable);

Journal Interface   /**
* An instance of this class provides access to CAS and IndexRepository updates
* made by a specific analysis component.
*
*/
public interface Journal {

  /**
   * Gets the delegate key name assigned to the component. If this component is
   * not a delegate, the component name will be "TopLevel".
   * Note that when this info is returned from a service, TopLevel could be
   * replaced by the delegate name of this component in the client aggregate.
   * @return
   */
  String getComponentName();

  /**
   * Gets the call path to the component. This is the fully-qualified name obtained by calling
   * <code>UimaContextAdmin.getQualifiedContextName(</code> for this component. This is a
   * slash-separated name consisting of each containing context name back to the root.
   * For example, the context name for an annotator nested within two AnalysisEngines might look like:
   * <code>/MyTopLevelAnalysisEngine/MyComponentAnalysisEngine/MyAnnotator/</code>.
   * @return
   */
  String getComponentPath();

  /**
   * Returns an array of of ids representing new FSs added by this component
   * @return
   */
  int[] getNewFS();

  /**
   * Return an array of ids representing FSs whose feature values were modified
   * by this component.
   * @return
   */
  int[] geModifiedFS();

  /**
   * Returns an array of ids representing FSs added to the specified view.
   * If viewname is null, returns ids of FSs added to the default view.
   * @return
   */
  int[] getIndexAdd(String viewname);

  /**
   * Returns an array of ids representing FSs that were reindexed in the specified view.
   * If viewname is null, returns ids of FSs added to the default view.
   * @return
   */
  int[] getIndexModify(String viewname);

  /**
   * Returns a list of ids representing FSs that were removed from the specified view.
   * If viewname is null, returns ids of FSs add to the default view.
   * @return
   */
  int[] getIndexDelete(String viewname);

}

Child pages

1 Comment

Mike Barborak