refactor(plc4go): godoc and slight refactoring

+ tracedPlcConnection is only local to cache
+ align file names to primary struct

plc4go/internal/cbus/Browser.go

@@ -22,12 +22,12 @@ package cbus
 import (
 	"context"
 	"fmt"
+	plc4go "github.com/apache/plc4x/plc4go/pkg/api"
 	"time"
 
 	apiModel "github.com/apache/plc4x/plc4go/pkg/api/model"
 	"github.com/apache/plc4x/plc4go/pkg/api/values"
 	readWriteModel "github.com/apache/plc4x/plc4go/protocols/cbus/readwrite/model"
-	"github.com/apache/plc4x/plc4go/spi"
 	_default "github.com/apache/plc4x/plc4go/spi/default"
 	spiModel "github.com/apache/plc4x/plc4go/spi/model"
 
@@ -37,11 +37,11 @@ import (
 
 type Browser struct {
 	_default.DefaultBrowser
-	connection      spi.PlcConnection
+	connection      plc4go.PlcConnection
 	sequenceCounter uint8
 }
 
-func NewBrowser(connection spi.PlcConnection) *Browser {
+func NewBrowser(connection plc4go.PlcConnection) *Browser {
 	browser := Browser{
 		connection:      connection,
 		sequenceCounter: 0,

plc4go/internal/cbus/Browser_test.go

@@ -22,10 +22,10 @@ package cbus
 import (
 	"context"
 	"fmt"
+	plc4go "github.com/apache/plc4x/plc4go/pkg/api"
 	apiModel "github.com/apache/plc4x/plc4go/pkg/api/model"
 	apiValues "github.com/apache/plc4x/plc4go/pkg/api/values"
 	readWriteModel "github.com/apache/plc4x/plc4go/protocols/cbus/readwrite/model"
-	"github.com/apache/plc4x/plc4go/spi"
 	_default "github.com/apache/plc4x/plc4go/spi/default"
 	spiModel "github.com/apache/plc4x/plc4go/spi/model"
 	"github.com/apache/plc4x/plc4go/spi/transports"
@@ -45,7 +45,7 @@ func TestNewBrowser(t *testing.T) {
 func TestBrowser_BrowseQuery(t *testing.T) {
 	type fields struct {
 		DefaultBrowser  _default.DefaultBrowser
-		connection      spi.PlcConnection
+		connection      plc4go.PlcConnection
 		sequenceCounter uint8
 	}
 	type args struct {
@@ -69,7 +69,7 @@ func TestBrowser_BrowseQuery(t *testing.T) {
 			name: "non responding browse",
 			fields: fields{
 				DefaultBrowser: nil,
-				connection: func() spi.PlcConnection {
+				connection: func() plc4go.PlcConnection {
 					transport := test.NewTransport()
 					transportUrl := url.URL{Scheme: "test"}
 					transportInstance, err := transport.CreateTransportInstance(transportUrl, nil)
@@ -145,8 +145,7 @@ func TestBrowser_BrowseQuery(t *testing.T) {
 						t.FailNow()
 						return nil
 					}
-					connection := connectionConnectResult.GetConnection()
-					return connection.(spi.PlcConnection)
+					return connectionConnectResult.GetConnection()
 				}(),
 				sequenceCounter: 0,
 			},
@@ -189,7 +188,7 @@ func TestBrowser_BrowseQuery(t *testing.T) {
 func TestBrowser_extractUnits(t *testing.T) {
 	type fields struct {
 		DefaultBrowser  _default.DefaultBrowser
-		connection      spi.PlcConnection
+		connection      plc4go.PlcConnection
 		sequenceCounter uint8
 	}
 	type args struct {
@@ -262,7 +261,7 @@ func TestBrowser_extractUnits(t *testing.T) {
 func TestBrowser_extractAttributes(t *testing.T) {
 	type fields struct {
 		DefaultBrowser  _default.DefaultBrowser
-		connection      spi.PlcConnection
+		connection      plc4go.PlcConnection
 		sequenceCounter uint8
 	}
 	type args struct {
@@ -312,7 +311,7 @@ func TestBrowser_extractAttributes(t *testing.T) {
 func TestBrowser_getInstalledUnitAddressBytes(t *testing.T) {
 	type fields struct {
 		DefaultBrowser  _default.DefaultBrowser
-		connection      spi.PlcConnection
+		connection      plc4go.PlcConnection
 		sequenceCounter uint8
 	}
 	type args struct {
@@ -329,7 +328,7 @@ func TestBrowser_getInstalledUnitAddressBytes(t *testing.T) {
 			name: "get units",
 			fields: fields{
 				DefaultBrowser: nil,
-				connection: func() spi.PlcConnection {
+				connection: func() plc4go.PlcConnection {
 					transport := test.NewTransport()
 					transportUrl := url.URL{Scheme: "test"}
 					transportInstance, err := transport.CreateTransportInstance(transportUrl, nil)
@@ -400,8 +399,7 @@ func TestBrowser_getInstalledUnitAddressBytes(t *testing.T) {
 						t.FailNow()
 						return nil
 					}
-					connection := connectionConnectResult.GetConnection()
-					return connection.(spi.PlcConnection)
+					return connectionConnectResult.GetConnection()
 				}(),
 				sequenceCounter: 0,
 			},

plc4go/pkg/api/cache/plc_connection_container.go → plc4go/pkg/api/cache/connectionContainer.go

@@ -22,7 +22,6 @@ package cache
 import (
 	"fmt"
 	plc4go "github.com/apache/plc4x/plc4go/pkg/api"
-	"github.com/apache/plc4x/plc4go/spi"
 	_default "github.com/apache/plc4x/plc4go/spi/default"
 	"github.com/pkg/errors"
 	"github.com/rs/zerolog"
@@ -35,7 +34,7 @@ type connectionContainer struct {
 	connectionString string
 	driverManager    plc4go.PlcDriverManager
 	tracerEnabled    bool
-	connection       spi.PlcConnection
+	connection       tracedPlcConnection
 	leaseCounter     uint32
 	closed           bool
 	// The current state of this connection.
@@ -102,8 +101,8 @@ func (t *connectionContainer) connect() {
 
 	t.cacheLog.Debug().Str("connectionString", t.connectionString).Msg("Successfully connected new cached connection.")
 	// Inject the real connection into the container.
-	if connection, ok := connectionResult.GetConnection().(spi.PlcConnection); !ok {
-		panic("Return connection doesn't implement the spi.PlcConnection interface")
+	if connection, ok := connectionResult.GetConnection().(tracedPlcConnection); !ok {
+		panic("Return connection doesn't implement the cache.tracedPlcConnection interface")
 	} else {
 		t.connection = connection
 	}

plc4go/pkg/api/cache/plc_connection_container_test.go → plc4go/pkg/api/cache/connectionContainer_test.go

@@ -23,7 +23,6 @@ import (
 	"fmt"
 	"github.com/apache/plc4x/plc4go/internal/simulated"
 	plc4go "github.com/apache/plc4x/plc4go/pkg/api"
-	"github.com/apache/plc4x/plc4go/spi"
 	"github.com/rs/zerolog"
 	"github.com/rs/zerolog/log"
 	"github.com/stretchr/testify/assert"
@@ -38,7 +37,7 @@ func Test_connectionContainer_String(t1 *testing.T) {
 		connectionString string
 		driverManager    plc4go.PlcDriverManager
 		tracerEnabled    bool
-		connection       spi.PlcConnection
+		connection       tracedPlcConnection
 		leaseCounter     uint32
 		closed           bool
 		state            cachedPlcConnectionState
@@ -79,7 +78,7 @@ func Test_connectionContainer_addListener(t1 *testing.T) {
 		connectionString string
 		driverManager    plc4go.PlcDriverManager
 		tracerEnabled    bool
-		connection       spi.PlcConnection
+		connection       tracedPlcConnection
 		leaseCounter     uint32
 		closed           bool
 		state            cachedPlcConnectionState
@@ -123,7 +122,7 @@ func Test_connectionContainer_connect(t1 *testing.T) {
 		connectionString string
 		driverManager    plc4go.PlcDriverManager
 		tracerEnabled    bool
-		connection       spi.PlcConnection
+		connection       tracedPlcConnection
 		leaseCounter     uint32
 		closed           bool
 		state            cachedPlcConnectionState
@@ -176,7 +175,7 @@ func Test_connectionContainer_lease(t1 *testing.T) {
 		connectionString string
 		driverManager    plc4go.PlcDriverManager
 		tracerEnabled    bool
-		connection       spi.PlcConnection
+		connection       tracedPlcConnection
 		leaseCounter     uint32
 		closed           bool
 		state            cachedPlcConnectionState
@@ -231,7 +230,7 @@ func Test_connectionContainer_returnConnection(t1 *testing.T) {
 		connectionString string
 		driverManager    plc4go.PlcDriverManager
 		tracerEnabled    bool
-		connection       spi.PlcConnection
+		connection       tracedPlcConnection
 		leaseCounter     uint32
 		closed           bool
 		state            cachedPlcConnectionState

plc4go/pkg/api/cache/plc_connection_lease.go → plc4go/pkg/api/cache/plcConnectionLease.go

@@ -36,10 +36,10 @@ type plcConnectionLease struct {
 	// Counter for the number of times this connection has been used before.
 	leaseId uint32
 	// The actual connection being cached.
-	connection spi.PlcConnection
+	connection tracedPlcConnection
 }
 
-func newPlcConnectionLease(connectionContainer *connectionContainer, leaseId uint32, connection spi.PlcConnection) *plcConnectionLease {
+func newPlcConnectionLease(connectionContainer *connectionContainer, leaseId uint32, connection tracedPlcConnection) *plcConnectionLease {
 	p := &plcConnectionLease{
 		connectionContainer: connectionContainer,
 		leaseId:             leaseId,

plc4go/pkg/api/cache/plc_connection_lease_test.go → plc4go/pkg/api/cache/plcConnectionLease_test.go

@@ -22,7 +22,6 @@ package cache
 import (
 	"github.com/apache/plc4x/plc4go/internal/simulated"
 	plc4go "github.com/apache/plc4x/plc4go/pkg/api"
-	"github.com/apache/plc4x/plc4go/spi"
 	"github.com/stretchr/testify/assert"
 	"github.com/viney-shih/go-lock"
 	"testing"
@@ -50,7 +49,7 @@ func TestLeasedPlcConnection_IsTraceEnabled(t *testing.T) {
 		if assert.NotNil(t, connectionResult) {
 			assert.Nil(t, connectionResult.GetErr())
 			if assert.NotNil(t, connectionResult.GetConnection()) {
-				connection := connectionResult.GetConnection().(spi.PlcConnection)
+				connection := connectionResult.GetConnection().(tracedPlcConnection)
 				assert.True(t, connection.IsTraceEnabled())
 				connection.BlockingClose()
 				func() {
@@ -76,7 +75,7 @@ func TestLeasedPlcConnection_IsTraceEnabled(t *testing.T) {
 		if assert.NotNil(t, connectionResult) {
 			assert.Nil(t, connectionResult.GetErr())
 			if assert.NotNil(t, connectionResult.GetConnection()) {
-				connection := connectionResult.GetConnection().(spi.PlcConnection)
+				connection := connectionResult.GetConnection().(tracedPlcConnection)
 				assert.False(t, connection.IsTraceEnabled())
 				connection.BlockingClose()
 				func() {
@@ -117,7 +116,7 @@ func TestLeasedPlcConnection_GetTracer(t *testing.T) {
 		if assert.NotNil(t, connectionResult) {
 			assert.Nil(t, connectionResult.GetErr())
 			if assert.NotNil(t, connectionResult.GetConnection()) {
-				connection := connectionResult.GetConnection().(spi.PlcConnection)
+				connection := connectionResult.GetConnection().(tracedPlcConnection)
 				assert.NotNil(t, connection.GetTracer())
 				connection.BlockingClose()
 				func() {
@@ -158,7 +157,7 @@ func TestLeasedPlcConnection_GetConnectionId(t *testing.T) {
 		if assert.NotNil(t, connectionResult) {
 			assert.Nil(t, connectionResult.GetErr())
 			if assert.NotNil(t, connectionResult.GetConnection()) {
-				connection := connectionResult.GetConnection().(spi.PlcConnection)
+				connection := connectionResult.GetConnection().(tracedPlcConnection)
 				assert.Greater(t, len(connection.GetConnectionId()), 0)
 				connection.BlockingClose()
 				func() {
@@ -199,7 +198,7 @@ func TestLeasedPlcConnection_Connect(t *testing.T) {
 		if assert.NotNil(t, connectionResult) {
 			assert.Nil(t, connectionResult.GetErr())
 			if assert.NotNil(t, connectionResult.GetConnection()) {
-				connection := connectionResult.GetConnection().(spi.PlcConnection)
+				connection := connectionResult.GetConnection().(tracedPlcConnection)
 				func() {
 					defer func() {
 						if r := recover(); r != nil {

plc4go/spi/PlcConnection.go → plc4go/pkg/api/cache/tracedPlcConnection.go

@@ -17,16 +17,17 @@
  * under the License.
  */
 
-package spi
+package cache
 
 import (
 	"github.com/apache/plc4x/plc4go/pkg/api"
+	"github.com/apache/plc4x/plc4go/spi"
 )
 
-type PlcConnection interface {
+type tracedPlcConnection interface {
 	plc4go.PlcConnection
 
 	GetConnectionId() string
 	IsTraceEnabled() bool
-	GetTracer() *Tracer
+	GetTracer() *spi.Tracer
 }

plc4go/spi/HandlerExposer.go

@@ -19,7 +19,10 @@
 
 package spi
 
+// HandlerExposer exposes PlcTagHandler and PlcValueHandler
 type HandlerExposer interface {
+	// GetPlcTagHandler returns the PlcTagHandler
 	GetPlcTagHandler() PlcTagHandler
+	// GetPlcValueHandler returns the PlcValueHandler
 	GetPlcValueHandler() PlcValueHandler
 }

plc4go/spi/Message.go

@@ -20,13 +20,10 @@
 package spi
 
 import (
-	"context"
-
 	"github.com/apache/plc4x/plc4go/spi/utils"
 )
 
 type Message interface {
 	utils.Serializable
-	GetLengthInBytes(ctx context.Context) uint16
-	GetLengthInBits(ctx context.Context) uint16
+	utils.LengthAware
 }

plc4go/spi/MessageCodec.go

@@ -43,6 +43,7 @@ type HandleMessage func(message Message) error
 // HandleError Function for handling the message, returns an error if anything goes wrong
 type HandleError func(err error) error
 
+// MessageCodec handles sending and retrieving of messages
 type MessageCodec interface {
 	// Connect connects this codec
 	Connect() error

plc4go/spi/PlcBrowser.go

@@ -22,18 +22,19 @@ package spi
 import (
 	"context"
 
-	"github.com/apache/plc4x/plc4go/pkg/api/model"
+	apiModel "github.com/apache/plc4x/plc4go/pkg/api/model"
 )
 
+// PlcBrowser defines an interface to browse PLCs
 type PlcBrowser interface {
 	// Browse Non-Blocking request, which will return a full result as soon as the operation is finished
-	Browse(ctx context.Context, browseRequest model.PlcBrowseRequest) <-chan model.PlcBrowseRequestResult
+	Browse(ctx context.Context, browseRequest apiModel.PlcBrowseRequest) <-chan apiModel.PlcBrowseRequestResult
 
 	// BrowseWithInterceptor Variant of the Browser, which allows immediately intercepting found resources
 	// This is ideal, if additional information has to be queried on such found resources
 	// and especially for connection-based protocols can reduce the stress on the system
 	// and increase throughput. It can also be used for simple filtering.
 	// If the interceptor function returns 'true' the result is added to the overall result
 	// if it's 'false' is is not.
-	BrowseWithInterceptor(ctx context.Context, browseRequest model.PlcBrowseRequest, interceptor func(result model.PlcBrowseItem) bool) <-chan model.PlcBrowseRequestResult
+	BrowseWithInterceptor(ctx context.Context, browseRequest apiModel.PlcBrowseRequest, interceptor func(result apiModel.PlcBrowseItem) bool) <-chan apiModel.PlcBrowseRequestResult
 }

plc4go/spi/PlcDiscoverer.go

@@ -21,11 +21,15 @@ package spi
 
 import (
 	"context"
-	"github.com/apache/plc4x/plc4go/pkg/api/model"
+
+	apiModel "github.com/apache/plc4x/plc4go/pkg/api/model"
 	"github.com/apache/plc4x/plc4go/spi/options"
 )
 
+// PlcDiscoverer defines an interface to discover PLCs
 type PlcDiscoverer interface {
-	Discover(callback func(event model.PlcDiscoveryItem), discoveryOptions ...options.WithDiscoveryOption) error
-	DiscoverWithContext(ctx context.Context, callback func(event model.PlcDiscoveryItem), discoveryOptions ...options.WithDiscoveryOption) error
+	// Discover discovers PLCs according to discoveryOptions and calls callback on every discovery
+	Discover(callback func(event apiModel.PlcDiscoveryItem), discoveryOptions ...options.WithDiscoveryOption) error
+	// DiscoverWithContext discovers PLCs according to discoveryOptions and calls callback on every discovery
+	DiscoverWithContext(ctx context.Context, callback func(event apiModel.PlcDiscoveryItem), discoveryOptions ...options.WithDiscoveryOption) error
 }

plc4go/spi/PlcReader.go

@@ -21,9 +21,12 @@ package spi
 
 import (
 	"context"
-	"github.com/apache/plc4x/plc4go/pkg/api/model"
+
+	apiModel "github.com/apache/plc4x/plc4go/pkg/api/model"
 )
 
+// PlcReader reads fields form a PLC
 type PlcReader interface {
-	Read(ctx context.Context, readRequest model.PlcReadRequest) <-chan model.PlcReadRequestResult
+	// Read reads a field from a PLC
+	Read(ctx context.Context, readRequest apiModel.PlcReadRequest) <-chan apiModel.PlcReadRequestResult
 }

plc4go/spi/PlcSubscriber.go

@@ -21,12 +21,18 @@ package spi
 
 import (
 	"context"
-	"github.com/apache/plc4x/plc4go/pkg/api/model"
+
+	apiModel "github.com/apache/plc4x/plc4go/pkg/api/model"
 )
 
+// PlcSubscriber handles subscriptions to a PLC
 type PlcSubscriber interface {
-	Subscribe(ctx context.Context, subscriptionRequest model.PlcSubscriptionRequest) <-chan model.PlcSubscriptionRequestResult
-	Unsubscribe(ctx context.Context, unsubscriptionRequest model.PlcUnsubscriptionRequest) <-chan model.PlcUnsubscriptionRequestResult
-	Register(consumer model.PlcSubscriptionEventConsumer, handles []model.PlcSubscriptionHandle) model.PlcConsumerRegistration
-	Unregister(registration model.PlcConsumerRegistration)
+	// Subscribe subscribes to fields of a PLC
+	Subscribe(ctx context.Context, subscriptionRequest apiModel.PlcSubscriptionRequest) <-chan apiModel.PlcSubscriptionRequestResult
+	// Unsubscribe removes subscriptions
+	Unsubscribe(ctx context.Context, unsubscriptionRequest apiModel.PlcUnsubscriptionRequest) <-chan apiModel.PlcUnsubscriptionRequestResult
+	// Register registers a callback for a model.PlcSubscriptionHandle
+	Register(consumer apiModel.PlcSubscriptionEventConsumer, handles []apiModel.PlcSubscriptionHandle) apiModel.PlcConsumerRegistration
+	// Unregister removes a model.PlcSubscriptionHandle
+	Unregister(registration apiModel.PlcConsumerRegistration)
 }