refer

type DependencyResolver ¶

type DependencyResolver struct {
	// contains filtered or unexported fields
}

DependencyResolver helper class for resolving component dependencies. The resolver is configured to resolve named dependencies by specific locator. During deployment the dependency locator can be changed. This mechanism can be used to clarify specific dependency among several alternatives. Typically components are configured to retrieve the first dependency that matches logical group, type and version. But if container contains more than one instance and resolution has to be specific about those instances, they can be given a unique name and dependency resolvers can be reconfigured to retrieve dependencies by their name.

Configuration parameters dependencies:
	[dependency name 1]: Dependency 1 locator (descriptor)
	...
	[dependency name N]: Dependency N locator (descriptor)
References must match configured dependencies.

func NewDependencyResolver() *DependencyResolver

Returns: *DependencyResolver

func NewDependencyResolverFromTuples(ctx context.Context, tuples ...any) *DependencyResolver

see NewDependencyResolverFromTuplesArray
Parameters:
	- ctx context.Context
	- tuples ...any a list of values where odd elements are
	dependency name and the following even elements
	are dependency locator (descriptor)
Returns: *DependencyResolver a newly created DependencyResolver.

func NewDependencyResolverWithParams(ctx context.Context,
	config *conf.ConfigParams, references IReferences) *DependencyResolver

see ConfigParams
see Configure
see IReferences
see SetReferences
Parameters:
	- ctx context.Context
	- config ConfigParams default configuration where key is
		dependency name and value is locator (descriptor)
	- references IReferences default component references
Returns: *DependencyResolver

func (c *DependencyResolver) Configure(ctx context.Context, config *conf.ConfigParams)

see ConfigParams
Parameters:
	- ctx context.Context
	- config *conf.ConfigParams configuration parameters to set.

func (c *DependencyResolver) Find(name string, required bool) ([]any, error)

Parameters:
	- ctx context.Context
	- name string the dependency name to locate.
	- required bool true to raise an exception when no dependencies are found.
Returns: []any, error a list of found dependencies and error

func (c *DependencyResolver) GetOneOptional(name string) any

Parameters:
	- ctx context.Context
	- name string the dependency name to locate.
Returns: any a dependency reference or nil of the dependency was not found

func (c *DependencyResolver) GetOneRequired(name string) (any, error)

Parameters:
	- ctx context.Context
	- name string the dependency name to locate.
Returns: any, error a dependency reference and error

func (c *DependencyResolver) GetOptional(name string) []any

Parameters: name string the dependency name to locate.
Returns:
	- []any a list with found dependencies or
	empty list of no dependencies was found.

func (c *DependencyResolver) GetRequired(name string) ([]any, error)

Parameters:
	- name string the dependency name to locate.
Returns: []any a list with found dependencies.

func (c *DependencyResolver) Locate(name string) any

Parameters: name string dependency name
Returns: any located dependency

func (c *DependencyResolver) Put(ctx context.Context, name string, locator any)

Parameters:
	- ctx context.Context
	- name string the dependency's name.
	- locator any the locator to find the dependency by.

func (c *DependencyResolver) SetReferences(ctx context.Context, references IReferences)

Parameters:
	- ctx context.Context
	- references IReferences references to set.

type Descriptor ¶

type Descriptor struct {
	// contains filtered or unexported fields
}

Descriptor locator type that most often used in PipServices toolkit. It locates components using several fields:

Group: a package or just named group of components like "pip-services"
Type: logical component type that defines it's contract like "persistence"
Kind: physical implementation type like "mongodb"
Name: unique component name like "default"
Version: version of the component contract like "1.0"

The locator matching can be done by all or only few selected fields. The fields that shall be excluded from the matching must be set to "*" or null. That approach allows to implement many interesting scenarios. For instance:

• Locate all loggers (match by type and version)

• Locate persistence components for a microservice (match by group and type)

• Locate specific component by its name (match by name) Example: locator1 := NewDescriptor("mygroup", "connector", "aws", "default", "1.0"); locator2 := NewDescriptorFromString("mygroup:connector:*:*:1.0");

  locator1.Match(locator2); // Result: true locator1.Equal(locator2); // Result: true locator1.ExactMatch(locator2); // Result: false

func NewDescriptor(group string, typ string, kind string, name string, version string) *Descriptor

Parameters:
	- group string a logical component group
	- type string a logical component type or contract
	- kind string a component implementation type
	- name string a unique component name
	- version string a component implementation version
Returns: *Descriptor

func ParseDescriptorFromString(value string) (*Descriptor, error)

Parameters: value string colon-separated descriptor fields to initialize Descriptor.
ReturnsЖ *Descriptor a newly created Descriptor.

func (c *Descriptor) Equals(value any) bool

see Match
Parameters: value any the value to match against this descriptor.
Returns: bool true if the value is matching descriptor and false otherwise.

func (c *Descriptor) ExactMatch(descriptor *Descriptor) bool

see Match
Parameters: descriptor *Descriptor the descriptor to match this one against.
Returns: bool true if descriptors match and false otherwise.

func (c *Descriptor) Group() string

Returns: string the component's logical group

func (c *Descriptor) IsComplete() bool

Returns: bool true if all descriptor fields are defined and false otherwise.

func (c *Descriptor) Kind() string

Returns: string the component's implementation type.

func (c *Descriptor) Match(descriptor *Descriptor) bool

see exactMatch
Parameters: descriptor *Descriptor the descriptor to match this one against.
Returns: bool true if descriptors match and false otherwise

func (c *Descriptor) Name() string

Returns: string the unique component's name.

func (c *Descriptor) String() string

Returns: string a string representation of the object.

func (c *Descriptor) Type() string

Returns: string the component's logical type.

func (c *Descriptor) Version() string

Returns: string the component's implementation version.

type IReferenceable ¶

type IReferenceable interface {
	// SetReferences sets references to dependent components.
	//	see IReferences
	//	Parameters:
	//		- ctx context.Context
	//		- references IReferences references to locate the component dependencies.
	SetReferences(ctx context.Context, references IReferences)
}

IReferenceable interface for components that depends on other components. If component requires explicit notification to unset references it shall additionally implement IUnreferenceable interface.

see IReferences
see IUnreferenceable
see Referencer
Example
	type MyController {
		_persistence IPersistence
	}
	func (mc* MyController) SetReferences(ctx context.Context, references IReferences) {
		mc._persistence = references.GetOneRequired(
			NewDescriptor("mygroup", "persistence", "*", "*", "1.0"))
		);
	}
	...

type IReferences ¶

type IReferences interface {

	// Put a new reference into this reference map.
	//	Parameters:
	//		- ctx context.Context
	//		- locator any a locator to find the reference by.
	//		- component any a component reference to be added.
	//	Returns: any
	Put(ctx context.Context, locator any, component any)

	// Remove a previously added reference that matches specified locator. If many references match the locator, it removes only the first one. When all references shall be removed, use removeAll method instead.
	//	see RemoveAll
	//	Parameters:
	//		- ctx context.Context
	//		- locator any a locator to remove reference
	//	Returns: any the removed component reference.
	Remove(ctx context.Context, locator any) any

	// RemoveAll removes all component references that match the specified locator.
	//	Parameters:
	//		- ctx context.Context
	//		- locator any the locator to remove references by.
	//	Returns: []any a list, containing all removed references.
	RemoveAll(ctx context.Context, locator any) []any

	// GetAllLocators gets locators for all registered component references in this reference map.
	//	Returns: []any a list with component locators.
	GetAllLocators() []any

	// GetAll gets all component references registered in this reference map.
	//	Returns: []any a list with component references.
	GetAll() []any

	// GetOptional gets all component references that match specified locator.
	//	Parameters:
	//		- locator any the locator to find references by.
	//	Returns: []any a list with matching component references or empty list if nothing was found.
	GetOptional(locator any) []any

	// GetRequired gets all component references that match specified locator. At least one component reference must be present. If it doesn't the method throws an error.
	// throws a ReferenceException when no references found.
	//	Parameters:
	//		- locator any the locator to find references by.
	//	Returns []any a list with matching component references.
	GetRequired(locator any) ([]any, error)

	// GetOneOptional gets an optional component reference that matches specified locator.
	//	Parameters:
	//		- locator any the locator to find references by.
	//	Returns: any a matching component reference or nil if nothing was found.
	GetOneOptional(locator any) any

	// GetOneRequired gets a required component reference that matches specified locator.
	// throws a ReferenceError when no references found.
	//	Parameters:
	//		- locator any the locator to find references by.
	//	Returns: any a matching component reference.
	GetOneRequired(locator any) (any, error)

	// Find gets all component references that match specified locator.
	// throws a ReferenceError when required is set to true but no references found.
	//	Parameters:
	//		- locator any the locator to find a reference by.
	//		- required bool forces to raise an exception if no reference is found.
	//	Returns: []any a list with matching component references.
	Find(locator any, required bool) ([]any, error)
}

IReferences interface for a map that holds component references and passes them to components to establish dependencies with each other. Together with IReferenceable and IUnreferenceable interfaces it implements a Locator pattern that is used by PipServices toolkit for Inversion of Control to assign external dependencies to components. The IReferences object is a simple map, where keys are locators and values are component references. It allows to add, remove and find components by their locators. Locators can be any values like integers, strings or component types. But most often PipServices toolkit uses Descriptor as locators that match by 5 fields: group, type, kind, name and version.

type IUnreferenceable ¶

type IUnreferenceable interface {
	// UnsetReferences (clears) previously set references to dependent components.
	UnsetReferences(ctx context.Context)
}

IUnreferenceable Interface for components that require explicit clearing of references to dependent components.

see IReferences
see IReferenceable
Example
	type MyController  {
		_persistence IMyPersistence;
	}
	func (mc* MyController) SetReferences(ctx context.Context, references *IReferences) {
		mc._persistence = references.GetOneRequired(
			NewDescriptor("mygroup", "persistence", "*", "*", "1.0"),
		);
	}

	func (mc* MyController) UnsetReferences(ctx context.Context) {
		mc._persistence = nil;
	}

type Reference ¶

type Reference struct {
	// contains filtered or unexported fields
}

Reference contains a reference to a component and locator to find it. It is used by References to store registered component references.

func NewReference(locator any, component any) *Reference

func (c *Reference) Component() any

Returns: any the component's references.

func (c *Reference) Locator() any

Returns: any the component's locator.

func (c *Reference) Match(locator any) bool

see Descriptor
Parameters:  locator any the locator to match.
Returns: bool true if locators are matching and false it they don't.

type References ¶

type References struct {
	// contains filtered or unexported fields
}

References the most basic implementation of IReferences to store and locate component references.

see IReferences
Example:
	type MyController  {
		_persistence IMyPersistence;
	}
	func (mc *MyController) setReferences(references IReferences) {
		mc._persistence = references.GetOneRequired(
			NewDescriptor("mygroup", "persistence", "*", "*", "1.0"),
		);
	}

	persistence := NewMyMongoDbPersistence();
	controller := MyController();

	references := NewReferencesFromTuples(
		new Descriptor("mygroup", "persistence", "mongodb", "default", "1.0"), persistence,
		new Descriptor("mygroup", "controller", "default", "default", "1.0"), controller
	);
	controller.setReferences(references);

func NewEmptyReferences() *References

Returns: *References

func NewReferences(ctx context.Context, tuples []any) *References

Parameters:
	- ctx context.Context
	- tuples []any a list of values where odd
		elements are locators and the following even elements are component references
Returns: *References

func NewReferencesFromTuples(ctx context.Context, tuples ...any) *References

Parameters:
	- ctx context.Context
	- tuples  ...any a list of values where
		odd elements are locators and the following even elements
		are component references
Returns: *References a newly created References.

func (c *References) Find(locator any, required bool) ([]any, error)

Parameters:
	- locator any the locator to find a reference by.
	- required bool forces to raise an exception if no reference is found.
Returns: []any a list with matching component references.

func (c *References) GetAll() []any

Returns: []any a list with component references.

func (c *References) GetAllLocators() []any

Returns: []any a list with component locators.

func (c *References) GetOneOptional(locator any) any

Parameters:
	- locator any a locator to remove reference
Returns: any a matching component reference or nil if nothing was found.

func (c *References) GetOneRequired(locator any) (any, error)

Parameters:
	- locator any a locator to remove reference
Returns: any a matching component reference.

func (c *References) GetOptional(locator any) []any

Parameters:
	- locator any a locator to remove reference
Returns: []any a list with matching component references or
	empty list if nothing was found.

func (c *References) GetRequired(locator any) ([]any, error)

Parameters:
	- locator any a locator to remove reference
Returns: []any a list with matching component references.

func (c *References) Put(ctx context.Context, locator any, component any)

Parameters:
	- ctx context.Context
	- locator any a locator to find the reference by.
	- component any a component reference to be added.

func (c *References) Remove(ctx context.Context, locator any) any

see RemoveAll
Parameters:
	- ctx context.Context
	- locator any a locator to remove reference
Returns: any the removed component reference.

func (c *References) RemoveAll(ctx context.Context, locator any) []any

Parameters:
	- ctx context.Context
	- locator any a locator to remove reference
Returns: []any a list, containing all removed references.