refer

Documentation

Index

• func NewReferenceError(correlationId string, locator interface{}) *errors.ApplicationError
• type DependencyResolver
  • func NewDependencyResolver() *DependencyResolver
  • func NewDependencyResolverFromTuples(tuples ...interface{}) *DependencyResolver
  • func NewDependencyResolverWithParams(config *conf.ConfigParams, references IReferences) *DependencyResolver
  • func (c *DependencyResolver) Configure(config *conf.ConfigParams)
  • func (c *DependencyResolver) Find(name string, required bool) ([]interface{}, error)
  • func (c *DependencyResolver) GetOneOptional(name string) interface{}
  • func (c *DependencyResolver) GetOneRequired(name string) (interface{}, error)
  • func (c *DependencyResolver) GetOptional(name string) []interface{}
  • func (c *DependencyResolver) GetRequired(name string) ([]interface{}, error)
  • func (c *DependencyResolver) Locate(name string) interface{}
  • func (c *DependencyResolver) Put(name string, locator interface{})
  • func (c *DependencyResolver) SetReferences(references IReferences)
• type Descriptor
  • func NewDescriptor(group string, typ string, kind string, name string, version string) *Descriptor
  • func ParseDescriptorFromString(value string) (*Descriptor, error)
  • func (c *Descriptor) Equals(value interface{}) bool
  • func (c *Descriptor) ExactMatch(descriptor *Descriptor) bool
  • func (c *Descriptor) Group() string
  • func (c *Descriptor) IsComplete() bool
  • func (c *Descriptor) Kind() string
  • func (c *Descriptor) Match(descriptor *Descriptor) bool
  • func (c *Descriptor) Name() string
  • func (c *Descriptor) String() string
  • func (c *Descriptor) Type() string
  • func (c *Descriptor) Version() string
• type IReferenceable
• type IReferences
• type IUnreferenceable
• type Reference
  • func NewReference(locator interface{}, component interface{}) *Reference
  • func (c *Reference) Component() interface{}
  • func (c *Reference) Locator() interface{}
  • func (c *Reference) Match(locator interface{}) bool
• type References
  • func NewEmptyReferences() *References
  • func NewReferences(tuples []interface{}) *References
  • func NewReferencesFromTuples(tuples ...interface{}) *References
  • func (c *References) Find(locator interface{}, required bool) ([]interface{}, error)
  • func (c *References) GetAll() []interface{}
  • func (c *References) GetAllLocators() []interface{}
  • func (c *References) GetOneOptional(locator interface{}) interface{}
  • func (c *References) GetOneRequired(locator interface{}) (interface{}, error)
  • func (c *References) GetOptional(locator interface{}) []interface{}
  • func (c *References) GetRequired(locator interface{}) ([]interface{}, error)
  • func (c *References) Put(locator interface{}, component interface{})
  • func (c *References) Remove(locator interface{}) interface{}
  • func (c *References) RemoveAll(locator interface{}) []interface{}
• type TReferencer
  • func (c *TReferencer) SetReferences(references IReferences, components []interface{})
  • func (c *TReferencer) SetReferencesForOne(references IReferences, component interface{})
  • func (c *TReferencer) UnsetReferences(components []interface{})
  • func (c *TReferencer) UnsetReferencesForOne(component interface{})

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.