Package de.saar.chorus.domgraph.codec

Class CodecManager

java.lang.Object
de.saar.chorus.domgraph.codec.CodecManager
public class CodecManager extends Object
A registry and factory for codecs. A codec manager is a place where different codec classes can be registered, using the methods registerCodec(Class) or registerAllDeclaredCodecs(). You can then ask the codec manager to construct new codec objects for you, using the getInputCodecFor... and getOutputCodecFor... methods.

While you can always instantiate your own codec classes yourself, the recommended way to dealing with codec classes is through a codec manager. This separates the world of codecs from the rest of the system, offers a uniform interface to all codecs, and deals with the codec metadata annotations correctly. In other words, we encourage you to never instantiate a codec class yourself, but use a codec manager for it.

Author:
Alexander Koller

  • Constructor Details

    • CodecManager

      public CodecManager()

  • Method Details

    • setAllowExperimentalCodecs

      public void setAllowExperimentalCodecs(boolean val)

    • getName

      public String getName(InputCodec codec)

    • getName

      public String getName(OutputCodec codec)

    • getInputCodecOptionTypes

      public Map<String,Class> getInputCodecOptionTypes(String codecname)
      Computes a map representing the parameter types of the constructor of an input codec. The key of each entry is the name of the parameter, as specified in its CodecOption annotation; its value is the class of this parameter. The class may be any primitive type except for void and char, the class String, or any enumeration class. Use this method to query the user for a string value for each parameter. You can then collect these values in a map that assigns (String) values to parameter names, and use this map to construct a new input codec object using the method getInputCodecForName(String, Map).
      Parameters:
      codecname - the name of the input codec whose parameter types you want
      Returns:
      a map that assigns to each parameter name, the type of this parameter

    • getOutputCodecOptionTypes

      public Map<String,Class> getOutputCodecOptionTypes(String codecname)
      Computes a map representing the parameter types of the constructor of an output codec. The key of each entry is the name of the parameter, as specified in its CodecOption annotation; its value is the class of this parameter. The class may be any primitive type except for void and char, the class String, or any enumeration class. Use this method to query the user for a string value for each parameter. You can then collect these values in a map that assigns (String) values to parameter names, and use this map to construct a new output codec object using the method getOutputCodecForName(String, Map).
      Parameters:
      codecname - the name of the output codec whose parameter types you want
      Returns:
      a map that assigns to each parameter name, the type of this parameter

    • getOutputCodecParameterDefaultValue

      public String getOutputCodecParameterDefaultValue(String codecname, String parametername)
      Returns the default value for a codec parameter of an output codec. The default value is encoded as a string and can be decoded e.g. using stringToValue(String, Class).
      Parameters:
      codecname - the name of an output codec
      parametername - the name of a parameter of this codec's codec constructor, as specified in its CodecOption annotation
      Returns:
      the default value of this parameter, or null if there is no output codec with this name, or its codec constructor doesn't have a parameter of this name. If you didn't specify a default value for the parameter, the system assumes a default value of "" (the empty string).

    • getInputCodecParameterDefaultValue

      public String getInputCodecParameterDefaultValue(String codecname, String parametername)
      Returns the default value for a codec parameter of an input codec. The default value is encoded as a string and can be decoded e.g. using stringToValue(String, Class).
      Parameters:
      codecname - the name of an input codec
      parametername - the name of a parameter of this codec's codec constructor, as specified in its CodecOption annotation
      Returns:
      the default value of this parameter, or null if there is no input codec with this name, or its codec constructor doesn't have a parameter of this name. If you didn't specify a default value for the parameter, the system assumes a default value of "" (the empty string).

    • stringToValue

      public Object stringToValue(String valueAsString, Class asClass)
      Converts a string representation of a datatype that is admissible as the type of a codec option into that type. For instance, it will convert the string "false" into the Boolean object for the value "false".

      Admissible datatypes (i.e., values for the asClass parameter are: all wrapper classes for the primitive datatypes, except for void and char; all enum types; and the datatype String.

      Parameters:
      valueAsString - the value, encoded as a string
      asClass - the datatype into which the value should be converted
      Returns:
      an object of the type asClass with the value corresponding to the first parameter, or null if the value could not be converted or the datatype is unsupported.

    • registerCodec

      public void registerCodec(Class codecClass) throws CodecRegistrationException
      Registers a codec. Pass a codec class (not object) as the argument. This class must be a subclass either of InputCodec or of OutputCodec, and is filed under the input or output codecs accordingly.

      Apart from the subclass requirement, a codec class must obey the following rules:

      • It is a class that can be instantiated, i.e. not an abstract class or an interface.
      • It has a CodecMetadata annotation.
      • It has at least one public constructor. If it has more than one public constructor, then exactly one public constructor must have a CodecConstructor annotation. We will the unique public constructor or the unique annotated public constructor the "codec constructor" below.
      • The codec constructor must not declare to throw any checked exceptions.
      • All parameters of the codec constructor must have a CodecOption annotation and must be of a primitive type (but not void or char), an enumeration type, or the class String.
      Parameters:
      codecClass - a codec class
      Throws:
      CodecRegistrationException - if the class violates any of the rules specified above.

    • getInputCodecForName

      public InputCodec getInputCodecForName(String codecname, String options)
      Constructs an input codec object for the input codec with the given name.
      Parameters:
      codecname - the name of a registered input codec
      options - an options string which is passed to the new codec
      Returns:
      an object of this codec class, or null if no codec with this name was registered.

    • getInputCodecForFilename

      public InputCodec getInputCodecForFilename(String filename, String options)
      Constructs an input codec object for the input codec associated with the given filename (extension).
      Parameters:
      filename - the filename for which we need a codec
      options - an options string which is passed to the new codec
      Returns:
      an object of this codec class, or null if no codec is associated with this filename extension

    • getOutputCodecForName

      public OutputCodec getOutputCodecForName(String codecname, String options)
      Constructs an output codec object for the output codec with the given name.
      Parameters:
      codecname - the name of a registered output codec
      options - an options string which is passed to the new codec
      Returns:
      an object of this codec class, or null if no codec with this name was registered.

    • getOutputCodecForFilename

      public OutputCodec getOutputCodecForFilename(String filename, String options)
      Constructs an output codec object for the output codec associated with the given filename (extension).
      Parameters:
      filename - the filename for which we need a codec
      options - an options string which is passed to the new codec
      Returns:
      an object of this codec class, or null if no codec is associated with this filename extension

    • getInputCodecForName

      public InputCodec getInputCodecForName(String codecname, Map<String,String> options)
      Constructs an input codec object for the input codec with the given name.
      Parameters:
      codecname - the name of a registered input codec
      options - a map that assigns values to parameter names of the codec class
      Returns:
      an object of this codec class, or null if no codec with this name was registered.

    • getInputCodecForFilename

      public InputCodec getInputCodecForFilename(String filename, Map<String,String> options)
      Constructs an input codec object for the input codec associated with the given filename (extension).
      Parameters:
      filename - the filename for which we need a codec
      options - a map that assigns values to parameter names of the codec class
      Returns:
      an object of this codec class, or null if no codec is associated with this filename extension

    • getOutputCodecForName

      public OutputCodec getOutputCodecForName(String codecname, Map<String,String> options)
      Constructs an output codec object for the output codec with the given name.
      Parameters:
      codecname - the name of a registered output codec
      options - a map that assigns values to parameter names of the codec class
      Returns:
      an object of this codec class, or null if no codec with this name was registered.

    • getOutputCodecForFilename

      public OutputCodec getOutputCodecForFilename(String filename, Map<String,String> options)
      Constructs an output codec object for the output codec associated with the given filename (extension).
      Parameters:
      filename - the filename for which we need a codec
      options - a map that assigns values to parameter names of the codec class
      Returns:
      an object of this codec class, or null if no codec is associated with this filename extension

    • displayAllCodecs

      public void displayAllCodecs(PrintStream out)
      Prints an overview of all registered codecs to an output stream.
      Parameters:
      out - the output stream to which the overview should be printed.

    • getOutputCodecNameForFilename

      public String getOutputCodecNameForFilename(String filename)
      Figure out the name of the output codec for the given filename.
      Parameters:
      filename -
      Returns:
      the name of the output codec, or null if no codec is associated with this filename.

    • getInputCodecNameForFilename

      public String getInputCodecNameForFilename(String filename)
      Figure out the name of the input codec for the given filename.
      Parameters:
      filename -
      Returns:
      the name of the input codec, or null if no codec is associated with this filename.

    • isExperimentalInputCodec

      public boolean isExperimentalInputCodec(String codecname)
      Determines whether or not an input codec has the status "EXPERIMENTAL". If the codecname does not exist or is no input codec, false is returned.
      Parameters:
      codecname - the codec's String representation
      Returns:
      true if the codec is experimental

    • isExperimentalOutputCodec

      public boolean isExperimentalOutputCodec(String codecname)
      Determines whether or not an output codec has the status "EXPERIMENTAL". If the codecname does not exist or is no output codec, false is returned.
      Parameters:
      codecname - the codec's String representation
      Returns:
      true if the codec is experimental

    • isMultiOutputCodec

      public boolean isMultiOutputCodec(String codecname)
      Determines whether or not an output codec supports the output of multiple solved forms into one file. If the codecname does not exist or is no output codec, false is returned.
      Parameters:
      codecname - the codec's String representation
      Returns:
      true if the codec allows the output of multiple solved forms

    • getAllInputCodecs

      public List<String> getAllInputCodecs()
      Returns the list of all registered input codecs.
      Returns:
      the names of all input codecs

    • getAllInputCodecExtensions

      public List<String> getAllInputCodecExtensions()

    • getAllOutputCodecExtensions

      public List<String> getAllOutputCodecExtensions()

    • getAllOutputCodecs

      public List<String> getAllOutputCodecs()
      Returns the list of all registered output codecs.
      Returns:
      the names of all output codecs

    • getAllMultiOutputCodecs

      public List<String> getAllMultiOutputCodecs()
      Returns the list of all registered output codecs that support the output of multiple solved forms into one file.
      Returns:
      the list of all such output codecs

    • registerAllDeclaredCodecs

      public void registerAllDeclaredCodecs() throws CodecRegistrationException
      Registers all codecs which are declared in a codecclasses.properties file. This file is assumed to contain the names of codec classes, one per line; all these classes will be registered as codecs in this codec manager.

      The method looks for the codecclasses file in the directory de/saar/chorus/domgraph/codec below the classpath. If there is more than one file with this pathname on the class path, this method will process each of these files in turn, i.e. the codecs of all files will be registered. This is designed to make it easy to codec developers to write their own codecs and use them from utool/domgraph without having to recompile the domgraph code.

      Each codec that is registered using this method is still subject to the rules laid out in the documentation of registerCodec(Class).

      Throws:
      CodecRegistrationException - if an error occurred while trying to register any of the listed codec classes. This happens when either an I/O error occurred, one of the class names could not be resolved to a class, or one of the classes is not a valid codec.

    • getInputCodecExtension

      public String getInputCodecExtension(String codecname)

    • getOutputCodecExtension

      public String getOutputCodecExtension(String codecname)