com.stripe.model

Class EventDataObjectDeserializer

java.lang.Object

com.stripe.model.EventDataObjectDeserializer

public class EventDataObjectDeserializer
extends java.lang.Object

Deserialization helper to get StripeObject and handle failure due to schema incompatibility between the data object and the model classes. Event data object always corresponds to the schema at API version of its creation time, available at Event.getApiVersion(), while the model classes correspond to schemas at a specific version pinned to this library Stripe.API_VERSION. Thus, only data object with same API versions is guaranteed to deserialize safely.

In practice, each Stripe.API_VERSION update only affects specific set of classes, so event data object for the unaffected classes can still be serialized successfully -- even when the API versions do not match. (Although it is considered unsafe by the API version comparison.)

Upon seeing deserialization failure from retrieving events or during receiving webhook events, consider defining your own custom EventDataObjectDeserializer.CompatibilityTransformer to transform the raw JSON to one with schema compatible with the current model classes. (Events in failed webhooks can be retrieved again from the event API.)

An example of event data object deserialization is:

 Event event = Event.retrieve("evt_123");
 EventDataObjectDeserializer deserializer = event.getDataObjectDeserializer();
 StripeObject stripeObject;
 if (deserializer.deserialize()) {
   stripeObject = deserializer.getObject();
 } else {
   try {
     stripeObject = deserializer.deserializeUnsafe();
   } catch (EventDataObjectDeserializationException e) {
     EventDataObjectDeserializer.CompatibilityTransformer transformer = myCustomerTransformer();
     stripeObject = deserializer.deserializeUnsafeWith(transformer);
   }
 }
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	EventDataObjectDeserializer.CompatibilityTransformer Definition of event data object JSON transformation to be compatible to API version of the library.

Method Summary

Modifier and Type	Method and Description
protected boolean	canEqual(java.lang.Object other)
boolean	deserialize() Safe deserialize raw JSON into StripeObject.
StripeObject	deserializeUnsafe() Force deserialize raw JSON to StripeObject.
StripeObject	deserializeUnsafeWith(EventDataObjectDeserializer.CompatibilityTransformer transformer) Deserialize JSON that has been processed by EventDataObjectDeserializer.CompatibilityTransformer.transform(JsonObject, String, String) into StripeObject.
boolean	equals(java.lang.Object o)
StripeObject	getObject() Gets data event object, in favor of the deprecated EventData.getObject().
java.lang.String	getRawJson() Get raw JSON string for the data object.
int	hashCode()

Methods inherited from class java.lang.Object

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

Method Detail

getObject

public StripeObject getObject()

Gets data event object, in favor of the deprecated EventData.getObject(). When non-null, the deserialized StripeObject preserves high data integrity because of correspondence between schema of the API response and the model class (the underlying concrete class for abstract StripeObject) schema. This is when Event.getApiVersion() matches Stripe.API_VERSION.

Returns:

stripe object that fully represent its original raw JSON response.

getRawJson

public java.lang.String getRawJson()

Get raw JSON string for the data object. This is the same data available in EventDataObjectDeserializationException.getRawJson() ()} upon deserialization failure.

Returns:

JSON string the event data object.

deserialize

public boolean deserialize()

Safe deserialize raw JSON into StripeObject. This operation mutates the state, and the successful result can be accessed via getObject(). Matching Event.getApiVersion() and Stripe.API_VERSION is necessary condition to guarantee safe deserialization.

Returns:

whether deserialization has been successful.

deserializeUnsafe

public StripeObject deserializeUnsafe()
                               throws EventDataObjectDeserializationException

Force deserialize raw JSON to StripeObject. The deserialized data is not guaranteed to fully represent the JSON. For example, events of new API version having fields that are not captured by current model class will be lost. Similarly, events of old API version having fields that should be translated into the new fields, like field rename, will be lost.

Upon deserialization failure, consider making the JSON compatible to the current model classes and recover from failure with deserializeUnsafeWith(CompatibilityTransformer).

Returns:

Object with no guarantee on full representation of its original raw JSON response.

Throws:

EventDataObjectDeserializationException - exception that contains the message error and the raw JSON response of the StripeObject to be deserialized.

deserializeUnsafeWith

public StripeObject deserializeUnsafeWith(EventDataObjectDeserializer.CompatibilityTransformer transformer)

Deserialize JSON that has been processed by EventDataObjectDeserializer.CompatibilityTransformer.transform(JsonObject, String, String) into StripeObject. This deserialization method should only be used to handle events with schema incompatible to model class schema of this library. Throws JsonParseException when the transformed JSON remains incompatible with the model classes.

Returns:

deserialized StripeObject from user-supplied compatible JSON.

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

canEqual

protected boolean canEqual(java.lang.Object other)

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object