| 1 | /**
|
| 2 | * Interface for a map that holds component references and passes them to components
|
| 3 | * to establish dependencies with each other.
|
| 4 | *
|
| 5 | * Together with [[IReferenceable]] and [[IUnreferenceable]] interfaces it implements
|
| 6 | * a Locator pattern that is used by PipServices toolkit for Inversion of Control
|
| 7 | * to assign external dependencies to components.
|
| 8 | *
|
| 9 | * The IReferences object is a simple map, where keys are locators
|
| 10 | * and values are component references. It allows to add, remove and find components
|
| 11 | * by their locators. Locators can be any values like integers, strings or component types.
|
| 12 | * But most often PipServices toolkit uses [[Descriptor]] as locators that match
|
| 13 | * by 5 fields: group, type, kind, name and version.
|
| 14 | *
|
| 15 | * @see [[Descriptor]]
|
| 16 | * @see [[References]]
|
| 17 | *
|
| 18 | * ### Example ###
|
| 19 | *
|
| 20 | * export class MyController implements IReferenceable {
|
| 21 | * public _persistence: IMyPersistence;
|
| 22 | * ...
|
| 23 | * public setReferences(references: IReferences): void {
|
| 24 | * this._persistence = references.getOneRequired<IMyPersistence>(
|
| 25 | * new Descriptor("mygroup", "persistence", "*", "*", "1.0")
|
| 26 | * );
|
| 27 | * }
|
| 28 | * ...
|
| 29 | * }
|
| 30 | *
|
| 31 | * let persistence = new MyMongoDbPersistence();
|
| 32 | *
|
| 33 | * let controller = new MyController();
|
| 34 | *
|
| 35 | * let references = References.fromTuples(
|
| 36 | * new Descriptor("mygroup", "persistence", "mongodb", "default", "1.0"), persistence,
|
| 37 | * new Descriptor("mygroup", "controller", "default", "default", "1.0"), controller
|
| 38 | * );
|
| 39 | * controller.setReferences(references);
|
| 40 | *
|
| 41 | */
|
| 42 | export interface IReferences {
|
| 43 | /**
|
| 44 | * Puts a new reference into this reference map.
|
| 45 | *
|
| 46 | * @param locator a locator to find the reference by.
|
| 47 | * @param component a component reference to be added.
|
| 48 | */
|
| 49 | put(locator: any, component: any): any;
|
| 50 | /**
|
| 51 | * Removes a previously added reference that matches specified locator.
|
| 52 | * If many references match the locator, it removes only the first one.
|
| 53 | * When all references shall be removed, use [[removeAll]] method instead.
|
| 54 | *
|
| 55 | * @param locator a locator to remove reference
|
| 56 | * @returns the removed component reference.
|
| 57 | *
|
| 58 | * @see [[removeAll]]
|
| 59 | */
|
| 60 | remove(locator: any): any;
|
| 61 | /**
|
| 62 | * Removes all component references that match the specified locator.
|
| 63 | *
|
| 64 | * @param locator the locator to remove references by.
|
| 65 | * @returns a list, containing all removed references.
|
| 66 | */
|
| 67 | removeAll(locator: any): any[];
|
| 68 | /**
|
| 69 | * Gets locators for all registered component references in this reference map.
|
| 70 | *
|
| 71 | * @returns a list with component locators.
|
| 72 | */
|
| 73 | getAllLocators(): any[];
|
| 74 | /**
|
| 75 | * Gets all component references registered in this reference map.
|
| 76 | *
|
| 77 | * @returns a list with component references.
|
| 78 | */
|
| 79 | getAll(): any[];
|
| 80 | /**
|
| 81 | * Gets all component references that match specified locator.
|
| 82 | *
|
| 83 | * @param locator the locator to find references by.
|
| 84 | * @returns a list with matching component references or empty list if nothing was found.
|
| 85 | */
|
| 86 | getOptional<T>(locator: any): T[];
|
| 87 | /**
|
| 88 | * Gets all component references that match specified locator.
|
| 89 | * At least one component reference must be present.
|
| 90 | * If it doesn't the method throws an error.
|
| 91 | *
|
| 92 | * @param locator the locator to find references by.
|
| 93 | * @returns a list with matching component references.
|
| 94 | *
|
| 95 | * @throws a [[ReferenceException]] when no references found.
|
| 96 | */
|
| 97 | getRequired<T>(locator: any): T[];
|
| 98 | /**
|
| 99 | * Gets an optional component reference that matches specified locator.
|
| 100 | *
|
| 101 | * @param locator the locator to find references by.
|
| 102 | * @returns a matching component reference or null if nothing was found.
|
| 103 | */
|
| 104 | getOneOptional<T>(locator: any): T;
|
| 105 | /**
|
| 106 | * Gets a required component reference that matches specified locator.
|
| 107 | *
|
| 108 | * @param locator the locator to find a reference by.
|
| 109 | * @returns a matching component reference.
|
| 110 | * @throws a [[ReferenceException]] when no references found.
|
| 111 | */
|
| 112 | getOneRequired<T>(locator: any): T;
|
| 113 | /**
|
| 114 | * Gets all component references that match specified locator.
|
| 115 | *
|
| 116 | * @param locator the locator to find a reference by.
|
| 117 | * @param required forces to raise an exception if no reference is found.
|
| 118 | * @returns a list with matching component references.
|
| 119 | *
|
| 120 | * @throws a [[ReferenceException]] when required is set to true but no references found.
|
| 121 | */
|
| 122 | find<T>(locator: any, required: boolean): T[];
|
| 123 | }
|