org.apache.beam.sdk.extensions.protobuf

Class ProtoCoder<T extends com.google.protobuf.Message>

java.lang.Object

org.apache.beam.sdk.coders.StructuredCoder<T>

org.apache.beam.sdk.coders.CustomCoder<T>

org.apache.beam.sdk.extensions.protobuf.ProtoCoder<T>

Type Parameters:

T - the Protocol Buffers Message handled by this Coder.

All Implemented Interfaces:

Serializable, Coder<T>

public class ProtoCoder<T extends com.google.protobuf.Message>
extends CustomCoder<T>

A Coder using Google Protocol Buffers binary format. ProtoCoder supports both Protocol Buffers syntax versions 2 and 3.

To learn more about Protocol Buffers, visit: https://developers.google.com/protocol-buffers

ProtoCoder is registered in the global CoderRegistry as the default Coder for any Message object. Custom message extensions are also supported, but these extensions must be registered for a particular ProtoCoder instance and that instance must be registered on the PCollection that needs the extensions:

 import MyProtoFile;
 import MyProtoFile.MyMessage;

 Coder<MyMessage> coder = ProtoCoder.of(MyMessage.class).withExtensionsFrom(MyProtoFile.class);
 PCollection<MyMessage> records =  input.apply(...).setCoder(coder);
 

Versioning

ProtoCoder supports both versions 2 and 3 of the Protocol Buffers syntax. However, the Java runtime version of the google.com.protobuf library must match exactly the version of protoc that was used to produce the JAR files containing the compiled .proto messages.

For more information, see the Protocol Buffers documentation.

ProtoCoder and Determinism

In general, Protocol Buffers messages can be encoded deterministically within a single pipeline as long as:

• The encoded messages (and any transitively linked messages) do not use map fields.
• Every Java VM that encodes or decodes the messages use the same runtime version of the Protocol Buffers library and the same compiled .proto file JAR.

ProtoCoder and Encoding Stability

When changing Protocol Buffers messages, follow the rules in the Protocol Buffers language guides for proto2 and proto3 syntaxes, depending on your message type. Following these guidelines will ensure that the old encoded data can be read by new versions of the code.

Generally, any change to the message type, registered extensions, runtime library, or compiled proto JARs may change the encoding. Thus even if both the original and updated messages can be encoded deterministically within a single job, these deterministic encodings may not be the same across jobs.

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface org.apache.beam.sdk.coders.Coder

Coder.Context, Coder.NonDeterministicException

Method Summary

Modifier and Type	Method and Description
static CoderProvider	coderProvider() A CoderProvider that returns a ProtoCoder with an empty ExtensionRegistry.
T	decode(InputStream inStream, Coder.Context context)
void	encode(T value, OutputStream outStream, Coder.Context context)
boolean	equals(Object other)
Set<Class<?>>	getExtensionHosts()
com.google.protobuf.ExtensionRegistry	getExtensionRegistry() Returns the ExtensionRegistry listing all known Protocol Buffers extension messages to T registered with this ProtoCoder.
Class<T>	getMessageType() Returns the Protocol Buffers Message type this ProtoCoder supports.
int	hashCode()
static <T extends com.google.protobuf.Message> ProtoCoder<T>	of(Class<T> protoMessageClass) Returns a ProtoCoder for the given Protocol Buffers Message.
static <T extends com.google.protobuf.Message> ProtoCoder<T>	of(String protoMessageClassName, List<String> extensionHostClassNames) Deprecated. For JSON deserialization only.
static <T extends com.google.protobuf.Message> ProtoCoder<T>	of(TypeDescriptor<T> protoMessageType) Returns a ProtoCoder for the Protocol Buffers Message indicated by the given TypeDescriptor.
void	verifyDeterministic()
ProtoCoder<T>	withExtensionsFrom(Class<?>... moreExtensionHosts) See withExtensionsFrom(Iterable).
ProtoCoder<T>	withExtensionsFrom(Iterable<Class<?>> moreExtensionHosts) Returns a ProtoCoder like this one, but with the extensions from the given classes registered.

Methods inherited from class org.apache.beam.sdk.coders.CustomCoder

getCoderArguments, getInstanceComponents, initializeCloudObject, of

Methods inherited from class org.apache.beam.sdk.coders.StructuredCoder

asCloudObject, consistentWithEquals, getComponents, getEncodedElementByteSize, getEncodedTypeDescriptor, isRegisterByteSizeObserverCheap, registerByteSizeObserver, structuralValue, toString, verifyDeterministic, verifyDeterministic

Methods inherited from class java.lang.Object

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

Method Detail

coderProvider

public static CoderProvider coderProvider()

A CoderProvider that returns a ProtoCoder with an empty ExtensionRegistry.

of

public static <T extends com.google.protobuf.Message> ProtoCoder<T> of(Class<T> protoMessageClass)

Returns a ProtoCoder for the given Protocol Buffers Message.

of

public static <T extends com.google.protobuf.Message> ProtoCoder<T> of(TypeDescriptor<T> protoMessageType)

Returns a ProtoCoder for the Protocol Buffers Message indicated by the given TypeDescriptor.

withExtensionsFrom

public ProtoCoder<T> withExtensionsFrom(Iterable<Class<?>> moreExtensionHosts)

Returns a ProtoCoder like this one, but with the extensions from the given classes registered.

Each of the extension host classes must be an class automatically generated by the Protocol Buffers compiler, protoc, that contains messages.

Does not modify this object.

withExtensionsFrom

public ProtoCoder<T> withExtensionsFrom(Class<?>... moreExtensionHosts)

See withExtensionsFrom(Iterable).

Does not modify this object.

encode

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

Throws:

IOException

decode

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

Throws:

IOException

equals

public boolean equals(Object other)

Overrides:

equals in class StructuredCoder<T extends com.google.protobuf.Message>

hashCode

public int hashCode()

Overrides:

hashCode in class StructuredCoder<T extends com.google.protobuf.Message>

verifyDeterministic

public void verifyDeterministic()
                         throws Coder.NonDeterministicException

Specified by:

verifyDeterministic in interface Coder<T extends com.google.protobuf.Message>

Overrides:

verifyDeterministic in class CustomCoder<T extends com.google.protobuf.Message>

Throws:

Coder.NonDeterministicException

getMessageType

public Class<T> getMessageType()

Returns the Protocol Buffers Message type this ProtoCoder supports.

getExtensionHosts

public Set<Class<?>> getExtensionHosts()

getExtensionRegistry

public com.google.protobuf.ExtensionRegistry getExtensionRegistry()

Returns the ExtensionRegistry listing all known Protocol Buffers extension messages to T registered with this ProtoCoder.

of

@Deprecated
public static <T extends com.google.protobuf.Message> ProtoCoder<T> of(String protoMessageClassName,
                                                                                   @Nullable
                                                                                   List<String> extensionHostClassNames)

Deprecated. For JSON deserialization only.