Kontakt

Ansicht
Dokumentation

ABENCDS_ANNOTATIONS_ANALYSIS - CDS ANNOTATIONS ANALYSIS

ABENCDS_ANNOTATIONS_ANALYSIS - CDS ANNOTATIONS ANALYSIS

RFUMSV00 - Advance Return for Tax on Sales/Purchases   BAL Application Log Documentation  
Diese Dokumentation steht unter dem Copyright der SAP AG.
SAP E-Book

- Auswertung von Annotationen

Bei der Aktivierung eines in einem CDS-Quelltext definierten Objekts werden die dort in CDS-Annotationssyntax definierten Annotationen in internen Systemtabellen abgelegt, auf die für eine Auswertung zugegriffen werden kann. Dies geschieht unabhängig von Bezeichner und Wert für jede syntaktisch korrekte Annotation.

Systemklasse CL_DD_DDL_ANNOTATION_SERVICE

Für die Auswertung der Annotationen von CDS-Entitäten steht folgende dokumentierte Systemklasse zur Verfügung:

CL_DD_DDL_ANNOTATION_SERVICE

Die Methoden dieser Klasse geben die Annotationen von CDS-Entitäten zurück. wobei standardmäßig zuerst die Annotationen aus Metadatenerweiterungen und dann die Annotationen der CDS-Entität selbst ausgewertet werden. Bei letzteren können direkte, abgeleitete und geerbte Annotationen unterschieden werden, wobei bei den geerbten Annotationen wiederum zuerst die eventuellen Metadatenerweiterungen berücksichtigt werden. Insbesondere wird bei einer Annotation, für die kein Werte angegeben ist, ein initialer Annotationswert zurück gegeben und nicht der eventuell in der Annotationsdefinition definierte Standardwert.

Hinweise

  • Auch die Methode GET_ANNOTATIONS der Klasse CL_DD_DDL_ANALYZE gibt die Annotationen von CDS-Entitäten zurück. Dabei ist aber zu beachten, dass diese nur den zugehörigen DDL-Quelltext auswertet. Nicht berücksichtigt werden Annotationen aus Metadatenerweiterungen, abgeleitete und geerbte Annotationen oder die Übersetzungen von Annotationen für übersetzbare Texte.
  • Bei der Auswertung von Annotationen mit der Systemklasse CL_DD_DDL_ANNOTATION_SERVICE werden die Annotationen der CDS-Entitäten genauso berücksichtigt, wie sie in deren DDL-Quelltext in CDS-Annotationssyntax angegeben sind. Die zugehörigen Annotationsdefinitionen spielen für CL_DD_DDL_ANNOTATION_SERVICE keine Rolle. Die Gültigkeit einer Annotation muss durch das zuständige Framework überprüft werden.
  • Die ADT unterstützen die Angabe gültiger Annotationen, d.h. Annotationen mit Annotationsdefinition, durch Quelltexteinfärbung und Code Completion.
  • Die Annotationen Semantics.amount.currencyCode und Semantics.quantity.unitofMeasure können nur dann aus DDIC-Datenbanktabellen abgeleitet werden, wenn der Name des referenzierten Währungsschlüssel- oder Einheitenschlüsselfelds in einer CDS-View-Entität nicht geändert wird. Wenn eine CDS-View, die aus einer Datenbanktabelle selektiert, einen Aliasnamen für ein Währungsschlüssel- oder Einheitenschlüsselfeld verwendet, kann die Annotation nicht durch das API CL_DD_DDL_ANNOTATION_SERVICE ausgewertet werden.

Auswertung von Annotationen

Metadatenerweiterungen

Metadatenerweiterungen fügen einer CDS-Entität weitere Annotationen hinzu oder übersteuern vorhandene Annotationen. Derzeit können Metadatenerweiterungen nur für CDS-Views und abstrakte CDS-Entitäten definiert werden. Metadatenerweiterungen können nur Annotationen hinzugefügt werden, die bei der Aktivierung der CDS-Entität ignoriert werden.

Die Methoden der Klasse CL_DD_DDL_ANNOTATION_SERVICE außer GET_DIRECT_ANNOS_... berücksichtigen bei der Auswertung der Annotationen einer CDS-Entität standardmäßig die im aktuellen AS ABAP vorhandenen Metadatenerweiterungen. Zu einer Entität kann es mehrere Metadatenerweiterungen geben. Zu einer Entität kann es mehrere Metadatenerweiterungen geben, die sich durch die Zuordnung zu verschiedenen Schichten wie Branche, Partner oder Kunde und durch die Verknüpfung mit CDS-Varianten unterscheiden. Die Methoden der Klasse CL_DD_DDL_ANNOTATION_SERVICE sammeln alle zur CDS-Entität gehörigen Annotationen in folgender Reihenfolge auf:

  • Annotationen aus Metadatenerweiterungen
  • direkte Annotationen aus der Datendefinition
  • indirekte Annotationen (abgeleitete und geerbte Annotationen)

Dabei wird jede Annotation genau einmal für ihren Geltungsbereich zurück gegeben. Bei gleichnamigen Annotationen richtet sich die Priorität zuerst nach der expliziten Angabe einer CDS-Variante beim Methodenaufruf und danach nach den Schichten der beteiligten Metadatenerweiterungen. Die Auswertung erfolgt in folgenden Stufen:

  • Zuerst werden die Metadatenerweiterungen der angegebenen Variante ausgewertet, wobei eine Annotation einer höheren Schicht die einer niedrigeren Schicht übersteuert.
  • Dann werden die Metadatenerweiterungen ausgewertet, die mit keiner Variante verknüpft sind, wobei wieder höhere Schichten niedrigere Schicht übersteuern.
  • Schließlich werden die direkten und indirekten Annotationen der CDS-Entität selbst ausgewertet. Bei der Auswertung der von anderen CDS-Entitäten geerbten Annotationen werden wieder zuerst deren eventuellen Metadatenerweiterungen berücksichtigt.

Annotationen, die in einer früheren Stufe der Auswertung gefunden werden haben immer die höhere Priorität. Eine Annotation aus einer späteren Stufe wird nur zurück gegeben, wenn sie nicht bereits in einer früheren Stufe gefunden wurde. In den Ergebnissen der Klasse CL_DD_DDL_ANNOTATION_SERVICE ist erkennbar, wo eine Annotation angegeben wurde.

Hinweise

  • Annotationen aus Metadatenerweiterungen sind nicht in den gleichen Systemtabellen wie die Annotationen aus dem DDL-Quelltext einer CDS-Entität abgelegt. Sie werden nur durch Verwendung der Klasse CL_DD_DDL_ANNOTATION_SERVICE zugänglich gemacht. Andere Klassen berücksichtigen keine Metadatenerweiterungen.
  • Das Programm ABAP_DOCU_MDE_ANNOS zeigt alle Annotationen, die in Metadatenerweiterungen angegeben werden können.

Direkte, geerbte und abgeleitete Annotationen

Bei der Auswertung von Annotationen einer CDS-Entität mit Methoden der Klasse CL_DD_DDL_ANNOTATION_SERVICE, die nicht von Metadatenerweiterungen übersteuert werden, können folgende Arten von Annotationen unterschieden werden:

  • direkte Annotationen
Diese Annotationen sind in Annotationssyntax direkt im DDL-Quelltext der CDS-Entität angegeben, die aktuell ausgewertet wird. Die Methoden GET_DIRECT_ANNOS_ der Klasse CL_DD_DDL_ANNOTATION_SERVICE lesen nur diese Annotationen aus.
  • indirekte Annotationen
Neben den direkten Annotationen geben die Methoden der Klasse CL_DD_DDL_ANNOTATION_SERVICE außer GET_DIRECT_ANNOS_ auch Annotationen zurück, die nicht im DDL-Quelltext angegeben sind:
  • geerbte Annotationen

Diese Annotationen werden falls nicht explizit im DDL-Quelltext der CDS-Entität angegeben von den in der CDS-Entität verwendeten Dictionary-Objekten nach Regeln, die in der Klassendokumentation von CL_DD_DDL_ANNOTATION_SERVICE beschriebenen sind, übernommen. Beim Zugriff auf andere CDS-Entitäten, werden deren in Metadatenerweiterungen angegebenen, direkten und abgeleiteten Annotationen geerbt. Andere Dictionary-Objekte wie DDIC-Datenbanktabellen, DDIC-Views usw. haben keine direkten Annotationen. Es werden aber deren von zugeordneten Datenelementen abgeleiteten Annotationen geerbt. Mit der View-Annotation Metadata.ignorePropagatedAnnotations kann gesteuert werden, ob die Klasse CL_DD_DDL_ANNOTATION_SERVICE geerbte Annotationen berücksichtigt oder nicht.
  • abgeleitete Annotationen

Diese Annotationen werden falls nicht explizit im DDL-Quelltext der CDS-Entität angegeben oder geerbt falls möglich von zugeordneten Datenelementen des ABAP Dictionary abgeleitet. Es handelt sich um die Element- und Parameterannotationen @EndUserText.Label, @EndUserText.QuickInfo und @EndUserText.Heading, die nach Regeln, die in der Klassendokumentation von CL_DD_DDL_ANNOTATION_SERVICE beschrieben sind, aus den Feldbezeichnern zugeordneter Datenelemente mit Texten versorgt werden. Die Annotation @EndUserText.Heading gibt es derzeit nur als implizite Annotation für diesen Zweck. Eine Angabe als direkte Annotation im DDL-Quelltext einer Datendefinition wird bei der Auswertung nicht als sprachabhängiger Text erkannt. Im DDLX-Quelltext einer Metadatenerweiterung ist @EndUserText.Heading ebenfalls nicht erlaubt.

Hinweise

  • Eine Vererbung findet insbesondere auch für die Elementannotationen von CDS-Assoziationen statt, die in der SELECT-Liste einer CDS-Entität über einen Pfadausdruck path_expr exponiert werden. Die Veröffentlichung einer CDS-Assoziation, die in einer anderen CDS-View angegeben ist, erbt die Elementannotationen vorhergehender Veröffentlichungen.
  • Von Datenelementen abgeleitete Annotationen hängen von der Zuordnung von Datenelementen an Elemente der aktuellen CDS-Entität ab. Diese Zuordnung erfolgt in den internen Metadaten einer CDS-Entität und ist unabhängig von der Vererbung.
  • Die hier beschriebenen Annotationsarten gelten speziell für Auswertungen mit der Klasse CL_DD_DDL_ANNOTATION_SERVICE. Andere APIs könnten die zugrunde liegenden Metadaten auch anders auswerten.

Beispiel

Die folgenden drei DDL-Quelltexte definieren drei Views, von denen die ersten beiden auf die dritte View zugreifen. Die ersten beiden Views unterscheiden sich nur durch die Angabe der Annotation @Metadata.ignorePropagatedAnnotations:true. In jeder View gibt es jeweils ein Element mit einer direkten Elementannotationen @EndUserText.label.

Das Programm DEMO_CDS_DERIVED_INHERIT_ANNOS liest mit einer Methode der Klasse CL_DD_DDL_ANNOTATION_SERVICE die Elementannotationen der ersten beiden CDS-View aus:

  • Fast alle Elementannotationen dieses Beispiels sind aus Datenelementen abgeleitete Annotationen. Dies gilt insbesondere für die Annotation @EndUserText.heading, die im Quelltext nicht angegeben werden kann. Die Texte des Elements destination stammen vom Datenelement demo_destination, das die automatische Zuordnung zu S_TO_CITY in einem CAST-Ausdruck übersteuert.
  • Ohne die Annotation @Metadata.ignorePropagatedAnnotations:true werden die abgeleiteten Annotationen von den verwendeten Objekten geerbt. Die Spalte SOURCEOBJECT enthält die Namen der Objekte.

  • Mit der Annotation @Metadata.ignorePropagatedAnnotations:true findet die Ableitung in der aktuellen View statt und die Spalte SOURCEOBJECT zeigt nur deren Namen.

  • Der Wert der Annotation @EndUserText.label des Elements id stammt von der in den ersten beiden Views direkt angegebenen Annotation.
  • Der Wert der Annotation @EndUserText.label des Elements flight stammt in der ersten View von der Annotation, die sie von der zweiten View erbt. In der zweiten View wird diese Vererbung durch die Annotation @Metadata.ignorePropagatedAnnotations:true unterdrückt.

Bei der in der Ausgabe sichtbaren Annotation ABAPCATALOG.INTERNAL.ISMANDT handelt es sich um eine interne Annotation, die das Mandantenfeld einer mandantenabhängigen CDS-Entität kennzeichnet.

Unterannotationen

Unterannotationen werden in der Annotationssyntax entweder als kommaseparierte Listen in geschweiften Klammern oder über strukturierte Namen angegeben. Die interne Ablage dieser Metadaten ist unabhängig von der Art der Angabe und die Methoden der Klasse CL_DD_DDL_ANNOTATION_SERVICE geben Unterannotationen immer als einzelne Annotation mit strukturiertem Namen zurück.

Beispiel

Die folgende Angabe von Unterannotationen

@DemoAnno: {subAnno1: true,
            subAnno2: { subAnno1: 1,
                        subAnno2: { subAnno1: 1,
                                    subAnno2: 2 } } }

ist gleichwertig zu dieser Angabe:

@DemoAnno.subAnno1: true
@DemoAnno.subAnno2.subAnno1: 1
@DemoAnno.subAnno2.subAnno2.subAnno1: 1
@DemoAnno.subAnno2.subAnno2.subAnno2: 2

Eine Auswertung beider Angaben mit der Methode GET_DIRECT_ANNOS_4_ENTITY der Klasse CL_DD_DDL_ANNOTATION_SERVICE ergibt:

ANNONAME VALUE
DEMOANNO.SUBANNO1 true
DEMOANNO.SUBANNO2.SUBANNO1 1
DEMOANNO.SUBANNO2.SUBANNO2.SUBANNO1 1
DEMOANNO.SUBANNO2.SUBANNO2.SUBANNO2 2

Annotationsarrays

Annotationsarrays werden in der Annotationssyntax durch kommaseparierte Listen in eckigen Klammern hinter der Angabe einer Annotation gebildet. In der internen Ablage dieser Metadaten werden die Elemente von Annotationsarrays als einzelne Annotationen aufgefasst. Sie werden dabei unter dem Namen des Arrays abgelegt, an den ein von $-Zeichen umgebener laufender Index $1$, $2$, ... angehängt ist. Die Methoden der Klasse CL_DD_DDL_ANNOTATION_SERVICE geben einen Array entsprechend als einzelne Annotationen zurück.

Hinweis

Die Annotationssyntax in DDL-Quelltexten für CDS-Entitäten ist für Annotationsarrays laxer als die Syntax von DEFINE ANNOTATION für Annotationsdefinitionen.

  • In der Annotationssyntax müssen Arrayelemente nicht gleichartig sein.
  • In der Annotationssyntax dürfen Arrays direkt geschachtelt werden

In den internen Metadaten und damit in den Ergebnissen der Methoden der Klasse CL_DD_DDL_ANNOTATION_SERVICE werden nicht gleichartige Arrayelemente genauso zurück gegeben wie in der Annotationssyntax angegeben. Direkt geschachtelte Arrays werden nicht gespeichert, bei der Indizierung der Elemente aber mitgezählt.

Beispiel

Die folgende Angabe eines Annotationsarrays ist zwar gültige Annotationssyntax, es kann aber keine Annotationsdefinition für sie geben.

@DemoAnno: [ true,
             [1,2,3],
             { subAnno1:1, subAnno2:2} ]

Zum einen sind die Elemente des Arrays nicht gleichartig, zum anderen ist das zweite Element ein direkt geschachtelter Array. Die Methode GET_DIRECT_ANNOS_4_ENTITY der Klasse CL_DD_DDL_ANNOTATION_SERVICE ergibt:

ANNONAME VALUE
DEMOANNO$1$ true
DEMOANNO$3$.SUBANNO1 1
DEMOANNO$3$.SUBANNO2 2

Beachten Sie, dass der geschachtelte Array nicht zurück gegeben aber gezählt wird.

Null-Werte

Für jede Elementannotation einer CDS-Entität, die nicht Teil eines Annotationsarrays ist, kann der spezielle Wert null (ohne Hochkommata) angegeben werden. An anderen Stellen führt der Wert null zu einem Syntaxfehler. Der Wert null bewirkt, dass die Annotation standardmäßig nicht von den Methoden der Klasse CL_DD_DDL_ANNOTATION_SERVICE zurückgegeben wird. Die Standardeinstellung kann mit dem Eingabeparameter NULL_VALUES der Methoden geändert werden.

Hinweise

  • Null-Werte sind im Wesentlichen dafür vorgesehen, unerwünschte abgeleitete und geerbte Annotationen in der Auswertung der Annotationen einer CDS-Entität auszublenden.
  • Ein Null-Wert wird wie jeder Wert vererbt. Eine direkte Annotation einer CDS-Entität überschreibt die von verwendeten Dictionary-Objekten übernommenen Annotationen. Damit können beliebige Werte mit dem Null-Wert überschrieben werden, ein Null-Wert kann aber auch selbst überschrieben werden.
  • Die Auswertung filtert genau die Annotationen aus, für deren Bezeichner ein Null-Wert angegeben ist.
  • Eine Angabe @annotation.annotation1:null wirkt genau auf den Bezeichner @annotation.annotation1 aber nicht auf beispielsweise @annotation.annotation1.annotation2.

  • Wenn der Null-Wert für ein Annotationsarray angegeben ist, wirkt er auf das gesamte Array. Eine Angabe @annot:null für ein geerbtes Annotationsarray @annot:[ ..., ..., ...] wirkt auf alle Elemente des Arrays.

  • Die Auswertung filtert Annotationen mit Null-Werten völlig unabhängig davon, ob es sich um vordefinierte SAP-Annotationen handelt oder nicht.

Beispiel

Die folgenden zwei DDL-Quelltexte definieren zwei Views, von denen die zweite auf die erste View zugreift. In der ersten View sind für jedes Element der SELECT-Liste @EndUserText-Annotationen mit literalen Werten angegeben. In der zweiten View werden diese teilweise mit dem Wert null überschrieben. Für die spezielle Annotation @EndUserText.heading geschieht dies schon in der ersten View.

Das Programm DEMO_CDS_NULL_ANNOS liest mit einer Methode der Klasse CL_DD_DDL_ANNOTATION_SERVICE die Elementannotationen der beiden CDS-View aus. Annotationen, die in der zweiten View den Wert null haben, werden für diese nicht zurückgegeben.

  • Die Annotation @EndUserText: null vor dem Element id hat keine Wirkung. Sie filtert nicht alle @EndUserText-Annotationen dieses Elements aus. Sie würde eine Elementannotation @EndUserText: ... der ersten View überschreiben, die dort aber nicht angegeben ist, da es sich um keine gültige ABAP-Annotation handelt.
  • Die Annotationen @EndUserText.label: null und @EndUserText.quickInfo: null vor den Elementen carrier bzw. flight überschreiben die Werte dieser Annotationen, die von der ersten View geerbt wurden. Sie werden von der Auswertung nicht zurückgegeben.
  • Die abgeleitete Annotation @EndUserText.Heading wird für jedes Element mit dem Wert null versehen. Für das Element id geschieht dies schon in der ersten View. Für diese gibt die Auswertung die Annotation für die anderen beiden Elemente zurück. In der zweiten View wird der Wert null auch für diese gesetzt und die Auswertung gibt die Annotation @EndUserText.Heading für keines der Elemente der CDS-View zurück.

Annotationen für übersetzbare Texte

Die Annotationswerte von Annotationen für die dies in deren Annotationsdefinition mit der Annotation @LanguageDependency festgelegt ist dienen der Definition übersetzbarer semantischer Texte für ein CDS-Objekt.

Hinweise

  • Auch in Metadatenerweiterungen werden die Annotationen für übersetzbare Texte speziell behandelt und in speziellen Tabellen angelegt, die an die Übersetzung angeschlossen sind.

Beispiel

Der folgende DDL-Quelltext zur Definition einer CDS-View enthält speziell die ABAP-Annotationen, die mit EndUserText eingeleitet werden.

Das Programm DEMO_CDS_DDL_TEXTS greift mit Methoden der Klasse CL_DD_DDL_ANNOTATION_SERVICE sprachabhängig auf die zugehörigen Texte zu. Die Originalsprache der View ist Englisch und die englischen Texte müssen in jedem System vorhanden sein. Wenn es eine deutsche Übersetzung gibt, wird diese ebenfalls ausgelesen und angezeigt.

Durchführung der Auswertung

Die Auswertung von Annotationen unterscheidet sich für die ABAP-Annotationen und die Framework-spezifischen Annotationen:

  • ABAP-Annotationen
Die ABAP-Annotationen legen technische und semantische Eigenschaften eines CDS-Objekts fest. Sie werden in der Regel für jedes CDS-Objekt bei der Aktivierung und vom ABAP-Laufzeit-Framework ausgewertet. ABAP-Annotationen können das Verhalten von-Anweisungen beeinflussen, die auf eine CDS-Entität zugreifen. Ein wichtiges Beispiel ist die Festlegung der Mandantenabhängigkeit einer CDS-Entität über die zugehörige ABAP-Annotation.
  • Framework-spezifische Annotationen
Die Framework-spezifischen Annotationen haben in der Regel keine Bedeutung für die Aktivierung und ABAP-Laufzeit-Framework, sondern müssen von den Frameworks der entsprechenden Software-Komponenten über eine geeignete API ausgewertet werden. Die Bezeichner und Werte der Framework-spezifischen Annotationen müssen dafür den Regeln des entsprechenden Frameworks folgen. Für die Komponenten der SAP können diese den Tabellen des Dokuments Framework-spezifische Annotationen entnommen werden.

Annotationen, die weder vom ABAP-Laufzeit-Framework noch von Frameworks anderer Software-Komponenten ausgewertet werden, haben in der Regel keine Wirkung.






ABAP Short Reference   ROGBILLS - Synchronize billing plans  
Diese Dokumentation steht unter dem Copyright der SAP AG.

Length: 35516 Date: 20240523 Time: 175536     sap01-206 ( 452 ms )