Plan: String ID

MVP

• pylib und webui können mit string ids umgehen, wenn diese statt integer vom server returned werden.
• server generiert string ids
• im legacy-id Mode gibt der server sowohl die (intern weiterhin verwendeten) integer ids als auch die neuen string ids zurück
• im legacy-id Mode mapped der server integer ids auf die neuen string ids.
• Wenn der legacy-id Mode aus ist, werden die integer ids unterdrückt.
• Neue ID heißt eid.

DoD

• MVP definieren
• Risikoanalyse der Umstellung
• Grobe Planung der nötigen Implementationsphasen (hier dokumentieren und issues erstellen)
• Alles im Story Telling vorstellen.

See also

%String ID

Risiken/Technical Dept

• pytinttests müssen teilweise refactored werden, weil cleanup häufig über "FIND Entity WITH id > 99" stattfindet.
• Die Umstellung bei den Entities selber dürfte kaum Probleme bereiten, insbesondere wenn der legacy-id mode an ist, sollten alte Clients die Umstellung überhaupt nicht bemerken.
• Probleme können bei der Abschaffung der alten Konvention von temporären ids auftauchen: Derzeit werden negative IDs als client ids verwendet. Diese sollten durch cuid ersetzt werden.
• Probleme können bei Reference Properties auftauchen: Alte Clients versuchen die Values als Integers zu parsen und sind gleichzeitig sehr restriktiv was mögliche Childnodes der Properties angeht.
• Weitestgehende Rückwärtskompatibilität zu wahren ist nur dann interessant, wenn dies auch beim versioning eingehalten werden kann.
• Risiken verbergen sich in den folgenden von uns verantworteten code bases: Server, MySQLBackend, WebUI, Pylib, Pyinttests, CaosadvancedTools, Customer Repos mit Erweiterungen in JS und Python, Demoinstanzen.
• Um nicht gezwungen zu sein, zu früh zu viel Code zu ändern, soll die implementation so gestaltet werden, dass vorerst nur pylib und webui umgestellt werden, mit der Fähigkeit sich im legacy-id mode so zu verhalten, als wenn eid einfach eine zusätzliche Eigenschaft von entities wäre.

Implementationsphasen

Alle Phasen und deren nummerierte Unterpunkte sind so designed, dass sie direkt reviewed und gemerged werden können, ohne komplexe Abhängigkeiten.

Phase 1 - Entities bekommen zusätzliche Eigenschaft eid.

1. Server: Entities (EntityInterface.java) bekommen in der internen representation eine weitere Membervariable: eid. Diese wird bei Insert-Transaktionen generiert (512 random bits, in Base36 codierung).
2. MySQL Backend: entities table bekommt weitere Spalte eid BLOB DEFAULT NULL. Diese wird bei retrieveEntity ausgelesen (Tests für retrieveEntity).
3. MySQL Backend, Server: eid wird in schreibende Transaktionen integriert (Unittests für MySQL und Server, noch keine integration tests).
4. Server: eid wird in XML Serialisierung integriert (Auch für Properties und Parents)
5. Server: ReferenceValue bekommen eid Membervariable, sodass Values von Reference Properties auch über die eid identifiziert werden können.
6. Pylib:
   • Entity in Pylib bekommt eid property.
   • Die parents von entities bekommen die eid property und können über Entity.get_parent(eid) gefunden werden.
   • Die properties von entities bekommen die eid property und können über Entity.get_property(eid) gefunden werden.
   • Container bekommen die get_entity(eid) methode. (Unittests)
   • Die Generierung von negativen IDs als temporären ids wird auf die Nutzung von cuids umgestellt. Dies ist im Server bereits möglich.
7. Pyinttests für eid mit insert/update/retrieve/delete - nur testen, dass die eid da ist.
8. WebUI:
   • data-entity-eid attribute analog data-entity-id.
   • getEntityEID methode analog getEntityID.
   • Nutzung von negative IDs als temporären IDs wird auf Nutzung von cuid umgestellt.

Phase 2 - Legacy-id Mode

9. Server:
   • ServerProperty "LEGACY_ID_MODE = TRUE|FALSE" mit default TRUE. Wenn FALSE, werden nur eids ausgegeben und akzeptiert ansonsten ids und eids nebeneinander.
   • Response bekommt legacy-id Eigenschaft, damit Clients verifizieren können, dass der Server sich im legacy-id mode befindet.
10. Pylib:
    • pycaosdb.ini/config module bekommen legacy-id option (default: true).
    • Exception, wenn sich Server und Pylib nicht im selben mode befinden.
11. WebUI:
    • WebUI bekommt build property BUILD_LEGACY_ID.
    • Alert, wenn Server und WebUI sich nicht im selben mode befinden.

Phase 3 - Reference Values werden vom Server als eìd ausgegeben.

10. Pylib/WebUI/Server
    • Pylib sucht im legacy-id mode beim Parsen von Reference Values nach <Legacy-id id="{id}"/> Nodes und gibt diese als Value aus. Pylib akzeptiert weiterhin ids als reference values.
    • WebUI: Der legacy-id mode sorgt beim Compilieren des webcaosdb.xsl scripts dafür, dass ` ausgelesen wird.
    • Server: Im LEGACY_ID mode werden ids und eids ausgegeben und aktzeptiert. Reference Values werden als <Value>{eid}<Legacy-id id="{id}"/></Value> xml-serialisiert.

Damit sollte die Einführung von eids abgeschlossen sein. Pyinttests und WebUI Unittests sollten weiterhin passen. Es folgen die Anpassungen der src/core/js/ Module in der WebUI und bei caosadvancedtools. Außerdem ist eine Duplizierung aller Pyinttests für eid ohne legacy-id mode zu erwägen. Dann kommen die customer repos.

Mit der Einführung von eids sind die Weichen gestellt für eine universale, persistente Identifikation von Entities, die nicht mehr von der Server-Instanz abhängt. Dann sollte in Zukunft erlaubt werden, eids beim Insert vorzugeben (mit entsprechenden Permissions) und außerdem das Namespace System eingeführt werden.

Discussion/Ausblick

• URIs are case-sensitive!
• Handle System PID: e.g. 21.1000/ABCD1234 info:hdl/21.1000/ABCD1234 https://hdl.handle.net/21.1000/ABCD1234
• URN: e.g. urn:isbn:0451450523
• HTTP URIS: e.g. https://caosdb.example.com/entity//
• URI SCHEME: e.g. git, https, mailto, urn, doi rdf. org.caosdb:/ org.linkahead:/<vid|eid>
• Namespaces: "core" - e.g. "core:unit", "core:comment", "core:datatype:integer", "DC" (Dublin Core Metadata Initiative) - e.g. "DC:Title"
• References ohne Namespace beziehen sich auf den Server der die Reference Property hat. References mit Namespace können evtl. vom Server aufgelöst werden. Jeder Server definiert einen eigenen Namespace unter dem Entities ohne explizite angabe des NS angelegt werden. Dieser sollte konfiguriert werden, default is hostname (Achtung docker).