refer

package
v1.1.6 Latest Latest
Warning

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

 Go to latest Published: Jan 12, 2023 License: MIT Imports: 6 Imported by: 117

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewReferenceError 

func NewReferenceError(correlationId string, locator interface{}) *errors.ApplicationError

Creates an error instance and assigns its values. Parameters:

  • correlationId string
  • locator interface{} the locator to find reference to dependent component.

Returns *errors.ApplicationError

Types

type DependencyResolver 

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

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 References must match configured dependencies.

Example:

func NewDependencyResolver 

func NewDependencyResolver() *DependencyResolver

Creates a new instance of the dependency resolver. Returns *DependencyResolver

func NewDependencyResolverFromTuples 

func NewDependencyResolverFromTuples(tuples ...interface{}) *DependencyResolver

Creates a new DependencyResolver from a list of key-value pairs called tuples where key is dependency name and value the depedency locator (descriptor). see NewDependencyResolverFromTuplesArray Parameters:

  • tuples ...interface{} 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(config *conf.ConfigParams, references IReferences) *DependencyResolver

Creates a new instance of the dependency resolver. see ConfigParams see configure see IReferences see setReferences Parameters:

  • 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(config *conf.ConfigParams)

Configures the component with specified parameters. see ConfigParams Parameters:

  • config *conf.ConfigParams configuration parameters to set.

func (*DependencyResolver) Find 

func (c *DependencyResolver) Find(name string, required bool) ([]interface{}, error)

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

  • name string the dependency name to locate.
  • required bool true to raise an exception when no dependencies are found.

Returns []interface{}, error a list of found dependencies and error

func (*DependencyResolver) GetOneOptional 

func (c *DependencyResolver) GetOneOptional(name string) interface{}

Gets one optional dependency by its name. Parameters:

  • name string the dependency name to locate.

Returns interface{} a dependency reference or nil of the dependency was not found

func (*DependencyResolver) GetOneRequired 

func (c *DependencyResolver) GetOneRequired(name string) (interface{}, error)

func (*DependencyResolver) GetOptional 

func (c *DependencyResolver) GetOptional(name string) []interface{}

Gets all optional dependencies by their name. Parameters:

  • name string

the dependency name to locate. Returns []interface{} a list with found dependencies or empty list of no dependencies was found.

func (*DependencyResolver) GetRequired 

func (c *DependencyResolver) GetRequired(name string) ([]interface{}, error)

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 []interface{} a list with found dependencies.

func (*DependencyResolver) Locate 

func (c *DependencyResolver) Locate(name string) interface{}

Locate dependency by name Parameters:

  • name string dependency name

Returns interface{} located dependency

func (*DependencyResolver) Put 

func (c *DependencyResolver) Put(name string, locator interface{})

func (*DependencyResolver) SetReferences 

func (c *DependencyResolver) SetReferences(references IReferences)

Sets the component references. References must match configured dependencies. Parameters:

  • references IReferences references to set.

type Descriptor 

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

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

func ParseDescriptorFromString 

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

Parses 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 interface{}) bool

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 interface{} 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

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

Gets the component's logical group. Returns string the component's logical group

func (*Descriptor) IsComplete 

func (c *Descriptor) IsComplete() bool

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

Gets the component's implementation type. Returns string the component's implementation type.

func (*Descriptor) Match 

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

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

Gets the unique component's name. Returns string the unique component's name.

func (*Descriptor) String 

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

Gets the component's logical type. Returns string the component's logical type.

func (*Descriptor) Version 

func (c *Descriptor) Version() string

Gets the component's implementation version. Returns string the component's implementation version.

type IReferenceable 

type IReferenceable interface {
	// 	Sets references to dependent components.
	// see
	// IReferences
	// Parameters:
	//  - references IReferences
	//  references to locate the component dependencies.
	SetReferences(references IReferences)
}

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(references IReferences) {
        mc._persistence = references.getOneRequired(
            NewDescriptor("mygroup", "persistence", "*", "*", "1.0"))
        );
    }
    ...
}

type IReferences 

type IReferences interface {
	// Puts a new reference into this reference map.
	// Parameters:
	//  - locator interface{}
	//  a locator to find the reference by.
	//  - component interface{}
	//  a component reference to be added.
	// Returns interface{}
	Put(locator interface{}, component interface{})
	// 	Removes 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:
	//  - locator interface{}
	//  a locator to remove reference
	// Returns interface{}
	// the removed component reference.
	Remove(locator interface{}) interface{}
	// 	Removes all component references that match the specified locator.
	// Parameters:
	//  - locator interface{}
	//  the locator to remove references by.
	// Returns []interface{}
	// a list, containing all removed references.
	RemoveAll(locator interface{}) []interface{}
	// 	Gets locators for all registered component references in this reference map.
	// Returns []interface{}
	// a list with component locators.
	GetAllLocators() []interface{}
	// Gets all component references registered in this reference map.
	// Returns []interface{}
	// a list with component references.
	GetAll() []interface{}
	// Gets all component references that match specified locator.
	// Parameters:
	//  - locator interface{}
	//  the locator to find references by.
	// Returns []interface{}
	// a list with matching component references or empty list if nothing was found.
	GetOptional(locator interface{}) []interface{}
	// 	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 interface{}
	//  the locator to find references by.
	// Returns []interface{}
	// a list with matching component references.
	GetRequired(locator interface{}) ([]interface{}, error)
	// 	Gets an optional component reference that matches specified locator.
	// Parameters:
	//  - locator interface{}
	//  the locator to find references by.
	// Returns interface{}
	// a matching component reference or nil if nothing was found.
	GetOneOptional(locator interface{}) interface{}
	// Gets a required component reference that matches specified locator.
	// throws
	// a ReferenceError when no references found.
	// Parameters:
	//  - locator interface{}
	//  the locator to find a reference by.
	// Returns interface{}
	// a matching component reference.
	GetOneRequired(locator interface{}) (interface{}, error)
	// 	Gets all component references that match specified locator.
	// throws
	// a ReferenceError when required is set to true but no references found.
	// Parameters:
	// 	 - locator interface{}
	// 	 the locator to find a reference by.
	// 	 - required bool
	// 	 forces to raise an exception if no reference is found.
	// Returns []interface{}
	// a list with matching component references.
	Find(locator interface{}, required bool) ([]interface{}, error)
}

type IUnreferenceable 

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

type Reference 

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

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 interface{}, component interface{}) *Reference

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

  • locator interface{} a locator to find the reference.
  • component interface {}

Returns *Reference

func (*Reference) Component 

func (c *Reference) Component() interface{}

Gets the stored component reference. Returns any the component's references.

func (*Reference) Locator 

func (c *Reference) Locator() interface{}

Gets the stored component locator. Returns any the component's locator.

func (*Reference) Match 

func (c *Reference) Match(locator interface{}) bool

Matches locator to this reference locator. Descriptors are matched using equal method. All other locator types are matched using direct comparison. see Descriptor Parameters:

  • locator interface{} 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
}

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

Creates a new instance of references and initializes it with references. Returns *References

func NewReferences 

func NewReferences(tuples []interface{}) *References

Creates a new instance of references and initializes it with references. Parameters:

  • tuples []interface{} a list of values where odd elements are locators and the following even elements are component references

Returns *References

func NewReferencesFromTuples 

func NewReferencesFromTuples(tuples ...interface{}) *References

Creates a new References from a list of key-value pairs called tuples. Parameters:

  • tuples ...interface{} 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 interface{}, required bool) ([]interface{}, error)

Gets all component references that match specified locator. throws a ReferenceError when required is set to true but no references found. Parameters:

  • locator interface{} the locator to find a reference by.
  • required bool forces to raise an exception if no reference is found.

Returns []interface{} a list with matching component references.

func (*References) GetAll 

func (c *References) GetAll() []interface{}

Gets all component references registered in this reference map. Returns []interface{} a list with component references.

func (*References) GetAllLocators 

func (c *References) GetAllLocators() []interface{}

Gets locators for all registered component references in this reference map. Returns []interface{} a list with component locators.

func (*References) GetOneOptional 

func (c *References) GetOneOptional(locator interface{}) interface{}

Gets an optional component reference that matches specified locator. Parameters:

  • locator interface{} the locator to find references by.

Returns interface{} a matching component reference or nil if nothing was found.

func (*References) GetOneRequired 

func (c *References) GetOneRequired(locator interface{}) (interface{}, error)

Gets a required component reference that matches specified locator. throws a ReferenceError when no references found. Parameters:

  • locator interface{} the locator to find a reference by.

Returns interface{} a matching component reference.

func (*References) GetOptional 

func (c *References) GetOptional(locator interface{}) []interface{}

Gets all component references that match specified locator. Parameters:

  • locator interface{} the locator to find references by.

Returns []interface{} a list with matching component references or empty list if nothing was found.

func (*References) GetRequired 

func (c *References) GetRequired(locator interface{}) ([]interface{}, error)

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 interface{} the locator to find references by.

Returns []interface{} a list with matching component references.

func (*References) Put 

func (c *References) Put(locator interface{}, component interface{})

Puts a new reference into this reference map. Parameters:

  • locator interface{} a locator to find the reference by.
  • component interface{} a component reference to be added.

func (*References) Remove 

func (c *References) Remove(locator interface{}) interface{}

Removes 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:

  • locator interface{} a locator to remove reference

Returns interface{} the removed component reference.

func (*References) RemoveAll 

func (c *References) RemoveAll(locator interface{}) []interface{}

Removes all component references that match the specified locator. Parameters:

  • locator interface{} the locator to remove references by.

Returns []interface{} a list, containing all removed references.

type TReferencer 

type TReferencer struct{}

Helper class that sets and unsets references to components. 

var Referencer *TReferencer = &TReferencer{}

func (*TReferencer) SetReferences 

func (c *TReferencer) SetReferences(references IReferences, components []interface{})

Sets references to multiple components. To set references components must implement IReferenceable interface. If they don't the call to this method has no effect. see IReferenceable Parameters:

  • references IReferences the references to be set.
  • components []interface{} a list of components to set the references to.

func (*TReferencer) SetReferencesForOne 

func (c *TReferencer) SetReferencesForOne(references IReferences, component interface{})

Sets references to specific component. To set references components must implement IReferenceable interface. If they don't the call to this method has no effect. see IReferenceable Parameters:

  • references IReferences the references to be set.
  • component interface{} the component to set references to.

func (*TReferencer) UnsetReferences 

func (c *TReferencer) UnsetReferences(components []interface{})

Unsets references in multiple components. To unset references components must implement IUnreferenceable interface. If they don't the call to this method has no effect. see IUnreferenceable Parameters:

  • components [] interface{} the list of components, whose references must be cleared.

func (*TReferencer) UnsetReferencesForOne 

func (c *TReferencer) UnsetReferencesForOne(component interface{})

Unsets references in specific component. To unset references components must implement IUnreferenceable interface. If they don't the call to this method has no effect. see IUnreferenceable Parameters:

  • component interface{} the component to unset 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.