1 package org.djunits.quantity.def;
2
3 import java.util.Map;
4
5 import org.djutils.base.Identifiable;
6
7 /**
8 * Reference contains information about the reference point or origin / zero point of an absolute quantity.
9 * <p>
10 * Copyright (c) 2025-2026 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See
11 * for project information <a href="https://djunits.org" target="_blank">https://djunits.org</a>. The DJUNITS project is
12 * distributed under a <a href="https://djunits.org/docs/license.html" target="_blank">three-clause BSD-style license</a>.
13 * @author Alexander Verbraeck
14 * @param <R> the reference type itself
15 * @param <A> the absolute quantity type for generics instantiation
16 * @param <Q> the relative quantity type for the offset
17 */
18 public interface Reference<R extends Reference<R, A, Q>, A extends AbsQuantity<A, Q, R>, Q extends Quantity<Q>>
19 extends Identifiable
20 {
21 /**
22 * Return a safe copy of the static reference map for this Reference subclass.
23 * @return a safe copy of the static reference map for this subclass
24 */
25 Map<String, Reference<?, ?, ?>> getReferenceMap();
26
27 /**
28 * Instance-level unregister; removes this reference from the per-class registry. Intended primarily for unit tests to clean
29 * up temporary references. Existing objects that hold a direct pointer to this instance continue to work.
30 * @return true if this reference was removed from the registry; false if it was not present
31 */
32 boolean unregister();
33
34 /**
35 * Return a strongly typed absolute quantity belonging to this reference.
36 * @param quantity the relative quantity that indicates the 'distance' to this reference point
37 * @return a strongly typed absolute quantity belonging to this reference
38 */
39 A instantiate(Q quantity);
40
41 /**
42 * Return the offset w.r.t. the offset reference, or zero when the offset is not defined.
43 * @return the offset expressed in the relative quantity
44 */
45 Q getOffset();
46
47 /**
48 * Return the offset reference for the offset, or null when the offset reference is not defined.
49 * @return the offset reference
50 */
51 R getOffsetReference();
52
53 /**
54 * Return the description of this reference point.
55 * @return description of this reference point
56 */
57 String getName();
58 }