pip_services3_commons.refer.References module

pip_services3_commons.refer.References

Referencescomponent implementation

copyright: Conceptual Vision Consulting LLC 2018-2019, see AUTHORS for more details.
license: MIT, see LICENSE for more details.

class pip_services3_commons.refer.References.References(tuples: Sequence[Any] = None)

Bases: pip_services3_commons.refer.IReferences.IReferences

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

Example:

class MyController(IReferenceable):
    _persistence = None

    def set_references(self, references):
        self._persistence = references.getOneRequired(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.

static from_tuples(*tuples: Any) → pip_services3_commons.refer.References.References 

Creates a new References from a list of key-args pairs called tuples.

Parameters: tuples – a list of values where odd elements are locators and the following even elements are component references
Returns: a newly created References.

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_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, component: Any = None)

Puts a new reference into this reference map.

Parameters

locator – a component reference to be added.
component – 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 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 by.
Returns: a list, containing all removed references.