Namespace
-A shared data layer connection is instantiated to a namespace and data is
-always read and modified within the namespace. Namespace provides data isolation across clients.
-Namespace instantiation happens when the sdlgo instance is created.
-E.g. the following code sets the SDL instance to use "example" as a namespace
- sdl := sdlgo.NewSdlInstance("example", sdlgo.NewDatabase())
-Applications can use several namespaces at the same time by creating several sdlgo instances.
+Namespace concept in a shared data layer connection is to isolate data write and read operations
+to happen within particular namespace.
+
+SDL instance
+
+There are two ways to create SDL instance, the first preferable option is to create so called
+SDL multi-namespace instance with `sdlgo.NewSyncStorage` call. The second option is to create
+SDL instance with `sdlgo.NewSdlInstance` call. Latter SDL instance creation method is deprecated
+and it should not be used anymore in any new application implementations, it is left to SDL API
+to guarantee backward compatibility for the old application implementations.
+The difference between multi-namespace `SyncStorage` SDL instance and the old one is that in
+`SyncStorage` case namespace is not defined at instance creation time, but it is defined when
+SDL read and write APIs are called. This means that with SDL `SyncStorage` instance it is much
+easier to write and read data from different namespaces in a single application client compared
+to the old SDL API where you needed to create own SDL instance for each namespace going to be
+used later to write and read data.
Database connection
-In addition to creating the SDL instance, application is responsible for creating the backend
-database connection with NewDatabase() method. When the connection is created, sdlgo shall open a
-tcp connection to backend database immediatelly. The resulting connection may be used with several
-SDL instances if application needs to use several namespaces at a time. E.g.
- connection := sdlgo.NewDatabase()
- ns1 := sdlgo.NewSdlInstance("ns1", connection)
- ns2 := sdlgo.NewSdlInstance("ns2", connection)
+When `SyncStorage` instance is created, it also creates database backend connection, this means
+that sdlgo shall open a tcp connection to backend database. Below is example how to create SDL
+`SyncStorage` instance and what also connects to database backend under the hood:
+ sdl := sdlgo.NewSyncStorage()
+
For the backend database connection a circuit breaker design is used. If the connection fails,
-an error is returned immediatelly to application. Restoration of the connection happens
+an error is returned immediately to application. Restoration of the connection happens
automatically by SDL and application should retry the operation again after a while.
-Database service is discovered by using environment variables DBAAS_SERVICE_HOST and
+Database service is discovered by using DBAAS* environment variables. For simple standalone
+DBAAS case there are needed two environment variables: DBAAS_SERVICE_HOST and
DBAAS_SERVICE_PORT. If not set, localhost and port 6379 are used by default.
Keys and data
Some examples on how to set the data using different kind of input parameters:
Basic usage, keys and values are given as own parameters (with mixed data types)
- err := s.Set("key1", "value1", "key2", 2)
+ err := s.Set("example-namaspace", "key1", "value1", "key2", 2)
Keys and values inside a slice (again with mixed types, thus empty interface used as a type)
exampleSlice := []interface{"key1", "value1", "key2", 2}
- err := s.Set(exampleSlice)
+ err := s.Set("example-namaspace", exampleSlice)
Data stored to a byte array
data := make([]byte), 3
In order to publish changes to SDL data, the publisher need to call an API function that supports
publishing. E.g.
- err := sdl.SetAndPublish([]string{"channel1", "event1", "channel2", "event2"}, "key", "value")
+ err := sdl.SetAndPublish("example-namespace", []string{
+ "channel1", "event1", "channel2", "event2"}, "key", "value",
+ )
+
This example will publish event1 to channel1 and event2 in channel2 after writing the data.
When subscribing the channels, the application needs to first create an SDL instance for the desired
It is possible to make several subscriptions for different channels using different callback
functions if different kind of handling is required.
- sdl := sdlgo.NewSdlInstance("namespace", sdlgo.NewDatabase())
+ sdl := sdlgo.NewSyncStorage()
cb1 := func(channel string, event ...string) {
fmt.Printf("cb1: Received %s from channel %s\n", event, channel)
fmt.Printf("cb2: Received %s from channel %s\n", event, channel)
}
- sdl.SubscribeChannel(cb1, "channel1", "channel2")
- sdl.SubscribeChannel(cb2, "channel3")
+ sdl.SubscribeChannel("example-namespace", cb1, "channel1", "channel2")
+ sdl.SubscribeChannel("example-namespace", cb2, "channel3")
-This example subscribes three channels from "namespace" and assigns cb1 for channel1 and channel2
+This example subscribes three channels from "example-namespace" and assigns cb1 for channel1 and channel2
whereas channel3 is assigned to cb2.
The callbacks are called from a context of a goroutine that is listening for the events. When
Code Review / ric-plt / sdlgo.git / blobdiff