This is a work in progress - not ready for use
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:
- Connect to a server
- (optional) Retrieve Server configuration information
- (optional) Send client configuration information
- (optional) Authenticate the client
- (optional) Fetch server partition information for Partitioned regions
- Perform operations
- (optional) send heartbeats to the server
- (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.
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
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
Performing a get() operation
Serialization of keys and values
TODO – point to data-serialization spec or other newer documents
TODO – also make sure there is a retry flag bit in messages that can be retried