coherence-go-client

module
v1.2.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 23, 2024 License: UPL-1.0

README

Coherence Go Client

Coherence Go Client License Security Rating

Go Report Card GitHub release (latest by date) Go Reference

The Coherence Go Client allows Go applications to act as cache clients to a Coherence Cluster using gRPC for the network transport.

Coherence is a scalable, fault-tolerant, cloud-ready, distributed platform for building grid-based applications and reliably storing data. The product is used at scale, for both compute and raw storage, in a vast array of industries such as critical financial trading systems, high performance telecommunication products and eCommerce applications.

Features
  • Familiar Map-like interface for manipulating cache entries including but not limited to:
    • Put, PutWithExpiry, 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
  • Near cache support to cache frequently accessed data in the Go client to avoid sending requests across the network
  • Support for Queues in Coherence Community Edition 24.03+
  • Full support for Go generics in all Coherence API's
Requirements
  • Coherence CE 22.06.4+, 24.03+ or Coherence 14.1.1.2206.4+ Commercial edition with a configured gRPCProxy.
  • Go 1.19.+
Starting a gRPC enabled Coherence cluster

Before testing the Go client, you must ensure a Coherence cluster is available. For local development, we recommend using the Coherence CE Docker image; it contains everything necessary for the client to operate correctly.

docker run -d -p 1408:1408 -p 30000:30000 ghcr.io/oracle/coherence-ce:24.03

Installation

go get github.com/oracle/coherence-go-client@latest

After executing this command coherence-go-client is ready to use, and it's source will be in:

$GOPATH/pkg/mod/github.com/oracle/coherence-go-client@version

Documentation

Examples

For a comprehensive set of Go client API examples, please see examples.

The following example connects to a Coherence cluster running gRPC Proxy on default port of 1408, creates a new NamedMap with key int and value of a string and issues Put(), Get() and Size() operations.

Note: Keys and values can also be Go structs. See detailed examples here.

package main

import (
    "context"
    "fmt"
    "github.com/oracle/coherence-go-client/coherence"
)

func main() {
    var (
        value *string
        ctx   = context.Background()
    )

    // create a new Session to the default gRPC port of 1408
    session, err := coherence.NewSession(ctx, coherence.WithPlainText())
    if err != nil {
        panic(err)
    }
    defer session.Close()

    // get a NamedMap with key of int and value of string
    namedMap, err := coherence.GetNamedMap[int, string](session, "my-map")
    if err != nil {
        panic(err)
    }

    // put a new key / value
    if _, err = namedMap.Put(ctx, 1, "one"); err != nil {
        panic(err)
    }
	
    // get the value for key 1
    if value, err = namedMap.Get(ctx, 1); err != nil {
       panic(err)
    }
    fmt.Println("Value for key 1 is", *value)

    // update the value for key 1
    if _, err = namedMap.Put(ctx, 1, "ONE"); err != nil {
        panic(err)
    }

    // get the updated value for key 1
    if value, err = namedMap.Get(ctx, 1); err != nil {
        panic(err)
    }
    fmt.Println("Updated value is", *value)

    // remove the entry
    if _, err = namedMap.Remove(ctx, 1); err != nil {
        panic(err)
    }
}

Help

We have a public Slack channel where you can get in touch with us to ask questions about using the Coherence Go client as well as give us feedback or suggestions about what features and improvements you would like to see. We would love to hear from you. To join our channel, please visit this site to get an invitation.
The invitation email will include details of how to access our Slack workspace. After you are logged in, please come to #coherence and say, "hello!"

If you would like to raise an issue please see here.

You may also find your question is already answered on our FAQ or troubleshooting Wiki.

Contributing

This project welcomes contributions from the community. Before submitting a pull request, please review our contribution guide

Security

Please consult the security guide for our responsible security vulnerability disclosure process.

License

Copyright (c) 2023 Oracle and/or its affiliates.

Released under the Universal Permissive License v1.0 as shown at https://oss.oracle.com/licenses/upl/.

Directories

Path Synopsis
Package coherence provides a set of functions and interfaces for Go programs to act as cache clients to a Coherence Cluster using gRPC for the network transport.
Package coherence provides a set of functions and interfaces for Go programs to act as cache clients to a Coherence Cluster using gRPC for the network transport.
aggregators
Package aggregators provides various aggregator functions and types.
Package aggregators provides various aggregator functions and types.
discovery
Package discovery provides an implementation of Coherence NSLookup.
Package discovery provides an implementation of Coherence NSLookup.
extractors
Package extractors provides various extractor functions and types.
Package extractors provides various extractor functions and types.
filters
Package filters provides various filter functions and types.
Package filters provides various filter functions and types.
processors
Package processors provides various entry processor functions and types.
Package processors provides various entry processor functions and types.
Package examples provides various examples using the coherence-go-client.
Package examples provides various examples using the coherence-go-client.
aggregators
Package main shows aggregation examples using a NamedMap with key of int and value of Person struct.
Package main shows aggregation examples using a NamedMap with key of int and value of Person struct.
basic/contains
Package main shows how to use ContainsKey, ContainsValue and ContainsEntry against a NamedCache.
Package main shows how to use ContainsKey, ContainsValue and ContainsEntry against a NamedCache.
basic/crud
Package main shows how to carry out basic operations against a NamedMap with primitive types.
Package main shows how to carry out basic operations against a NamedMap with primitive types.
basic/expiry
Package main shows how to put entries that expire in a NamedCache.
Package main shows how to put entries that expire in a NamedCache.
basic/expiry_cache
Package main shows how to put entries that expire in a NamedCache using the coherence.WithExpiry option.
Package main shows how to put entries that expire in a NamedCache using the coherence.WithExpiry option.
basic/near_cache/high_units
Package main shows how to use a near cache with a NamedMap or NamedCache with high units of 1000.
Package main shows how to use a near cache with a NamedMap or NamedCache with high units of 1000.
basic/near_cache/memory
Package main shows how to use a near cache with a NamedMap or NamedCache with high units memory of 10k.
Package main shows how to use a near cache with a NamedMap or NamedCache with high units memory of 10k.
basic/near_cache/ttl
Package main shows how to use a near cache with a NamedMap or NamedCache with an expiry of 10 seconds.
Package main shows how to use a near cache with a NamedMap or NamedCache with an expiry of 10 seconds.
basic/struct
Package main shows how to carry out basic operations against a NamedMap with a key of int and value of Person struct.
Package main shows how to carry out basic operations against a NamedMap with a key of int and value of Person struct.
basic/struct_keys
Package main shows how to carry out basic operations against a NamedMap where a key and value are structs.
Package main shows how to carry out basic operations against a NamedMap where a key and value are structs.
events
Package events shows examples using events.
Package events shows examples using events.
events/cache
Package cache shows examples using MapEvents.
Package cache shows examples using MapEvents.
events/cache/all
Package main shows how to listen for all events on a NamedMap or NamedCache.
Package main shows how to listen for all events on a NamedMap or NamedCache.
events/cache/delete
Package main shows how to listen for delete events on a NamedMap or NamedCache.
Package main shows how to listen for delete events on a NamedMap or NamedCache.
events/cache/filters
Package main shows how to listen for all events on a NamedMap or NamedCache using filters.
Package main shows how to listen for all events on a NamedMap or NamedCache using filters.
events/cache/insert
Package main shows how to listen for insert events on a NamedMap or NamedCache.
Package main shows how to listen for insert events on a NamedMap or NamedCache.
events/cache/key
Package main shows how to listen for events on a NamedMap or NamedCache for a specific key.
Package main shows how to listen for events on a NamedMap or NamedCache for a specific key.
events/cache/people_insert
Package main inserts entries into a people NamedMap insert PutAll().
Package main inserts entries into a people NamedMap insert PutAll().
events/cache/people_listen
Package main listens for all events on a NamedMap or NamedCache.
Package main listens for all events on a NamedMap or NamedCache.
events/cache/update
Package main shows how to listen for update events on a NamedMap or NamedCache.
Package main shows how to listen for update events on a NamedMap or NamedCache.
events/lifecycle/all
Package main shows how to listen for all lifecycle events on a NamedMap or NamedCache.
Package main shows how to listen for all lifecycle events on a NamedMap or NamedCache.
events/lifecycle/destroyed
Package main shows how to listen for destroyed events on a NamedMap or NamedCache.
Package main shows how to listen for destroyed events on a NamedMap or NamedCache.
events/lifecycle/released
Package main shows how to listen for released events on a NamedMap or NamedCache.
Package main shows how to listen for released events on a NamedMap or NamedCache.
events/lifecycle/truncated
Package main shows how to listen for truncated events on a NamedMap or NamedCache.
Package main shows how to listen for truncated events on a NamedMap or NamedCache.
events/session/all
Package main shows how to listen for all session events on a NamedMap or NamedCache.
Package main shows how to listen for all session events on a NamedMap or NamedCache.
indexes
Package main shows examples using indexes.
Package main shows examples using indexes.
processors/blind
Package main shows how to run processors against a NamedMap or NamedCache using the *Blind utilities methods.
Package main shows how to run processors against a NamedMap or NamedCache using the *Blind utilities methods.
processors/standard
Package main shows how to run processors against a NamedMap or NamedCache.
Package main shows how to run processors against a NamedMap or NamedCache.
querying
Package main shows how to run open-ended queries against a NamedMap or NamedCache using keys.
Package main shows how to run open-ended queries against a NamedMap or NamedCache using keys.
querying/filters
Package main shows how to run queries against a NamedMap or NamedCache using filters.
Package main shows how to run queries against a NamedMap or NamedCache using filters.
querying/keys
Package main shows how to run queries against a NamedMap or NamedCache using keys.
Package main shows how to run queries against a NamedMap or NamedCache using keys.
queues
Package main shows examples using queues.
Package main shows examples using queues.
queues/blocking/processor
Package main shows how to use a blocking queue.
Package main shows how to use a blocking queue.
queues/blocking/publisher
Package main shows how to use a blocking queue.
Package main shows how to use a blocking queue.
queues/blocking/subscriber
Package main shows how to use a blocking queue.
Package main shows how to use a blocking queue.
queues/standard
Package main shows how to use queues.
Package main shows how to use queues.
rest
Package main starts a listener on port localhost:17268 which provides a basic REST API providing POST, GET, PUT and DELETE operations against a NamedMap.
Package main starts a listener on port localhost:17268 which provides a basic REST API providing POST, GET, PUT and DELETE operations against a NamedMap.
Package proto contains automatically generated gRPC code.
Package proto contains automatically generated gRPC code.
Package test provides tests for the coherence-go-client.
Package test provides tests for the coherence-go-client.
e2e/queues
Package queues provides integration tests for the coherence-go-client with queues for 24.03 and above.
Package queues provides integration tests for the coherence-go-client with queues for 24.03 and above.
e2e/scope
Package scope provides integration tests for the coherence-go-client with scope set.
Package scope provides integration tests for the coherence-go-client with scope set.
e2e/standalone
Package standalone provides integration tests for the coherence-go-client.
Package standalone provides integration tests for the coherence-go-client.
utils
Package utils provides various utilities for testing the coherence-go-client.
Package utils provides various utilities for testing the coherence-go-client.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL