Skip to end of metadata
Go to start of metadata

This is a work in progress - not ready for use

Introduction

This document will guide you through creating a client API for Geode in the language of your choice based on the New Client/Server Protocol.  It is a work in progress and subject to change while the new protocol is being developed.  This initial version does not address communicating with the Locator location service and addresses getting to the point where you can perform a put() and get() on a cache Region.  We will get into subscriptions, function execution and other advanced topics in later revisions.

Steps in working with a server

A client must perform startup operations in this order:

  1. Connect to a server
  2. (optional) Retrieve Server configuration information
  3. (optional) Send client configuration information
  4. (optional) Authenticate the client
  5. (optional) Fetch server partition information for Partitioned regions
  6. Perform operations
  7. (optional) send heartbeats to the server
  8. (optional) send a shutdown message

Once a shutdown message has been sent the client must start over at step 1.

We’ll go into each of these steps in the following sections but first let’s look at what a basic message looks like.

Message basics

The Geode client API breaks operations down into request messages sent to a server over TCP/IP and response messages received from the server.  All messages are transmitted using network byte ordering (a.k.a. big endian order).  All messages have a common header format and a payload specific to the message type ID.  Most client requests will cause a response message to be sent by the server when the operation completes.

Connect to a Server

Before being able to perform any operations a client must connect to a server and inform the server about its messaging capabilities (see Connect).

After connecting to the server a client may request information about the server.  This informs the client about the server’s security requirements and also tells the client how frequently it must be in contact with the server in order to keep the server from timing the client out and disconnecting from it.

At this point, unless security is enabled in the server, the client is free to send operation messages to the server and receive responses.

Retrieve server information

Depending on how it is configured a server may require a client to authenticate itself and/or perform a Diffie-Hellman key-exchange and encrypt subsequent messages.

TODO: details and links needed

Diffie-Hellman key exchange and encryption

TODO

Serialization of Keys and Values

Geode has several serialization mechanisms for keys and values such as PDX, DataSerializable and Java serialization.  It also supports conversion of JSON documents into PDX and vice-versa.  The new client/server protocol initially supports only byte arrays and JSON documents.  Support for other types of serialization will be added when 1) PDX and/or DataSerializable is documented so that clients can implement it, or 2) when serialization in Geode is made pluggable so that you can use any serialization package you like.

When using JSON to store information in Geode servers it is important to keep fields in the same order and not omit fields since doing these things will cause new PDX types to be created, slowing down your operations and bloating the server-side PDX type registry.

Performing a put() operation

To perform a Region.put(key,value) operation you must write a Put Request to the server.  The server will respond with a Put Response indicating success or failure of the operation.

Performing a get() operation

TODO

Serialization of keys and values

TODO – point to data-serialization spec or other newer documents

Handling errors

TODO

Retrying operations

TODO – also make sure there is a retry flag bit in messages that can be retried

 

  • No labels