Package org.apache.uima.util

# Class CasIOUtils

java.lang.Object
org.apache.uima.util.CasIOUtils

public class CasIOUtils extends Object

A collection of static methods aimed at making it easy to

- save and load CASes, and to
- optionally include the CAS's Type System (abbreviated TS (only available for Compressed Form 6)) and optionally also include the CAS's indexes definition.
- The combination of Type System and Indexes definition is called TSI.
  - The TSI's purpose: to replace the CAS's existing type system and index definition.
  - The TS's purpose: to specify the type system used in the serialized data for format Compressed Form 6, in order to allow deserializing into some other type system in the CAS, leniently.

TSI information can be

- embedded
- externally supplied (via another input source to the load)
- both embedded and externally supplied. In this case the embedded takes precedence.

TS information is available embedded, for COMPRESSED_FILTERED_TS format, and also from embedded or external TSI information (since it also contains the type system information).

When an external TSI is supplied while loading Compressed Form 6,

- for COMPRESSED_FILTERED_TS
  - it uses the embedded TS for decoding
  - it uses the external TSI to replace the CAS's existing type system and index definition if CasLoadMode == REINIT.
- for COMPRESSED_FILTERED_TSI
  - the external TSI is ignored, the embedded one overrides, but otherwise operates as above.
- for COMPRESSED_FILTERED
  - the external TSI's type system part is used for decoding.
  - if CasLoadMode == REINIT, the external TSI is also used to replace the CAS's existing type system and index definition.

Compressed Form 6 loading decoding type system is picked from these sources, in this order:

- a passed in type system
- an embedded TS or TSI
- an external TSI
- the CAS's type system

The serialization formats supported here are specified in the SerialFormat enum.

The `load` api's automatically use the appropriate deserializers, based on the input data format.

Loading inputs may be supplied as URLs or as an appropriately buffered InputStream.

Note: you can use Files or Paths by converting these to URLs:

- `URL url = a_path.toUri().toURL();`
- `URL url = a_file.toUri().toURL();`

When loading, an optional CasLoadMode enum value maybe specified to indicate

- LENIENT loading - used with XCas and XMI data data sources to silently ignore types and features present in the serialized form, but not in the receiving type system.
- REINIT - used with Compressed Form 6 loading to indicate that if no embedded TSI information is available, the external TSI is to be used to replace the CAS's existing type system and index definition.

For more details, see the Javadocs for CasLoadMode.

When TS or TSI information is saved, it is either saved in the same destination (e.g. file or stream), or in a separate one.

- The serialization formats ending in _TSI and _TS support saving the TSI (or TS) in the same destination.
- The save APIs for other formats can optionally also save the TSI into a separate (second) OutputStream.

Summary of APIs for saving:

       save(aCAS, outputStream, aSerialFormat)
       save(aCAS, outputStream, tsiOutputStream, aSerialFormat)

Summary of APIs for loading:

       load(aURL       , aCas)
       load(inputStream, aCas)
       load(inputStream, aCas, typeSystem) // typeSystem used for decoding Compressed Form 6
       load(inputStream, tsiInputStream, aCas)

       load(aURL       , tsiURL        , aCAS, casLoadMode)   - the second URL is for loading a separately-stored TSI
       load(inputStream, tsiInputStream, aCAS, aCasLoadMode)
       load(aURL       , tsiURL        , aCAS, lenient)       - lenient is used to set the CasLoadMode to LENIENT or DEFAULT
       load(inputStream, tsiInputStream, aCAS, lenient)

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CasIOUtils()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static SerialFormat`
  `load(InputStream casInputStream, InputStream tsiInputStream, CAS aCAS)`
  Loads a CAS from an Input Stream.
  `static SerialFormat`
  `load(InputStream casInputStream, InputStream tsiInputStream, CAS aCAS, boolean leniently)`
  Loads a CAS from an Input Stream.
  `static SerialFormat`
  `load(InputStream casInputStream, InputStream tsiInputStream, CAS aCAS, CasLoadMode casLoadMode)`
  Loads a CAS from an Input Stream.
  `static SerialFormat`
  `load(InputStream casInputStream, CAS aCAS)`
  Loads a Cas from an Input Stream.
  `static SerialFormat`
  `load(InputStream casInputStream, CAS aCAS, TypeSystem typeSystem)`
  This load variant can be used for loading Form 6 compressed CASes where the type system to use to deserialize is provided as an argument.
  `static SerialFormat`
  `load(URL casUrl, URL tsiUrl, CAS aCAS, boolean leniently)`
  Loads a CAS from a URL source.
  `static SerialFormat`
  `load(URL casUrl, URL tsiUrl, CAS aCAS, CasLoadMode casLoadMode)`
  Loads a CAS from a URL source.
  `static SerialFormat`
  `load(URL casUrl, CAS aCAS)`
  Loads a Cas from a URL source.
  `static void`
  `save(CAS aCas, OutputStream docOS, OutputStream tsiOS, SerialFormat format)`
  Write the CAS in the specified format.
  `static void`
  `save(CAS aCas, OutputStream docOS, SerialFormat format)`
  Write the CAS in the specified format.
  `static void`
  `writeTypeSystem(CAS aCas, OutputStream aOS, boolean includeIndexDefs)`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### CasIOUtils

    public CasIOUtils()

- ## Method Details

  - ### load

    public static SerialFormat load(URL casUrl, CAS aCAS) throws IOException
    Loads a Cas from a URL source. For SerialFormats ending with _TSI except for COMPRESSED_FILTERED_TSI, the CAS's type system and indexes definition are replaced. CasLoadMode is DEFAULT.
    Parameters:
      `casUrl` - The url containing the CAS
      `aCAS` - The CAS that should be filled
    Returns:
      the SerialFormat of the loaded CAS
    Throws:
      `IOException` - - Problem loading from given URL

  - ### load

    public static SerialFormat load(URL casUrl, URL tsiUrl, CAS aCAS, CasLoadMode casLoadMode) throws IOException
    Loads a CAS from a URL source. The format is determined from the content. If the value of tsiUrl is null it is ignored.
    Parameters:
      `casUrl` - The url to deserialize the CAS from
      `tsiUrl` - null or an optional url to deserialize the type system and index definitions from
      `aCAS` - The CAS that should be filled
      `casLoadMode` - specifies how to handle reinitialization and lenient loading see the Javadocs for CasLoadMode
    Returns:
      the SerialFormat of the loaded CAS
    Throws:
      `IOException` - Problem loading

  - ### load

    public static SerialFormat load(URL casUrl, URL tsiUrl, CAS aCAS, boolean leniently) throws IOException
    Loads a CAS from a URL source. The format is determined from the content. For SerialFormats ending with _TSI except for COMPRESSED_FILTERED_TSI, the CAS's type system and indexes definition are replaced. CasLoadMode is set according to the leniently flag.
    Parameters:
      `casUrl` - The url to deserialize the CAS from
      `tsiUrl` - The optional url to deserialize the type system and index definitions from
      `aCAS` - The CAS that should be filled
      `leniently` - true means do lenient loading
    Returns:
      the SerialFormat of the loaded CAS
    Throws:
      `IOException` - Problem loading

  - ### load

    public static SerialFormat load(InputStream casInputStream, CAS aCAS) throws IOException
    Loads a Cas from an Input Stream. The format is determined from the content. For SerialFormats ending with _TSI except for COMPRESSED_FILTERED_TSI, the CAS's type system and indexes definition are replaced. CasLoadMode is DEFAULT.
    Parameters:
      `casInputStream` - The input stream containing the CAS. Caller should buffer this appropriately.
      `aCAS` - The CAS that should be filled
    Returns:
      the SerialFormat of the loaded CAS
    Throws:
      `IOException` - - Problem loading from given InputStream

  - ### load

    public static SerialFormat load(InputStream casInputStream, InputStream tsiInputStream, CAS aCAS) throws IOException
    Loads a CAS from an Input Stream. The format is determined from the content. For SerialFormats ending with _TSI the embedded value is used instead of any supplied external TSI information. TSI information is available either via embedded value, or if a non-null input is passed for tsiInputStream. If TSI information is available, the CAS's type system and indexes definition are replaced, except for SerialFormats COMPRESSED_FILTERED, COMPRESSED_FILTERED_TS, and COMPRESSED_FILTERED_TSI. The CasLoadMode is DEFAULT.
    Parameters:
      `casInputStream` - The input stream containing the CAS. Caller should buffer this appropriately.
      `tsiInputStream` - -
      `aCAS` - The CAS that should be filled
    Returns:
      the SerialFormat of the loaded CAS
    Throws:
      `IOException` - -

  - ### load

    public static SerialFormat load(InputStream casInputStream, InputStream tsiInputStream, CAS aCAS, boolean leniently) throws IOException
    Loads a CAS from an Input Stream. The format is determined from the content. For SerialFormats ending with _TSI the embedded value is used instead of any supplied external TSI information. TSI information is available either via embedded value, or if a non-null input is passed for tsiInputStream. If TSI information is available, the CAS's type system and indexes definition are replaced, except for SerialFormats `SerialFormat.COMPRESSED_FILTERED`, `SerialFormat.COMPRESSED_FILTERED_TS`, and `SerialFormat.COMPRESSED_FILTERED_TSI`. The CasLoadMode is set to `CasLoadMode.LENIENT` if the leniently flag is true; otherwise it is set to `CasLoadMode.DEFAULT`.
    Parameters:
      `casInputStream` - the stream to load the CAS from
      `tsiInputStream` - an optional stream to read the type system and index information from
      `aCAS` - the target CAS
      `leniently` - if true, missing types in the target CAS will be ignored instead of leading to an exception
    Returns:
      the format that was detected in the CAS input stream
    Throws:
      `IOException` - if the data could not be loaded

  - ### load

    public static SerialFormat load(InputStream casInputStream, InputStream tsiInputStream, CAS aCAS, CasLoadMode casLoadMode) throws IOException
    Loads a CAS from an Input Stream. The format is determined from the content. For formats of ending in _TSI SERIALIZED_TSI or COMPRESSED_FILTERED_TSI, the type system and index definitions are read from the cas input source; the value of tsiInputStream is ignored. For other formats, if the tsiInputStream is not null, type system and index definitions are read from that source. If TSI information is available, the CAS's type system and indexes definition are replaced, except for SerialFormats `SerialFormat.COMPRESSED_FILTERED`, `SerialFormat.COMPRESSED_FILTERED_TS`, and `SerialFormat.COMPRESSED_FILTERED_TSI`. If the CasLoadMode == REINIT, then the TSI information is also used for these 3 formats to replace the CAS's definitions.
    Parameters:
      `casInputStream` - The input stream containing the CAS, appropriately buffered.
      `tsiInputStream` - The optional input stream containing the type system, appropriately buffered. This is only used if it is non null and - the casInputStream does not already come with an embedded CAS Type System and Index Definition, or - the serial format is COMPRESSED_FILTERED_TSI
      `aCAS` - The CAS that should be filled
      `casLoadMode` - specifies loading alternative like lenient and reinit, see CasLoadMode.
    Returns:
      the SerialFormat of the loaded CAS
    Throws:
      `IOException` - if the data could not be loaded

  - ### load

    public static SerialFormat load(InputStream casInputStream, CAS aCAS, TypeSystem typeSystem) throws IOException
    This load variant can be used for loading Form 6 compressed CASes where the type system to use to deserialize is provided as an argument. It can also load other formats, where its behavior is identical to load(casInputStream, aCas). Loads a CAS from an Input Stream. The format is determined from the content. For SerialFormats of ending in _TSI SERIALIZED_TSI or COMPRESSED_FILTERED_TSI, the type system and index definitions are read from the cas input source; the value of typeSystem is ignored. For COMPRESSED_FILTERED_xxx formats, if the typeSystem is not null, the typeSystem is used for decoding. If TSI information is available, the CAS's type system and indexes definition are replaced, except for SerialFormats `SerialFormat.COMPRESSED_FILTERED`, `SerialFormat.COMPRESSED_FILTERED_TS`, and `SerialFormat.COMPRESSED_FILTERED_TSI`. To replace the CAS's type system and indexes definition for these, use a load form which has the CasLoadMode argument, and set this to `CasLoadMode.REINIT`.
    Parameters:
      `casInputStream` - The input stream containing the CAS, appropriately buffered.
      `aCAS` - The CAS that should be filled
      `typeSystem` - the type system to use for decoding the serialized form, must be non-null
    Returns:
      the SerialFormat of the loaded CAS
    Throws:
      `IOException` - Problem loading from given InputStream

  - ### save

    public static void save(CAS aCas, OutputStream docOS, SerialFormat format) throws IOException
    Write the CAS in the specified format.
    Parameters:
      `aCas` - The CAS that should be serialized and stored
      `docOS` - The output stream for the CAS
      `format` - The SerialFormat in which the CAS should be stored.
    Throws:
      `IOException` - - Problem saving to the given InputStream

  - ### save

    public static void save(CAS aCas, OutputStream docOS, OutputStream tsiOS, SerialFormat format) throws IOException
    Write the CAS in the specified format. If the format does not include typesystem information and the optional output stream of the typesystem is specified, then the typesystem information is written there.
    Parameters:
      `aCas` - The CAS that should be serialized and stored
      `docOS` - The output stream for the CAS, with appropriate buffering
      `tsiOS` - Optional output stream for type system information. Only used if the format does not support storing typesystem information directly in the main output file.
      `format` - The SerialFormat in which the CAS should be stored.
    Throws:
      `IOException` - - Problem saving to the given InputStream

  - ### writeTypeSystem

    public static void writeTypeSystem(CAS aCas, OutputStream aOS, boolean includeIndexDefs) throws IOException
    Throws:
      `IOException`