Address comments during code review

Author: sthelen-enqs

api/usecases.go

@@ -56,6 +56,15 @@ type UseCaseBaseInterface interface {
 type UseCaseInterface interface {
 	UseCaseBaseInterface
 
-	// add the features
+	// add the features described by the Use Case
+	//
+	// returns an error if any Feature could not be added
+	// - errors should not occur during normal usage of eebus-go, and should
+	//   generally be considered fatal implementation errors
+	// - if an error occurs while adding features to a new Entity, that Entity
+	//   will be in an incomplete state and should not be added to the service
+	//
+	// No cleanup occurs on error, some features may end up partially
+	// configured and unused
 	AddFeatures() error
 }

service/service.go

@@ -193,6 +193,13 @@ func (s *Service) IsRunning() bool {
 }
 
 // add a use case to the service
+//
+// returns an error when adding features to the entity fails
+//
+// errors should not occur during normal usage of eebus-go, and should
+// generally be considered fatal implementation errors
+//
+// see usecase.AddFeatures() for more information
 func (s *Service) AddUseCase(useCase api.UseCaseInterface) error {
 	s.usecases = append(s.usecases, useCase)
 

usecases/api/api.go

@@ -1,7 +1,34 @@
 package api
 
-import "github.com/enbility/spine-go/model"
+import (
+	"github.com/enbility/eebus-go/api"
+	"github.com/enbility/spine-go/model"
+)
 
 //go:generate mockery
 
 var PhaseNameMapping = []model.ElectricalConnectionPhaseNameType{model.ElectricalConnectionPhaseNameTypeA, model.ElectricalConnectionPhaseNameTypeB, model.ElectricalConnectionPhaseNameTypeC}
+
+// used to enable batch data updates for certain usecases
+//
+// a usecase that wants to provide batch update capabilities using this interface should
+//
+// 1. provide methods that return a type implementing this interface
+// 2. provide an Update method that accepts a list of this interface
+//
+// The Update method can then iterate over the provided UpdateData, ensure all
+// data points are supported, and then create a batched spine update request
+type UpdateData interface {
+	Supported() bool
+	NotSupportedError() error
+}
+
+// used to enable batch data updates for MeaserumentData
+//
+// usecases can use this interface to provide batch update capabilities by
+// implementing a method that takes a list of this interface and passes a list
+// of MeasurementData to Measurement.UpdateDataForIds
+type UpdateMeasurementData interface {
+	UpdateData
+	MeasurementData() api.MeasurementDataForID
+}

usecases/api/mu_mpc.go

@@ -1,9 +1,9 @@
 package api
 
 import (
-	"github.com/enbility/eebus-go/api"
-	"github.com/enbility/spine-go/model"
 	"time"
+
+	"github.com/enbility/spine-go/model"
 )
 
 // Actor: Monitoring Unit
@@ -91,29 +91,29 @@ type MuMPCInterface interface {
 	// possible errors:
 	//   - ErrMissingData if the id is not available
 	//   - and others
-	Update(data ...UpdateData) error
+	Update(data ...UpdateMeasurementData) error
 
 	// Scenario 1
 
 	// use UpdateDataPowerTotal in Update to set the momentary active power consumption or production
 	// The timestamp is optional and can be nil
 	// The valueState shall be set if it differs from the normal valueState otherwise it can be nil
-	UpdateDataPowerTotal(value float64, timestamp *time.Time, valueState *model.MeasurementValueStateType) UpdateData
+	UpdateDataPowerTotal(value float64, timestamp *time.Time, valueState *model.MeasurementValueStateType) UpdateMeasurementData
 
 	// use UpdateDataPowerPhaseA in Update to set the momentary active power consumption or production per phase
 	// The timestamp is optional and can be nil
 	// The valueState shall be set if it differs from the normal valueState otherwise it can be nil
-	UpdateDataPowerPhaseA(value float64, timestamp *time.Time, valueState *model.MeasurementValueStateType) UpdateData
+	UpdateDataPowerPhaseA(value float64, timestamp *time.Time, valueState *model.MeasurementValueStateType) UpdateMeasurementData
 
 	// use UpdateDataPowerPhaseB in Update to set the momentary active power consumption or production per phase
 	// The timestamp is optional and can be nil
 	// The valueState shall be set if it differs from the normal valueState otherwise it can be nil
-	UpdateDataPowerPhaseB(value float64, timestamp *time.Time, valueState *model.MeasurementValueStateType) UpdateData
+	UpdateDataPowerPhaseB(value float64, timestamp *time.Time, valueState *model.MeasurementValueStateType) UpdateMeasurementData
 
 	// use UpdateDataPowerPhaseC in Update to set the momentary active power consumption or production per phase
 	// The timestamp is optional and can be nil
 	// The valueState shall be set if it differs from the normal valueState otherwise it can be nil
-	UpdateDataPowerPhaseC(value float64, timestamp *time.Time, valueState *model.MeasurementValueStateType) UpdateData
+	UpdateDataPowerPhaseC(value float64, timestamp *time.Time, valueState *model.MeasurementValueStateType) UpdateMeasurementData
 
 	// Scenario 2
 
@@ -127,7 +127,7 @@ type MuMPCInterface interface {
 		valueState *model.MeasurementValueStateType,
 		evaluationStart *time.Time,
 		evaluationEnd *time.Time,
-	) UpdateData
+	) UpdateMeasurementData
 
 	// use UpdateDataEnergyProduced in Update to set the total feed in energy
 	// The timestamp is optional and can be nil
@@ -139,67 +139,61 @@ type MuMPCInterface interface {
 		valueState *model.MeasurementValueStateType,
 		evaluationStart *time.Time,
 		evaluationEnd *time.Time,
-	) UpdateData
+	) UpdateMeasurementData
 
 	// Scenario 3
 
 	// use UpdateDataCurrentPhaseA in Update to set the momentary phase specific current consumption or production
 	// The timestamp is optional and can be nil
 	// The valueState shall be set if it differs from the normal valueState otherwise it can be nil
-	UpdateDataCurrentPhaseA(value float64, timestamp *time.Time, valueState *model.MeasurementValueStateType) UpdateData
+	UpdateDataCurrentPhaseA(value float64, timestamp *time.Time, valueState *model.MeasurementValueStateType) UpdateMeasurementData
 
 	// use UpdateDataCurrentPhaseB in Update to set the momentary phase specific current consumption or production
 	// The timestamp is optional and can be nil
 	// The valueState shall be set if it differs from the normal valueState otherwise it can be nil
-	UpdateDataCurrentPhaseB(value float64, timestamp *time.Time, valueState *model.MeasurementValueStateType) UpdateData
+	UpdateDataCurrentPhaseB(value float64, timestamp *time.Time, valueState *model.MeasurementValueStateType) UpdateMeasurementData
 
 	// use UpdateDataCurrentPhaseC in Update to set the momentary phase specific current consumption or production
 	// The timestamp is optional and can be nil
 	// The valueState shall be set if it differs from the normal valueState otherwise it can be nil
-	UpdateDataCurrentPhaseC(value float64, timestamp *time.Time, valueState *model.MeasurementValueStateType) UpdateData
+	UpdateDataCurrentPhaseC(value float64, timestamp *time.Time, valueState *model.MeasurementValueStateType) UpdateMeasurementData
 
 	// Scenario 4
 
 	// use UpdateDataVoltagePhaseA in Update to set the phase specific voltage details
 	// The timestamp is optional and can be nil
 	// The valueState shall be set if it differs from the normal valueState otherwise it can be nil
-	UpdateDataVoltagePhaseA(value float64, timestamp *time.Time, valueState *model.MeasurementValueStateType) UpdateData
+	UpdateDataVoltagePhaseA(value float64, timestamp *time.Time, valueState *model.MeasurementValueStateType) UpdateMeasurementData
 
 	// use UpdateDataVoltagePhaseB in Update to set the phase specific voltage details
 	// The timestamp is optional and can be nil
 	// The valueState shall be set if it differs from the normal valueState otherwise it can be nil
-	UpdateDataVoltagePhaseB(value float64, timestamp *time.Time, valueState *model.MeasurementValueStateType) UpdateData
+	UpdateDataVoltagePhaseB(value float64, timestamp *time.Time, valueState *model.MeasurementValueStateType) UpdateMeasurementData
 
 	// use UpdateDataVoltagePhaseC in Update to set the phase specific voltage details
 	// The timestamp is optional and can be nil
 	// The valueState shall be set if it differs from the normal valueState otherwise it can be nil
-	UpdateDataVoltagePhaseC(value float64, timestamp *time.Time, valueState *model.MeasurementValueStateType) UpdateData
+	UpdateDataVoltagePhaseC(value float64, timestamp *time.Time, valueState *model.MeasurementValueStateType) UpdateMeasurementData
 
 	// use UpdateDataVoltagePhaseAToB in Update to set the phase specific voltage details
 	// The timestamp is optional and can be nil
 	// The valueState shall be set if it differs from the normal valueState otherwise it can be nil
-	UpdateDataVoltagePhaseAToB(value float64, timestamp *time.Time, valueState *model.MeasurementValueStateType) UpdateData
+	UpdateDataVoltagePhaseAToB(value float64, timestamp *time.Time, valueState *model.MeasurementValueStateType) UpdateMeasurementData
 
 	// use UpdateDataVoltagePhaseBToC in Update to set the phase specific voltage details
 	// The timestamp is optional and can be nil
 	// The valueState shall be set if it differs from the normal valueState otherwise it can be nil
-	UpdateDataVoltagePhaseBToC(value float64, timestamp *time.Time, valueState *model.MeasurementValueStateType) UpdateData
+	UpdateDataVoltagePhaseBToC(value float64, timestamp *time.Time, valueState *model.MeasurementValueStateType) UpdateMeasurementData
 
 	// use UpdateDataVoltagePhaseCToA in Update to set the phase specific voltage details
 	// The timestamp is optional and can be nil
 	// The valueState shall be set if it differs from the normal valueState otherwise it can be nil
-	UpdateDataVoltagePhaseCToA(value float64, timestamp *time.Time, valueState *model.MeasurementValueStateType) UpdateData
+	UpdateDataVoltagePhaseCToA(value float64, timestamp *time.Time, valueState *model.MeasurementValueStateType) UpdateMeasurementData
 
 	// Scenario 5
 
 	// use AcFrequency in Update to set the frequency
 	// The timestamp is optional and can be nil
 	// The valueState shall be set if it differs from the normal valueState otherwise it can be nil
-	UpdateDataFrequency(value float64, timestamp *time.Time, valueState *model.MeasurementValueStateType) UpdateData
-}
-
-type UpdateData interface {
-	Supported() bool
-	NotSupportedError() error
-	MeasurementData() api.MeasurementDataForID
+	UpdateDataFrequency(value float64, timestamp *time.Time, valueState *model.MeasurementValueStateType) UpdateMeasurementData
 }