Konfigurierbare Klasseninstanzen

Erzeugen einer Instanz

Für das Erzeugen einer Instanz kann die statische Methode getInstanceOf in der Klasse MCRConfiguration2 mit einem frei wählbaren Konfigurationsnamen aufgerufen werden. Wenn das Vorhandensein einer Instanz unabdingbar ist, bietet sich die Nutzung der Methode createConfigurationException an.

1
2
3

MyConfigurableClass mandatoryInstance = MCRConfiguration2
    .getInstanceOf(MyConfigurableClass.class, "MCR.Configurable.Class")
    .orElseThrow(() -> MCRConfiguration2.createConfigurationException("MCR.Configurable.Class"));

Damit eine entsprechende Instanz erzeugt werden kann, muss getInstanceOf als zweiten Parameter der Name eines Properties übergeben werden, in dem der vollqualifizierten Klassennamen der zu instanziierenden Klasse steht (im Folgenden: Konfigurationsname). Der erste Parameter gibt die Klasse vor, zu der die instanziierte Instanz zuweisungskompatibel sein soll (also z.B. eine Überklasse der instanziierten Klasse, oder ein Interface, dass von der instanziierten Klasse implementiert wird).

1

 MCR.Configurable.Class=my.configurable.MyConfigurableSubClass

In diesem Beispiel muss MyConfigurableSubClass eine Unterklasase von MyConfigurableClass sein. Zudem darf diese Klasse nicht abstrakt sein und muss

• eine einzelne öffentliche, statische, parameterlose Methode mit passendem Rückgabewert und Namen getInstance,
• eine einzelne öffentliche, statische, parameterlose Methode mit passendem Rückgabewert und Annotation @MCRFactory oder
• einen öffentlichen, parameterlosen Konstruktor

anbieten, wobei die jeweils früher genannte Variante bevorzugt wird.

Endet der gewählte Konfigurationsname (wie in diesem Beispiel) auf .Class oder .class, so werden für die im Folgenden beschriebenen Funktionen alle weitere Properties relativ zu dem davorstehenden Namensanteil (im Beispiel My.Configurable) gesucht, andernfalls relativ zum vollen Namen.

Statt getInstanceOf in Kombination mit createConfigurationException kann auch getInstanceOfOrThrow verwendet werden. In diesem Fall wird ein Fehler geworfen, wenn keine passende Konfiguration existiert.

Statt getInstanceOf oder getInstanceOfOrThrow kann auch getSingleInstanceOf bzw. getSingleInstanceOfOrThrow verwendet werden. In diesem Fall wird eine erzeugte Instanz gecacht und erneut zurückgegeben, wenn derselbe Konfigurationsname nochmals übergeben wird.

Zuweisen von Properties mit @MCRProperty

Falls die Klasse MyConfigurableClass zusätzliche Konfigurationswerte benötigt, so können Felder oder Methoden mit der Annotation @MCRProperty versehen werden. Annotierte Felder muss öffentlich und vom Typ String oder Map<String, String> sein. Annotierte Methoden muss öffentlich sein und einen einzigen Parameter vom Typ String oder Map<String, String> nehmen.

Die Annotation hat folgende Konfigurationsmöglichkeiten:

• Das notwendige Attribut mame gibt den Namen des zugehörigen Properties an, sofern das annotierte Feld bzw. die annotierte Methode den Typ String nutzt. Genau dann, wenn das annotierte Feld bzw. die annotierte Methode den Typ Map<String, String> nutzt, muss hier der besondere Wert * angegeben werden. In diesem Fall wird statt einem einzelnen Property eine Map mit allen unterhalb des gewählten Konfigurationsnamens vorhandenen Properties bereitgestellt.
• Das optionale Attribut required gibt an, ob ein entsprechendes Property vorhanden sein muss. Der Standardwert ist true. Wenn false gewählt wird und kein entsprechendes Property vorhanden ist, wird der (z.B. im Konstruktor gesetzte) vorhandene Wert des annotierten Feldes nicht auf null gesetzt. Eine annotierte Methode wird in diesem Fall nicht aufgerufen. Wird eine annotierte Methode aufgerufen, so ist der übergebene Wert niemals null.
• Das optionale Attribut absolute gibt an, ob der unter name angegeben Wert absolute (und nicht relativ zum Konfigurationsnamen) aufgefasst werden soll.
• Das optionale Attribut defaultName gibt den absolut aufgefassten Namen eines Standardproperties an, dass verwendet werden soll, wenn das eigentliche Property nicht vorhanden ist. Dieses Standardproperty muss auf jeden Fall konfiguriert sein. Dieses Vorgehen ist hart kodierten Standardwerten vorzuziehen.
• Das optionale Attribut order gibt die Reihenfolge an, in der die annotierten Felder gesetzt bzw. die annotierten Methoden aufgerufen werden, wobei niedrigere bevorzugt werden. Der Standardwert ist 0. Haben z.B. mehrere annotierte Methoden denselben Wert, so wird keine Reihenfolge garantiert.

Java-Code in der Klasse MyConfigurableClass (Auszug):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

@MCRProperty(name = "Foo", required = false)
public String foo = "default";

@MCRProperty(name = "*")
public Map<String, String> map;

private Integer number;

@MCRProperty(name = "MCR.InterestingNumber.Local", absolute=true, defaultName="MCR.InterestingNumber.Global")
public void setNumber(String number){
this.foo = Integer.parseInt(number);
}

Eine passende Konfiguration könnte beispielsweise so aussehen:

1
2
3
4
5

MCR.Configurable.Class=my.configurable.MyConfigurableClass
MCR.Configurable.Foo=custom
MCR.Configurable.Bar=baz
# MCR.InterestingNumber.Local=23
MCR.InterestingNumber.Global=42

In diesem Beispiel bekommt das Feld foo den Wert custom aus dem Property MCR.Configurable.Foo. Der vordefiniert Wert default wird überschrieben. Das Feld map bekommt eine Map mit den Einträgen Foo=custom und Bar=baz. Die Methode setNumber wird mit dem Wert 42 aus dem Standardproperty MCR.InterestingNumber.Global aufgerufen. Wäre das Property MCR.InterestingNumber.Local nicht auskommentiert, so würde die Methode mit dessen Wert 23 aufgerufen werden.

Geschachtelte Instanzen mit @MCRInstance

Falls die Klasse MyConfigurableClass statt einfachen Konfigurationswerten komplexere Objekte benötigt, so können Felder oder Methoden mit der Annotation @MCRInstance versehen werden. Annotierte Felder müssen öffentlich und von einem Typ sein, der zuweisungskompatibel zu dem im Attribut valueClass der Annotation angegebenen Klasse sein muss. Annotierte Methoden müssen öffentlich sein und einen einzigen Parameter von einem solchen Typ nehmen.

Die Annotation hat folgende Konfigurationsmöglichkeiten:

• Das notwendige Attribut mame gibt den Namen des zugehörigen Properties an. In diesem muss die zu instanziierende Klasse mit ihrem vollqualifizierten Klassennamen benennen. Endet der gewählte ursprünglich Konfigurationsname (wie in diesem Beispiel) auf .Class oder .class, so wird diese Endung übernommen.
• Das notwendige Attribut valueClass benennt die Klasse, zu der die in name benannte Klasse zuweisungskompatibel sein muss. Dass annotierte Feld bzw. der Parameter der annotierten Methode muss ebenfalls diesen Typ haben.
• Das optionale Attribut required gibt an, ob ein entsprechendes Property vorhanden sein muss. Der Standardwert ist true. Wenn false gewählt wird und kein entsprechendes Property vorhanden ist, wird der (z.B. im Konstruktor gesetzte) vorhandene Wert des annotierten Feldes nicht auf null gesetzt. Eine annotierte Methode wird in diesem Fall nicht aufgerufen. Wird eine annotierte Methode aufgerufen, so ist der übergebene Wert niemals null.
• Das optionale Attribut order gibt die Reihenfolge an, in der die annotierten Felder gesetzt bzw. die annotierten Methoden aufgerufen werden, wobei niedrigere bevorzugt werden. Der Standardwert ist 0. Haben z.B. mehrere annotierte Methoden denselben Wert, so wird keine Reihenfolge garantiert.

Java-Code in der Klasse MyConfigurableClass (Auszug):

1
2
3
4
5
6
7
8

@MCRProperty(name = "Foo")
public String foo;

@MCRInstance(name = "Nested1", valueClass=MyConfigurableClass.class, required=false)
public MyConfigurableClass nested1;

@MCRInstance(name = "Nested2", valueClass=MyConfigurableClass.class, required=false)
public MyConfigurableClass nested2;

Eine passende Konfiguration könnte beispielsweise so aussehen:

1
2
3
4
5
6

MCR.Configurable.Class=my.configurable.MyConfigurableClass
MCR.Configurable.Foo=foo
MCR.Configurable.Nested1.Class=my.configurable.MyConfigurableClass
MCR.Configurable.Nested1.Foo=bar
MCR.Configurable.Nested2.Class=my.configurable.MyConfigurableClass
MCR.Configurable.Nested2.Foo=baz

In diesem Beispiel bekommt das Feld foo den Wert foo aus dem Property MCR.Configurable.Foo. Zudem werden zwei weitere Instanzen der Klasse MyConfigurableClass erzeugt und den Feldern nested1 und nested2 zugewiesen. Dem Feld foo dieser geschachtelten Instanzen wird der Wert bar bzw. der Wert baz zugewiesen.

Mehrere geschachtelte Instanzen mit @MCRInstanceMap oder @MCRInstanceList

Falls die Klasse MyConfigurableClass statt mehrere statt einzelnen komplexere Objekte benötigt, so können Felder oder Methoden mit der Annotation @MCRInstanceMap oder @MCRInstanceList versehen werden. Annotierte Felder müssen öffentlich und vom Typ Map<String, X> bzw. List<X> sein, wobei X zuweisungskompatibel zu dem im Attribut valueClass der Annotation angegebenen Klasse sein muss. Annotierte Methoden müssen öffentlich sein und einen einzigen Parameter von einem solchen Typ nehmen.

Die Annotationen haben dieselben Konfigurationsmöglichkeiten wie @MCRInstance. Das Attribute name ist jedoch optional und gibt nur einen Prefix für die zu beachtenden Properties an. Wird kein Wert angegeben, so werden alle Properties behandelt.

Alle behandelten Properties werden ausgewertet und zur Erzeugung geschachtelter Instanzen herangezogen. Der führende Namensanteil (abzüglich dem ggf. im Attribut name angegebenen Prefix) wird im Falle von @MCRInstanceMap als Schlüssel für die gebildete Map und im Falle von @MCRInstanceList (als Zahlenwert interpretiert) für die Reihenfolge der gebildeten List verwendet. Endet der gewählte ursprünglich Konfigurationsname (wie in diesem Beispiel) auf .Class oder .class, so wird diese Endung übernommen.

Java-Code in der Klasse MyConfigurableClass (Auszug):

1
2
3
4
5

@MCRInstanceMap(name = "NestedMap", valueClass=Nested.class)
public Map<String, Nested> nestedMap;

@MCRInstanceList(name = "NestedList", valueClass=Nested.class)
public List<Nested> nestedList;

Eine passende Konfiguration könnte beispielsweise so aussehen:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

MCR.Configurable.Class=my.configurable.MyConfigurableClass
MCR.Configurable.NestedMap.foo.Class=my.configurable.MyNestedClassA
MCR.Configurable.NestedMap.foo.ConfigValue1=...
MCR.Configurable.NestedMap.foo.ConfigValue2=...
MCR.Configurable.NestedMap.bar.Class=my.configurable.MyNestedClassB
MCR.Configurable.NestedMap.bar.ConfigValue1=...
MCR.Configurable.NestedMap.bar.ConfigValue2=...
MCR.Configurable.NestedList.100.Class=my.configurable.MyNestedClassC
MCR.Configurable.NestedList.100.ConfigValue1=...
MCR.Configurable.NestedList.100.ConfigValue2=...
MCR.Configurable.NestedList.200.Class=my.configurable.MyNestedClassD
MCR.Configurable.NestedList.200.ConfigValue1=...
MCR.Configurable.NestedList.200.ConfigValue2=...

In diesem Beispiel ist Nested ein Interface oder eine (ggf. abstrakte) Basisklasse. Das Feld nestedMap bekommt als Wert eine Map mit zwei Einträge mit Schlüsseln foo und bar. Die Werte dieser Einträge sind Instanzen der Klassen MyNestedClassA bzw. MyNestedClassB. Das Feld nestedList bekommt als Wert eine List mit ebenfalls zwei Einträge. Die Werte dieser Einträge sind Instanzen der Klassen MyNestedClassC bzw. MyNestedClassD. Alle vier erzeugte Instanzen wurden mit weiteren Konfigurationswerten konfiguriert.

Auf das Attribut name der Annotation verzichtet werden. In diesem Fall entfällt der entsprechende Namensbestandteil in den Properties. Allerdings kann die Klasse keine weiteren Konfigurationswerte bekommen, da alle vorhandenen Properties für die Einträge der Map bzw. List verwendet werden.

Java-Code in der Klasse MyConfigurableClass (Auszug):

1
2

@MCRInstanceMap(valueClass=Nested.class)
public Map<String, Nested> nestedMap;

Eine passende Konfiguration könnte beispielsweise so aussehen:

1
2
3
4
5
6
7

MCR.Configurable.Class=my.configurable.MyConfigurableClass
MCR.Configurable.foo.Class=my.configurable.MyNestedClassA
MCR.Configurable.foo.ConfigValue1=...
MCR.Configurable.foo.ConfigValue2=...
MCR.Configurable.bar.Class=my.configurable.MyNestedClassB
MCR.Configurable.bar.ConfigValue1=...
MCR.Configurable.bar.ConfigValue2=...

Das Feld nestedMap bekommt als Wert eine Map mit zwei Einträge mit Schlüsseln foo und bar. Die Werte dieser Einträge sind Instanzen der Klassen MyNestedClassA bzw. MyNestedClassB.

Abschließende Initialisierung mit @MCRPostConstruction

Da man Felder eines Objektes nicht zuweisen kann bevor der Konstruktor aufgerufen wurde, man jedoch für die Initialisierung möglicherweise die zugewiesenen Felder benötigt, gibt es die Möglichkeit weitere Methoden nach der Initialisierung aufrufen zu lassen. Dazu muss die Methode public sein, entweder keinen oder genau einen Parameter vom Typ String nehmen und mit @MCRPostConstruction annotiert sein. Die Annotation hat ein optionale Attribut order das analog zum gleichnamigen Attribut von @MCRProperty funktioniert.

Java-Code in der Klasse MyConfigurableClass (Auszug):

1
2
3
4

@MCRPostConstruction
public void init(String property) {
  assert this.foo!=null;
} 

Falls die Methode einen Parameter nimmt, so wird der Konfigurationsnamen übergeben. Im Beispiel also MCR.Configurable.Class.

Initialisierungsreihenfolge

Die Reihenfolge der Initialisierung ist:

1. Aufrufen des Konstruktors
2. Zuweisung der mit @MCRProperty, @MCRInstance, etc. annotierten Felder (in aufsteigenden order-Reihenfolge)
3. Aufrufen der mit @MCRProperty, @MCRInstance, etc. annotierten Methoden (in aufsteigenden order-Reihenfolge)
4. Aufrufen der mit @MCRPostConstruction annotierten Methode (in aufsteigenden order-Reihenfolge)

Redundante Konfigurationseinträge

Bei den Annotationen @MCRInstance, @MCRInstanceMap oder @MCRInstanceList kann es den Fall geben, dass

• ein Property mit dem Klassennamen der zu instanziierenden Klasse notwendig ist (weil required=false nicht gesetzt wurde),
• es nur einen einzigen möglichen Wert für dieses Property gibt (weil die unter valueClass benannte Klasse final ist) und
• kontextuell klar ist, dass ein solches Property vorhanden sein muss (weil weitere Properties für die zu instanziierende Klasse gesetzt sind).

In so einem Fall kann das Property mit dem Klassennamen aus der Konfiguration weggelassen werden.

Eine solche Kombination kann z.B. bei Value-Klassen vorkommen, die die Konfiguration übersichtlicher machen, z.B.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

@MCRInstanceList(name = "Mappings", valueClass = Mapping.class)
public List<Mapping> mappings;

...

public static final class Mapping {

  @MCRProperty(name = "From")
  public String from;

  @MCRProperty(name = "To")
  public String to;

}

Eine passende Konfiguration könnte beispielsweise so aussehen:

1
2
3
4
5
6
7

MCR.Configurable.Class=my.configurable.MyConfigurableClass
MCR.Configurable.Mappings.10.Class=my.configurable.MyConfigurableClass$Mapping
MCR.Configurable.Mappings.10.From=foo
MCR.Configurable.Mappings.10.To=bar
MCR.Configurable.Mappings.20.Class=my.configurable.MyConfigurableClass$Mapping
MCR.Configurable.Mappings.20.From=this
MCR.Configurable.Mappings.20.To=that

Die redundanten Einträge MCR.Configurable.Mappings.10.Class und MCR.Configurable.Mappings.20.Class können hier weggelassen werden.

Unterbundene Initialisierung mit @MCRSentinel

Zuweilen möchte man in der Konfiguration diverse geschachtelte Instanzen vorhalten (die teilweise aus einer erheblichen Menge von Konfigurationswerten bestehen können), diese aber nicht in der tatsächlich verwendeten Konfiguration verwenden (z.B. exemplarische Konfigurationen oder solche, die nur gelegentlich oder alternativ benötigt werden). Damit in solchen Situationen nicht mit Aus- und Einkommentieren der zugehörigen Konfigurationswerte gearbeitet werden muss, besteht mit MCRSentinel eine Möglichkeit, die Instantiierung von geschachtelten Instanzen zu unterbinden. Dazu kann bei den Annotationen @MCRInstance, @MCRInstanceMap und @MCRInstanceList jeweils das Attribut sentinel verwendet werden. Dies führt dazu, dass bei jeder geschachtelten Instanz zunächst der Konfigurationswert mit dem Namen Enabled ausgewertet wird. Ist dieses vorhanden und hat den Wert false, so wird die Instantiierung der jeweiligen geschachtelten Instanz unterbunden.

Java-Code in der Klasse MyConfigurableClass (Auszug):

1
2

@MCRInstanceMap(name = "NestedMap", valueClass=Nested.class, sentinel=@MCRSentinel)
public Map<String, Nested> nestedMap;

Eine passende Konfiguration könnte beispielsweise so aussehen:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

MCR.Configurable.Class=my.configurable.MyConfigurableClass
MCR.Configurable.NestedMap.foo.Class=my.configurable.MyNestedClassA
MCR.Configurable.NestedMap.foo.Enabled=true
MCR.Configurable.NestedMap.foo.ConfigValue1=...
MCR.Configurable.NestedMap.foo.ConfigValue2=...
MCR.Configurable.NestedMap.bar.Class=my.configurable.MyNestedClassB
MCR.Configurable.NestedMap.bar.ConfigValue1=...
MCR.Configurable.NestedMap.bar.ConfigValue2=...
MCR.Configurable.NestedMap.baz.Class=my.configurable.MyNestedClassB
MCR.Configurable.NestedMap.baz.Enabled=false
MCR.Configurable.NestedMap.baz.ConfigValue1=...
MCR.Configurable.NestedMap.baz.ConfigValue2=...

In diesem Beispiel würden nur die beiden geschachtelten Instanzen mit den Namen foo und bar instanziiert werden. Die geschachtelte Instanz mit den Namen baz wird vollständig ignoriert.

Mit dem Attribut name von MCRSentinel kann der Name des ausgewerteten Konfigurationswerts angepasst werden. Mit dem Attribut rejectionValue von MCRSentinel kann bestimmt werden, bei welchem Konfigurationswert die Instanziierung der jeweiligen geschachtelten Instanz unterbunden wird. Mit dem Attribut defaultValue von MCRSentinel kann der Standardwert bei Nichtvorhandensein des Konfigurationswerts gesetzt werden.

Java-Code in der Klasse MyConfigurableClass (Auszug):

1
2
3

@MCRInstance(name = "Nested", valueClass=Nested.class, required=false,
    sentinel=@MCRSentinel(name = "Default", rejectionValue=true, defaultValue=false))
public Nested nested = new DefaultNestedClass();

Eine passende Konfiguration könnte beispielsweise so aussehen:

1
2
3
4
5

MCR.Configurable.Class=my.configurable.MyConfigurableClass
MCR.Configurable.Nested.Class=my.configurable.MySpecialNestedClass
MCR.Configurable.Nested.Default=true
MCR.Configurable.Nested.ConfigValue1=...
MCR.Configurable.Nested.ConfigValue2=...

In diesem Beispiel würde die geschachtelte Instanz nicht instanziiert werden, sondern das "Standardverhalten" verwendet werden. Der Variable nested wird also eine Instanz von DefaultNestedClass zugewiesen, nicht von MySpecialNestedClass. Würde der Wert von MCR.Configurable.Nested.Default auf false geändert, würde der Konfigurationsmechanismus wieder greifen und eine Instanz von DefaultNestedClass anhand der weiteren Konfigurationswerte instanziiert werden.

Stellvertretende Initialisierung mit @MCRConfigurationProxy

In Situationen, in denen die oben beschriebene Anforderung (z.B., dass eine zu konfigurierende Klasse einen öffentlichen, parameterlosen Konstruktor oder eine qualifizierte Factory-Methode haben muss) nicht umsetzbar ist oder eine derartige Umsetzung anderen Design-Entscheidungen (z.B. Kapselung, Immutability) entgegen spricht, oder die Klasse allgemein vom Konfigurationsmechanismus entkoppelt werden soll, so kann die zu instanziierende Klasse mit MCRConfigurationProxy annotiert werden. Diese Annotation hat ein Attribut proxyClass, dass eine Klasse benennt, die stattdessen mit dem hier beschriebenen Mechanismus konfiguriert und anschließend verwendet wird, um eine Instanz der eigentlich zu instanziierende Klasse zu erlangen. Hierzu muss diese Klasse das Interface Supplier<X> implementieren, wobei X die eigentlich zu instanziierende Klasse ist.

Java-Code in der Klasse MyConfigurableClass:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

@MCRConfigurationProxy(proxyClass = MyConfigurableClass.Factory.class)
public final class MyConfigurableClass {

private final int value;

public MyConfigurableClass(int value) {
    this.value = value;
}

public int value() {
    return value;
}

public static class Factory implements Supplier<MyConfigurableClass> {

    @MCRProperty(name = "Value")
    public String value;

    public MyConfigurableClass get() {
        return new MyConfigurableClass(Integer.parseInt(this.value));
    }

}

}