This page discusses use cases and operation in V3 related to migrating V2 JCas classes to V3 and handling PEAR files which have embedded JCas classes.

Reporting and Automated Conversions

When a user starts running a pipeline (or calls some other UIMA API operations, see section under "When"), some migrating actions and reporting occurs.  For example, checking is done to validate JCas classes, looking for various conflicts, or version issues.  Automatic conversion of V2 JCas classes may be attempted; these may fail when the user has customized the JCas definition from the plain vanilla one JCasGen created.  Reports can be generated describing the state of affairs detected when starting a pipeline, etc.

We divide these topics here into When, What, and Where:

• When - what events trigger the reporting or converting actions
• What - When the event trigger happens, what is done? If reporting, what is being reported?
• Where - Where does the output go, how is it organized?

Common Use Cases

• A User starts a pipeline described by a descriptor; has JCas classes defined uniquely for all UIMA types in the pipeline, generated using UIMA V3.  In this case, the pipeline starts up, perhaps optionally reporting to a log.
• Same, but the user is using V2 standard JCas Gen with no (or trivial) customization: V3 classes are auto-generated.
• Same, but there is non-trivial customization.  The pipeline generates a report, with enough information to permit a developer to manually integrate customization into a V3 version of the class.
• A User starts a pipeline having 1 (or more) embedded PEAR files. If the PEAR files do not define any JCas classes, things run as now, with PEAR classpath isolation.  If the PEAR defines JCas classes, these are "promoted" to outside-the-PEAR, if no conflict exists with same-named classes; otherwise, if these can be trivially merged, they are; otherwise the pipeline isn't run and a report is generated.

Definitions

• Runtime-mergable: Two JCas classes, are identical, or existing fields/methods the same, and unique methods/fields don't conflict.
• Customized - simple: is customized with extra fields and/or methods, in a way which can be handled automatically
• Customized - complex: arbitrary customization, needing developer to do manual merging
• AutoConvert: convert at runtime using bytecode parse/generation from V2 to V3 form
• AutoExpand: augment at runtime using bytecode parse/generation for V3 form, adding additional fields not already present in the JCas form.
   

When - events that trigger reporting or converting actions

At TypeSystem commit: when finding JCas classes:

If JCas class not already loaded:

Might be already loaded if a type system is being defined by API or by deserializing 

• • Maybe do AutoConvert, AutoExpand (has to be deferred until type merge is complete) 
  • Determine if class exists but isn't JCas class. (Allowed, but inefficient perhaps)
  • Determine if multiple definitions exist; see if Runtime-mergable
  • Determine if Customized (if needed by above)

Can't re-define already loaded JCas class, under one class-loader. 

At PEAR produce-resource time: 

• • For all PEAR-defined JCas classes, see if can "promote" up to outside the PEAR: 
    • OK if JCas class not found outside of PEAR, 
    • or if found, is Runtime-mergable

What - what gets reported, or what kinds of automated actions are done

UIMA types

• Report: source category: 
  • from TypeSystem API call,
  • from UIMA Pipeline,
  • from deserialization
• Show import hierarchy
• Show for all fields, which type(s) contributed the field

JCas Classes

• Which are V2, which are V3
• Which classes are non-JCas
• Which classes are Customized (simple or complex)
• Which UIMA types have no JCas class definitions
• Which JCas classes have multiple definitions
  • which can be merged, which need manual merging
  • which are multiple due to PEAR promotion
• Which classes were AutoConverted from V2 to V3
  • Which classes need manual converting V2 to V3
• Decompile listing
  • for classes with complex customization that need updating
  • for classes that are non_JCas

AutoConvert

• Report what was done, including customization status; optional decompile before/after

AutoExpand

• • Report what was AutoExpanded, including customization status, documenting what features were added; optional decompile before/after

Where - where reports or generated things go, how they are organized