com.google.cloud.dataflow.sdk.coders

## Class NullableCoder<T>

- java.lang.Object
- - com.google.cloud.dataflow.sdk.coders.StandardCoder<T>
  - - com.google.cloud.dataflow.sdk.coders.NullableCoder<T>

Type Parameters:
  `T` - the type of the values being transcoded

All Implemented Interfaces:
  Coder<T>, Serializable

    public class NullableCoder<T>
    extends StandardCoder<T>

A `NullableCoder` encodes nullable values of type `T` using a nested `Coder<T>` that does not tolerate `null` values. `NullableCoder` uses exactly 1 byte per entry to indicate whether the value is `null`, then adds the encoding of the inner coder for non-null values.

See Also:
  Serialized Form

### Nested Class Summary

### Nested classes/interfaces inherited from interface com.google.cloud.dataflow.sdk.coders.Coder

`Coder.Context, Coder.NonDeterministicException`

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`boolean` `consistentWithEquals()` `NullableCoder` is consistent with equals if the nested `Coder` is.
`T` `decode(InputStream inStream, Coder.Context context)` Decodes a value of type `T` from the given input stream in the given context.
`void` `encode(T value, OutputStream outStream, Coder.Context context)` Encodes the given value of type `T` onto the given output stream in the given context.
`List<Coder<T>>` `getCoderArguments()` If this is a `Coder` for a parameterized type, returns the list of `Coder`s being used for each of the parameters, or returns `null` if this cannot be done or this is not a parameterized type.
`protected long` `getEncodedElementByteSize(T value, Coder.Context context)` Overridden to short-circuit the default `StandardCoder` behavior of encoding and counting the bytes.
`boolean` `isRegisterByteSizeObserverCheap(T value, Coder.Context context)` `NullableCoder` is cheap if `valueCoder` is cheap.
`static <T> NullableCoder<T>` `of(Coder<T> valueCoder)`
`static NullableCoder<?>` `of(List<Coder<?>> components)`
`void` `registerByteSizeObserver(T value, com.google.cloud.dataflow.sdk.util.common.ElementByteSizeObserver observer, Coder.Context context)` Overridden to short-circuit the default `StandardCoder` behavior of encoding and counting the bytes.
`Object` `structuralValue(T value)` Returns an object with an `Object.equals()` method that represents structural equality on the argument.
`void` `verifyDeterministic()` `NullableCoder` is deterministic if the nested `Coder` is.

### Methods inherited from class com.google.cloud.dataflow.sdk.coders.StandardCoder

`asCloudObject, equals, getAllowedEncodings, getComponents, getEncodingId, hashCode, toString, verifyDeterministic, verifyDeterministic`

### Methods inherited from class java.lang.Object

`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

### Method Detail

#### of

    public static <T> NullableCoder<T> of(Coder<T> valueCoder)

#### of

    public static NullableCoder<?> of(List<Coder<?>> components)

#### encode

    public void encode(@Nullable
                       T value,
                       OutputStream outStream,
                       Coder.Context context)
                throws IOException,
                       CoderException

Description copied from interface: `Coder`
Encodes the given value of type `T` onto the given output stream in the given context.

Throws:
  `IOException` - if writing to the `OutputStream` fails for some reason
  `CoderException` - if the value could not be encoded for some reason

#### decode

    @Nullable
    public T decode(InputStream inStream,
                              Coder.Context context)
                       throws IOException,
                              CoderException

Description copied from interface: `Coder`
Decodes a value of type `T` from the given input stream in the given context. Returns the decoded value.

Throws:
  `IOException` - if reading from the `InputStream` fails for some reason
  `CoderException` - if the value could not be decoded for some reason

#### getCoderArguments

    public List<Coder<T>> getCoderArguments()

Description copied from interface: `Coder`
If this is a `Coder` for a parameterized type, returns the list of `Coder`s being used for each of the parameters, or returns `null` if this cannot be done or this is not a parameterized type.

#### verifyDeterministic

    public void verifyDeterministic()
                             throws Coder.NonDeterministicException

`NullableCoder` is deterministic if the nested `Coder` is. Throw `Coder.NonDeterministicException` if the coding is not deterministic.

In order for a `Coder` to be considered deterministic, the following must be true:

- two values that compare as equal (via `Object.equals()` or `Comparable.compareTo()`, if supported) have the same encoding.
- the `Coder` always produces a canonical encoding, which is the same for an instance of an object even if produced on different computers at different times.

Throws:
  `Coder.NonDeterministicException` - if this coder is not deterministic.

#### consistentWithEquals

    public boolean consistentWithEquals()

`NullableCoder` is consistent with equals if the nested `Coder` is. Returns `true` if this `Coder` is injective with respect to `Object.equals(java.lang.Object)`.

Whenever the encoded bytes of two values are equal, then the original values are equal according to `Objects.equals()`. Note that this is well-defined for `null`.

This condition is most notably false for arrays. More generally, this condition is false whenever `equals()` compares object identity, rather than performing a semantic/structural comparison.

Specified by:
  `consistentWithEquals` in interface `Coder<T>`
Overrides:
  `consistentWithEquals` in class `StandardCoder<T>`
Returns:
  `false` for `StandardCoder` unless overridden.

#### structuralValue

    public Object structuralValue(@Nullable
                                  T value)
                           throws Exception

Description copied from interface: `Coder`
Returns an object with an `Object.equals()` method that represents structural equality on the argument.

For any two values `x` and `y` of type `T`, if their encoded bytes are the same, then it must be the case that `structuralValue(x).equals(@code structuralValue(y)`.

Most notably:

- The structural value for an array coder should perform a structural comparison of the contents of the arrays, rather than the default behavior of comparing according to object identity.
- The structural value for a coder accepting `null` should be a proper object with an `equals()` method, even if the input value is `null`.

See also `Coder.consistentWithEquals()`.

Specified by:
  `structuralValue` in interface `Coder<T>`
Overrides:
  `structuralValue` in class `StandardCoder<T>`
Throws:
  `Exception`

#### registerByteSizeObserver

    public void registerByteSizeObserver(@Nullable
                                         T value,
                                         com.google.cloud.dataflow.sdk.util.common.ElementByteSizeObserver observer,
                                         Coder.Context context)
                                  throws Exception

Overridden to short-circuit the default `StandardCoder` behavior of encoding and counting the bytes. The size is known (1 byte) when `value` is `null`, otherwise the size is 1 byte plus the size of nested `Coder`'s encoding of `value`. Notifies the `ElementByteSizeObserver` about the byte size of the encoded value using this `Coder`.

Not intended to be called by user code, but instead by `PipelineRunner` implementations.

For `StandardCoder` subclasses, this notifies `observer` about the byte size of the encoded value using this coder as returned by `StandardCoder.getEncodedElementByteSize(T, com.google.cloud.dataflow.sdk.coders.Coder.Context)`.

Specified by:
  `registerByteSizeObserver` in interface `Coder<T>`
Overrides:
  `registerByteSizeObserver` in class `StandardCoder<T>`
Throws:
  `Exception`

#### getEncodedElementByteSize

    protected long getEncodedElementByteSize(@Nullable
                                             T value,
                                             Coder.Context context)
                                      throws Exception

Overridden to short-circuit the default `StandardCoder` behavior of encoding and counting the bytes. The size is known (1 byte) when `value` is `null`, otherwise the size is 1 byte plus the size of nested `Coder`'s encoding of `value`. Returns the size in bytes of the encoded value using this coder.

Overrides:
  `getEncodedElementByteSize` in class `StandardCoder<T>`
Throws:
  `Exception`

#### isRegisterByteSizeObserverCheap

    public boolean isRegisterByteSizeObserverCheap(@Nullable
                                                   T value,
                                                   Coder.Context context)

`NullableCoder` is cheap if `valueCoder` is cheap. Returns whether `Coder.registerByteSizeObserver(T, com.google.cloud.dataflow.sdk.util.common.ElementByteSizeObserver, com.google.cloud.dataflow.sdk.coders.Coder.Context)` cheap enough to call for every element, that is, if this `Coder` can calculate the byte size of the element to be coded in roughly constant time (or lazily).

Not intended to be called by user code, but instead by `PipelineRunner` implementations.

Specified by:
  `isRegisterByteSizeObserverCheap` in interface `Coder<T>`
Overrides:
  `isRegisterByteSizeObserverCheap` in class `StandardCoder<T>`
Returns:
  `false` unless it is overridden. `StandardCoder.registerByteSizeObserver(T, com.google.cloud.dataflow.sdk.util.common.ElementByteSizeObserver, com.google.cloud.dataflow.sdk.coders.Coder.Context)` invokes `StandardCoder.getEncodedElementByteSize(T, com.google.cloud.dataflow.sdk.coders.Coder.Context)` which requires re-encoding an element unless it is overridden. This is considered expensive.