UNPKG

4.8 kBTypeScriptView Raw
1/** @module refer */
2import { Reference } from './Reference';
3import { IReferences } from './IReferences';
4/**
5 * The most basic implementation of [[IReferences]] to store and locate component references.
6 *
7 * @see [[IReferences]]
8 *
9 * ### Example ###
10 *
11 * export class MyController implements IReferenceable {
12 * public _persistence: IMyPersistence;
13 * ...
14 * public setReferences(references: IReferences): void {
15 * this._persistence = references.getOneRequired<IMyPersistence>(
16 * new Descriptor("mygroup", "persistence", "*", "*", "1.0")
17 * );
18 * }
19 * ...
20 * }
21 *
22 * let persistence = new MyMongoDbPersistence();
23 *
24 * let controller = new MyController();
25 *
26 * let references = References.fromTuples(
27 * new Descriptor("mygroup", "persistence", "mongodb", "default", "1.0"), persistence,
28 * new Descriptor("mygroup", "controller", "default", "default", "1.0"), controller
29 * );
30 * controller.setReferences(references);
31 */
32export declare class References implements IReferences {
33 protected _references: Reference[];
34 /**
35 * Creates a new instance of references and initializes it with references.
36 *
37 * @param tuples (optional) a list of values where odd elements are locators and the following even elements are component references
38 */
39 constructor(tuples?: any[]);
40 /**
41 * Puts a new reference into this reference map.
42 *
43 * @param locator a locator to find the reference by.
44 * @param component a component reference to be added.
45 */
46 put(locator: any, component: any): void;
47 /**
48 * Removes a previously added reference that matches specified locator.
49 * If many references match the locator, it removes only the first one.
50 * When all references shall be removed, use [[removeAll]] method instead.
51 *
52 * @param locator a locator to remove reference
53 * @returns the removed component reference.
54 *
55 * @see [[removeAll]]
56 */
57 remove(locator: any): any;
58 /**
59 * Removes all component references that match the specified locator.
60 *
61 * @param locator the locator to remove references by.
62 * @returns a list, containing all removed references.
63 */
64 removeAll(locator: any): any[];
65 /**
66 * Gets locators for all registered component references in this reference map.
67 *
68 * @returns a list with component locators.
69 */
70 getAllLocators(): any[];
71 /**
72 * Gets all component references registered in this reference map.
73 *
74 * @returns a list with component references.
75 */
76 getAll(): any[];
77 /**
78 * Gets an optional component reference that matches specified locator.
79 *
80 * @param locator the locator to find references by.
81 * @returns a matching component reference or null if nothing was found.
82 */
83 getOneOptional<T>(locator: any): T;
84 /**
85 * Gets a required component reference that matches specified locator.
86 *
87 * @param locator the locator to find a reference by.
88 * @returns a matching component reference.
89 * @throws a [[ReferenceException]] when no references found.
90 */
91 getOneRequired<T>(locator: any): T;
92 /**
93 * Gets all component references that match specified locator.
94 *
95 * @param locator the locator to find references by.
96 * @returns a list with matching component references or empty list if nothing was found.
97 */
98 getOptional<T>(locator: any): T[];
99 /**
100 * Gets all component references that match specified locator.
101 * At least one component reference must be present.
102 * If it doesn't the method throws an error.
103 *
104 * @param locator the locator to find references by.
105 * @returns a list with matching component references.
106 *
107 * @throws a [[ReferenceException]] when no references found.
108 */
109 getRequired<T>(locator: any): T[];
110 /**
111 * Gets all component references that match specified locator.
112 *
113 * @param locator the locator to find a reference by.
114 * @param required forces to raise an exception if no reference is found.
115 * @returns a list with matching component references.
116 *
117 * @throws a [[ReferenceException]] when required is set to true but no references found.
118 */
119 find<T>(locator: any, required: boolean): T[];
120 /**
121 * Creates a new References from a list of key-value pairs called tuples.
122 *
123 * @param tuples a list of values where odd elements are locators and the following even elements are component references
124 * @returns a newly created References.
125 *
126 * @see [[fromTuplesArray]]
127 */
128 static fromTuples(...tuples: any[]): References;
129}