Der Persistenzdienst ist eine Softwareschicht zur Verwaltung persistenter Objekte. Diese Softwareschicht besteht aus einem allgemeinen Anteil und einem klassenspezifischen Anteil und ist aus globalen Klassen und Interfaces der Klassenbibliothek aufgebaut. Der klassenspezifische Anteil wird speziell für jede einzelne persistente Klasse generiert.
Die folgende Abbildung zeigt die für den ABAP-Programmierer relevanten Komponenten des Persistenzdiensts:
Die Klasse CL_persistent ist die Klasse, die als persistente Klasse mit dem Class Builder angelegt wird. Das Anlegen persistenter Klassen mit dem Class Builder ist in der Dokumentation Persistente Klassen anlegen beschrieben. Die Objekte dieser Klasse werden vom Persistenzdienst verwaltet. Solche Objekte nennen wir verwaltete Objekte (ein verwaltetes Objekt muss nicht notwendigerweise persistent sein).
Eine persistente Klasse CL_persistent ist entweder geschützt instanzierbar (CREATE PROTECTED) oder abstrakt.
Der Class Builder generiert die SET- und GET-Methoden für die Attribute dieser Klasse. Der Name einer solchen Klasse beginnt immer mit dem Präfix CL_, während der übrige Teil frei wählbar ist. Die generierte Klasse kann an eigene Bedürfnisse angepasst werden.
Zu jeder persistenten Klasse CL_persistent generiert der Class Builder zwei weitere Klassen, CA_persistent und CB_persistent. Diese Klassen sind der klassenspezifische Anteil des Persistenzdiensts. CB_persistent ist Unterklasse einer allgemeinen abstrakten Oberklasse CL_OS_CA_COMMON aller Klassenakteure.
CA_persistent ist der sogenannte Klassenakteur (oder Agent), über den das verwaltete Objekt der Klasse CL_persistent verwaltet wird und in dem die tatsächlichen Datenbankzugriffe stattfinden. Die entsprechenden Methoden erbt der Klassenakteur von der abstrakten Oberklasse CB_persistent. Der Programmierer kann den Klassenakteur erweitern und die Methoden (insbesondere die Datenbankzugriffe) redefinieren. Die Oberklasse CB_persistent darf nicht geändert werden. Ein Klassenakteur ist ein Freund der verwalteten Klasse. Der Klassenakteur ist ein Singleton: Er hat die Eigenschaft CREATE PRIVATE und beim ersten Zugriff wird genau eine Instanz eines Klassenakteurs angelegt.
Der Klassenakteur implementiert die Interfaces IF_OS_FACTORY, IF_OS_CA_PERSISTENCY und IF_OS_CA_INSTANCE. Die Interfacemethoden können neben den Klassenmethoden verwendet werden. Weiterhin ermöglichen die Interfaces den generischen Zugang über Interfacereferenzvariablen: In einem ABAP-Programm kann es verschiedene Klassenakteure für verschiedene persistente Klassen geben, auf die über Interfacereferenzvariablen des gleichen Typs zugegriffen werden kann. Die Interfaces stellen den allgemeinen Teil des Persistenzdiensts dar.
Die persistente Klasse implementiert das Verwaltungs-Interface IF_OS_STATE, das einen gleichartigen Zugang zu den verwalteten Objekten verschiedener persistenter Klasse ermöglicht.
Die persistente Klasse und der Klassenakteur stehen zu weiteren Interfaces und Klassen in des Persistenzdienstes in Beziehung, die aber hauptsächlich intern genutzt werden. Sie finden die Namen dieser Objekttypen, wenn Sie sich die Definitionen von persistenter Klasse und Klassenakteur im Class Builder ansehen.
Das statische Attribut AGENT ist eine Referenzvariable vom Typ der Klasse CA_persistent selbst. Beim ersten Zugriff auf das Attribut in einem ABAP-Programm erzeugt der statische Konstruktor der Klasse CA_persistent genau eine Instanz dieser Klasse, auf die das Attribut AGENT zeigt. Dieses Objekt ist Teil des Persistenzdiensts und mit seinen Methoden wird das Objekt der persistenten Klasse verwaltet. Es gibt pro Programm nur ein Objekt der Klasse CA_persistent, da mit CREATE OBJECT keine Objekte von außen erzeugt werden können.
Ein Klassenakteur verwaltet eines oder mehrere Objekte der betreffenden persistenten Klasse, die dann unterschiedliche Schlüssel haben müssen.
Die folgenden Methoden werden vom Class Builder beim Anlegen der persistenten Klasse generiert. Sie können in der Klasse CA_persistent redefiniert werden. Andere Methoden sind für die interne Verwendung im Persistenzdienst vorgesehen.
Erzeugt ein neues persistentes Objekt. Die Schnittstelle wird gemäß dem Mapping der persistenten Klasse auf das ABAP Dictionary generiert. Falls das persistente Objekt über sogenannte Business-Keys verwaltet wird, gibt es die entsprechenden Importing-Parameter. Falls das persistente Objekt über sogenannte GUIDs verwaltet wird, wird bei Erzeugung des Objekts eine neue Instanz-GUID generiert. Unabhängig davon durch welche Keys das Objekt verwaltet wird, gibt es für alle persistenten Attribute optionale Importing-Parameter. Der Rückgabewert RESULT ist vom Typ der persistenten Klasse und enthält eine Referenz auf das erzeugte persistente Objekt. Es kann in einem Programm nur ein Objekt zu einem Schlüssel existieren. Das Objekt wird durch die Anweisung COMMIT WORK auf der Datenbank gespeichert. Der Persistenzdienst überprüft bei der Erzeugung aber nicht, ob das Objekt bereits auf der Datenbank vorhanden ist. Es kommt erst zu einem Fehler, wenn versucht wird, ein vorhandenes Objekt zu speichern. Daher empfiehlt es sich, in Zweifelsfällen die Existenz mit der Methode GET_PERSISTENT zu überprüfen.
Lädt ein persistentes Objekt von der Datenbank und erzeugt ein passendes Laufzeitobjekt im ABAP-Programm. Die Schnittstelle wird gemäß dem Mapping der persistenten Klasse auf das ABAP Dictionary generiert. Die Methode ist nur vorhanden, falls das persistente Objekt über sogenannte Business-Keys verwaltet wird, und hat die entsprechenden Importing-Parameter. Der Rückgabewert RESULT ist vom Typ der persistenten Klasse und enthält eine Referenz auf das geladene persistente Objekt. Falls schon ein Objekt des gleichen Schlüssels im Programm vorhanden ist, wird es nicht noch einmal geladen, sondern es wird die Referenz auf das bereits geladene Objekt zurückgegeben. Änderungen an den Attributen des Laufzeitobjekts werden durch die Anweisung COMMIT WORK auf der Datenbank festgeschreiben.
Löscht ein persistentes Objekt. Um das persistente Objekt auch auf der Datenbank zu löschen, muß die Anweisung COMMIT WORK ausgeführt werden. Die Schnittstelle wird gemäß dem Mapping der persistenten Klasse auf das ABAP Dictionary generiert. Die Methode ist nur vorhanden, falls das persistente Objekt über sogenannte Business-Keys verwaltet wird, und hat die entsprechenden Importing-Parameter.
Erzeugt ein transientes Objekt der persistenten Klasse. Die Schnittstelle der Methode ist die gleiche wie die der Methode CREATE_PERSISTENT. Ein mit CREATE_TRANSIENT erzeugtes Objekt unterliegt zwar der Verwaltung des Persistenzdiensts, hat aber keinen Anschluß an die Datenbank. Es kann aber auch mit CREATE_TRANSIENT nur genau ein Objekt mit dem gleichen Schlüssel im Programm erzeugt werden.
Besorgt die Referenz auf ein transientes Objekt der persistenten Klasse. Die Schnittstelle der Methode ist die gleiche wie die der Methode GET_PERSISTENT. Das Objekt muß zuvor mit CREATE_TRANSIENT angelegt worden sein. Es wird nicht auf der Datenbank nach einem entsprechenden persistenten Objekt gesucht.
Falls die persistente Klasse nicht über Business-Keys verwaltet wird, kann statt der Klassenmethode CREATE_PERSISTENT diese Interfacemethode verwendet werden, um ein persistentes Objekt der Klasse CL_persistent zu erzeugen. Der Rückgabewert RESULT ist vom Typ der persistenten Klasse und enthält eine Referenz auf das erzeugte persistente Objekt. Bei Erzeugung des Objekts wird eine neue Instanz-GUID generiert.
Falls die persistente Klasse über Business-Keys verwaltet wird, kann statt der Klassenmethode CREATE_PERSISTENT diese Interfacemethode verwendet werden, um ein persistentes Objekt der Klasse CL_persistent zu erzeugen. Der Schlüssel wird dabei als Struktur, die die Schlüsselfelder als Komponenten hat, an den generischen Parameter I_KEY vom Typ ANY übergeben. Der Rückgabewert RESULT ist vom allgemeinen Typ REF TO OBJECT und enthält eine Referenz auf das erzeugte persistente Objekt. Falls das persistente Objekt über sogenannte GUIDs verwaltet wird, wird bei Erzeugung des Objekts eine neue Instanz-GUID generiert.
Veranlasst das Laden der aktuellen Attribute eines persistenten Objekts von der Datenbank in das ABAP-Programm. Hierfür wird die Referenz auf das Objekt dem Eingabeparameter I_OBJECT vom Typ IF_OS_STATE übergeben. Die aktuellen Attribute werden beim nächsten Zugriff auf ein Attribut von der Datenbank geholt (bedarfsgetriebenes Laden). Der Verwaltungszustand des Objekts muss entweder OSCON_OSTATUS_LOADED oder OSCON_OSTATUS_NOT_LOADED sein. Direkt nach Ausführung der Methode und vor einem Attributzugriff ist der Verwaltungszustand OSCON_OSTATUS_NOT_LOADED.
Löscht ein persistentes Objekt. Hierfür wird die Referenz auf das Objekt dem Eingabeparameter I_OBJECT vom Typ IF_OS_STATE übergeben. Um das persistente Objekt auch auf der Datenbank zu löschen, muß die Anweisung COMMIT WORK ausgeführt werden.
Falls die persistente Klasse nicht über Business-Keys verwaltet wird, kann statt der Klassenmethode CREATE_TRANSIENT diese Interfacemethode verwendet werden, um ein transientes Objekt der Klasse CL_persistent zu erzeugen. Der Rückgabewert RESULT ist vom Typ der persistenten Klasse und enthält eine Referenz auf das erzeugte transiente Objekt.
Falls die persistente Klasse über Business-Keys verwaltet wird, kann statt der Klassenmethode CREATE_TRANSIENT diese Interfacemethode verwendet werden, um ein transientes Objekt der Klasse CL_persistent zu erzeugen Der Schlüssel wird dabei als Struktur, die die Schlüsselfelder als Komponenten hat, an den generischen Parameter I_KEY vom Typ ANY übergeben. Der Rückgabewert RESULT ist vom allgemeinen Typ REF TO OBJECT und enthält eine Referenz auf das erzeugte transiente Objekt.
Löst ein durch den Klassenakteur verwaltetes Objekt vollständig aus der Verwaltung des Persistenzdiensts. Hierfür wird die Referenz auf das Objekt dem Eingabeparameter I_OBJECT vom Typ IF_OS_STATE übergeben. Der Verwaltungszustand des Objekts muss entweder OSCON_OSTATUS_LOADED oder OSCON_OSTATUS_NOT_LOADED sein.
Falls die persistente Klasse nicht über Business-Keys verwaltet wird, kann statt der Klassenmethode GET_PERSISTENT diese Interfacemethode verwendet werden, um ein persistentes Objekt von der Datenbank zu holen und ein passendes Laufzeitobjekt im ABAP-Programm zu erzeugen. Die Kennung des Objekts wird hierfür, an den Parameter I_OID vom Typ OS_GUID übergeben. Der Rückgabewert RESULT ist vom allgemeinen Typ REF TO OBJECT und enthält eine Referenz auf das persistente Objekt.
Falls die persistente Klasse über Business-Keys verwaltet wird, kann statt der Klassenmethode GET_PERSISTENT diese Interfacemethode verwendet werden, um ein persistentes Objekt von der Datenbank zu holen und ein passendes Laufzeitobjekt im ABAP-Programm zu erzeugen. Der Schlüssel wird dabei als Struktur, die die Schlüsselfelder als Komponenten hat, an den generischen Parameter I_KEY vom Typ ANY übergeben. Der Rückgabewert RESULT ist vom allgemeinen Typ REF TO OBJECT und enthält eine Referenz auf das persistente Objekt.
Falls die persistente Klasse nicht über Business-Keys verwaltet wird, kann diese Interfacemethode verwendet werden, um mehr als ein persistentes Objekt auf einmal von der Datenbank zu holen und passende Laufzeitobjekte im ABAP-Programm zu erzeugen. Die Kennung der Objekte werden dabei in einer internen Tabelle an den Parameter I_OID_TAB vom Typ INDEX TABLE übergeben. Der Rückgabewert RESULT ist vom allgemeinen Typ OSREFTAB und enthält eine Tabelle von Referenzen auf die geladenen persistenten Objekte. Für jeden Eintrag in der Tabelle der Kennungen gibt es in der Ergebnistabelle an der gleichen Position einen entsprechenden Eintrag, der entweder eine Objektreferenz auf das geladene Objekt enthält oder initial ist, wenn zur entsprechenden Kennung kein Objekt gefunden wurde. Es gibt keine entsprechende Methode im Klassenakteur.
Um diese Methode verwenden zu können, muss im Mapping Assistant das Ankreuzfeld Mehrfachzugriff im Bild Generatoreinstellungen markiert sein.
Falls die persistente Klasse über Business-Keys verwaltet wird, kann diese Interfacemethode verwendet werden, um mehr als ein persistentes Objekt auf einmal von der Datenbank zu holen und passende Laufzeitobjekte im ABAP-Programm zu erzeugen. Die Schlüssel der Objekte werden dabei in einer internen Tabelle, deren Zeilentyp die Schlüsselfelder als Komponenten hat, an den generischen Parameter I_KEY_TAB vom Typ INDEX TABLE übergeben. Der Rückgabewert RESULT ist vom allgemeinen Typ OSREFTAB und enthält eine Tabelle von Referenzen auf die geladenen persistenten Objekte. Für jeden Eintrag in der Schlüsseltabelle gibt in der Ergebnistabelle an der gleichen Position einen entsprechenden Eintrag, der entweder eine Objektreferenz auf das geladene Objekt enthält oder initial ist, wenn zum entsprechenden Schlüssel kein Objekt gefunden wurde. Es gibt keine entsprechende Methode im Klassenakteur.
Um diese Methode verwenden zu können, muss im Mapping Assistant das Ankreuzfeld Mehrfachzugriff im Bild Generatoreinstellungen markiert sein.
Diese Interfacemethode kann verwendet werden, um mehr als ein persistentes Objekt auf einmal von der Datenbank zu holen und passende Laufzeitobjekte im ABAP-Programm zu erzeugen. Dabei bestimmt ein logischer Ausdruck, der Attribute der persistenten Klasse mit frei wählbaren Parametern oder Werten vergleicht, welche persistenten Objekte geladen werden. Der logische Ausdruck wird durch eine Instanz einer Klasse, die das Interface IF_OS_QUERY implementiert, realisiert. Eine solche Instanz stellt ein Query-Objekt oder kurz eine Query dar und kann mit der Methode CREATE_QUERY des Interfaces IF_OS_QUERY_MANAGER erzeugt werden (siehe Abschnitt Query). Eine Referenz auf die Query wird an den Parameter I_QUERY übergeben. Die Vergleichswerte für die Query werden in einer internen Tabelle an den Parameter I_PARAMETER_TAB übergeben. Falls die Query höchstens drei Vergleichswerte mit elementarem Typ benötigt, könne diese auch einzeln an die Parameter I_PAR1, I_PAR2 und I_PAR3 übergeben werden. Mit Hilfe der Parameter I_SUBCLASSES und I_UPTO kann bestimmt werden, ob auch Instanzen von Unterklassen der persistenten Klasse geladen werden bzw. wie viele Instanzen höchstens geladen werden. Der Rückgabewert RESULT ist vom allgemeinen Typ OSREFTAB und enthält eine Tabelle von Referenzen auf die geladenen persistenten Objekte. Eine Sortierung der Objektreferenzen kann auch über die Query bestimmt werden. Es gibt keine entsprechende Methode im Klassenakteur.
Um diese Methode verwenden zu können, muss im Mapping Assistant das Ankreuzfeld Mehrfachzugriff im Bild Generatoreinstellungen markiert sein.
Ermittelt den Verwaltungszustand eines verwalteten Objekts. Hierfür wird dem Eingabeparameter vom allgemeinen Typ REF TO OBJECT eine Referenz auf das verwaltete Objekt übergeben. Der Rückgabewert RESULT ist vom Typ OS_STATUS und kann die Werte 0, 1, 2, 3, 4 und 10 haben, was den Konstanten OSTATUS_... der Typgruppe OSCON entspricht.
Ermittelt alle vom Klassenakteur verwalteten Objekte im Verwaltungszustand OSCON_OSTATUS_NOT_LOADED (0). Der Rückgabewert ist eine interne Tabelle vom allgemeinen Zeilentyp REF TO OBJECT.
Ermittelt alle vom Klassenakteur verwalteten Objekte im Verwaltungszustand OSCON_OSTATUS_NEW (1). Der Rückgabewert ist eine interne Tabelle vom allgemeinen Zeilentyp REF TO OBJECT.
Ermittelt alle vom Klassenakteur verwalteten Objekte im Verwaltungszustand OSCON_OSTATUS_LOADED (2). Der Rückgabewert ist eine interne Tabelle vom allgemeinen Zeilentyp REF TO OBJECT.
Ermittelt alle vom Klassenakteur verwalteten Objekte im Verwaltungszustand OSCON_OSTATUS_CHANGED (3). Der Rückgabewert ist eine interne Tabelle vom allgemeinen Zeilentyp REF TO OBJECT.
Ermittelt alle vom Klassenakteur verwalteten Objekte im Verwaltungszustand OSCON_OSTATUS_DELETED (4). Der Rückgabewert ist eine interne Tabelle vom allgemeinen Zeilentyp REF TO OBJECT.
Ermittelt alle vom Klassenakteur verwalteten Objekte im Verwaltungszustand OSCON_OSTATUS_TRANSIENT (10). Der Rückgabewert ist eine interne Tabelle vom allgemeinen Zeilentyp REF TO OBJECT.
Das Interface IF_OS_STATE definiert eine Schnittstelle einer durch Object Services verwaltbaren Klasse, die es ermöglicht, Objekte dieser Klasse zu beobachten und zu verwalten.
Wird beim Erzeugen eines persistenten oder transienten Objektes und beim Laden eines persistenten Objektes nach dem Setzen der persistenten Attribute aufgerufen. Hier können z.B. transiente Attribute initialisiert werden, Check-Agents oder Ereignis-Behandler registriert werden.
Wird beim Löschen eines persistenten Objektes, beim Erzwingen des Nachladens eines persistenten Objektes und beim Starten einer Folge-Transaktion nach dem Zurücksetzen der persistenten Attribute für persistente Objekte aufgerufen. Hier können z.B. transiente Attribute zurückgesetzt werden oder Ereignis-Behandler deregistriert werden. Wird auch beim Zurücksetzen durch den UNDO-Dienst aufgerufen.
Wird beim Auftreten einer Ausnahme in den GET- und SET-Methoden aufgerufen und löst die Ausnahme, die als Parameter übergeben wird, aus. Hier kann eine Behandlung der aufgetretenen Ausnahmen stattfinden. Im Allgemeinen sollte die Behandlung der Ausnahmen aber vom Verwender der GET- und SET-Methoden durchgeführt werden.
Diese Methoden dienen der internen Verwendung und dürfen nicht verändert werden.