Package com.hubspot.immutables.utils

Class WireSafeEnum<T extends Enum<T>>

java.lang.Object

com.hubspot.immutables.utils.WireSafeEnum<T>

public final class WireSafeEnum<T extends Enum<T>>
extends Object

This utility is meant to help with the fragility introduced by using an enum across API boundaries. The most common example is adding a new enum constant causing clients to explode on deserialization if they don't have the updated enum definition. Instead of using the enum in your models directly, you could instead wrap the field in a WireSafeEnum. This should be transparent from a serialization perspective, but will allow you to more gracefully handle the case of an unknown enum constant. It also stores the JSON value when deserializing, and uses that for serialization. This means that intermedaries preserve, rather than mangle, unknown enum values. For the most part WireSafeEnum should be a drop-in replacement, but there are some things to be aware of: 1. every enum constant must serialize to JSON as a non-null string (serializing as a number or null is not supported) 2. T and WireSafeEnum are different types so migrating is a breaking change from a code perspective and Java code usages of the field will need to get updated

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	WireSafeEnum.Deserializer

Method Summary

Modifier and Type	Method	Description
Optional<T>	asEnum()
T	asEnumOrThrow()	Deprecated. this method doesn't handle unknown enum values, and eliminates the benefits of WireSafeEnum.
<X extends Throwable> T	asEnumOrThrow(Supplier<? extends X> exceptionSupplier)	Deprecated. this method doesn't handle unknown enum values, and eliminates the benefits of WireSafeEnum.
String	asString()
boolean	contains(T value)
Class<T>	enumType()
boolean	equals(Object o)
static <T extends Enum<T>> WireSafeEnum<T>	fromJson(Class<T> enumType, String jsonValue)
int	hashCode()
static <T extends Enum<T>> WireSafeEnum<T>	of(T value)
String	toString()

Methods inherited from class java.lang.Object

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

Method Detail

of

@Nonnull
public static <T extends Enum<T>> WireSafeEnum<T> of(@Nonnull
                                                     T value)

fromJson

@Nonnull
public static <T extends Enum<T>> WireSafeEnum<T> fromJson(@Nonnull
                                                           Class<T> enumType,
                                                           @Nonnull
                                                           String jsonValue)

enumType

@Nonnull
public Class<T> enumType()

asString

@Nonnull
public String asString()

asEnum

@Nonnull
public Optional<T> asEnum()

asEnumOrThrow

@Nonnull
@Deprecated
public <X extends Throwable> T asEnumOrThrow(Supplier<? extends X> exceptionSupplier)
                                      throws X extends Throwable

Deprecated.

this method doesn't handle unknown enum values, and eliminates the benefits of WireSafeEnum. If you want to compare to a specific value, you can call contains(Enum), which handles unknown values gracefully. If you do really need to coerce to an enum, you can replace this method with .asEnum().orElseThrow(exceptionSupplier)

Throws:

X extends Throwable

asEnumOrThrow

@Nonnull
@Deprecated
public T asEnumOrThrow()

Deprecated.

this method doesn't handle unknown enum values, and eliminates the benefits of WireSafeEnum. If you want to compare to a specific value, you can call contains(Enum), which handles unknown values gracefully. If you do really need to coerce to an enum, you can replace this method with .asEnum().get()

contains

public boolean contains(@Nonnull
                        T value)

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object