-
Notifications
You must be signed in to change notification settings - Fork 3
FAQ
The Coherence Go client allows Go applications to act as cache clients to a Coherence cluster using gRPC for the network transport.
The Coherence Go client supports Go version 1.19 and above.
Note: Version 1.18 of Go is not supported due to various generics bugs in Go itself.
The following Coherence versions are supported with a configured gRPCProxy.
- Coherence CE versions 22.06.4+ and 24.03+
- Coherence Commercial versions 14.1.1.2206.4+
Yes, the Coherence Go client fully supports Go generics when accessing Coherence API's.
- Familiar Map-like operations for manipulating cache entries such as:
-
Put,PutIfAbsent,PutAll,Get,GetAll,Remove,Clear,GetOrDefault,Replace,ReplaceMapping,Size,IsEmpty,ContainsKey,ContainsValue,ContainsEntry
-
- Cluster-side querying, aggregation and filtering of map entries
- Cluster-side manipulation of map entries using EntryProcessors
- Registration of listeners to be notified of:
- mutations such as insert, update and delete on Maps
- map lifecycle events such as truncated, released or destroyed
- session lifecycle events such as connected, disconnected, reconnected and closed
- Support for storing Go structs as JSON as well as the ability to serialize to Java objects on the server for access from other Coherence language API's
By default, the Coherence Go Client serializes any keys and values to JSON and then stores them as JsonObjects in Coherence. This is usually sufficient for most applications where you are only accessing your data via the Go Client.
If you wish to access your data via other clients such as Java, JavaScript, C++, .NET or Python, you can use Java classes, known to Coherence server, representing the data model.
See the Documentation for more information.
NamedMap and NamedCache are identical except that NamedCache provides the PutWithExpiry function allowing you to expire cache entries. If you do not wish to expire entries, then just use NamedMap as entries will never expire.
The Coherence Go client return pointers to generic types, to allow for nil (or null equivalent in Java) values to be represented.
In Go, generic values cannot be nil and it is not correct assume a generic types' zero value represents nil as the zero value could represent a valid value. e.g. 0 for an int.
For example, the definition of Get() is shown below, in which if you try to get a value for a key which doesn't exist, it will return nil pointer.
type NamedMap[K comparable, V any] interface {
...
// Get returns the value to which the specified key is mapped. V will be nil
// if there was no previous value.
Get(ctx context.Context, key K) (*V, error)
We could use this example like below to test for a nil value or non-existence of a value for a key.
if value, err = namedCache.Get(ctx, 1); err != nil {
panic(err)
}
if value == nil {
fmt.Println("Value for key 1 does not exist")
return
}
// NOTE: we need to dereference the pointer otherwise we will get the pointer and not the value
fmt.Println("Value for key 1 is", *value)
Note: You could also use
ContainsKeyin this specific case.
By default there is a 30000 millis (or 30 seconds) timeout for all operations that take a Context. This timeout is configured automatically on each API call if you do not specify a Context with a deadline, e.g. context.Background().
Note: This timeout is applied by creating a new
context.WithTimeouton each API using the timeout configured in the session.
If you specify a Context with a deadline, then your Context will be used for all calls.
You can override the default timeout using the following:
-
Specify timeout on creating a session
session, err = coherence.NewSession(ctx, coherence.WithRequestTimeout(time.Duration(5) * time.Second)) -
Set the
COHERENCE_CLIENT_REQUEST_TIMEOUTenvironment variableFor example, set the session timeout to 20000 millis
COHERENCE_CLIENT_REQUEST_TIMEOUT=20000 go run main.go
By default, if an endpoint is not ready, the Go client will fail-fast. You can change this behaviour by setting
the option coherence.WithReadyTimeout to a value millis value greater than zero which will cause the Go client
to wait until up to the timeout specified until it fails if no endpoint is available.
You can also use the environment variable COHERENCE_READY_TIMEOUT.
For example, if you want to wait 5 seconds before raising an error when connecting, you can use:
session, err = coherence.NewSession(ctx, coherence.WithReadyTimeout(time.Duration(5) * time.Second))
You have the ability to control maximum amount of time, in milliseconds, a Session may remain in a disconnected state
without successfully reconnecting. For this you use the option coherence.WithDisconnectTimeout() or the environment
variable COHERENCE_SESSION_DISCONNECT_TIMEOUT.
session, err = coherence.NewSession(ctx, coherence.WithDisconnectTimeout(time.Duration(30) * time.Second))
You can export the environment variable COHERENCE_SESSION_DEBUG=true to show additional session connection information.
You can also set COHERENCE_RESOLVER_DEBUG=true to show debug information when using the Coherence Resolver.
Yes, if you do not specify -Dcoherence.grpc.server.port=1408 when starting Coherence, and leave it at the default of zero (0), Coherence will use ephemeral ports for the listen ports. You can then use the following URL to specify to connect to the cluster port, usually 7574, and the gRPC ports will automatically be discovered by the configured gRPC resolver.
COHERENCE_SERVER_ADDRESS=coherence:///server1:7574
OR
session, err := coherence.NewSession(ctx, coherence.WithAddress("coherence:///localhost:7574"))
The gRPC connections will be load balanced across all gRPC endpoints in the cluster.
- Comprehensive Go client API examples
- Coherence ToDo Client including Java, JavaScript, GraphQL and Go clients
If you would like to raise an issue please see here.
Please consult the security guide for our responsible security vulnerability disclosure process.