| 1 |
Delegate lookup feature |
| 2 |
======================= |
| 3 |
|
| 4 |
This document describes a standard for dependency injection containers. |
| 5 |
|
| 6 |
The goal set by the *delegate lookup* feature is to allow several containers to share entries. |
| 7 |
Containers implementing this feature can perform dependency lookups in other containers. |
| 8 |
|
| 9 |
Containers implementing this feature will offer a greater lever of interoperability |
| 10 |
with other containers. Implementation of this feature is therefore RECOMMENDED. |
| 11 |
|
| 12 |
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", |
| 13 |
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be |
| 14 |
interpreted as described in [RFC 2119][]. |
| 15 |
|
| 16 |
The word `implementor` in this document is to be interpreted as someone |
| 17 |
implementing the delegate lookup feature in a dependency injection-related library or framework. |
| 18 |
Users of dependency injections containers (DIC) are referred to as `user`. |
| 19 |
|
| 20 |
[RFC 2119]: http://tools.ietf.org/html/rfc2119 |
| 21 |
|
| 22 |
1. Vocabulary |
| 23 |
------------- |
| 24 |
|
| 25 |
In a dependency injection container, the container is used to fetch entries. |
| 26 |
Entries can have dependencies on other entries. Usually, these other entries are fetched by the container. |
| 27 |
|
| 28 |
The *delegate lookup* feature is the ability for a container to fetch dependencies in |
| 29 |
another container. In the rest of the document, the word "container" will reference the container |
| 30 |
implemented by the implementor. The word "delegate container" will reference the container we are |
| 31 |
fetching the dependencies from. |
| 32 |
|
| 33 |
2. Specification |
| 34 |
---------------- |
| 35 |
|
| 36 |
A container implementing the *delegate lookup* feature: |
| 37 |
|
| 38 |
- MUST implement the [](ContainerInterface.md`ContainerInterface`](ContainerInterface.md](ContainerInterface.md) |
| 39 |
- MUST provide a way to register a delegate container (using a constructor parameter, or a setter, |
| 40 |
or any possible way). The delegate container MUST implement the [](ContainerInterface.md`ContainerInterface`](ContainerInterface.md](ContainerInterface.md). |
| 41 |
|
| 42 |
When a container is configured to use a delegate container for dependencies: |
| 43 |
|
| 44 |
- Calls to the `get` method should only return an entry if the entry is part of the container. |
| 45 |
If the entry is not part of the container, an exception should be thrown |
| 46 |
(as requested by the [](ContainerInterface.md`ContainerInterface`](ContainerInterface.md](ContainerInterface.md)). |
| 47 |
- Calls to the `has` method should only return `true` if the entry is part of the container. |
| 48 |
If the entry is not part of the container, `false` should be returned. |
| 49 |
- If the fetched entry has dependencies, **instead** of performing |
| 50 |
the dependency lookup in the container, the lookup is performed on the *delegate container*. |
| 51 |
|
| 52 |
Important: By default, the dependency lookups SHOULD be performed on the delegate container **only**, not on the container itself. |
| 53 |
|
| 54 |
It is however allowed for containers to provide exception cases for special entries, and a way to lookup |
| 55 |
into the same container (or another container) instead of the delegate container. |
| 56 |
|
| 57 |
3. Package / Interface |
| 58 |
---------------------- |
| 59 |
|
| 60 |
This feature is not tied to any code, interface or package. |
| 61 |
|
