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 combinaton 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 and Description
CasIOUtils()

Method Summary

Modifier and Type	Method and Description
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(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(URL casUrl, CAS aCAS) Loads a Cas from a URL source.
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 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 Detail

CasIOUtils

public CasIOUtils()

Method Detail

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

tsiInputStream - -

aCAS - -

Returns:

-

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 COMPRESSED_FILTERED, COMPRESSED_FILTERED_TS, and COMPRESSED_FILTERED_TSI. The CasLoadMode is set to LENIENT if the leniently flag is true; otherwise it is set to DEFAULT.

Parameters:

casInputStream - -

tsiInputStream - -

aCAS - -

leniently - -

Returns:

-

Throws:

IOException - -

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 COMPRESSED_FILTERED, COMPRESSED_FILTERED_TS, and 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 - - Problem loading from given InputStream

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