de.up.ling.irtg.codec

Class InputCodec<E>

java.lang.Object

de.up.ling.irtg.codec.InputCodec<E>

Direct Known Subclasses:

BinaryIrtgInputCodec, BolinasHrgInputCodec, BottomUpTreeAutomatonInputCodec, ChenTagInputCodec, IrtgInputCodec, IsiAmrInputCodec, JoshuaInputCodec, PcfgIrtgInputCodec, PtbTreeInputCodec, SGraphInputCodec, TemplateIrtgInputCodec, TiburonTreeAutomatonInputCodec, TreeAutomatonInputCodec

public abstract class InputCodec<E>
extends Object

Reconstructs an object from a representation. Representations will typically be strings, but you could also implement an input codec for binary representations.

The codec will attempt to decode the representation into an object of the class specified by the type parameter E. For instance, a IrtgInputCodec will decode a string representation into an InterpretedTreeAutomaton, whereas a TreeAutomatonInputCodec will decode a string into a TreeAutomaton.

Concrete input codec implementations must implement the abstract method read(java.io.InputStream), which reads data from an input stream and decodes it into an object. This class then provides a number of convenience methods that make use of the concrete implementation of read.

Input codecs can be registered by adding them to the file src/main/resources/META-INF/services/de.up.ling.codec.InputCodec. Input codecs that are suitable for a given class of objects can then be found using getInputCodecs(java.lang.Class).

In order to be discovered correctly, each input codec needs to be annotated with CodecMetadata, such as the type of E and a filename extension.

Author:

koller

Constructor Summary

Constructors

Constructor and Description
InputCodec()

Method Summary

Modifier and Type	Method and Description
void	addOptions(String options)
static Iterable<InputCodec>	getAllInputCodecs() Returns all registered input codecs.
static InputCodec	getInputCodecByExtension(String extension) Returns the registered input codec for the given filename extension (as per the codec metadata's extension field).
static InputCodec	getInputCodecByName(String name) Returns the registered input codec with the given name (as per the codec metadata's name field).
static InputCodec	getInputCodecByNameOrExtension(String filename, String codecName) Returns the input codec specified by the given codec name and/or filename.
static <T> List<InputCodec<T>>	getInputCodecs(Class<T> forClass) Returns all registered input codecs that can produce objects of class T (or a subtype).
CodecMetadata	getMetadata() Returns the metadata for this input codec.
String	getOption(String key)
boolean	hasTrueOption(String key)
static void	main(String[] args)
abstract E	read(InputStream is) Reads an object from an input stream.
E	read(String s) Reads an object from a string representation.
void	setOption(String option, String value)
void	setProgressListener(ProgressListener listener) Sets the progress listener for this codec.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

InputCodec

public InputCodec()

Method Detail

read

public abstract E read(InputStream is)
                throws CodecParseException,
                       IOException

Reads an object from an input stream.

Parameters:

is -

Returns:

Throws:

CodecParseException - if an error occurred while decoding the input stream into an object

IOException - if an error occurred while reading data from the input stream

read

public E read(String s)
       throws CodecParseException

Reads an object from a string representation. This method uses String.getBytes() to decode the string into a sequence of bytes using the platform's default encoding, and then reads an object from this byte stream using read(java.io.InputStream). It is provided as a convenience method for the frequent special case where the object is represented as a string of some kind.

Parameters:

s -

Returns:

Throws:

CodecParseException

getMetadata

public CodecMetadata getMetadata()

Returns the metadata for this input codec.

Returns:

getAllInputCodecs

public static Iterable<InputCodec> getAllInputCodecs()

Returns all registered input codecs. You can register a new input codec by adding its fully qualified class name to the file META-INF/services/de.up.ling.irtg.codec.InputCodec. You can find this file under src/main/resources in the IRTG source code repository. Note: It is usually a better idea to call getInputCodecs(java.lang.Class) to ensure type-safety.

Returns:

getInputCodecs

public static <T> List<InputCodec<T>> getInputCodecs(Class<T> forClass)

Returns all registered input codecs that can produce objects of class T (or a subtype). For instance, call InputCodec.getInputCodecs(Tree.class) to obtain all input codecs for trees. The method takes the information about what class an input codec reads from the type field in the codec's metadata annotation.

Type Parameters:

T -

Parameters:

forClass -

Returns:

getInputCodecByName

public static InputCodec getInputCodecByName(String name)

Returns the registered input codec with the given name (as per the codec metadata's name field). If no codec with this name can be found, returns null.

Parameters:

name -

Returns:

getInputCodecByExtension

public static InputCodec getInputCodecByExtension(String extension)

Returns the registered input codec for the given filename extension (as per the codec metadata's extension field). If no codec for this extension can be found, returns null.

Parameters:

extension -

Returns:

getInputCodecByNameOrExtension

public static InputCodec getInputCodecByNameOrExtension(String filename,
                                                        String codecName)
                                                 throws Exception

Returns the input codec specified by the given codec name and/or filename. If the codecName is non-null, tries to resolve it to a registered input codec; if none is found, the method throws an exception. If the codecName is null, tries to determine the input codec from the filename extension of the (non-null) filename argument. If this is not possible, or both arguments are null, throws an exception.

Parameters:

filename -

codecName -

Returns:

Throws:

Exception

setProgressListener

public void setProgressListener(ProgressListener listener)

Sets the progress listener for this codec. If the input codec takes a long time to decode an input stream, it may inform the user about its progress by sending updates to the progress listener. You can call this method with a null argument to disable progress updates.

Parameters:

listener -

addOptions

public void addOptions(String options)

setOption

public void setOption(String option,
                      String value)

getOption

public String getOption(String key)

hasTrueOption

public boolean hasTrueOption(String key)

main

public static void main(String[] args)
                 throws Exception

Throws:

Exception