org.apache.beam.sdk.coders

Class CoderRegistry

java.lang.Object

org.apache.beam.sdk.coders.CoderRegistry

All Implemented Interfaces:

CoderProvider

public class CoderRegistry
extends Object
implements CoderProvider

A CoderRegistry allows registering the default Coder to use for a Java class, and looking up and instantiating the default Coder for a Java type.

CoderRegistry uses the following mechanisms to determine a default Coder for a Java class, in order of precedence:

1. Registration:
   • A CoderFactory can be registered to handle a particular class via registerCoder(Class, CoderFactory).
   • A Coder class with the static methods to satisfy CoderFactories.fromStaticMethods(java.lang.Class<T>) can be registered via registerCoder(Class, Class).
   • Built-in types are registered via registerStandardCoders().
2. Annotations: DefaultCoder can be used to annotate a type with the default Coder type. The Coder class must satisfy the requirements of CoderProviders.fromStaticMethods(java.lang.Class<T>).
3. Fallback: A fallback CoderProvider is used to attempt to provide a Coder for any type. By default, there are two chained fallback coders: ProtoCoder.coderProvider(), which can provide a coder to efficiently serialize any Protocol Buffers message, and then SerializableCoder.PROVIDER, which can provide a Coder for any type that is serializable via Java serialization. The fallback CoderProvider can be get and set respectively using getFallbackCoderProvider() and setFallbackCoderProvider(org.apache.beam.sdk.coders.CoderProvider). Multiple fallbacks can be chained together using CoderProviders.firstOf(org.apache.beam.sdk.coders.CoderProvider...).

Constructor Summary

Constructors

Constructor and Description
CoderRegistry()

Method Summary

Modifier and Type	Method and Description
<T> Coder<T>	getCoder(TypeDescriptor<T> typeDescriptor) See getDefaultCoder(TypeDescriptor).
<T,OutputT> Coder<OutputT>	getDefaultCoder(Class<? extends T> subClass, Class<T> baseClass, Map<Type,? extends Coder<?>> knownCoders, TypeVariable<?> param) Returns the Coder to use for the specified type parameter specialization of the subclass, given Coders to use for all other type parameters (if any).
<T> Coder<T>	getDefaultCoder(Class<T> clazz) Returns the Coder to use by default for values of the given class.
<T> Coder<T>	getDefaultCoder(T exampleValue) Returns the Coder to use for the provided example value, if it can be determined.
<InputT,OutputT> Coder<OutputT>	getDefaultCoder(TypeDescriptor<OutputT> typeDescriptor, TypeDescriptor<InputT> inputTypeDescriptor, Coder<InputT> inputCoder) Returns the Coder to use by default for values of the given type, where the given input type uses the given Coder.
<T> Coder<T>	getDefaultCoder(TypeDescriptor<T> typeDescriptor) Returns the Coder to use by default for values of the given type.
<InputT,OutputT> Coder<OutputT>	getDefaultOutputCoder(SerializableFunction<InputT,OutputT> fn, Coder<InputT> inputCoder) Returns the Coder to use on elements produced by this function, given the Coder used for its input elements.
CoderProvider	getFallbackCoderProvider() Returns the fallback CoderProvider for this registry.
void	registerCoder(Class<?> clazz, Class<?> coderClazz) Registers coderClazz as the default Coder class to handle encoding and decoding instances of clazz, overriding prior registrations if any exist.
void	registerCoder(Class<?> clazz, CoderFactory coderFactory) Registers coderFactory as the default CoderFactory to produce Coder instances to decode and encode instances of clazz.
<T> void	registerCoder(Class<T> rawClazz, Coder<T> coder) Register the provided Coder for encoding all values of the specified Class.
void	registerStandardCoders() Registers standard Coders with this CoderRegistry.
void	setFallbackCoderProvider(CoderProvider coderProvider) Sets the fallback CoderProvider for this registry.

Methods inherited from class java.lang.Object

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

Constructor Detail

CoderRegistry

public CoderRegistry()

Method Detail

registerStandardCoders

public void registerStandardCoders()

Registers standard Coders with this CoderRegistry.

registerCoder

public void registerCoder(Class<?> clazz,
                          Class<?> coderClazz)

Registers coderClazz as the default Coder class to handle encoding and decoding instances of clazz, overriding prior registrations if any exist.

Supposing T is the static type corresponding to the clazz, then coderClazz should have a static factory method with the following signature:

 
 public static Coder<T> of(Coder<X> argCoder1, Coder<Y> argCoder2, ...)
  

This method will be called to create instances of Coder<T> for values of type T, passing Coders for each of the generic type parameters of T. If T takes no generic type parameters, then the of() factory method should have no arguments.

If T is a parameterized type, then it should additionally have a method with the following signature:

 
 public static List<Object> getInstanceComponents(T exampleValue);
  

This method will be called to decompose a value during the Coder inference process, to automatically choose Coders for the components.

Parameters:

clazz - the class of objects to be encoded

coderClazz - a class with static factory methods to provide Coders

registerCoder

public void registerCoder(Class<?> clazz,
                          CoderFactory coderFactory)

Registers coderFactory as the default CoderFactory to produce Coder instances to decode and encode instances of clazz. This will override prior registrations if any exist.

registerCoder

public <T> void registerCoder(Class<T> rawClazz,
                              Coder<T> coder)

Register the provided Coder for encoding all values of the specified Class. This will override prior registrations if any exist.

Not for use with generic rawtypes. Instead, register a CoderFactory via registerCoder(Class, CoderFactory) or ensure your Coder class has the appropriate static methods and register it directly via registerCoder(Class, Class).

getDefaultCoder

public <T> Coder<T> getDefaultCoder(TypeDescriptor<T> typeDescriptor)
                             throws CannotProvideCoderException

Returns the Coder to use by default for values of the given type.

Throws:

CannotProvideCoderException - if there is no default Coder.

getCoder

public <T> Coder<T> getCoder(TypeDescriptor<T> typeDescriptor)
                      throws CannotProvideCoderException

See getDefaultCoder(TypeDescriptor).

Specified by:

getCoder in interface CoderProvider

Throws:

CannotProvideCoderException - if no coder can be provided

getDefaultCoder

public <InputT,OutputT> Coder<OutputT> getDefaultCoder(TypeDescriptor<OutputT> typeDescriptor,
                                                       TypeDescriptor<InputT> inputTypeDescriptor,
                                                       Coder<InputT> inputCoder)
                                                throws CannotProvideCoderException

Returns the Coder to use by default for values of the given type, where the given input type uses the given Coder.

Throws:

CannotProvideCoderException - if there is no default Coder.

getDefaultOutputCoder

public <InputT,OutputT> Coder<OutputT> getDefaultOutputCoder(SerializableFunction<InputT,OutputT> fn,
                                                             Coder<InputT> inputCoder)
                                                      throws CannotProvideCoderException

Returns the Coder to use on elements produced by this function, given the Coder used for its input elements.

Throws:

CannotProvideCoderException

getDefaultCoder

public <T,OutputT> Coder<OutputT> getDefaultCoder(Class<? extends T> subClass,
                                                  Class<T> baseClass,
                                                  Map<Type,? extends Coder<?>> knownCoders,
                                                  TypeVariable<?> param)
                                           throws CannotProvideCoderException

Returns the Coder to use for the specified type parameter specialization of the subclass, given Coders to use for all other type parameters (if any).

Throws:

CannotProvideCoderException - if there is no default Coder.

getDefaultCoder

public <T> Coder<T> getDefaultCoder(T exampleValue)
                             throws CannotProvideCoderException

Returns the Coder to use for the provided example value, if it can be determined.

Throws:

CannotProvideCoderException - if there is no default Coder or more than one Coder matches

getDefaultCoder

public <T> Coder<T> getDefaultCoder(Class<T> clazz)
                             throws CannotProvideCoderException

Returns the Coder to use by default for values of the given class. The following three sources for a Coder will be attempted, in order:

1. A Coder class registered explicitly via a call to registerCoder(java.lang.Class<?>, java.lang.Class<?>),
2. A DefaultCoder annotation on the class,
3. This registry's fallback CoderProvider, which may be able to generate a Coder for an arbitrary class.

Throws:

CannotProvideCoderException - if a Coder cannot be provided

setFallbackCoderProvider

public void setFallbackCoderProvider(CoderProvider coderProvider)

Sets the fallback CoderProvider for this registry. If no other method succeeds in providing a Coder<T> for a type T, then the registry will attempt to create a Coder using this CoderProvider.

By default, this is set to the chain of ProtoCoder.coderProvider() and SerializableCoder.PROVIDER.

See getFallbackCoderProvider().

getFallbackCoderProvider

public CoderProvider getFallbackCoderProvider()

Returns the fallback CoderProvider for this registry.

See setFallbackCoderProvider(org.apache.beam.sdk.coders.CoderProvider).