www.aleph1.co.uk Git - yaffs-website/blob - vendor/container-interop/container-interop/docs/Delegate-lookup.md

   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`](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`](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`](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.