Categorygithub.com/JorgenPo/hazelcast-go-client
modulepackage
1.2.1
Repository: https://github.com/jorgenpo/hazelcast-go-client.git
Documentation: pkg.go.dev

# README


Note to Hazelcast Go Client for Hazelcast 3 Users

Support for Hazelcast 3.x ended on April 9th 2021, so Go client for Hazelcast 3 will not be updated. You can still use Go client for Hazelcast 3 by migrating your project to use Go modules and adding the following in your go.mod file:

require github.com/JorgenPo/hazelcast-go-client v0.6.0

Hazelcast Go Client

Hazelcast is an open-source distributed in-memory data store and computation platform that provides a wide variety of distributed data structures and concurrency primitives.

Hazelcast Go client is a way to communicate to Hazelcast IMDG clusters and access the cluster data.

Sample Code

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/JorgenPo/hazelcast-go-client"
)

func main() {
	ctx := context.TODO()
	// create the client and connect to the cluster
	client, err := hazelcast.StartNewClient(ctx) 
    if err != nil {
    	log.Fatal(err)
    }
    // get a map
    people, err := client.GetMap(ctx, "people")
    if err != nil {
        log.Fatal(err)
    }
    personName := "Jane Doe"
    // set a value in the map
    if err = people.Set(ctx, personName, 30); err != nil {
    	log.Fatal(err)
    }
    // get a value from the map
    age, err := people.Get(ctx, personName)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("%s is %d years old.\n", personName, age)
    // stop the client to release resources
    client.Shutdown(ctx)
}

Features

  • Distributed, partitioned and queryable in-memory key-value store implementation, called Map.
  • Additional data structures and simple messaging constructs such as Replicated Map, Queue, List, PNCounter, Set and Topic.
  • Support for serverless and traditional web service architectures with Unisocket and Smart operation modes.
  • Go context support for all distributed data structures.
  • Hazelcast Cloud integration.
  • External smart client discovery.
  • Hazelcast Management Center integration.
  • Ability to listen to client lifecycle, cluster state, and distributed data structure events.

Install

Requirements:

  • Hazelcast Go client is compatible only with Hazelcast IMDG 4.x and above.
  • We support Go 1.15 and up.

In your Go module enabled project, add a dependency to github.com/JorgenPo/hazelcast-go-client:

# Depend on a specific release
$ go get github.com/JorgenPo/[email protected]

Quick Start

Hazelcast Go client requires a working Hazelcast IMDG cluster. This cluster handles the storage and manipulation of the user data.

A Hazelcast IMDG cluster consists of one or more cluster members. These members generally run on multiple virtual or physical machines and are connected to each other via the network. Any data put on the cluster is partitioned to multiple members transparent to the user. It is therefore very easy to scale the system by adding new members as the data grows. Hazelcast IMDG cluster also offers resilience. Should any hardware or software problem causes a crash to any member, the data on that member is recovered from backups and the cluster continues to operate without any downtime.

The quickest way to start a single member cluster for development purposes is to use our Docker images.

docker run --rm --name hazelcast -p 5701:5701 hazelcast/hazelcast:4.2

You can also use our ZIP or TAR distributions. After the download, you can start the Hazelcast member using the bin/start.sh script.

Starting the Default Client

Start the client with the default Hazelcast IMDG host and port using hazelcast.StartNewClient:

ctx := context.TODO()
client, err := hazelcast.StartNewClient(ctx)
// handle client start error

Starting the Client with Given Options

Note that Config structs are not thread-safe. Complete creation of the configuration in a single goroutine.

// create the default configuration
config := hazelcast.Config{}

// optionally set member addresses manually
config.Cluster.Network.SetAddresses("member1.example.com", "member2.example.com")

// create and start the client with the configuration provider
client, err := hazelcast.StartNewClientWithConfig(ctx, config)
// handle client start error

Documentation

Hazelcast Go Client documentation is hosted at pkg.go.dev.

You can view the documentation locally by using godoc:

$ godoc -http=localhost:5500

godoc is not installed by default with the base Go distribution. Install it using:

$ go get -u golang.org/x/tools/...`

Support

Join us at Go Client channel or Hazelcast at Google Groups.

Running the tests

Currently, we support only Linux, MacOS and WSL (Windows Subsystem for Linux) for testing the client.

You need to have the following installed in order to run integration tests:

  • Java 8
  • Maven 3 or better
  • Bash
  • Make

Before running the tests, starts Hazelcast Remote Controller, which enables the test suite to create clusters:

# Start RC with Hazelcast Community features
$ ./rc.sh start

# Or, start RC with Hazelcast Enterprise features
$ HAZELCAST_ENTERPRISE_KEY=ENTERPRISE-KEY-HERE ./rc.sh start 

You can run the tests using one of the following approaches:

  • Run make test-all to run integration tests.
  • Run make test-all-race to run integration tests with race detection.
  • Run make test-cover to generate the coverage report and make view-cover to view the test coverage summary and generate an HTML report.

Testing the client with SSL support requires running the remote controller with Hazelcast Enterprise features. To enable SSL connections, add ENABLE_SSL=1 to environment variables, or prepend it to the make commands above.

In order to turn on verbose logging, add ENABLE_TRACE=1 to environment variables, or prepend it to the make commands above.

License

Apache 2 License.

Copyright (c) 2008-2021, Hazelcast, Inc. All Rights Reserved.

Visit www.hazelcast.com for more information.

# Packages

Package aggregate provides aggregation functions.
No description provided by the author
Package cluster contains functions and types needed to connect to a Hazelcast cluster.
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
Package serialization contains serialization functions and types for Hazelcast Go client.
Package types contains various helper types.

# Functions

NewConfig creates the default configuration.
StartNewClient creates and starts a new client with the default configuration.
StartNewClientWithConfig creates and starts a new client with the given configuration.

# Constants

No description provided by the author
DistributedObjectCreated is the event type when a distributed object is created.
DistributedObjectDestroyed is the event type when a distributed object is destroyed.
EntryAdded is dispatched if an entry is added.
EntryAllCleared is dispatched if all entries are cleared.
EntryAllEvicted is dispatched if all entries are evicted.
EntryEvicted is dispatched if an entry is evicted.
EntryExpired is dispatched if an entry is expired.
EntryInvalidated is dispatched if an entry is invalidated.
EntryLoaded is dispatched if an entry is loaded.
EntryMerged is dispatched if an entry is merged after a network partition.
EntryRemoved is dispatched if an entry is removed.
EntryUpdated is dispatched if an entry is updated.
ItemAdded stands for item added event.
ItemRemoved stands for item removed event.
LifecycleStateChangedCluster signals that the client is connected to a new cluster.
LifecycleStateConnected signals that the client connected to the cluster.
LifecycleStateDisconnected signals that the client disconnected from the cluster.
LifecycleStateShutDown signals that the client shut down.
LifecycleStateShuttingDown signals that the client is shutting down.
LifecycleStateStarted signals that the client started.
LifecycleStateStarting signals that the client is starting.
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author

# Structs

Client enables you to do all Hazelcast operations without being a member of the cluster.
Config contains configuration for a client.
DistributedObjectNotified contains informatino about the distributed object event.
EntryNotified contains information about an entry event.
FlakeIDGenerator is a cluster-wide unique ID generator.
FlakeIDGeneratorConfig contains configuration for the pre-fetching behavior of FlakeIDGenerator.
LifecycleStateChanged contains information about a lifecycle event.
List is a concurrent, distributed, ordered collection.
ListItemNotified describes the List item event.
Map is a distributed map.
MapEntryListenerConfig contains configuration for a map entry listener.
MessagePublished contains information about a message published event.
PNCounter is a PN (Positive-Negative) CRDT counter.
Queue is a concurrent, blocking, distributed, observable queue.
QueueItemNotified contains information about an item notified event.
ReplicatedMap is a distributed key-value data structure where the data is replicated to all members in the cluster.
Set is a concurrent, distributed set implementation.
SetItemNotified contains information about an item notified event.
StatsConfig contains configuration for Management Center.
Topic is a distribution mechanism for publishing messages that are delivered to multiple subscribers, which is also known as a publish/subscribe (pub/sub) messaging model.

# Type aliases

DistributedObjectEventType describes event type of a distributed object.
DistributedObjectNotifiedHandler is called when a distribute object event occurs.
EntryEventType is the type of an entry event.
EntryNotifiedHandler is called when an entry event happens.
ItemEventType describes event types for item related events.
LifecycleState indicates the state of the lifecycle event.
LifecycleStateChangeHandler is called when a lifecycle event occurs.
ListItemNotifiedHandler is a handler function for the List item listener.
QueueItemNotifiedHandler is called when an item notified event is generated for a Queue.
SetItemNotifiedHandler is called when an item notified event is generated for a Set.
No description provided by the author