Class IterableLikeCoder<T,IterableT extends java.lang.Iterable<T>>
- java.lang.Object
-
- org.apache.beam.sdk.coders.Coder<T>
-
- org.apache.beam.sdk.coders.StructuredCoder<IterableT>
-
- org.apache.beam.sdk.coders.IterableLikeCoder<T,IterableT>
-
- Type Parameters:
T
- the type of the elements of theIterable
s being transcodedIterableT
- the type of the Iterables being transcoded
- All Implemented Interfaces:
java.io.Serializable
- Direct Known Subclasses:
CollectionCoder
,DequeCoder
,IterableCoder
,ListCoder
,SetCoder
public abstract class IterableLikeCoder<T,IterableT extends java.lang.Iterable<T>> extends StructuredCoder<IterableT>
An abstract base class with functionality for assembling aCoder
for a class that implementsIterable
.To complete a subclass, implement the
decodeToIterable(java.util.List<T>)
method. This superclass will decode the elements in the input stream into aList
and then pass them to that method to be converted into the appropriate iterable type. Note that this means the input iterables must fit into memory.The format of this coder is as follows:
- If the input
Iterable
has a known and finite size, then the size is written to the output stream in big endian format, followed by all of the encoded elements. - If the input
Iterable
is not known to have a finite size, then each element of the input is preceded bytrue
encoded as a byte (indicating "more data") followed by the encoded element, and terminated byfalse
encoded as a byte.
- See Also:
- Serialized Form
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from class org.apache.beam.sdk.coders.Coder
Coder.Context, Coder.NonDeterministicException
-
-
Constructor Summary
Constructors Modifier Constructor Description protected
IterableLikeCoder(Coder<T> elementCoder, java.lang.String iterableName)
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description IterableT
decode(java.io.InputStream inStream)
Decodes a value of typeT
from the given input stream in the given context.protected abstract IterableT
decodeToIterable(java.util.List<T> decodedElements)
Builds an instance ofIterableT
, this coder's associatedIterable
-like subtype, from a list of decoded elements.protected IterableT
decodeToIterable(java.util.List<T> decodedElements, long terminatorValue, java.io.InputStream in)
Builds an instance ofIterableT
, this coder's associatedIterable
-like subtype, from a list of decoded elements with theInputStream
at the position where this coder detected the end of the stream.void
encode(IterableT iterable, java.io.OutputStream outStream)
Encodes the given value of typeT
onto the given output stream.java.util.List<? extends Coder<?>>
getCoderArguments()
Coder<T>
getElemCoder()
boolean
isRegisterByteSizeObserverCheap(IterableT iterable)
Returns whetherCoder.registerByteSizeObserver(T, org.apache.beam.sdk.util.common.ElementByteSizeObserver)
cheap enough to call for every element, that is, if thisCoder
can calculate the byte size of the element to be coded in roughly constant time (or lazily).void
registerByteSizeObserver(IterableT iterable, ElementByteSizeObserver observer)
Notifies theElementByteSizeObserver
about the byte size of the encoded value using thisCoder
.void
verifyDeterministic()
ThrowCoder.NonDeterministicException
if the coding is not deterministic.-
Methods inherited from class org.apache.beam.sdk.coders.StructuredCoder
equals, getComponents, hashCode, toString
-
Methods inherited from class org.apache.beam.sdk.coders.Coder
consistentWithEquals, decode, encode, getEncodedElementByteSize, getEncodedTypeDescriptor, structuralValue, verifyDeterministic, verifyDeterministic
-
-
-
-
Method Detail
-
decodeToIterable
protected abstract IterableT decodeToIterable(java.util.List<T> decodedElements)
Builds an instance ofIterableT
, this coder's associatedIterable
-like subtype, from a list of decoded elements.Override
decodeToIterable(List, long, InputStream)
if you need access to the terminator value and theInputStream
.
-
decodeToIterable
protected IterableT decodeToIterable(java.util.List<T> decodedElements, long terminatorValue, java.io.InputStream in) throws java.io.IOException
Builds an instance ofIterableT
, this coder's associatedIterable
-like subtype, from a list of decoded elements with theInputStream
at the position where this coder detected the end of the stream.- Throws:
java.io.IOException
-
encode
public void encode(IterableT iterable, java.io.OutputStream outStream) throws java.io.IOException, CoderException
Description copied from class:Coder
Encodes the given value of typeT
onto the given output stream.- Specified by:
encode
in classCoder<IterableT extends java.lang.Iterable<T>>
- Throws:
java.io.IOException
- if writing to theOutputStream
fails for some reasonCoderException
- if the value could not be encoded for some reason
-
decode
public IterableT decode(java.io.InputStream inStream) throws java.io.IOException, CoderException
Description copied from class:Coder
Decodes a value of typeT
from the given input stream in the given context. Returns the decoded value.- Specified by:
decode
in classCoder<IterableT extends java.lang.Iterable<T>>
- Throws:
java.io.IOException
- if reading from theInputStream
fails for some reasonCoderException
- if the value could not be decoded for some reason
-
getCoderArguments
public java.util.List<? extends Coder<?>> getCoderArguments()
Description copied from class:Coder
If this is aCoder
for a parameterized type, returns the list ofCoder
s being used for each of the parameters in the same order they appear within the parameterized type's type signature. If this cannot be done, or thisCoder
does not encode/decode a parameterized type, returns the empty list.- Specified by:
getCoderArguments
in classCoder<IterableT extends java.lang.Iterable<T>>
-
verifyDeterministic
public void verifyDeterministic() throws Coder.NonDeterministicException
ThrowCoder.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()
orComparable.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.
- Specified by:
verifyDeterministic
in classCoder<IterableT extends java.lang.Iterable<T>>
- Throws:
Coder.NonDeterministicException
- always. Encoding is not deterministic for the generalIterable
case, as it depends upon the type of iterable. This may allow two objects to compare as equal while the encoding differs.
- two values that compare as equal (via
-
isRegisterByteSizeObserverCheap
public boolean isRegisterByteSizeObserverCheap(IterableT iterable)
Returns whetherCoder.registerByteSizeObserver(T, org.apache.beam.sdk.util.common.ElementByteSizeObserver)
cheap enough to call for every element, that is, if thisCoder
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.By default, returns false. The default
Coder.registerByteSizeObserver(T, org.apache.beam.sdk.util.common.ElementByteSizeObserver)
implementation invokesCoder.getEncodedElementByteSize(T)
which requires re-encoding an element unless it is overridden. This is considered expensive.- Overrides:
isRegisterByteSizeObserverCheap
in classCoder<IterableT extends java.lang.Iterable<T>>
- Returns:
true
if the iterable is of a known class that supports lazy counting of byte size, since that requires minimal extra computation.
-
registerByteSizeObserver
public void registerByteSizeObserver(IterableT iterable, ElementByteSizeObserver observer) throws java.lang.Exception
Description copied from class:Coder
Notifies theElementByteSizeObserver
about the byte size of the encoded value using thisCoder
.Not intended to be called by user code, but instead by
PipelineRunner
implementations.By default, this notifies
observer
about the byte size of the encoded value using this coder as returned byCoder.getEncodedElementByteSize(T)
.- Overrides:
registerByteSizeObserver
in classCoder<IterableT extends java.lang.Iterable<T>>
- Throws:
java.lang.Exception
-
-