Adding JSON Documents to the VMware Tanzu GemFire Cache

This topic discusses use of the the JsonDocumentFactory API in VMware Tanzu GemFire. Previous versions of Tanzu GemFire use the JSONFormatter API.

The JSONFormatter API has been deprecated in Tanzu GemFire v10. For information about the JSONFormatter API, see Adding JSON Documents to the VMware Tanzu GemFire Cache in the Tanzu GemFire v9.15 documentation.

Caution: Do not use JsonDocuments using the BSON format or KeepSerialized unless all members have been upgraded to Tanzu GemFire v10. Attempts to use these before all members have been upgraded to Tanzu GemFire v10 will result in a deserialization exception on the client.

Overview

The JsonDocumentFactory API allows you to convert a JSON String into a binary form that can be stored in a Tanzu GemFire region. The JSON String must be a single JSON object, starting and ending with curly braces. Tanzu GemFire accesses each field in the binary form without needing to re-parse JSON or deserialize the binary form.

Usage

For querying and indexing, any field contained inside a JsonDocument can be used, including any nested field within JSON objects or JSON arrays.

• To specify a field of a JSON object for the query or index, specify the field name. In some cases a dot before the field name may be required.
• To specify an element of a JSON array, use brackets. For example, jsonArray[1].

When an application gets a JsonDocument, the application can convert it back to a JSON String by calling toJson(), or the application can access any of its fields by calling getField(fieldName). For a full list of methods that can be used to read the fields, see the Document interface.

Tanzu GemFire v10 supports two different binary formats:

• BSON: Default. Based on the BSON standard. Recommended if your data does not have a well defined schema.
• PDX: Recommended for data that has a well-defined schema.

PDX stores the schema, which is beneficial if the schema is reused often. If the schema must be created for each document, PDX becomes more costly than BSON.

REST clients can both access and store JsonDocuments. The REST client stores JsonDocuments using the PDX format, but they can access JsonDocuments that are stored using the BSON format.

For more information about these APIs, see the Java API documentation for the org.apache.geode.json package.

BSON

• Get a JsonDocumentFactory: To get a JsonDocumentFactory that uses the BSON format, call getJsonDocumentFactory() on your Tanzu GemFire Cache. The interface that represents the binary form is JsonDocument.

  Caution: Do not use JsonDocuments using the BSON format or KeepSerialized unless all members have been upgraded to Tanzu GemFire v10. Attempts to use these before all members have been upgraded to Tanzu GemFire v10 will result in a deserialization exception on the client.

• Access By Clients Running Earlier Versions of GemFire: JsonDocuments using the BSON format cannot be accessed in a client running earlier versions of Tanzu GemFire. This is also true of the KeepSerialized interface. Attempts to do so will result in a deserialization exception on the client. JsonDocuments using the BSON format cannot be sent to older versions of Tanzu GemFire in a cluster or over WAN during rolling upgrade. This is also true of the KeepSerialized interface. The BSON format and the KeepSerialized interface should only be used once all the members have been upgraded to Tanzu GemFire v10.

• Queries on Regions: When performing queries on regions with JsonDocuments that use the BSON format, query results that contain one or more instances of org.apache.geode.cache.query.Struct will always show a StructType of “Object”.

PDX

• Get a JsonDocumentFactory: To get a factory that uses PDX call getJsonDocumentFactory(StorageFormat.PDX) on your Tanzu GemFire Cache.

• Access By Clients Running Earlier Versions of GemFire: JsonDocuments using the PDX format can be accessed by clients running earlier versions of Tanzu GemFire.

• Java Domain Class Mapping: JsonDocuments using the PDX format have support for mapping the document to a Java domain class using a “@type” field in the document.

• Queries on Regions: When performing on regions with JsonDocuments that use the PDX format, query results that contain one of more instances of org.apache.geode.cache.query.Struct will include more specific StructType values like “String” and “Integer”.