com.google.cloud.dataflow.sdk.coders

## Class CoderRegistry

- java.lang.Object
- - com.google.cloud.dataflow.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, this is `SerializableCoder.PROVIDER`, which can provide a `Coder` for any type that is serializable via Java serialization. The fallback `CoderProvider` can be get and set via `getFallbackCoderProvider()` and `setFallbackCoderProvider(com.google.cloud.dataflow.sdk.coders.CoderProvider)`. Multiple fallbacks can be chained together using `CoderProviders.firstOf(com.google.cloud.dataflow.sdk.coders.CoderProvider...)`.

### Constructor Summary

Constructors
Constructor and Description
`CoderRegistry()`

### Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
`<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.
`<T> Map<Type,Coder<?>>` `getDefaultCoders(Class<? extends T> subClass, Class<T> baseClass, Map<Type,? extends Coder<?>> knownCoders)` Deprecated. this method is not part of the public interface and will be made private
`<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 `SerializableCoder.PROVIDER`.

See `getFallbackCoderProvider()`.

#### getFallbackCoderProvider

    public CoderProvider getFallbackCoderProvider()

Returns the fallback `CoderProvider` for this registry.

See `setFallbackCoderProvider(com.google.cloud.dataflow.sdk.coders.CoderProvider)`.

#### getDefaultCoders

    @Deprecated
    public <T> Map<Type,Coder<?>> getDefaultCoders(Class<? extends T> subClass,
                                                               Class<T> baseClass,
                                                               Map<Type,? extends Coder<?>> knownCoders)

Deprecated. this method is not part of the public interface and will be made private
Returns a `Map` from each of `baseClass`'s type parameters to the `Coder` to use by default for it, in the context of `subClass`'s specialization of `baseClass`.

If no `Coder` can be inferred for a particular type parameter, then that type variable will be absent from the returned `Map`.

For example, if `baseClass` is `Map.class`, where `Map<K, V>` has type parameters `K` and `V`, and `subClass` extends `Map<String, Integer>` then the result will map the type variable `K` to a `Coder<String>` and the type variable `V` to a `Coder<Integer>`.

The `knownCoders` parameter can be used to provide known `Coders` for any of the parameters; these will be used to infer the others.

Note that inference is attempted for every type variable. For a type `MyType<One, Two, Three>` inference will be attempted for all of `One`, `Two`, `Three`, even if the requester only wants a `Coder` for `Two`.

For this reason `getDefaultCoders` (plural) does not throw an exception if a `Coder` for a particular type variable cannot be inferred, but merely omits the entry from the returned `Map`. It is the responsibility of the caller (usually `getDefaultCoder(com.google.cloud.dataflow.sdk.values.TypeDescriptor<T>)` to extract the desired coder or throw a `CannotProvideCoderException` when appropriate.

Parameters:
  `subClass` - the concrete type whose specializations are being inferred
  `baseClass` - the base type, a parameterized class
  `knownCoders` - a map corresponding to the set of known `Coders` indexed by parameter name