de.saar.chorus.domgraph.codec
Class CodecManager

Object
  extended by 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 Summary
CodecManager()
           
 
Method Summary
 void displayAllCodecs(PrintStream out)
          Prints an overview of all registered codecs to an output stream.
 List<String> getAllInputCodecExtensions()
           
 List<String> getAllInputCodecs()
          Returns the list of all registered input codecs.
 List<String> getAllMultiOutputCodecs()
          Returns the list of all registered output codecs that support the output of multiple solved forms into one file.
 List<String> getAllOutputCodecExtensions()
           
 List<String> getAllOutputCodecs()
          Returns the list of all registered output codecs.
 String getInputCodecExtension(String codecname)
           
 InputCodec getInputCodecForFilename(String filename, Map<String,String> options)
          Constructs an input codec object for the input codec associated with the given filename (extension).
 InputCodec getInputCodecForFilename(String filename, String options)
          Constructs an input codec object for the input codec associated with the given filename (extension).
 InputCodec getInputCodecForName(String codecname, Map<String,String> options)
          Constructs an input codec object for the input codec with the given name.
 InputCodec getInputCodecForName(String codecname, String options)
          Constructs an input codec object for the input codec with the given name.
 String getInputCodecNameForFilename(String filename)
          Figure out the name of the input codec for the given filename.
 Map<String,Class> getInputCodecOptionTypes(String codecname)
          Computes a map representing the parameter types of the constructor of an input codec.
 String getInputCodecParameterDefaultValue(String codecname, String parametername)
          Returns the default value for a codec parameter of an input codec.
 String getName(InputCodec codec)
           
 String getName(OutputCodec codec)
           
 String getOutputCodecExtension(String codecname)
           
 OutputCodec getOutputCodecForFilename(String filename, Map<String,String> options)
          Constructs an output codec object for the output codec associated with the given filename (extension).
 OutputCodec getOutputCodecForFilename(String filename, String options)
          Constructs an output codec object for the output codec associated with the given filename (extension).
 OutputCodec getOutputCodecForName(String codecname, Map<String,String> options)
          Constructs an output codec object for the output codec with the given name.
 OutputCodec getOutputCodecForName(String codecname, String options)
          Constructs an output codec object for the output codec with the given name.
 String getOutputCodecNameForFilename(String filename)
          Figure out the name of the output codec for the given filename.
 Map<String,Class> getOutputCodecOptionTypes(String codecname)
          Computes a map representing the parameter types of the constructor of an output codec.
 String getOutputCodecParameterDefaultValue(String codecname, String parametername)
          Returns the default value for a codec parameter of an output codec.
 boolean isExperimentalInputCodec(String codecname)
          Determines whether or not an input codec has the status "EXPERIMENTAL".
 boolean isExperimentalOutputCodec(String codecname)
          Determines whether or not an output codec has the status "EXPERIMENTAL".
 boolean isMultiOutputCodec(String codecname)
          Determines whether or not an output codec supports the output of multiple solved forms into one file.
 void registerAllDeclaredCodecs()
          Registers all codecs which are declared in a codecclasses.properties file.
 void registerCodec(Class codecClass)
          Registers a codec.
 void setAllowExperimentalCodecs(boolean val)
           
 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.
 
Methods inherited from class Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CodecManager

public CodecManager()
Method Detail

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:

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)