Infinispan Go Client Guide

go get infinispan.org/go-client

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"infinispan.org/go-client/hotrod"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()

	client, err := hotrod.NewClient(ctx, "hotrod://admin:password@localhost:11222")
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	cache := client.Cache("my-cache")

	cache.Put(ctx, []byte("greeting"), []byte("hello world"))

	val, found, err := cache.Get(ctx, []byte("greeting"))
	if err != nil {
		log.Fatal(err)
	}
	if found {
		fmt.Println(string(val))
	}
}

hotrod://username:password@host:port
hotrods://username:password@host:port

client, err := hotrod.NewClient(ctx, "hotrod://admin:password@localhost:11222",
	hotrod.WithClientIntelligence(hotrod.IntelligenceTopologyAware),
	hotrod.WithConnectTimeout(5*time.Second),
	hotrod.WithSocketTimeout(10*time.Second),
)

hotrod://admin:password@localhost:11222?connect_timeout=5s&socket_timeout=10s&tcp_no_delay=true&tcp_keep_alive=false

client, err := hotrod.NewClient(ctx, "hotrod://admin:password@localhost:11222")

client, err := hotrod.NewClient(ctx, "hotrod://localhost:11222",
	hotrod.WithAuth("SCRAM-SHA-256", "admin", "password"),
)

client, err := hotrod.NewClient(ctx, "hotrod://localhost:11222",
	hotrod.WithToken("eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."),
)

hotrod://localhost:11222?sasl_mechanism=OAUTHBEARER&token=eyJhbGci...

client, err := hotrod.NewClient(ctx, "hotrod://localhost:11222",
	hotrod.WithAuth("OAUTHBEARER", "", ""),
	hotrod.WithToken(token),
)

hotrods://admin:password@localhost:11222?trust_store_file_name=/path/to/ca.pem&sni_host_name=infinispan.example.com
hotrods://localhost:11222?client_cert=/path/to/cert.pem&client_key=/path/to/key.pem

cache := client.Cache("my-cache")

// Store an entry.
err := cache.Put(ctx, []byte("key"), []byte("value"))

// Retrieve an entry.
val, found, err := cache.Get(ctx, []byte("key"))

// Delete an entry.
err = cache.Remove(ctx, []byte("key"))

// Store and get the previous value.
prev, err := cache.GetAndPut(ctx, []byte("key"), []byte("new-value"))

// Remove and get the previous value.
prev, existed, err := cache.GetAndRemove(ctx, []byte("key"))

mv, found, err := cache.GetWithMetadata(ctx, []byte("key"))
if found {
	fmt.Printf("value=%s version=%d created=%d lifespan=%d\n",
		mv.Value, mv.Version, mv.Created, mv.Lifespan)
}

ok, err := cache.ReplaceIfUnmodified(ctx, []byte("key"), []byte("new"), mv.Version)
ok, err = cache.RemoveIfUnmodified(ctx, []byte("key"), mv.Version)

entries := map[string][]byte{
	"key1": []byte("val1"),
	"key2": []byte("val2"),
}
err := cache.PutAll(ctx, entries)

result, err := cache.GetAll(ctx, []string{"key1", "key2"})

cache.Put(ctx, []byte("key"), []byte("value"),
	hotrod.WithLifespan(30*time.Second),
	hotrod.WithMaxIdle(10*time.Second),
)

cache.Put(ctx, []byte("key"), []byte("value"),
	hotrod.WithPutFlag(hotrod.FlagSkipListenerNotification),
)

schemas := client.Schemas()

err := schemas.Register(ctx, "person.proto", `
syntax = "proto3";
package example;

message Person {
    string name = 1;
    int32 age = 2;
}
`)

content, found, err := schemas.Get(ctx, "person.proto")

marshaller := hotrod.NewProtoStreamMarshaller("example.Person")

cache := hotrod.NewTypedCache[string, *Person](
	client, "people", marshaller,
	func() *Person { return &Person{} },
)

err := cache.Put(ctx, "john", &Person{Name: "John", Age: 30})

person, found, err := cache.Get(ctx, "john")

type Marshaller interface {
	MarshalKey(key any) ([]byte, error)
	UnmarshalKey(data []byte, target any) error
	MarshalValue(value any) ([]byte, error)
	UnmarshalValue(data []byte, target any) error
	MediaType() int32
}

nc, err := hotrod.NewNearCache(ctx, client, "my-cache",
	hotrod.WithMaxNearCacheEntries(1000),
)
defer nc.Close(ctx)

listener, err := cache.AddListener(ctx)
if err != nil {
	log.Fatal(err)
}
defer cache.RemoveListener(ctx, listener)

for event := range listener.Events {
	fmt.Printf("type=%d key=%s\n", event.Type, event.Key)
}

listener, err := cache.AddListener(ctx,
	hotrod.WithListenerInterests(hotrod.EventCreated, hotrod.EventRemoved),
	hotrod.WithChannelSize(128),
)

result, err := cache.Query(ctx, "FROM example.Person WHERE age >= 30")

result, err := cache.Query(ctx, "FROM example.Person")

result, err := cache.Query(ctx, "FROM example.Person WHERE age > :minAge",
    hotrod.WithQueryParam("minAge", int32(25)),
)

result, err := cache.Query(ctx, "SELECT name, age FROM example.Person WHERE age > :minAge",
    hotrod.WithQueryParam("minAge", int32(25)),
)

result, err := cache.Query(ctx, "FROM example.Person ORDER BY age DESC")

result, err := cache.Query(ctx, "FROM example.Person ORDER BY age",
    hotrod.WithQueryMaxResults(10),
    hotrod.WithQueryStartOffset(0),
)
fmt.Printf("returned=%d total=%d exact=%v\n",
    result.NumResults, result.HitCount, result.HitCountExact)

result, err := cache.Query(ctx,
    "FROM example.PersonWithAddress WHERE addresses.city = :city",
    hotrod.WithQueryParam("city", "London"),
)

result, err := cache.Query(ctx,
    "FROM example.PersonWithAddress WHERE addresses.city = :city AND age > :minAge",
    hotrod.WithQueryParam("city", "London"),
    hotrod.WithQueryParam("minAge", int32(25)),
)

cq, err := cache.ContinuousQuery(ctx, "FROM example.Person WHERE age >= :minAge",
	hotrod.WithCQParam("minAge", int32(18)),
)
if err != nil {
	log.Fatal(err)
}
defer cache.RemoveContinuousQuery(ctx, cq)

for event := range cq.Events {
	switch event.Type {
	case hotrod.CQJoining:
		fmt.Printf("joined: key=%s\n", event.Key)
	case hotrod.CQUpdated:
		fmt.Printf("updated: key=%s\n", event.Key)
	case hotrod.CQLeaving:
		fmt.Printf("left: key=%s\n", event.Key)
	}
}

client, err := hotrod.NewClient(ctx, uri,
	hotrod.WithClientIntelligence(hotrod.IntelligenceTopologyAware),
)

servers := client.TopologyServers()
fmt.Printf("cluster members: %v\n", servers)

if client.HasConsistentHash("my-cache") {
	owners := client.ConsistentHashOwnerCount("my-cache")
	fmt.Printf("owner count: %d\n", owners)
}

mm := client.Multimap("my-multimap")

mm := client.Multimap("my-multimap",
	hotrod.WithSupportsDuplicates(true),
)

err := mm.Put(ctx, []byte("colors"), []byte("red"), []byte("blue"), []byte("green"))

values, err := mm.Get(ctx, []byte("colors"))
for _, v := range values {
	fmt.Println(string(v))
}

err := mm.PutWithOptions(ctx, []byte("colors"),
	[][]byte{[]byte("red"), []byte("blue")},
	[]hotrod.PutOption{hotrod.WithLifespan(30 * time.Second)},
)

coll, found, err := mm.GetWithMetadata(ctx, []byte("colors"))
if found {
	fmt.Printf("values=%d version=%d\n", len(coll.Values), coll.Version)
}

removed, err := mm.RemoveKey(ctx, []byte("colors"))
removed, err = mm.RemoveEntry(ctx, []byte("colors"), []byte("red"))

hasKey, err := mm.ContainsKey(ctx, []byte("colors"))
hasEntry, err := mm.ContainsEntry(ctx, []byte("colors"), []byte("red"))
total, err := mm.Size(ctx)

counters := client.Counters()

created, err := counters.Define(ctx, "my-counter", &hotrod.CounterConfiguration{
	Type:         hotrod.CounterStrong,
	Storage:      hotrod.StoragePersistent,
	Bounded:      true,
	LowerBound:   0,
	UpperBound:   1000,
	InitialValue: 0,
})

// List all counter names.
names, err := counters.Names(ctx)

// Check if a counter exists.
exists, err := counters.IsDefined(ctx, "my-counter")

// Get the configuration of a counter.
config, err := counters.GetConfiguration(ctx, "my-counter")

// Remove a counter. It is re-created if accessed again.
err = counters.Remove(ctx, "my-counter")

counter := counters.Counter("my-counter")

// Get the current value.
val, err := counter.Get(ctx)

// Add a delta and get the new value.
newVal, err := counter.AddAndGet(ctx, 5)

// Set a new value and get the previous value.
prev, err := counter.GetAndSet(ctx, 100)

// Atomic compare-and-swap.
oldVal, swapped, err := counter.CompareAndSwap(ctx, 100, 200)

// Reset to the initial value.
err = counter.Reset(ctx)

listener, err := counter.AddListener(ctx)
if err != nil {
	log.Fatal(err)
}
defer counter.RemoveListener(ctx, listener)

for event := range listener.Events {
	fmt.Printf("counter=%s old=%d new=%d\n", event.Name, event.OldValue, event.NewValue)
}

iter, err := cache.Iterator(ctx,
	hotrod.WithIteratorBatchSize(500),
	hotrod.WithIteratorMetadata(),
)

for iter.Next() {
	key, value := iter.Entry()
	md := iter.Metadata()
	if md != nil {
		fmt.Printf("key=%s version=%d created=%d\n", key, md.Version, md.Created)
	}
}

go build ./...

go test -short ./...

go test -timeout 120s ./test/...