Obsolete Proposal for CAS and CAS View Interface Redesign

IMPORTANT: This proposal did not acheive a consensus among developers and will not be implemented. It is being left here only for informational purposes, so that we might refer to it in any future redesign.

This page lists the methods on each interface in the proposed redesign. For rationale and discussion see http://www.mail-archive.com/uima-dev@incubator.apache.org/msg00945.html.

"D-" before a method name indicates that the method is deprecated.

New methods, deleted methods, and methods with changed return types are specifically noted.

CommonCas

  • CONSTANTS
  • D- addFsToIndexes(FS)
  • createFeaturePath()
  • createFeatureValuePath()
  • createFilteredIterator(FSIterator, FSMatchConstraint)
  • fs2listIterator(FSIterator)
  • getConstraintFactory()
  • D- getDocumentLanaguage()
  • D- getDocumentText()
  • D- getIndexRepository()
  • D- getSofaDataArray()
  • D- getSofaDataStream()
  • D- getSofaDataURI()
  • getSofaIterator()
  • D- getViewName()
  • D- removeFsFromIndexes(FS)
  • reset()
  • D- setDocumentLanguage(String)
  • D- setDocumentText(String)
  • D- setSofaDataArray(FeatureStrucutre, String)
  • D- setSofaDataString(String, String)
  • D- setSofaDataURI(String, String)
  • size()

Deleted

  • D- createSofa(SofaID, String) [deprecated since 2.0, and this proposal breaks compatibility for multi-sofa code anyway}

CommonCasView

  • addFsToIndexes(FS)
  • getDocumentLanaguage()
  • getDocumentText()
  • getIndexRepository()
  • getSofaDataArray()
  • getSofaDataStream()
  • getSofaDataURI()
  • getViewName()
  • removeFsFromIndexes(FS)
  • setDocumentLanguage(String)
  • setDocumentText(String)
  • setSofaDataArray(FeatureStrucutre, String)
  • setSofaDataString(String, String)
  • setSofaDataURI(String, String)

CAS

(extends CommonCas)

  • D- createAnnotation(Type, int, int)
  • createArrayFS(int)
  • createBooleanArrayFS(int)
  • createDoubleArrayFS(int)
  • createFloatArrayFS(int)
  • createFS(Type)
  • createIntArrayFS(int)
  • createLongArrayFS(int)
  • createStringArrayFS(int)
  • createView(String) [CHANGED - now returns type CasView]
  • D- getAnnotationIndex()
  • D- getAnnotationIndex(Type)
  • getAnnotationType()
  • getBeginFeature()
  • D- getDocumentAnnotation()
  • getEndFeature()
  • getJCas()
  • getLowLevelCAS()
  • D- getSofa()
  • getView(SofaFS) [CHANGED - now returns type CasView]
  • getView(String) [CHANGED - now returns type CasView]
  • setCurrentComponentInfo(ComponentInfo)
  • getCurrentView() [NEW]
  • createAnnotation(Type, int, int, SofaFS) [NEW]

Deleted

  • getJCas(SofaFS) [can be replaced by getView(SofaFS).getJCas()]
  • D- getJCas(SofaID) [deprecated since 2.0]
  • D- getSofa(SofaID) [deprecated since 2.0]
  • D- getTCAS() [deprecated since 2.0, replaced by getView()]
  • D- getTCAS(SofaFS) [deprecated since 2.0, replaced by getView(String)]

CasView

(extends CommonCasView)

  • createAnnotation(Type, int, int)
  • getAnnotationIndex()
  • getAnnotationIndex(Type)
  • getDocumentAnnotation()
  • getSofa()
  • getCAS() [NEW - gets the CAS that contains this view)

Also we will add the following convenience methods that forward to the same method on CAS (this is still the subject of some debate)

  • createArrayFS(int)
  • createBooleanArrayFS(int)
  • createDoubleArrayFS(int)
  • createFloatArrayFS(int)
  • createFS(Type)
  • createIntArrayFS(int)
  • createLongArrayFS(int)
  • createStringArrayFS(int)

JCas

(extends CommonCas)

  • checkArrayBounds(int ,int)
  • createView(String)
  • getCas()
  • getCasImpl()
  • getCasType(int)
  • D- getDocumentAnnotation() [deprecated since 1.4]
  • D- getDocumentAnnotationFs()
  • getFloatArray0L()
  • getFSArray0L()
  • D- getFSIndexRepository()
  • getIntegerArray0L()
  • getJfsFromCaddr(int)
  • D- getJFSIndexRepository()
  • getLowLevelCas()
  • getLowLevelIndexRepository()
  • getRequiredFeature(Type, String)
  • getRequiredFeatureDE(Type, String, String, boolean)
  • getRequiredType(String)
  • D- getSofa()
  • getStringArray0L()
  • getType(int)
  • D- getType(TOP) [was already deprecated - time to remove yet??]
  • getView(SofaFS) [CHANGED - now returns type JCasView]
  • getView(String) [CHANGED - now returns type JCasView]
  • D- processInit() [was already deprecated - time to remove yet??]
  • putJfsFromCaddr(int, FeatureStructure)
  • getCurrentView() [NEW]

Deleted

  • getJCas(Sofa) [replaced by getView(Sofa)]
  • D- getSofa(SofaID) [deprecated since 2.0]
  • getTypeSystem() [not necessary to define on JCas since it is already on CommonCas]

JCasView

(extends CommonCasView)

  • getDocumentAnnotationFs()
  • getJFSIndexRepository()
  • getSofa()
  • getJCas() [NEW - gets the JCas that contains this view)

LowLevelCAS

It's not clear exactly what to do with the Low Level CAS APIs. There don't appear to be Sofa data access APIs here, so I think we could just do only the following changes:

  • Deprecate ll_getIndexRepository()
  • Add ll_getView(String) [return type LowLevelCasView]
  • Add ll_getCurrentView() [return type LowLevelCasView]
  • Change return type of ll_getSofaCasView(int) to LowLevelCasView
  • Define new interface LowLevelCasView with just one method: ll_getIndexRepository()

Or, perhaps simpler would be to not define a LowLevelCasView interface at all but just add to LowLevelCAS the method:
ll_getIndexRepository(String viewName)

JCAS-generated Cover Classes

This is still under some debate. The main issues are:

  1. What view does TOP.addToIndexes() add to?
  2. What Sofa does new Annotation(JCas) refer to?

A rough proposal, not yet agreed upon:

  1. deprecate TOP.addToIndexes(). Document that it's here only to
    provide compatibility with older single-sofa code, and does not
    support multi-sofa code. Suggest that users migrate to
    JCasView.addFsToIndexes(fs) instead.
  1. Add the constructors AnnotationBase(JCas, Sofa) and
    AnnotationBase(JCasView). These set the sofa pointer of the new
    annotation appropriately.
  1. Deprecate the constructor AnnotationBase(JCas). It always sets the
    Sofa reference to the "current view" and does not support multi-sofa
    code. Users should migrate to one of the other constructors.
  1. Apply the above changes to all subclasses of AnnotationBase, and
    update JCasGen to generate the appropriate constructors for subclasses
    of AnnotationBase.
  1. Either we enhance our migration utility so that it makes these
    constructor changes automatically, or we require users to rerun
    JCasGen when the migrate to Apache. The latter is starting to not
    sound like such a bad thing. In any case, custom constructors that a
    user added would need to be manually addressed by the user.
  • No labels

4 Comments

  1. Thilo Goetz

    I would propose the following changes:

    • Leave createFeaturePath() and friends at the CAS. These methods require/return CAS-specific data structures and don't need to be accessible anywhere else.
    • On CasView, remove getJCasView() and getLowLevelCasView(). Those should be accessed from the JCas and LowLevelCas, respectively.
    • Similarly, on JCasView, remove getCasView() and getLowLevelCasView().
    • On the JCas interface, can we remove some of the APIs and just make them available on the impl object? I'm thinking of things like putJfsFromCaddr(int, FeatureStructure) and getType(int).

    --Thilo

  2. Marshall Schor

    Re: JCas Interface:

    • putJfsFromCaddr(int, FeaturesStructure) - this is only used by the generated JCas code, not by a user directly. Things like this belong in the "impl", I agree.
    • getType(int) is a somewhat frequently used user method - used as getType(MyJCasType.type) - to allow the user to quickly/efficiently get the "type handle" corresponding to his JCas Type for the APIs that need that object. So I would leave this in the interface.

  3. Adam P. Lally

    Made the following changes:

    • Implemented Thilo's second and third suggestions.
    • Added method CAS.createAnnotation(Type,int,int,SofaFS) as discussed on uima-dev list
    • Added some discussion of LowLevelCAS at the end of the page

  4. Adam P. Lally

    Made the following changes:

    • Added FS-creation convenience methods to CasView, with a note that this is still under debate. However this seems to be the majority view so I thought it was appropriate to add it.
    • Added a section on what to do with the JCasGen-erated cover classes. This is also still under debate.