Versions Compared

Old Version 103

changes.mady.by.user Udo Kohlmeyer

Saved on

compared with

New Version 104

changes.mady.by.user Udo Kohlmeyer

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

 

Table of Contents

 

Introduction

Apache Geode is a data management platform that provides real-time, consistent access to data-intensive applications throughout widely distributed cloud architectures. While it currently has high-speed client interfaces for Java, C++ and .NET there is both a need to create lighter-weight clients and a demand to access Geode from other programming languages. Unfortunately, the existing client-server protocol is undocumented.  It evolved over time and is overly complex to meet either of these needs.

...

At the same time, we realize that serialization of application keys, values, callback arguments, function parameters and so forth are a separate matter and are not necessarily tied to the serialization protocol used for client/server messaging.  The initial protocol will support primitive types such as scalars, strings, and byte - arrays.  It will also support JSON documents as values and convert between these and Geode PDX-serialized objects in the servers.

Goals

The high-level goals for the protocol are defined here.


Protocol Terms

Protocol Terminology

  Any binary protocol requires the following things:

  • Version: This indicates the API version.

  • Correlation Id: This should be different per request sent. It allows correlation of request and response.

  • Object Type: The type of a serialized object.

  • Response Type: It indicates whether a response is partial or complete.

  • ErrorCodes: It indicates the problem with API invocation.

  • Chunk Response: Send large response in multiple chunks.

  • Continuous Response: Client can register(Observer pattern) for events and then server notify the client if those events occur.

  • Request: It indicates client's message

  • Response: It indicates server's message.

  • Request Format: Format of request API and its parameters, which client wants to invoke.

  • Response Format: Format for API return value, which client invoked.

  • Message: Set of bytes which contain the Message Header and Request/Response.

  • Serialized Byte Order: Big Endian

 

 

Connect 

 

In order to fit into the existing Geode client/server infrastructure, we will be leveraging the current Geode "cache server" component.  It accepts an initial byte that tells it what type of client is connecting to the server and how the client should be handled. A client using the new protocol can connect with the Geode server by sending a protocol byte. Initially, we will support the following two protocols:

...

We may add additional protocol definitions here to indicate use the use of an alternative serialization mechanism.  For instance bytes 112 & 113 might indicate the but require the server to use protobuf Protobuf for serialization of client/server messages.  How we handle other serialization libraries will be addressed when the pluggable-serialization architecture is roughed out.

...

The protocol descriptions use the following types. These may be mapped to a pluggable serialization description language but their native serialization is described here.  The native serialization uses network byte - order ("big-endian").

 

TypeNumber Of BytesValueSerializedBytes
booleanFixed = 1true0x01 
booleanFixed = 1false0x00
int8Fixed = 110x01
int16Fixed = 210x00 0x01 
int32Fixed = 410x00 0x00 0x00 0x01 
int64Fixed = 810x00 0x00 0x00 0x00 0x00 0x00 0x00 0x01 
String(modified UTF 8 )

Variable

  • 2 byte(int16) for length of encoded String
  • Utf Encoding
"Geode"

0x00 0x05 (length)

0x47 0x65 0x6f 0x64 0x65 (utf encoding)

byte[]

Variable

  • 2 bytes(int16) for number of bytes
  • series of bytes.
{1,2}

0x00 0x02 (length)

0x01 0x02 

bytes

Variable: series of bytes containing a serialized value.

  

...