177 dockter 1 (#178)

* #177 Migrate from g2 to er/sz * #177 Savepoint * #177 Savepoint * #177 Savepoint * #177 Prepare for versioned release
senzing-garage · Aug 19, 2024 · 22480a2 · 22480a2
1 parent 8e315d8
commit 22480a2
Show file tree

Hide file tree

Showing 31 changed files with 203 additions and 144 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,12 @@ and this project adheres to [Semantic Versioning].
 
 -
 
+## [0.14.0] - 2024-08-19
+
+### Changed in 0.14.0
+
+- Change from `g2` to `sz`/`er`
+
 ## [0.13.6] - 2024-08-02
 
 ### Changed in 0.13.6

diff --git a/Makefile b/Makefile
@@ -33,10 +33,10 @@ GO_ARCH = $(word 2, $(GO_OSARCH))
 
 # Conditional assignment. ('?=')
 # Can be overridden with "export"
-# Example: "export LD_LIBRARY_PATH=/path/to/my/senzing/g2/lib"
+# Example: "export LD_LIBRARY_PATH=/path/to/my/senzing/er/lib"
 
 GOBIN ?= $(shell go env GOPATH)/bin
-LD_LIBRARY_PATH ?= /opt/senzing/g2/lib
+LD_LIBRARY_PATH ?= /opt/senzing/er/lib
 
 # Export environment variables.
 

diff --git a/README.md b/README.md
@@ -93,6 +93,7 @@ Documentation and examples for the implementations are at:
 [Senzing/sz-sdk-go-core]: https://github.com/senzing-garage/sz-sdk-go-core
 [Senzing/sz-sdk-go-grpc]: https://github.com/senzing-garage/sz-sdk-go-grpc
 [Senzing/sz-sdk-go-mock]: https://github.com/senzing-garage/sz-sdk-go-mock
+[sz-sdk-go-core]: https://pkg.go.dev/github.com/senzing-garage/sz-sdk-go-core
 [sz-sdk-go-grpc]: https://pkg.go.dev/github.com/senzing-garage/sz-sdk-go-grpc
 [sz-sdk-go-mock]: https://pkg.go.dev/github.com/senzing-garage/sz-sdk-go-mock
 [Szconfig]: https://pkg.go.dev/github.com/senzing-garage/sz-sdk-go/szconfig#Szconfig

diff --git a/doc.go b/doc.go
@@ -1,18 +1,45 @@
 /*
+The Senzing sz-sdk-go packages contain interface definitions for the Senzing Go SDK.
+
 # Synopsis
 
-The Senzing sz-sdk-go packages contain definitions that are common to implementations of the Senzing Go SDK.
+The Senzing sz-sdk-go packages contain definitions, messages, and functions that are common to implementations of the Senzing Go SDK.
 
 # Overview
 
-The Senzing sz-sdk-go implementations enable Go programs to call Senzing library functions.
-Under the covers, Golang's CGO is used by the sz-sdk-go packages to make the calls
-to the Senzing C library functions.
+The Senzing [sz-sdk-go] implementations enable Go programs to call Senzing library functions.
+
+Implementations:
+
+  - [sz-sdk-go-core] - An implementation that uses the Senzing native C binaries.
+  - [sz-sdk-go-grpc] - An implementation that communicates with a [Senzing gRPC server].
+  - [sz-sdk-go-mock] - An implementation that creates Senzing [mock objects].
 
-More information at https://github.com/senzing-garage/sz-sdk-go
+A client of the Senzing Go SDK API should use the following interfaces to maintain compatiblity across implementations.
 
-# Examples
+  - [senzing.SzAbstractFactory]
+  - [senzing.SzConfig]
+  - [senzing.SzConfigManager]
+  - [senzing.SzDiagnostic]
+  - [senzing.SzEngine]
+  - [senzing.SzProduct]
 
-Examples of use can be seen in the xxxx_test.go files.
+More information at [sz-sdk-go].
+
+[mock objects]: https://en.wikipedia.org/wiki/Mock_object
+[Senzing gRPC server]: https://github.com/senzing-garage/serve-grpc
+[sz-sdk-go-core]: https://pkg.go.dev/github.com/senzing-garage/sz-sdk-go-core
+[sz-sdk-go-grpc]: https://pkg.go.dev/github.com/senzing-garage/sz-sdk-go-grpc
+[sz-sdk-go-mock]: https://pkg.go.dev/github.com/senzing-garage/sz-sdk-go-mock
+[sz-sdk-go]: https://github.com/senzing-garage/sz-sdk-go
 */
 package main
+
+import (
+	"github.com/senzing-garage/sz-sdk-go/senzing"
+)
+
+// Hack to import "senzing"
+func _() {
+	_ = senzing.Bit18
+}
diff --git a/docs/development.md b/docs/development.md
@@ -21,8 +21,8 @@ These are "one-time tasks" which may already have been completed.
 Since the Senzing library is a prerequisite, it must be installed first.
 
 1. Verify Senzing C shared objects, configuration, and SDK header files are installed.
-    1. `/opt/senzing/g2/lib`
-    1. `/opt/senzing/g2/sdk/c`
+    1. `/opt/senzing/er/lib`
+    1. `/opt/senzing/er/sdk/c`
     1. `/etc/opt/senzing`
 
 1. If not installed, see [How to Install Senzing for Go Development].
@@ -114,7 +114,7 @@ Create a code coverage map.
 
 1. If a web page doesn't appear, visit [localhost:6060].
 1. Senzing documentation will be in the "Third party" section.
-   `github.com` > `senzing` > `go-cmdhelping`
+   `github.com` > `senzing-garage` > `sz-sdk-go`
 
 1. When a versioned release is published with a `v0.0.0` format tag,
 the reference can be found by clicking on the following badge at the top of the README.md page.

diff --git a/makefiles/darwin.mk b/makefiles/darwin.mk
@@ -4,7 +4,7 @@
 # Variables
 # -----------------------------------------------------------------------------
 
-SENZING_DIR ?= /opt/senzing/g2
+SENZING_DIR ?= /opt/senzing/er
 SENZING_TOOLS_SENZING_DIRECTORY ?= $(SENZING_DIR)
 
 LD_LIBRARY_PATH ?= $(SENZING_TOOLS_SENZING_DIRECTORY)/lib:$(SENZING_TOOLS_SENZING_DIRECTORY)/lib/macos

diff --git a/makefiles/linux.mk b/makefiles/linux.mk
@@ -4,7 +4,7 @@
 # Variables
 # -----------------------------------------------------------------------------
 
-LD_LIBRARY_PATH ?= /opt/senzing/g2/lib
+LD_LIBRARY_PATH ?= /opt/senzing/er/lib
 SENZING_TOOLS_DATABASE_URL ?= sqlite3://na:na@nowhere/tmp/sqlite/G2C.db
 PATH := $(MAKEFILE_DIRECTORY)/bin:/$(HOME)/go/bin:$(PATH)
 

diff --git a/response/doc.go b/response/doc.go
@@ -1,4 +1,4 @@
 /*
-The response package...
+Package response is used to marshal JSON strings into Go objects.
 */
 package response
diff --git a/response/response_test.go b/response/response_test.go
@@ -1,7 +1,7 @@
 // DO NOT EDIT.  This code is generated.
 // Generated by: sz-sdk-go/bin/generate_senzing_unmarshal_test.py
 // Generated for: sz-sdk-go/senzing/unmarshal_test.go
-// Generated date: 2024-08-02T14:30:08.928798+00:00
+// Generated date: 2024-08-19T19:40:12.113984+00:00
 
 package response
 

diff --git a/senzing/doc.go b/senzing/doc.go
@@ -0,0 +1,4 @@
+/*
+Package senzing contains the Senzing Go SDK API interface.
+*/
+package senzing
diff --git a/senzing/flags.go b/senzing/flags.go
@@ -4,13 +4,18 @@ package senzing
 // Constants
 // ----------------------------------------------------------------------------
 
+/*
+A flag with no flags set.
+*/
 const (
 	SzNoFlags int64 = 0
 )
 
-// Flags used by the Senzing SzEngine.
-// These flags are single-bit flags.
-// BitNN is for bits numbered as 1..64 (not 0..63).  Comments are for bits numbered as 0..63
+/*
+Flags used by the Senzing SzEngine.
+These flags are single-bit flags.
+BitNN is for bits numbered as 1..64 (not 0..63).  Comments are for bits numbered as 0..63
+*/
 const (
 	SzExportIncludeMultiRecordEntities  int64 = 1 << iota // 0 we should include entities with "resolved" relationships
 	SzExportIncludePossiblySame                           // 1 we should include entities with "possibly same" relationships
@@ -95,35 +100,48 @@ const (
 	SzWithInfo                        // 62 return "WithInfo" information
 )
 
-// Flags used by the Senzing G2Engine.
-// These flags combine single-bit flags.
-const (
-	/* Flags for exporting entity data.  */
+// Compound Flags used by the Senzing SzEngine.
 
+/*
+Flags for exporting entity data.
+*/
+const (
 	SzExportIncludeAllEntities            = SzExportIncludeMultiRecordEntities | SzExportIncludeSingleRecordEntities                                          // Include all entities.
 	SzExportIncludeAllHavingRelationships = SzExportIncludeDisclosed | SzExportIncludeNameOnly | SzExportIncludePossiblyRelated | SzExportIncludePossiblySame // Include all entities with relationships.
+)
 
-	/* Flags for outputting entity relation data  */
-
+/*
+Flags for outputting entity relation data
+*/
+const (
 	SzEntityIncludeAllRelations = SzEntityIncludeDisclosedRelations | SzEntityIncludeNameOnlyRelations | SzEntityIncludePossiblyRelatedRelations | SzEntityIncludePossiblySameRelations // Include all relationships on entities.
+)
 
-	/* Flags for searching for entities.  */
-
+/*
+Flags for searching for entities.
+*/
+const (
 	SzSearchIncludeAllEntities     = SzSearchIncludeNameOnly | SzSearchIncludePossiblyRelated | SzSearchIncludePossiblySame | SzSearchIncludeResolved
 	SzSearchIncludeNameOnly        = SzExportIncludeNameOnly
 	SzSearchIncludePossiblyRelated = SzExportIncludePossiblyRelated
 	SzSearchIncludePossiblySame    = SzExportIncludePossiblySame
 	SzSearchIncludeResolved        = SzExportIncludeMultiRecordEntities
+)
 
-	/* Recommended settings for searching by attributes. */
-
+/*
+Recommended settings for searching by attributes.
+*/
+const (
 	SzSearchByAttributesAll           = SzEntityIncludeEntityName | SzEntityIncludeRecordSummary | SzEntityIncludeRepresentativeFeatures | SzSearchIncludeAllEntities | SzIncludeFeatureScores                            // The recommended flag values for searching by attributes, returning all matching entities.
 	SzSearchByAttributesMinimalAll    = SzSearchIncludeAllEntities                                                                                                                                                        // Return minimal data with all matches.
 	SzSearchByAttributesMinimalStrong = SzSearchIncludePossiblySame | SzSearchIncludeResolved                                                                                                                             // Return minimal data with only the strongest matches.
 	SzSearchByAttributesStrong        = SzEntityIncludeEntityName | SzEntityIncludeRecordSummary | SzEntityIncludeRepresentativeFeatures | SzIncludeFeatureScores | SzSearchIncludePossiblySame | SzSearchIncludeResolved // The recommended flag values for searching by attributes, returning only strongly matching entities.
+)
 
-	/* Recommended defaults */
-
+/*
+Recommended defaults
+*/
+const (
 	SzEntityBriefDefaultFlags        = SzEntityIncludeAllRelations | SzEntityIncludeRecordMatchingInfo | SzEntityIncludeRelatedMatchingInfo                                                                                                                                                                                                         // The recommended default flag values for a brief entity result.
 	SzEntityDefaultFlags             = SzEntityIncludeAllRelations | SzEntityIncludeEntityName | SzEntityIncludeRecordData | SzEntityIncludeRecordMatchingInfo | SzEntityIncludeRecordSummary | SzEntityIncludeRelatedEntityName | SzEntityIncludeRelatedMatchingInfo | SzEntityIncludeRelatedRecordSummary | SzEntityIncludeRepresentativeFeatures // The recommended default flag values for getting entities.
 	SzExportDefaultFlags             = SzEntityDefaultFlags | SzExportIncludeAllEntities                                                                                                                                                                                                                                                            // The recommended default flag values for exporting entities.

diff --git a/senzing/main.go b/senzing/main.go
@@ -27,7 +27,7 @@ type SzAbstractFactory interface {
 	CreateSzProduct(ctx context.Context) (SzProduct, error)
 }
 
-// The SzConfig interface is a Golang representation of Senzing's libg2config.h
+// The SzConfig interface is a Golang representation of Senzing's libSzconfig.h
 type SzConfig interface {
 	AddDataSource(ctx context.Context, configHandle uintptr, dataSourceCode string) (string, error)
 	CloseConfig(ctx context.Context, configHandle uintptr) error
@@ -39,7 +39,7 @@ type SzConfig interface {
 	ImportConfig(ctx context.Context, configDefinition string) (uintptr, error)
 }
 
-// The SzConfigManager interface is a Golang representation of Senzing's libg2configmgr.h
+// The SzConfigManager interface is a Golang representation of Senzing's libSzconfigmgr.h
 type SzConfigManager interface {
 	AddConfig(ctx context.Context, configDefinition string, configComments string) (int64, error)
 	Destroy(ctx context.Context) error
@@ -50,7 +50,7 @@ type SzConfigManager interface {
 	SetDefaultConfigID(ctx context.Context, configID int64) error
 }
 
-// The SzDiagnostic interface is a Golang representation of Senzing's libg2diagnostic.h
+// The SzDiagnostic interface is a Golang representation of Senzing's libSzdiagnostic.h
 type SzDiagnostic interface {
 	CheckDatastorePerformance(ctx context.Context, secondsToRun int) (string, error)
 	Destroy(ctx context.Context) error
@@ -60,7 +60,7 @@ type SzDiagnostic interface {
 	Reinitialize(ctx context.Context, configID int64) error
 }
 
-// The SzEngine interface is a Golang representation of Senzing's libg2.h
+// The SzEngine interface is a Golang representation of Senzing's libSz.h
 type SzEngine interface {
 	AddRecord(ctx context.Context, dataSourceCode string, recordID string, recordDefinition string, flags int64) (string, error)
 	CloseExport(ctx context.Context, exportHandle uintptr) error
@@ -97,7 +97,7 @@ type SzEngine interface {
 	WhyRecords(ctx context.Context, dataSourceCode1 string, recordID1 string, dataSourceCode2 string, recordID2 string, flags int64) (string, error)
 }
 
-// The SzProduct interface is a Golang representation of Senzing's libg2product.h
+// The SzProduct interface is a Golang representation of Senzing's libSzproduct.h
 type SzProduct interface {
 	Destroy(ctx context.Context) error
 	GetLicense(ctx context.Context) (string, error)

diff --git a/senzing/parameters.go b/senzing/parameters.go
@@ -4,6 +4,9 @@ package senzing
 // Constants
 // ----------------------------------------------------------------------------
 
+/*
+Empty values for parameter.
+*/
 const (
 	SzInitializeWithDefaultConfiguration int64  = 0
 	SzNoAttributes                       string = ""

diff --git a/szconfig/doc.go b/szconfig/doc.go
@@ -1,4 +1,4 @@
 /*
-The szconfig package is a wrapper over Senzing's G2Config C binding.
+Package szconfig is used to modify the in-memory representation of a Senzing configuration.
 */
 package szconfig
diff --git a/szconfig/main.go b/szconfig/main.go
@@ -43,16 +43,16 @@ var IDMessages = map[int]string{
 	706:  "Exit  " + Prefix + "SetLogLevel(%s) returned (%v).",
 	707:  "Enter " + Prefix + "UnregisterObserver(%s).",
 	708:  "Exit  " + Prefix + "UnregisterObserver(%s) returned (%v).",
-	4001: Prefix + "G2Config_addDataSource(%v, %s) failed. Return code: %d",
-	4002: Prefix + "G2Config_close(%v) failed. Return code: %d",
-	4003: Prefix + "G2Config_create() failed. Return code: %d",
-	4004: Prefix + "G2Config_deleteDataSource(%v, %s) failed. Return code: %d",
-	4005: Prefix + "G2Config_destroy() failed. Return code: %d",
-	4006: Prefix + "G2Config_getLastException() failed. Return code: %d",
-	4007: Prefix + "G2Config_init(%s, %s, %d) failed. Return code: %d",
-	4008: Prefix + "G2Config_listDataSources(%d) failed. Return code: %d",
-	4009: Prefix + "G2Config_load(%s) failed. Return code: %d",
-	4010: Prefix + "G2Config_save(%v) failed. Return code: %d",
+	4001: Prefix + "SzConfig_addDataSource(%v, %s) failed. Return code: %d",
+	4002: Prefix + "SzConfig_close(%v) failed. Return code: %d",
+	4003: Prefix + "SzConfig_create() failed. Return code: %d",
+	4004: Prefix + "SzConfig_deleteDataSource(%v, %s) failed. Return code: %d",
+	4005: Prefix + "SzConfig_destroy() failed. Return code: %d",
+	4006: Prefix + "SzConfig_getLastException() failed. Return code: %d",
+	4007: Prefix + "SzConfig_init(%s, %s, %d) failed. Return code: %d",
+	4008: Prefix + "SzConfig_listDataSources(%d) failed. Return code: %d",
+	4009: Prefix + "SzConfig_load(%s) failed. Return code: %d",
+	4010: Prefix + "SzConfig_save(%v) failed. Return code: %d",
 	8001: Prefix + "AddDataSource",
 	8002: Prefix + "CloseConfig",
 	8003: Prefix + "CreateConfig",

diff --git a/szconfig/szconfig_test.go b/szconfig/szconfig_test.go
@@ -5,7 +5,7 @@ import (
 )
 
 // ----------------------------------------------------------------------------
-// Test interface functions
+// Interface methods - test
 // ----------------------------------------------------------------------------
 
 func TestSzconfig_Null(test *testing.T) {

diff --git a/szconfigmanager/doc.go b/szconfigmanager/doc.go
@@ -1,4 +1,4 @@
 /*
-The szconfigmanager package is a wrapper over Senzing's G2Configmgr C binding.
+Package szconfigmanager is used to modify Senzing configuration JSON documents in the Senzing datastore.
 */
 package szconfigmanager
diff --git a/szconfigmanager/main.go b/szconfigmanager/main.go
@@ -41,14 +41,14 @@ var IDMessages = map[int]string{
 	706:  "Exit  " + Prefix + "SetLogLevel(%s) returned (%v).",
 	707:  "Enter " + Prefix + "UnregisterObserver(%s).",
 	708:  "Exit  " + Prefix + "UnregisterObserver(%s) returned (%v).",
-	4001: Prefix + "G2ConfigMgr_addConfig(%s, %s) failed. Return code: %d",
-	4002: Prefix + "G2ConfigMgr_destroy() failed. Return code: %d",
-	4003: Prefix + "G2ConfigMgr_getConfig(%d) failed. Return code: %d",
-	4004: Prefix + "G2ConfigMgr_getConfigList() failed. Return code: %d",
-	4005: Prefix + "G2ConfigMgr_getDefaultConfigID() failed. Return code: %d",
-	4006: Prefix + "G2ConfigMgr_init(%s, %s, %d) failed. Return code: %d",
-	4007: Prefix + "G2ConfigMgr_replaceDefaultConfigID(%d, %d) failed. Return code: %d",
-	4008: Prefix + "G2ConfigMgr_setDefaultConfigID(%d) failed. Return code: %d",
+	4001: Prefix + "SzConfigMgr_addConfig(%s, %s) failed. Return code: %d",
+	4002: Prefix + "SzConfigMgr_destroy() failed. Return code: %d",
+	4003: Prefix + "SzConfigMgr_getConfig(%d) failed. Return code: %d",
+	4004: Prefix + "SzConfigMgr_getConfigList() failed. Return code: %d",
+	4005: Prefix + "SzConfigMgr_getDefaultConfigID() failed. Return code: %d",
+	4006: Prefix + "SzConfigMgr_init(%s, %s, %d) failed. Return code: %d",
+	4007: Prefix + "SzConfigMgr_replaceDefaultConfigID(%d, %d) failed. Return code: %d",
+	4008: Prefix + "SzConfigMgr_setDefaultConfigID(%d) failed. Return code: %d",
 	8001: Prefix + "AddConfig",
 	8002: Prefix + "Destroy",
 	8003: Prefix + "GetConfig",

diff --git a/szconfigmanager/szconfigmanager_test.go b/szconfigmanager/szconfigmanager_test.go
@@ -5,7 +5,7 @@ import (
 )
 
 // ----------------------------------------------------------------------------
-// Test interface functions
+// Interface methods - test
 // ----------------------------------------------------------------------------
 
 func TestSzconfigmanager_Null(test *testing.T) {

diff --git a/szdiagnostic/doc.go b/szdiagnostic/doc.go
@@ -1,4 +1,4 @@
 /*
-The szdiagnostic package is a wrapper over Senzing's G2Diagnostic C binding.
+Package szdiagnostic is used to inspect the Senzing environment.
 */
 package szdiagnostic
diff --git a/szdiagnostic/main.go b/szdiagnostic/main.go
@@ -39,14 +39,14 @@ var IDMessages = map[int]string{
 	706:  "Exit  " + Prefix + "SetLogLevel(%s) returned (%v).",
 	707:  "Enter " + Prefix + "UnregisterObserver(%s).",
 	708:  "Exit  " + Prefix + "UnregisterObserver(%s) returned (%v).",
-	4001: Prefix + "G2Diagnostic_checkDatastorePerformance(%d) failed. Return code: %d",
-	4002: Prefix + "G2Diagnostic_destroy() failed.  Return code: %d",
-	4003: Prefix + "G2Diagnostic_getDatastoreInfo() failed. Return code: %d",
-	4004: Prefix + "G2Diagnostic_getFeature(%d) failed. Return code: %d",
-	4005: Prefix + "G2Diagnostic_init(%s, %s, %d) failed. Return code: %d",
-	4006: Prefix + "G2Diagnostic_initWithConfigID(%s, %s, %d, %d) failed. Return code: %d",
-	4007: Prefix + "G2Diagnostic_purgeRepository() failed. Return Code: %d",
-	4008: Prefix + "G2Diagnostic_reinit(%d) failed. Return Code: %d",
+	4001: Prefix + "SzDiagnostic_checkDatastorePerformance(%d) failed. Return code: %d",
+	4002: Prefix + "SzDiagnostic_destroy() failed.  Return code: %d",
+	4003: Prefix + "SzDiagnostic_getDatastoreInfo() failed. Return code: %d",
+	4004: Prefix + "SzDiagnostic_getFeature(%d) failed. Return code: %d",
+	4005: Prefix + "SzDiagnostic_init(%s, %s, %d) failed. Return code: %d",
+	4006: Prefix + "SzDiagnostic_initWithConfigID(%s, %s, %d, %d) failed. Return code: %d",
+	4007: Prefix + "SzDiagnostic_purgeRepository() failed. Return Code: %d",
+	4008: Prefix + "SzDiagnostic_reinit(%d) failed. Return Code: %d",
 	8001: Prefix + "CheckDatastorePerformance",
 	8002: Prefix + "Destroy",
 	8003: Prefix + "GetDatastoreInfo",