Kapitel 2. Neu in Version 5.0

Das Document-Interface erweitert die Schnittstelle PropertiesProvider. Diese Schnittstelle findet sich noch in einer ganzen Reihe weiterer Klassen und Interfaces der document platform. In allen Fällen dient sie dem gleichen Zweck, nämlich es zu erlauben, integrationsspezifische Zusatzdaten an diese Objekte anzuhängen. PropertiesProvider stellen zu diesem Zweck eine Map zur Verfügung, die Strings als Schlüssel verlangt, jedoch beliebige Objekte als Werte enthalten kann. Diese Funktionalität gab es bereits in jadice 4 in Form der Methoden putUserProperty(key,value)/getUserProperty(key), allerdings haben wir in der neuen Version einige wesentliche Änderungen vorgenommen:

Die Beschreibung der in einem PropertiesProvider geführten Daten als ›integrationsspezifische Zusatzdaten‹ bedeutet allerdings nicht, dass die jadice document platform nicht selbst Zusatzdaten an PropertiesProvider anhängt. Vielmehr nutzen wir diese auch selbst, und zwar in Fällen, in denen eine Anwendung zu speziell ist, als dass eine API-Erweiterung gerechtfertigt wäre. Generell sollten Sie allerdings keine Annahmen über die verwendeten Keys machen. Selbst wenn wir für die Implementierung einer Funktionalität Properties eines PropertiesProvider zur Speicherung benutzen, werden wir immer ein API zur Verfügung stellen, das dieses Implementierungsdetail verbirgt. Darüber hinaus verwenden wir als Keys generell Zeichenfolgen, die mit com.levigo. beginnen. Sie haben also ohne Weiteres die Möglichkeit, Kollisionen zu vermeiden und können leicht erkennen, wo es sich um jadice-eigene Properties handelt. Wir halten es für eine gute Idee, für die Keys eine Namenskonvention ähnlich der von Java-Packages zu verwenden, dies ist aber keineswegs verpflichtend.

Als Inspiration hier ein Beispiel, wie sie Properties verwenden könnten:

// Erzeugen eines Dokumentes
final Document doc = new BasicDocument();

// Laden des Dokumentes...
final File sourceFile = new File("MeineBeispieldatei.txt");

// ...

// Anreichern mit Properties
doc.getProperties().put("org.example.SourceFile", sourceFile);
doc.getProperties().put("org.example.LoadTime", new Date());
doc.getProperties().put("org.example.Weather", Weather.Cloudy);

// ... später
System.out.println("Eigenschaften des Dokuments");
for (final Map.Entry<String, Object> e : doc.getProperties().entrySet())
System.out.println(" " + e.getKey() + " -> " + e.getValue());

Neben dem Document sind derzeit noch folgende weitere Klassen beziehungsweise Interfaces PropertiesProvider:

sowie darüber hinaus noch einige mehr.

Properties sind in der Regel an den Lebenszyklus des Objektes gebunden, an dem sie angefügt wurden. Dies bedeutet einerseits, dass Properties automatisch per garbage collection entsorgt werden, sobald das übergeordnete Objekt entsorgt wird und der Eigenschaftswert nicht noch anderweitig referenziert wird. Andererseits müssen Sie aber beachten, dass Eigenschaftswerte über hard references gehalten werden. Sie sollten also bei ›teuren‹ Objekten gegebenenfalls darauf achten, diese mittels remove(key)auch wieder zu entfernen, da von ihnen belegter Speicher und andere Ressourcen sonst erst freigegeben werden, wenn das übergeordnete Objekt entsorgt wird.

Manche Klassen, darunter die Standardimplementierungen BasicDocument und BasicPage versenden Benachrichtigungen bei Änderungen an ihren Properties. Um diese Benachrichtigungen zu empfangen, können auf dem Document als DocumentListener beziehungsweise auf der Page als PageListener registriert werden. Beide Interfaces erben die Funktionalität der altbekannten Schnittstelle java.beans.PropertyChangeListener. Da sowohl das Document als auch die Page über die Änderungen an den Properties hinaus für Änderungen ihren Objekteigenschaften ensprechende PropertyChangeEvents versenden, werden den Keys der Properties im PropertyChangeEvent folgende String-Konstanten als Kennzeichnungen vorangestellt:

Das folgende Beispiel verdeutlicht den Sachverhalt an Hand eines DocumentListeners.

Die von jadice bereit gestellten Implementierungen von PropertiesProvider benutzen ausschließlich ConcurrentHashMaps zur Bereitstellung der PropertiesProvider-Funktionalität. Sie sind daher Thread-sicher. Dies ist jedoch keine Zusage der PropertiesProvider-Schnittstelle. Im Zweifelsfalle ist es daher besser, die Dokumentation der fraglichen Implementierung hierzu zu konsultieren.