refer

package
v0.0.1-2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 24, 2023 License: MIT Imports: 8 Imported by: 94

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var Referencer = &_TReferencer{}

Referencer Helper class that sets and unsets references to components.

Functions

func NewReferenceError 

func NewReferenceError(ctx context.Context, locator any) *errors.ApplicationError

NewReferenceError Creates an error instance and assigns its values. 

Parameters:
	- ctx context.Context execution context to trace execution through call chain.
	- locator any the locator to find reference to dependent component.
Returns *errors.ApplicationError

Types

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 

func NewDependencyResolver() *DependencyResolver

NewDependencyResolver creates a new instance of the dependency resolver. 

Returns: *DependencyResolver

func NewDependencyResolverFromTuples 

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

NewDependencyResolverFromTuples creates a new DependencyResolver from a list of key-value pairs called tuples where key is dependency name and value the dependency locator (descriptor). 

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 

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

NewDependencyResolverWithParams creates a new instance of the dependency resolver. 

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 (*DependencyResolver) Configure 

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

Configure the component with specified parameters. 

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

func (*DependencyResolver) Find 

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

Find all matching dependencies by their name. throws a ReferenceError of required is true and no dependencies found. 

Parameters:
	- ctx context.Context execution context to trace execution through call chain.
	- 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 (*DependencyResolver) GetOneOptional 

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

GetOneOptional gets one optional dependency by its name. 

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 (*DependencyResolver) GetOneRequired 

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

GetOneRequired gets one required dependency by its name. At least one dependency must present. If the dependency was found it throws a ReferenceError throws a ReferenceError if dependency was not found. 

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

func (*DependencyResolver) GetOptional 

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

GetOptional gets all optional dependencies by their name. 

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

func (*DependencyResolver) GetRequired 

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

GetRequired gets all required dependencies by their name. At least one dependency must be present. If no dependencies was found it throws a ReferenceError throws a ReferenceError if no dependencies were found. 

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

func (*DependencyResolver) Locate 

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

Locate dependency by name 

Parameters: name string dependency name
Returns: any located dependency

func (*DependencyResolver) Put 

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

Put adds a new dependency into this resolver. 

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

func (*DependencyResolver) SetReferences 

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

SetReferences sets the component references. References must match configured dependencies. 

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 

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

NewDescriptor creates a new instance of the 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 

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

ParseDescriptorFromString зarses colon-separated list of descriptor fields and returns them as a Descriptor. throws a ConfigError if the descriptor string is of a wrong format. 

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

func (*Descriptor) Equals 

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

Equals compares this descriptor to a value. If value is a Descriptor it tries to match them, otherwise the method returns false. 

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 (*Descriptor) ExactMatch 

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

ExactMatch matches this descriptor to another descriptor by all fields. No exceptions are made. 

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

func (*Descriptor) Group 

func (c *Descriptor) Group() string

Group gets the component's logical group. 

Returns: string the component's logical group

func (*Descriptor) IsComplete 

func (c *Descriptor) IsComplete() bool

IsComplete checks whether all descriptor fields are set. If descriptor has at least one "*" or null field it is considered "incomplete", 

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

func (*Descriptor) Kind 

func (c *Descriptor) Kind() string

Kind gets the component's implementation type. 

Returns: string the component's implementation type.

func (*Descriptor) Match 

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

Match partially matches this descriptor to another descriptor. Fields that contain "*" or null are excluded from the match. 

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

func (*Descriptor) Name 

func (c *Descriptor) Name() string

Name gets the unique component's name. 

Returns: string the unique component's name.

func (*Descriptor) String 

func (c *Descriptor) String() string

String gets a string representation of the object. The result is a colon-separated list of descriptor fields as "mygroup:connector:aws:default:1.0" 

Returns: string a string representation of the object.

func (*Descriptor) Type 

func (c *Descriptor) Type() string

Type gets the component's logical type. 

Returns: string the component's logical type.

func (*Descriptor) Version 

func (c *Descriptor) Version() string

Version gets the component's implementation version. 

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 

func NewReference(locator any, component any) *Reference

NewReference create a new instance of the reference object and assigns its values. Parameters:

  • locator any a locator to find the reference.
  • component interface {} Returns: *Reference

func (*Reference) Component 

func (c *Reference) Component() any

Component gets the stored component reference. 

Returns: any the component's references.

func (*Reference) Locator 

func (c *Reference) Locator() any

Locator gets the stored component locator. 

Returns: any the component's locator.

func (*Reference) Match 

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

Match locator to this reference locator. Descriptors are matched using equal method. All other locator types are matched using direct comparison. 

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 

func NewEmptyReferences() *References

NewEmptyReferences creates a new instance of references and initializes it with references. 

Returns: *References

func NewReferences 

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

NewReferences creates a new instance of references and initializes it with 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 

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

NewReferencesFromTuples creates a new References from a list of key-value pairs called tuples. 

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 (*References) Find 

func (c *References) Find(locator any, required bool) ([]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.

func (*References) GetAll 

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

GetAll gets all component references registered in this reference map. 

Returns: []any a list with component references.

func (*References) GetAllLocators 

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

GetAllLocators gets locators for all registered component references in this reference map. 

Returns: []any a list with component locators.

func (*References) GetOneOptional 

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

GetOneOptional gets an optional component reference that matches specified locator. 

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

func (*References) GetOneRequired 

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

GetOneRequired gets a required component reference that matches specified locator. throws a ReferenceError when no references found. 

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

func (*References) GetOptional 

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

GetOptional gets all component references that match specified locator. 

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

func (*References) GetRequired 

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

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 ReferenceError when no references found. 

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

func (*References) Put 

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

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.

func (*References) Remove 

func (c *References) Remove(ctx context.Context, locator any) 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.

func (*References) RemoveAll 

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

RemoveAll removes all component references that match the specified locator. 

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.