pip_services3_container.refer package¶
Submodules¶
- pip_services3_container.refer.BuildReferencesDecorator module
- pip_services3_container.refer.ContainerReferences module
- pip_services3_container.refer.LinkReferencesDecorator module
- pip_services3_container.refer.ManagedReferences module
- pip_services3_container.refer.ReferencesDecorator module
- pip_services3_container.refer.RunReferencesDecorator module
Module contents¶
pip_services3_container.refer.__init__¶
Provides the inversion of control design pattern but does not contain the fully functional container (we can just only create a class that will set various references).
Once the objects of a container are configured, if they implement the IReferencable interface,
they are passed a set of references for recreating links between objects in the container.
If objects implement the IOpenable interface, the open()
method is called and they start to work.
Connections to various services are made, after which the objects start,
the container starts running, and the objects carry out their tasks. When the container starts to close,
the objects that implement the ICloseable interface are closed via their
close()
method (which should make them stop working and disconnect from other services),
after which objects that implement the IUnreferenceable interface delete various links between objects,
and, finally, the contains destroys all objects and turns off.
BuildReferencesDecorator
, LinkReferencesDecorator
, and
RunReferencesDecorator
- ReferenceDecorators are used during the corresponding building, linking,
and running stages and are united in ManagedReferences
, which are extended by ContainerReferences
.
- copyright
Conceptual Vision Consulting LLC 2018-2019, see AUTHORS for more details.
- license
MIT, see LICENSE for more details.
-
class
pip_services3_container.refer.
BuildReferencesDecorator
(next_references: pip_services3_commons.refer.IReferences.IReferences, top_references: pip_services3_commons.refer.IReferences.IReferences)¶ Bases:
pip_services3_container.refer.ReferencesDecorator.ReferencesDecorator
References decorator that automatically creates missing components using available component factories upon component retrival.
-
clarify_locator
(locator: Any, factory: pip_services3_components.build.IFactory.IFactory) → Any¶ Clarifies a component locator by merging two descriptors into one to replace missing fields. That allows to get a more complete descriptor that includes all possible fields.
- Parameters
locator – a component locator to clarify.
factory – a factory that shall create the component.
- Returns
clarified component descriptor (locator)
-
create
(locator: Any, factory: pip_services3_components.build.IFactory.IFactory) → Any¶ Creates a component identified by given locator.
- Parameters
locator – a locator to identify component to be created.
factory – a factory that shall create the component.
- Returns
the created component.
-
find
(locator: Any, required: bool) → List[Any]¶ Gets all component references that match specified locator.
- Parameters
locator – the locator to find a component by.
required – forces to raise an exception if no component is found.
- Returns
a list with matching component references.
-
find_factory
(locator: Any) → Optional[pip_services3_components.build.IFactory.IFactory]¶ Finds a factory capable creating component by given descriptor from the components registered in the references.
- Parameters
locator – a locator of component to be created.
- Returns
found factory or null if factory was not found.
-
-
class
pip_services3_container.refer.
ContainerReferences
(tuples: Sequence[Any] = None)¶ Bases:
pip_services3_container.refer.ManagedReferences.ManagedReferences
Container managed references that can be created from container configuration.
-
put_from_config
(config: pip_services3_container.config.ContainerConfig.ContainerConfig)¶ Puts components into the references from container configuration.
- Parameters
config – a container configuration with information of components to be added.
-
-
class
pip_services3_container.refer.
LinkReferencesDecorator
(next_references: pip_services3_commons.refer.IReferences.IReferences, top_references: pip_services3_commons.refer.IReferences.IReferences)¶ Bases:
pip_services3_container.refer.ReferencesDecorator.ReferencesDecorator
,pip_services3_commons.run.IOpenable.IOpenable
References decorator that automatically sets references to newly added components that implement
IReferenceable
interface and unsets references from removed components that implementIUnreferenceable
interface.-
close
(correlation_id: Optional[str])¶ Closes component and frees used resources.
- Parameters
correlation_id – (optional) transaction id to trace execution through call chain.
-
is_open
() → bool¶ Checks if the component is opened.
- Returns
true if the component has been opened and false otherwise.
-
open
(correlation_id: Optional[str])¶ Opens the component.
- Parameters
correlation_id – (optional) transaction id to trace execution through call chain.
-
put
(locator: Any = None, component: Any = None) → Any¶ Puts a new component into this component map.
- Parameters
locator – a locator to find the component by.
component – a component component to be added.
-
remove
(locator: Any) → Any¶ Removes a previously added component 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 component
- Returns
the removed component component.
-
remove_all
(locator: Any) → List[Any]¶ Removes all component references that match the specified locator.
- Parameters
locator – the locator to remove references by.
- Returns
a list, containing all removed references.
-
-
class
pip_services3_container.refer.
ManagedReferences
(tuples: Sequence[Any] = None)¶ Bases:
pip_services3_container.refer.ReferencesDecorator.ReferencesDecorator
,pip_services3_commons.run.IOpenable.IOpenable
- Managed references that in addition to keeping and locating references can also manage their lifecycle:
Auto-creation of missing component using available factories
Auto-linking newly added components
Auto-opening newly added components
Auto-closing removed components
-
close
(correlation_id: Optional[str])¶ Closes component and frees used resources.
- Parameters
correlation_id – (optional) transaction id to trace execution through call chain.
-
static
from_tuples
(*tuples: Any) → pip_services3_container.refer.ManagedReferences.ManagedReferences¶ Creates a new ManagedReferences object filled with provided key-value pairs called tuples. Tuples parameters contain a sequence of locator1, component1, locator2, component2, … pairs.
- Parameters
tuples – the tuples to fill a new ManagedReferences object.
- Returns
a new ManagedReferences object.
-
class
pip_services3_container.refer.
ReferencesDecorator
(next_references: Optional[pip_services3_commons.refer.IReferences.IReferences], top_references: Optional[pip_services3_commons.refer.IReferences.IReferences])¶ Bases:
pip_services3_commons.refer.IReferences.IReferences
Chainable decorator for
IReferences
that allows to inject additional capabilities such as automatic component creation, automatic registration and opening.-
find
(locator: Any, required: bool) → List[Any]¶ Gets all component references that match specified locator.
- Parameters
locator – the locator to find a component by.
required – forces to raise an exception if no component 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 component map.
- Returns
a list with component references.
-
get_all_locators
() → List[Any]¶ Gets locators for all registered component references in this component map.
- Returns
a list with component locators.
-
get_one_before
(reference, locator)¶
-
get_one_optional
(locator: Any) → Any¶ Gets an optional component component that matches specified locator.
- Parameters
locator – the locator to find references by.
- Returns
a matching component component or null if nothing was found.
-
get_one_required
(locator: Any) → Any¶ Gets a required component component that matches specified locator.
- Parameters
locator – the locator to find a component by.
- Returns
a matching component component.
- 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 component 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 locator to find the reference by.
component – a component reference to be added.
-
remove
(locator: Any) → Any¶ Removes a previously added component 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 component
- Returns
the removed component component.
-
remove_all
(locator: Any) → List[Any]¶ Removes all component references that match the specified locator.
- Parameters
locator – the locator to remove references by.
- Returns
a list, containing all removed references.
-
-
class
pip_services3_container.refer.
RunReferencesDecorator
(next_references: pip_services3_commons.refer.IReferences.IReferences, top_references: pip_services3_commons.refer.IReferences.IReferences)¶ Bases:
pip_services3_container.refer.ReferencesDecorator.ReferencesDecorator
,pip_services3_commons.run.IOpenable.IOpenable
References decorator that automatically opens to newly added components that implement
IOpenable
interface and closes removed components that implementIClosable
interface.-
close
(correlation_id: Optional[str])¶ Closes component and frees used resources.
- Parameters
correlation_id – (optional) transaction id to trace execution through call chain.
-
is_open
() → bool¶ Checks if the component is opened.
- Returns
true if the component has been opened and false otherwise.
-
open
(correlation_id: Optional[str])¶ Opens the component.
- Parameters
correlation_id – (optional) transaction id to trace execution through call chain.
-
put
(locator: Any = None, component: Any = None)¶ Puts a new component into this component map.
- Parameters
locator – a locator to find the component by.
component – a component component to be added.
-
remove
(locator: Any) → Any¶ Removes a previously added component 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.- Parameters
locator – a locator to remove component
- Returns
the removed component component.
-
remove_all
(locator: Any) → List[Any]¶ Removes all component references that match the specified locator.
- Parameters
locator – the locator to remove references by.
- Returns
a list, containing all removed references.
-