model

Documentation

Overview

Package model defines the inner most layer of the Clean Architecture containing the business-level models, also called entities or domain. This layer may not depend on outter layers, while all other layers may depend on it. By the way, it is acceptable to annotate structs in this package with multiple frameworks dependent tags (e.g., as required by ORM libraries) since adding more tags does not complicate definition of a struct, but can prevent unnecessary structs duplication.

Index

• Variables
• type Car
• type Coordinate
• type ImmutableSettings
• type ParkingMethodSettings
• type ParkingMode
  • func ParseParkingMode(p string) (ParkingMode, error)
  • func (p ParkingMode) String() string
  • func (p ParkingMode) Validate() error
• type ParkingModeError
  • func (e ParkingModeError) Error() string
• type SemVer
  • func (sv *SemVer) Marshal() string
  • func (sv *SemVer) MarshalText() ([]byte, error)
  • func (sv SemVer) String() string
  • func (sv *SemVer) UnmarshalText(text []byte) (err error)
• type Settings
• type VisibleSettings

Variables

var ErrUnknownParkingMode = errors.New("unknown parking mode")

ErrUnknownParkingMode indicates that a given string may not be parsed as a valid/known parking mode. This error encodes a description err string and does not communicate the invalid parking mode string itself because the caller of Parse already knows about the invalid parking mode string. An error should be devised with this assumption that caller is aware of the function which is returning that error in addition to its arguments and other relevant system states which may be known before calling the function which is returning the error. Thereafter, the caller should wrap the obtained error and add the function name and arguments (or alternative information which makes the error complete in its new context), so it can be returned. Ultimately, one caller which is responsible to consume the error, can determine the entire call stack information from the single error chain with no reflection.

Types

type Car

type Car struct {
	Name       string     // name of the car
	Coordinate Coordinate // current location of car
	Parked     bool       // a flag to indicate if car is parked/moving
}

Car models a car which may be persisted in a database. This model does not contain an ID in order to demonstrate that how a model which has no tags and its fields do not match with the expected table may be managed by the adapter layer. For the corresponding struct which fixes these issues and stores the resulting struct in the database, see the unexported gCar struct in the pkg/adapter/db/postgres/carsrp/query.go file.

type Coordinate

type Coordinate struct {
	Lat, Lon float64 // latitude and longitude of the geo-location
}

Coordinate represents a geographical location with a latitude and longitude. This struct is included in the Car struct in order to demonstrate how a struct may be embedded while mapping them to a database table.

type ImmutableSettings

type ImmutableSettings struct {
	// Logger reports if server-side REST API logging is enabled.
	//
	// This field must always have a non-nil value when it represents
	// the setting value and must always be nil when it represents the
	// boundary values.
	Logger *bool `json:"logger"`
}

ImmutableSettings contains settings which are immutable (and can be configured only using the configuration file or environment variables alone), but are visible by end-users (settings must be at least visible or mutable, otherwise, they may not be called a setting).

This model layer struct is required (in addition to its version dependent adapters layer counterparts) because settings should be reported to and taken from end-users as required from the use cases layer. A repository package is responsible to manage conversion between these structs (only supporting the latest configuration version at any time).

type ParkingMethodSettings

type ParkingMethodSettings struct {
	// Delay represents the old parking method delay.
	Delay *time.Duration `json:"delay" binding:"required"`
}

ParkingMethodSettings represents the old parking method related settings. These settings are considered both visible and mutable.

type ParkingMode

type ParkingMode int

ParkingMode specifies the parking mode enum and accepts two old and new methods. Although this enum is numeric, it is (de)serialized as a string for readability in the adapter layer.

const (
	ParkingModeInvalid ParkingMode = iota // zero value is invalid

	ParkingModeOld // old method incurs more delay
	ParkingModeNew // new method parks the car with no delay
)

Valid values for the ParkingMode enum.

func ParseParkingMode

func ParseParkingMode(p string) (ParkingMode, error)

ParseParkingMode parses the given string and returns a ParkingMode, helping to deserialize it when reading a REST API request. For invalid strings, ParkingModeInvalid and ErrUnknownParkingMode will be returned.

func (ParkingMode) String

func (p ParkingMode) String() string

String converts the ParkingMode enum to a string, helping to serialize it for transmission to web clients (for improved readability). Invalid parking mode causes a panic.

func (ParkingMode) Validate

func (p ParkingMode) Validate() error

Validate returns nil if ParkingMode value is valid. For invalid values, an instance of the ParkingModeError will be returned.

type ParkingModeError

type ParkingModeError int

ParkingModeError indicates an invalid parking mode. This error contains the invalid mode as an integer. Principally, this error type is not required (read the doc of ErrUnknownParkingMode). However, it is declared in order to show how extra parameters may be included in an error. The rare scenario which requires such an error instances (with parameters) belongs to functions which find out about the parameter during their execution and not by their arguments. For example, if a range-loop index is relevant for an error, it may be wrapped and returned by error like this.

func (ParkingModeError) Error

func (e ParkingModeError) Error() string

Error implements the error interface, returning a string representation of the ParkingModeError.

type SemVer

type SemVer [3]uint

SemVer represents a released semantic version, consisting of three components. First component indicates the major version. Incrementing it represents backward-incompatible changes. Second component is the minor version which represents feature additions and changes which are backward compatible and visible in the versioned API level. The last component is the patch version. It represents internal implementation changes which are invisible in the API level.

No pre-release version is considered because unreleased versions are not supposed to be maintained and so do not need migration. If such a migration was required in a development machine, the source version may be migrated back to some released version by one binary and then migrated forward to another unreleased version by another binary (where they are seen as a yet to be evolved released version).

func (*SemVer) Marshal

func (sv *SemVer) Marshal() string

Marshal serializes sv semantic version as its string representation. This is required for YAML serialization.

func (*SemVer) MarshalText

func (sv *SemVer) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler interface and serializes `sv` semantic version as its string representation.

func (SemVer) String

func (sv SemVer) String() string

String returns the sv semantic version as a dot-separated string consisting of three numbers like major.minor.patch where all numbers are non-negative.

func (*SemVer) UnmarshalText

func (sv *SemVer) UnmarshalText(text []byte) (err error)

UnmarshalText deserializes text byte slice as a string consisting of three dot-separated numbers and fills the sv SemVer instance. In case of errors, sv will be left unchanged.

type Settings

type Settings struct {
	VisibleSettings
}

Settings contains those settings which are mutable & invisible, that is, write-only settings. It also embeds the VisibleSettings struct, so it effectively contains all kinds of settings. When fetching settings, the nested ImmutableSettings pointer can be set to nil in order to keep the mutable (visible or invisible) settings and when reporting settings, the embedded VisibleSettings struct can be reported alone (having a non-nil ImmutableSettings pointer) in order to exclude the invisible settings.

This model layer struct is required (in addition to its version dependent adapters layer counterparts) because settings should be reported to and taken from end-users as required from the use cases layer. A repository package is responsible to manage conversion between these structs (only supporting the latest configuration version at any time).

All fields should have pointer types because Settings has two usages, (1) to represent the settings themselves, and (2) to represent the acceptable boundary values for those settings. Since each setting may or may not have a lower/upper boundary value, all fields need to accept nil as an unrestricted boundary. A non-pointer type is only justified if a setting and its minimum/maximum boundary values are always required.

type VisibleSettings

type VisibleSettings struct {
	// ParkingMethod contains the old parking method related settings.
	ParkingMethod ParkingMethodSettings `json:"parking_method"`

	*ImmutableSettings `binding:"isdefault"`
}

VisibleSettings contains settings which are visible by end-users. These settings may be mutable or immutable. The immutable & visible settings are managed by the embedded ImmutableSettings struct. When it is desired to serialize and transmit settings to end-users, the ImmutableSettings pointer should be non-nil and its fields should be poppulated. However, when it is desired to fetch settings from end-users and deserialize them, the ImmutableSettings pointer should be set to nil in order to abandon them.

This model layer struct is required (in addition to its version dependent adapters layer counterparts) because settings should be reported to and taken from end-users as required from the use cases layer. A repository package is responsible to manage conversion between these structs (only supporting the latest configuration version at any time).