Package de.saar.chorus.domgraph.codec

package de.saar.chorus.domgraph.codec
Provides basic classes for implementing codecs. A codec is a class which supports the conversion of an underspecified representation in some concrete syntax into a labelled dominance graph (input codec) or vice versa (output codec).

This package contains the following groups of classes:

  • the base classes InputCodec and OutputCodec, from which all concrete codec classes are derived;
  • classes for dealing with codec management: CodecManager;
  • the annotation types CodecMetadata, CodecOption, and CodecConstructor, which are required to equip codec classes with metadata;
  • classes for various exception that can occur while either using or registering a codec.
Codecs must follow certain fairly strict rules that guarantee that they can be used from a variety of different contexts (such as the main Utool command-line tool and the GUI). These rules are as follows.
  • A codec class must be a non-abstract class that is derived from InputCodec or from OutputCodec. It must have an annotation of type CodecMetadata which defines its name and, optionally, its associated filename extension. A codec whose extension is the empty string, "", is assumed not to be associated with any extension.
  • A codec class must have exactly one codec constructor. A codec constructor is a public constructor of the codec class. If there is only one public constructor, then it is automatically used as the codec constructor. If there is more than one public constructor in the class, then exactly one of them must be marked with a CodecConstructor annotation. The codec constructor must not declare any checked exceptions.
  • Each parameter of the codec constructor must have an annotation of type CodecOption. The annotation specifies the name and, optionally, a default value for this option. Each parameter must be of one of the following types:
    • any primitive type except for void and char
    • any enumeration type
    • the class String.
The intended way to instantiate a codec class is by calling one of the getInputCodecFor... or getOutputCodecFor... methods of a CodecManager object. These methods all expect either a codec name or a filename as their first arguments. As their second arguments, you can pass either a string or a map specifying the options that should be passed to the constructor of the new codec object. The map should associate each parameter name of the codec constructor (as per the CodecOption annotations) with a String value for this option. This string is then automatically translated into the appropriate primitive or enum type if needed, as per the valueOf methods in the case of the primitive types. If you pass the options in a string, this string is assumed to be of the form "opt1=val1,opt2=val2,...,optn=valn". It is then broken up into a map that assigns values to option names, and instantiation proceeds as above.