Package com.inductiveautomation.ignition.common.rpc.proto

Class ProtoRpcSerializer

java.lang.Object

com.inductiveautomation.ignition.common.rpc.proto.ProtoRpcSerializer

All Implemented Interfaces:

ClientRpcSerializer, GatewayRpcSerializer, DeserializationContext, SerializationContext, RpcSerializer

public final class ProtoRpcSerializer
extends Object
implements RpcSerializer, SerializationContext, DeserializationContext

A Protobuf based serialization handler. This class provides implementation logic to encode and decode objects to and from a specific Protobuf format; see the RpcMessage class. Modules will likely have to construct their own instance using ProtoSerializerBuilder, unless they are able to restrict their RPC sending and receiving to common "atomic" Java, standard library, and Ignition types.

See Also:

• ProtoSerializerBuilder
• newBuilder()

Field Summary

Fields

Modifier and Type	Field	Description
static final ProtoRpcSerializer	DEFAULT_INSTANCE	A default instance of the ProtoRpcSerializer; equivalent to newBuilder().build()

Method Summary

Modifier and Type	Method	Description
<T> PushNotificationDeserializer<T>	asPushNotificationDeserializer()
<T> PushNotificationSerializer<T>	asPushNotificationSerializer()
Throwable	decodeError(Error value)	Decode the supplied Error into a Throwable.
com.inductiveautomation.ignition.common.gson.JsonElement	decodeToGson(Value value)	Attempts to decode the supplied Value to JSON, using the following approach: Number/boolean/string/null values are mapped to equivalent JSON primitives Binary data is returned as a base64 encoded string primitive Maps are returned as JSON objects (if possible) Any other collection type is returned as a JSON array
Error	encodeThrowable(Throwable throwable)	Encode the supplied Throwable as an Error Protobuf message.
com.inductiveautomation.ignition.common.gson.Gson	gson()
static ProtoSerializerBuilder	newBuilder()
static ProtoSerializerBuilder	newBuilder(com.inductiveautomation.ignition.common.gson.GsonBuilder base)	Create a new ProtoRpcSerializer builder, using the supplied GsonBuilder as the base of all further GSON customization.
<T> T	protoDecode(Value value)	Attempts to decode the supplied Value as the implicit type T, using a deserializer keyed off identifier in the value.
<T> T	protoDecode(Value value, @Nullable Class<T> clazz)	Attempts to decode the supplied Value as the implicit type T, using a deserializer identified by the supplied class.
Value	protoEncode(Object any)	Encode the supplied object using whatever implicit serializer is registered that can handle it, returning the resulting Value.
Value	protoEncode(Object any, Class<?> identifier)	Encodes the supplied object using specific serialization handling for clazz, which could be some more specific type than automatic serialization lookup would use.
@NotNull List<Object>	readParameters(@NotNull InputStream stream, @NotNull RpcCall call)
Object	readReturnValue(@NotNull InputStream stream, @NotNull RpcCall call)	Read the return value from the stream, decoding it from a Protobuf message.
void	writeParameters(@NotNull OutputStream stream, @NotNull RpcCall call, @NotNull Object... parameters)	Write the supplied parameters to the stream, encoding them as Protobuf messages.
void	writeReturnValue(@NotNull OutputStream stream, @NotNull RpcCall call, @NotNull Object parameter)

Methods inherited from class java.lang.Object

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

Field Details

DEFAULT_INSTANCE

public static final ProtoRpcSerializer DEFAULT_INSTANCE

A default instance of the ProtoRpcSerializer; equivalent to newBuilder().build()

Method Details

newBuilder

public static ProtoSerializerBuilder newBuilder(com.inductiveautomation.ignition.common.gson.GsonBuilder base)

Create a new ProtoRpcSerializer builder, using the supplied GsonBuilder as the base of all further GSON customization.

newBuilder

public static ProtoSerializerBuilder newBuilder()

encodeThrowable

public Error encodeThrowable(Throwable throwable)

Encode the supplied Throwable as an Error Protobuf message.

The Error will contain the class name, message, stack trace, and cause (if present) of the Throwable.

If the Throwable is an instance of RpcException, the error number will also be set.

Parameters:

throwable - The Throwable to encode.

Returns:

An Error Protobuf message representing the Throwable.

See Also:

• decodeError(Error)

decodeError

public Throwable decodeError(Error value)

Decode the supplied Error into a Throwable.

If the Error's className is not recognized, a ProtoWrappedException will be returned.

If the Error's cause is present, it will be recursively decoded and set as the cause of the returned Throwable.

Parameters:

value - The Error to decode.

Returns:

A Throwable representing the error.

See Also:

• encodeThrowable(Throwable)

gson

public com.inductiveautomation.ignition.common.gson.Gson gson()

Specified by:

gson in interface DeserializationContext

Specified by:

gson in interface SerializationContext

protoEncode

public Value protoEncode(Object any)
                  throws ProtoSerializationException

Description copied from interface: SerializationContext

Encode the supplied object using whatever implicit serializer is registered that can handle it, returning the resulting Value.

Specified by:

protoEncode in interface SerializationContext

Throws:

ProtoSerializationException - if the supplied value could not be proto serialized.

protoEncode

public Value protoEncode(Object any,
 Class<?> identifier)
                  throws ProtoSerializationException

Description copied from interface: SerializationContext

Encodes the supplied object using specific serialization handling for clazz, which could be some more specific type than automatic serialization lookup would use.

Specified by:

protoEncode in interface SerializationContext

Throws:

ProtoSerializationException

protoDecode

public <T> T protoDecode(Value value)
                  throws ProtoSerializationException

Description copied from interface: DeserializationContext

Attempts to decode the supplied Value as the implicit type T, using a deserializer keyed off identifier in the value.

Specified by:

protoDecode in interface DeserializationContext

Throws:

ProtoSerializationException

protoDecode

public <T> T protoDecode(Value value,
 @Nullable
 @Nullable Class<T> clazz)
                  throws ProtoSerializationException

Description copied from interface: DeserializationContext

Attempts to decode the supplied Value as the implicit type T, using a deserializer identified by the supplied class.

Specified by:

protoDecode in interface DeserializationContext

Throws:

ProtoSerializationException

decodeToGson

public com.inductiveautomation.ignition.common.gson.JsonElement decodeToGson(Value value)
                                                                      throws ProtoSerializationException

Description copied from interface: DeserializationContext

Attempts to decode the supplied Value to JSON, using the following approach:

• Number/boolean/string/null values are mapped to equivalent JSON primitives
• Binary data is returned as a base64 encoded string primitive
• Maps are returned as JSON objects (if possible)
• Any other collection type is returned as a JSON array

Specified by:

decodeToGson in interface DeserializationContext

Throws:

ProtoSerializationException - if anything inside the Value could not be decoded to a JsonElement.

See Also:

• Base64

writeParameters

public void writeParameters(@NotNull
 @NotNull OutputStream stream,
 @NotNull
 @NotNull RpcCall call,
 @NotNull
 @NotNull Object... parameters)
                     throws IOException

Write the supplied parameters to the stream, encoding them as Protobuf messages.

Specified by:

writeParameters in interface ClientRpcSerializer

call - The call information, useful for disambiguation or debugging.

parameters - An array (possibly empty and possibly containing null elements) of parameters to write.

Throws:

IOException - If there was any issue writing to the stream.

See Also:

• for implementation details.

readReturnValue

public Object readReturnValue(@NotNull
 @NotNull InputStream stream,
 @NotNull
 @NotNull RpcCall call)
                       throws IOException

Read the return value from the stream, decoding it from a Protobuf message.

Specified by:

readReturnValue in interface ClientRpcSerializer

Returns:

Whatever the return value was from the RPC call; possibly null.

Throws:

IOException - If there was an error reading from the stream.

See Also:

• decodeRpcMessage(RpcMessage)

readParameters

@NotNull
public @NotNull List<Object> readParameters(@NotNull
 @NotNull InputStream stream,
 @NotNull
 @NotNull RpcCall call)
                                     throws IOException

Specified by:

readParameters in interface GatewayRpcSerializer

Throws:

IOException

writeReturnValue

public void writeReturnValue(@NotNull
 @NotNull OutputStream stream,
 @NotNull
 @NotNull RpcCall call,
 @NotNull
 @NotNull Object parameter)
                      throws IOException

Specified by:

writeReturnValue in interface GatewayRpcSerializer

Throws:

IOException

asPushNotificationSerializer

public <T> PushNotificationSerializer<T> asPushNotificationSerializer()

asPushNotificationDeserializer

public <T> PushNotificationDeserializer<T> asPushNotificationDeserializer()