Benutzerdefinierte Berechnungsfunktionen entwickeln

26 Benutzerdefinierte Berechnungsfunktionen entwickeln

Um die für Essbase-Block Storage-Cubes verfügbaren Berechnungsfunktionen zu verbessern, können Sie mit Java eigene benutzerdefinierte Funktionen (CDFs) entwickeln. Nachdem Sie die Funktionen geschrieben haben, installieren Sie die Java-Klasse, und registrieren Sie die Funktionen entweder global beim Essbase-Server oder lokal in einer Anwendung.

Sie können Ihre benutzerdefinierten Funktionen in Essbase-Berechnungsskripten verwenden.

Essbase stellt keine Tools zum Erstellen von Java-Klassen und -Archiven bereit. Sie benötigen eine unterstützte Version von JDK.

Beispiele für benutzerdefinierte Funktionen finden Sie unter Java-Codebeispiele.

Benutzerdefinierte Funktionen sind nur für Block Storage Cubes verfügbar (nicht relevant für Aggregate Storage Cubes).

Um eine benutzerdefinierte Funktion zu erstellen, verwenden Sie den folgenden Workflow.

Prüfen Sie die Anforderungen für benutzerdefinierte Funktionen: Anforderungen für die Gültigkeit benutzerdefinierter Funktionen
Erstellen Sie eine öffentliche Java-Klasse, die mindestens eine öffentliche, statische Methode enthält, die als benutzerdefinierte Funktion verwendet werden soll: Java-Klasse für benutzerdefinierte Funktionen erstellen und kompilieren
Java-Klasse installieren: Java-Klassen auf Essbase-Server installieren
Benutzerdefinierte Funktion als lokale oder globale Funktion registrieren: Benutzerdefinierte Funktionen registrieren

Anforderungen an die Gültigkeit benutzerdefinierter Funktionen

Sie entwerfen Ihre benutzerdefinierten Essbase-Funktionen als Methoden in einer Java-Klasse. Für globale Funktionen schreiben Sie Methoden in einer Klasse. Verwenden Sie für Anwendungsfunktionen separate Klassen und JAR-Dateien pro Anwendung. Testen Sie Funktionen lokal in einer Anwendung, bevor Sie sie global registrieren. Beachten Sie die unterstützten Datentypen, Variablen und Benennungskonventionen.

Sie können mehrere Methoden in einer Klasse zur Verwendung als benutzerdefinierte Funktion erstellen. In der Regel empfiehlt Oracle, die Methoden zu erstellen, die Sie für alle Anwendungen auf einem Essbase-Server als benutzerdefinierte Funktionen in einer einzelnen Klasse verwenden möchten. Wenn Sie jedoch benutzerdefinierte Funktionen hinzufügen möchten, die in selektiven Anwendungen auf dem Essbase-Server verwendet werden, erstellen Sie diese benutzerdefinierten Funktionen in einer separaten Klasse, und fügen Sie sie dem Essbase-Server in einer separaten .jar-Datei hinzu.

Wenn Sie mehrere Java-Klassen erstellen, die Methoden zur Verwendung als benutzerdefinierte Funktionen enthalten, prüfen Sie, ob jeder Klassenname eindeutig ist. Doppelte Klassennamen führen dazu, dass Methoden in der doppelten Klasse nicht erkannt werden, und Sie können diese Methoden nicht als benutzerdefinierte Funktionen registrieren.

Testen Sie die Java-Klassen und -Methoden mithilfe von Testprogrammen in Java. Wenn Sie mit der Ausgabe der Methoden zufrieden sind, installieren Sie sie auf dem Essbase-Server, und registrieren Sie sie in einer einzigen Testanwendung. Registrieren Sie Funktionen nicht global für Tests. Dies erschwert die Aktualisierung, wenn Probleme auftreten.

Methoden in benutzerdefinierten Funktionen können eine beliebige Kombination der folgenden unterstützten Datentypen als Eingabeparameter aufweisen:

boolean (boolescher Datentyp)
byte
char
com.hyperion.essbase.calculator.CalcBoolean
schweben, doppelt
java.lang.String
kurz, int, lang
Arrays einer dieser Typen

CalcBoolean ist ein Essbase-spezifischer Datentyp, der drei Werte enthalten kann: TRUE, FALSE und #MISSING. Informationen zu den anderen aufgeführten Datentypen finden Sie in der JDK-Dokumentation.

Der Datentyp für die Methodenrückgabe kann ungültig oder einer der vorhergehenden Datentypen sein. Zurückgegebene Datentypen werden in Essbase-spezifische Datentypen konvertiert. Zeichenfolgen werden einem Stringtyp zugeordnet. Boolesche Werte werden dem Datentyp "CalcBoolean" zugeordnet. Alle anderen Werte sind einem doppelten Typ zugeordnet.

Hinweis:

Essbase unterstützt keine doppelten Variablen, die mit unendlichen oder Nicht-Zahlen-Werten zurückgegeben werden. Wenn diese Werte von einem Java-Programm zurückgegeben werden, werden sie möglicherweise nicht korrekt in Essbase aufgezeichnet oder angezeigt. Doppelte Variablen müssen auf unendliche oder Nicht-eine-Zahl-Werte geprüft und auf endliche Werte gesetzt werden, bevor sie an Essbase zurückgegeben werden. Der Eintrag für die Klasse Double wird in der JDK-Dokumentation beschrieben.

Für das Erstellen, Löschen und Verwalten benutzerdefinierter Funktionen benötigt Essbase die folgenden Sicherheitsberechtigungen:

Lokale, anwendungsweite, benutzerdefinierte Funktionen: Application Manager oder höher
Globale, serverweite, benutzerdefinierte Funktionen: Systemadministrator

Wenn Sie eine benutzerdefinierte Funktion in Essbase registrieren, geben Sie der Funktion einen Namen, der in Berechnungsskripten und Formeln verwendet wird und sich von dem von der Funktion verwendeten Java-Klassen- und Methodennamen unterscheidet.

Für die Benennung benutzerdefinierter Funktionen gelten folgende Anforderungen:

Beginnen Sie den Namen mit dem @-Symbol. Der Rest eines Funktionsnamens kann Buchstaben, Zahlen und die folgenden Symbole enthalten: @, #, $ und _. Funktionsnamen dürfen keine Leerzeichen enthalten.

Beispiel: @MYFUNCTION
Starten Sie die Namen von benutzerdefinierten Funktionen, die nur von benutzerdefinierten Makros mit "@_" aufgerufen werden, um sie von allgemeinen Funktionen und Makros zu unterscheiden.

Beispiel: @_MYFUNCTION
Benutzerdefinierte Funktionen müssen eindeutige Namen haben. Funktionsnamen müssen sich voneinander unterscheiden, von den Namen benutzerdefinierter Makros und von den Namen vorhandener Berechnungsfunktionen.
Wenn eine Essbase-Anwendung eine lokale Funktion enthält, die denselben Namen wie eine globale Funktion hat, wird die lokale Funktion zur Berechnung verwendet.

Java-Klasse für benutzerdefinierte Funktionen erstellen und kompilieren

Um eine Java-Klasse für benutzerdefinierte Essbase-Funktionen (CDFs) zu erstellen und zu kompilieren, schreiben Sie die Klasse mit einem Texteditor oder einer IDE (integrierte Entwicklungsumgebung) und kompilieren Sie sie mit dem Tool javac.

Beispielworkflow zum Erstellen einer Java-Klasse für ein CDF:

Erstellen Sie in einem Texteditor eine Java-Klasse.

Beispiel:

public class CalcFunc {
  public static double sum (double[] data) {
    int i, n = data.length;
    double sum = 0.0d;
    for (i=0; i<n; i++) {
      double d = data [i];
      sum = sum + d;
    }
    return sum;
  }
}

Speichern Sie die Datei mit der Erweiterung .java.
Beispiel:
```
CalcFunc.java
```
Navigieren Sie zu dem Verzeichnis, in dem sich die Datei .java befindet. Geben Sie an einer Eingabeaufforderung den folgenden Befehl ein:
```
javac java_filename
```
Beispiel:
```
javac CalcFunc.java
```
Beheben Sie alle Kompilierungsfehler, bis der Compiler eine neue Datei mit der Erweiterung .class erstellt.
Beispiel:
```
CalcFunc.class
```

Java-Klassen auf Essbase Server installieren

Um die Java-Klassen für Ihre benutzerdefinierten Berechnungsfunktionen (CDFs) auf dem Essbase-Server zu installieren, kompilieren Sie sie, kopieren Sie die JAR-Datei in ein globales Verzeichnis oder in das Verzeichnis udf auf Anwendungsebene, wie in diesen Anweisungen angegeben, und starten Sie die Anwendung oder den Server neu.

Java-Klassen müssen mit dem JDK-Tool jar in einer JAR-Datei kompiliert werden.

So erstellen Sie eine .jar-Datei und installieren sie auf einem Essbase-Server:

Navigieren Sie zu dem Verzeichnis, in dem sich die Datei .class befindet. Geben Sie an einer Eingabeaufforderung den folgenden Befehl ein:
```
jar cf jar_filename class_filename
```
Beispiel:
```
jar cf CalcFunc.jar CalcFunc.class
```
Kopieren Sie auf dem Essbase-Server die Datei .jar in eines der folgenden Verzeichnisse (falls das Verzeichnis nicht vorhanden ist, erstellen Sie es):
- Für .jar-Dateien mit globalen benutzerdefinierten Funktionen:
  ESSBASEPATH/java/udf/
- Damit .jar-Dateien nur mit bestimmten Anwendungen verwendet werden können:
  <Application Directory>/app/appname/udf/
  wobei appname der Name der Anwendung ist, in der das lokale CDF verwendet wird.
Wenn Sie den Speicherort von ESSBASEPATH oder <Application Directory> nicht kennen, lesen Sie Umgebungsvariablen in der Essbase-Plattform.

Wenn die Datei .jar anschließend an einem anderen Speicherort abgelegt wird, müssen Sie die Variable CLASSPATH so ändern, dass der vollständige Pfad und der Dateiname für die Datei .jar eingeschlossen werden.
Wenn die Funktionen nur von bestimmten Anwendungen verwendet werden, starten Sie diese Anwendungen neu. Starten Sie andernfalls Essbase-Server neu. Informationen zu unabhängigen Deployments finden Sie unter Server starten, stoppen und prüfen oder Befehle zum Starten, Stoppen und Anzeigen des Status von Prozessen verwenden für das Stack-Deployment auf OCI.

Benutzerdefinierte Funktionen registrieren

Verwenden Sie MaxL, um Ihre benutzerdefinierten Funktionen (CDFs) bei Essbase zu registrieren. Die Registrierungsaufgabe wird ausgeführt, nachdem Sie die CDFs in Java-Klassen geschrieben, die Klassen kompiliert und die JAR-Dateien installiert haben.

Nachdem Sie die Java-Klassen für CDFs in .jar-Dateien kompiliert und die .jar-Dateien auf Essbase Server installiert haben, müssen Sie die Funktionen registrieren, bevor Sie sie in Berechnungsskripten und Formeln verwenden können. Siehe Voraussetzungen für die Gültigkeit benutzerdefinierter Funktionen.

Wenn Sie ein globales CDF registrieren, können es alle Essbase-Anwendungen auf dem Essbase-Server verwenden. Testen Sie die Funktionen in einer einzelnen Anwendung (und registrieren Sie sie nur in dieser Anwendung), bevor Sie sie global machen.

Verwenden Sie denselben Prozess zum Aktualisieren des Funktionskatalogs wie zum Aktualisieren des Makrokatalogs. Siehe Katalog benutzerdefinierter Makros aktualisieren.

Achtung:

Registrieren Sie keine globalen Funktionen zum Testen. Dies erschwert das Ändern dieser Funktionen, wenn Probleme auftreten.

Um ein CDF zu registrieren, verwenden Sie die create function-Anweisung MaxL.

Um eine CDF mit lokalem Geltungsbereich zu registrieren, geben Sie den Anwendungsnamen als Präfix an. Beispiel: Die folgende MaxL-Anweisung registriert die Funktion @JSUM in der Klasse CalcFunc als lokale Funktion für die Verwendung in der Beispielanwendung:

create function Sample.'@JSUM'
as 'CalcFunc.sum'
spec '@JSUM(memberRange)'
comment 'adds list of input members';

Um eine CDF mit globalem Geltungsbereich zu registrieren, geben Sie den Anwendungsnamen nicht als Präfix an. Beispiel: Die folgende MaxL-Anweisung registriert die Funktion @JSUM in der CalcFunc-Klasse als globale Funktion zur Verwendung in einer beliebigen Anwendung auf dem Essbase-Server:

create function '@JSUM'
as 'CalcFunc.sum'
spec '@JSUM(memberRange)'
comment 'adds list of input members';

Hinweis:

Die Angabe von Eingabeparametern für die Java-Methode ist optional. Wenn Sie keine Eingabeparameter angeben, liest Essbase diese aus der Methodendefinition im Java-Code. Wenn Sie jedoch mehrere CDFs mit demselben Methodennamen, aber mit unterschiedlichen Parametersätzen registrieren, müssen Sie jede Version der Funktion separat registrieren und die Parameter für jede Version der Funktion angeben.

Registrierte benutzerdefinierte Funktionen implementieren

Sie können registrierte benutzerdefinierte Funktionen (CDFs) in Berechnungsskripten und Formeln verwenden, genauso wie native Essbase-Berechnungsfunktionen.

So verwenden Sie ein registriertes CDF:

Erstellen oder öffnen Sie ein vorhandenes Berechnungsskript oder eine vorhandene Formel.
- Wenn das CDF lokal – innerhalb einer bestimmten Anwendung – registriert wurde, müssen Sie ein Berechnungsskript oder eine Formel in dieser Anwendung verwenden.
- Wenn das CDF global registriert wurde, können Sie ein beliebiges Berechnungsskript oder eine beliebige Formel auf dem Essbase-Server verwenden.
Fügen Sie die Funktion dem Berechnungsskript oder der Formel hinzu.

Beispiel: Um JSUM zu verwenden, verwenden Sie dieses Berechnungsskript:

"New York" = @JSUM(@LIST(2.3, 4.5, 6.6, 1000.34));

Verwenden Sie dieses Berechnungsskript mit der Sample.Basic-Beispieldatenbank, oder ersetzen Sie "New York" durch den Namen eines Elements in einer Testdatenbank.
Speichern Sie das Berechnungsskript oder die Formel, und führen Sie es wie gewohnt aus.

Benutzerdefinierte Features aktualisieren

Um eine benutzerdefinierte Essbase-Funktion (CDF) zu aktualisieren, bestimmen Sie, ob sie lokal oder global ist, fahren Sie die betroffenen Anwendungen herunter, ersetzen Sie die Datei .jar mit dem Code für die Funktion, und registrieren Sie die Funktion erneut.

Das Verfahren zum Aktualisieren von CDFs hängt von den folgenden Bedingungen ab:

Ob die Funktion lokal oder global registriert ist.
Ob die Signatur des CDF (Klassenname, Methodenname oder Eingabeparameter) im Java-Code geändert wurde.

Um ein CDF zu aktualisieren, müssen Sie in der Regel die Datei .jar ersetzen, die den Code für die Funktion enthält, und sie dann erneut registrieren. Wenn sich die Signatur des CDF jedoch nicht geändert hat und nur einen Satz von Eingabeparametern enthält (es handelt sich nicht um eine überladene Methode), können Sie die Datei .jar ersetzen, in der die Funktion enthalten ist.

Hinweis:

Nur Administratoren sollten globale CDFs aktualisieren.

So aktualisieren Sie eine CDF:

Stellen Sie fest, ob die Funktion lokal oder global ist.

Siehe Benutzerdefinierte Funktionen anzeigen.
Nehmen Sie die Änderungen an der Java-Klasse für CDF vor, und testen Sie die Ausgabe mit Java-Testprogrammen.
Kompilieren Sie die Java-Klassen, und archivieren Sie sie in einer neuen .jar-Datei mit demselben Namen wie die vorherige .jar-Datei.

Nehmen Sie alle anderen Klassen und Methoden für CDFs auf, die in der vorherigen .jar-Datei enthalten waren.
Führen Sie eine Aktion aus, je nachdem, ob Sie eine lokale oder globale benutzerdefinierte Funktion aktualisieren:
1. Lokal: Fahren Sie alle Essbase-Anwendungen herunter, die Funktionen in der Datei .jar verwenden.
2. Global: Alle Essbase-Anwendungen herunterfahren
Wenn Sie nicht sicher sind, welche Essbase-Anwendungen welche Funktionen in der Datei .jar verwenden, fahren Sie alle Essbase-Anwendungen herunter.
Kopieren Sie die neue Datei .jar in den Essbase-Server, und ersetzen Sie die vorhandene Datei .jar durch denselben Namen.
Wenn sich die Signatur des CDF nicht geändert hat, fahren Sie mit Schritt 8 fort.

Um das CDF zu ersetzen, verwenden Sie die Anweisung create or replace function MaxL. Beispiel:

Lokal:

create or replace function sample.'@JSUM'
as 'CalcFunc.sum';

Global:

create or replace function '@JSUM'
as 'CalcFunc.sum';

Starten Sie die heruntergefahrenen Anwendungen neu, wodurch der Katalog aktualisiert wird.

Benutzerdefinierte Funktionen anzeigen

Zeigen Sie eine benutzerdefinierte Funktion (CDF) in Essbase an, um zu bestimmen, ob sie erfolgreich registriert wurde und ob sie lokal oder global im Geltungsbereich ist. CDFs werden erst angezeigt, wenn sie erstellt und registriert wurden.

So zeigen Sie eine CDF an:

Verwenden Sie die display function-MaxL-Anweisung.

Beispiel: Verwenden Sie die folgende MaxL-Anweisung, um die CDFs in der Beispielanwendung und alle registrierten globalen Funktionen anzuzeigen:

display function Sample;

Mit der Anweisung display function werden globale Funktionen ohne einen Anwendungsnamen aufgeführt, um anzugeben, dass sie global sind. Wenn die Anwendung eine Funktion mit demselben Namen wie eine globale Funktion enthält, wird nur die lokale Funktion aufgeführt.

Benutzerdefinierte Funktionen entfernen

Um benutzerdefinierte Essbase-Funktionen (CDFs) zu entfernen bzw. deren Registrierung aufzuheben, stellen Sie zunächst sicher, dass sie nicht verwendet werden. Fahren Sie dann die Anwendungen herunter, in denen die CDFs definiert sind, entfernen Sie die CDFs, indem Sie die MaxL drop function-Anweisung absetzen und die betroffenen Anwendungen neu starten.

Die folgenden Berechtigungen sind erforderlich, um ein CDF zu entfernen:

Lokal: Mindestens Application Manager-Berechtigung für die Anwendung
Global: Systemadministratorberechtigung

Bevor Sie CDFs entfernen, sollten Sie sicherstellen, dass keine Berechnungsskripte oder Formeln verwendet werden. Globale CDFs können in Berechnungsskripten und Formeln auf dem gesamten Essbase-Server verwendet werden. Sie müssen daher sicherstellen, dass keine Berechnungsskripte oder Formeln auf dem Essbase-Server ein globales CDF verwenden, bevor Sie es entfernen.

Achtung:

Entfernen Sie globale CDFs nur, wenn Benutzer nicht auf Essbase-Cubes zugreifen und keine Berechnungsroutinen ausgeführt werden.

So entfernen Sie eine CDF:

Stellen Sie fest, ob die Funktion lokal oder global ist.

Siehe Benutzerdefinierte Funktionen anzeigen.
Führen Sie eine Aktion aus, je nachdem, ob Sie eine lokale oder globale CDF entfernen:
1. Lokal: Fahren Sie alle Essbase-Anwendungen herunter, die Funktionen in der Datei .jar verwenden.
2. Global: Fahren Sie alle Essbase-Anwendungen herunter.
Um das CDF zu entfernen, verwenden Sie die Anweisung drop function MaxL. Beispiel:
- Lokal:
```
drop function Sample.'@JSUM';
```
- Global:
```
drop function '@JSUM';
```
Starten Sie die heruntergefahrenen Anwendungen neu, wodurch der Katalog aktualisiert wird.

Benutzerdefinierte Funktionen kopieren

Sie können benutzerdefinierte Funktionen (CDFs) in jeden Essbase-Server und jede Anwendung kopieren, auf die Sie entsprechenden Zugriff haben.

Um ein CDF zu kopieren, verwenden Sie die create or replace function as-Anweisung MaxL.

Überlegungen zur Performance für benutzerdefinierte Funktionen

Da benutzerdefinierte Funktionen als Erweiterung des Essbase-Rechner-Frameworks implementiert werden, können Sie davon ausgehen, dass CDFs weniger effizient arbeiten als native Essbase-Berechnungsfunktionen.

Um die Performance zu optimieren, beschränken Sie die Verwendung benutzerdefinierter Funktionen auf Berechnungen, die Sie nicht mit nativen Essbase-Berechnungsbefehlen und Funktionen ausführen können, insbesondere in Anwendungen, in denen die Berechnungsgeschwindigkeit kritisch ist.