pip_services3_commons.refer.IReferences module
pip_services3_commons.refer.IReferences
Interface for references components.
- copyright
Conceptual Vision Consulting LLC 2018-2019, see AUTHORS for more details.
- license
MIT, see LICENSE for more details.
-
class
pip_services3_commons.refer.IReferences.
IReferences
Bases:
abc.ABC
Interface for a map that holds component references and passes them to components to establish dependencies with each obj.
Together with
IReferenceable
andIUnreferenceable
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.Example:
class MyController(IReferences): _persistence = None def set_references(self, references): self._persistence = references.get_one_required(Descriptor("mygroup", "persistence", "*", "*", "1.0")) persistence = MyMongoDbPersistence() references = References.from_tuples( Descriptor("mygroup", "persistence", "mongodb", "default", "1.0"), persistence, Descriptor("mygroup", "controller", "default", "default", "1.0"), controller) controller.set_references(references)
-
find
(locator: Any, required: bool) → List[Any] Gets all component references that match specified locator.
- Parameters
locator – the locator to find a reference by.
required – forces to raise an error if no reference is found.
- Returns
a list with matching component references.
- Raises
a
ReferenceException
when __required is set to true but no references found.
-
get_all
() → List[Any] Gets all component references registered in this reference map.
- Returns
a list with component references.
-
get_all_locators
() → List[Any] Gets locators for all registered component references in this reference map.
- Returns
a list with component locators.
-
get_one_before
(reference, locator)
-
get_one_optional
(locator: Any) → Any Gets an optional component reference that matches specified locator.
- Parameters
locator – the locator to find references by.
- Returns
a matching component reference or null if nothing was found.
-
get_one_required
(locator: Any) → Any Gets a __required component reference that matches specified locator.
- Parameters
locator – the locator to find a reference by.
- Returns
a matching component reference.
- Raises
a
ReferenceException
when no references found.
-
get_optional
(locator: Any) → List[Any] Gets all component references that match specified locator.
- Parameters
locator – the locator to find references by.
- Returns
a list with matching component references or empty list if nothing was found.
-
get_required
(locator: Any) → List[Any] 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.
- Parameters
locator – the locator to find references by.
- Returns
a list with matching component references.
- Raises
a
ReferenceException
when no references found.
-
put
(locator: Any = None, reference: Any = None) Puts a new reference into this reference map.
- Parameters
locator – a component reference to be added.
reference – a locator to find the reference by.
-
remove
(locator: Any) → Any 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 :func:remove_all method instead.
- Parameters
locator – a locator to remove reference
- Returns
the removed component reference.
-
remove_all
(locator: Any) → List[Any] Removes all component references that match the specified locator.
- Parameters
locator – a locator to remove reference
- Returns
a list, containing all removed references.
-