1                     Kurzbeschreibung

Die Semiramis-CORBA-Schnittstelle ist eine Infrastrukur für die entfernte, direkte, synchrone Kommunikation zwischen Semiramis und CORBA-Clients. CORBA-Clients können über die Schnittstelle spezielle Funktionen in Semiramis aufrufen. Diese Funktionen sind in Semiramis immer als Hintergrundanwendungen implementiert und können prinzipiell unabhängig vom konkreten Ein-Ausgabekanal, d. h. unabhängig von der jeweilgen Schnittstellen- bzw. Kommunikationstechnologie aufgerufen werden. Der Implementierer einer Hintergrundanwendung ist von der konkreten Technologie für den Aufruf abgeschirmt. Hierdurch ist die Wiederverwendbarkeit bei einer späteren Erweiterung oder Änderungen der Kommunikationstechnologien gewährleistet. Eine der Technologien, die in Semiramis integriert ist, ist CORBA.

Dieses Dokument enthält die Beschreibung der Semiramis-CORBA-Schnittstelle sowie der Entfernten BIS-Schnittstelle über CORBA.

Über die Semiramis-CORBA-Schnittstelle wird Semiramis immer von außen aufgerufen. Die umgekehrte Richtung, aus Semiramis heraus andere CORBA-Server aufzurufen, ist von der Semiramis-CORBA-Schnittstelle nicht abgedeckt und wird daher hier nicht weiter beschrieben. Sie ist im Wesentlichen durch den zu verwendenden CORBA-Server und dessen Schnisttstellen bestimmt. Es ist sinnvoll, auch in diesen Fällen die mit Semiramis ausgelieferte ORB-Implementierung JacORB zu verwenden.

Hinweis:

Beachten Sie auch die Informationen auf folgenden Webseiten, Stand: März 2006:

• Java und CORBA (http://java.sun.com/j2se/1.4.2/docs/guide/corba/index.html)
• Java und IDL (http://java.sun.com/j2se/1.4.2/docs/guide/idl/GShome.html)
• JacORB (http://www.jacorb.org)

2                     Zielgruppe

Verwender der CORBA-Server Schnittstelle, Entwickler von entfernt aufrufbaren Hintergrundanwendungen. Ein tieferes Verständnis für CORBA und seine Funktionsweise wird vorausgesetzt.

3                     Begriffsbestimmung

CORBA

Abkürzung für »Common Object Request Broker Architecture«, zu Deutsch »gemeinsame Architektur für Objektanforderungsvermittler«. Eine 1992 von der OMG (Object Management Group) entwickelte Spezifikation, bei der Teile von Programmen (Objekte) mit anderen Objekten anderer Programme kommunizieren. Die Kommunikation ist auch dann möglich, wenn zwei Programme in verschiedenen Programmiersprachen geschrieben wurden oder auf unterschiedlichen Plattformen laufen. Hierfür wurde die plattformunabhängige Schnittstellen-Beschreibungssprache IDL (Interface Definition Language) definiert. Bei CORBA fordert ein Programm Objekte mit Hilfe eines ORB (Object Request Broker) an. Kenntnisse hinsichtlich der Strukturen des Programms, aus dem das Objekt stammt, sind dabei nicht erforderlich. CORBA wurde für den Einsatz in objektorientierten Umgebungen entwickelt.

Anmeldung (Session)

Die Ausführung von Hintergrundanwendungen ist auf das Vorhandensein einer Semiramis Laufzeitumgebung angewiesen, in der alle Funktionen der Semiramis System Engine (z. B. der Persistenzdienst) zur Verfügung stehen. Bei dem entfernten Ausführen von Hintergrundanwendungen muss durch eine Anmeldung eine solche Umgebung explizit erstellt werden. Parameter für die Anmeldung sind der Name des Semiramis Benutzers, sein Kennwort und der Name der aktiven OLTP-Datenbank (optional). Diese Parameter können während der Lebensdauer der Anmeldung nicht mehr geändert werden.

Zustandsloser Aufruf

Ein entfernter Aufruf einer Hintergrundanwendung ist ein Aufruf, zu dessen Begin eine neue Instanz der Hintergrundanwendungen erstellt wird, anschließend die run()-Methode der Hintergrundanwendung aufgerufen wird und bei dessen Ende diese Anwendungsinstanz auch wieder freigegeben wird.

Zustandsbehafteter Aufruf

Ein zustandbehafteter Aufruf einer Hintergrundanwendung ist eine Folge von entfernten Aufrufen, die mit dem Erstellen einer neuen Instanz einer Hintergrundanwendung beginnt, mehrere Aufrufe an die run()-Methode der Hintergrundanwendung beinhaltet und mit einem expliziten Aufruf zur Freigabe der Hintergrundanwendung endet.

4                     CORBA-Clients

4.1               Unterstützte CORBA-Implementierungen

Die Semiramis-CORBA-Schnittstelle verwendet auf der Serverseite die ORB-Implementierung JacORB. Hierbei handelt es sich um eine Open Source ORB-Implementierung für Java, die eine hohe Performanz und Stabilität bei geringem Resourcenverbauch aufweist. CORBA-Clients sind allerdings nicht auf die Verwendung von JacORB festgelegt; prinzipiell können auch andere Implementierungen verwendet werden.

Die folgende Tabelle gibt an, welche CORBA-Implementierungen für Clients offiziell unterstützt werden, in Abhängigkeit von den Betriebssystemen, auf denen der Client bzw. der Semiramis-CORBA-Server laufen.

Mit „JDK-ORB“ wird die mit dem JDK ausgelieferte CORBA-Implementierung bezeichnet.

	Semiramis-CORBA-Server Betriebssystem
CORBA-Client Betriebssystem, CORBA-Implementierung	Windows	Linux	iSeries
Windows, JacORB	ja	ja	ja
Windows, JDK-ORB	ja	ja	ja
Linux, JacORB	ja	ja	ja
Linux, JDK-ORB	ja	ja	ja
iSeries, JacORB	ja	ja	ja
iSeries, JDK-ORB	nein	nein	nein

Andere CORBA-Implementierungen, insbesondere auch für andere Programmiersprachen als Java, wurden nicht getestet und sind nicht offiziell unter­stützt.

4.2               Systembestandteile eines Clients

Ein CORBA-Client braucht eine passende CORBA-Implementierung und die aus der IDL generierten Klassen. Die hierzu notwendigen Bestandteile sind von der CORBA-Implementierung abhängig. Nachfolgend sind sie für JacORB beschrieben.

JacORB

Ein Java-Client, der JacORB benutzt, braucht folgende Bestandteile:

• Bibliotheken jacorb.jar, avalon-framework.jar und logkit.jar im Klassenpfad. (In Semiramis-Installtion enthalten; benötigte JARs können für JacORB-Versionen höher als 2.2.1 abweichen.)
• JacORB-Konfigurationsdatei jacorb.properties im Klassenpfad.
  (In Semiramis Bestandteil des Anwendungscodes.)
• CORBA-Schnittstellenklassen im Klassenpfad
  (Aus der IDL-Datei generierte Klassen; sind in der System Engine im Package com.cisag.pgm.external.corba enthalten, oder können aus der IDL-Datei erzeugt werden.)

Für produktiv genutzte Clients empfehlen wir, die beschriebenen Bestandteile getrennt von Semiramis zu installieren, um Abhängigkeiten zur Semiramis-Installation zu vermeiden. Test-Clients können hingegen die in der Semiramis-Installation vorhandene Version von JacORB direkt verwenden.

Weitere Informationen über JacORB finden Sie unter http://www.jacorb.org.

5                     Semiramis-CORBA-Server

Im Sinne der CORBA-Spezifikation stellt Semiramis einen eigenen CORBA-Server (Semiramis-CORBA-Server) zur Verfügung. Dieser stellt die Semiramis-CORBA-Schnittstelle zur Verfügung.

Je Semiramis Application Server kann maximal ein Semiramis-CORBA-Server gestartet werden. Ein Semiramis-CORBA-Server kann die Anfragen von beliebig vielen CORBA-Clients bearbeiten. Der Start des Semiramis-CORBA-Servers innerhalb eines Semiramis Application Servers kann beim Start des Semiramis Application Servers automatisch oder zu jedem beliebigen späteren Zeitpunkt manuell erfolgen.

5.1               Manueller Start

Für den manuellen Start steht das Toolshell-Kommando strscs (Dokumentation: Semiramis-CORBA-Server starten) zur Verfügung. Der Semiramis-CORBA-Server kann auch jederzeit mit dem Toolshell-Kommando endscs (Dokumentation: Semiramis-CORBA-Server beenden) beendet werden. Die Syntax der beiden Kommandos lautet

strscs [-host:<text>] -port:<int> [-timeoutInterval:<duration>]

-host:<text>                 ORB-Host.

-port:<int>                  ORB-Port.

-timeoutInterval:<duration>  Timeout-Intervall. Default: 30000.

Wird der Parameter –host nicht angegeben, verwendet Semiramis einen Default. Auf der Toolshell erscheint der verwendete Host in jedem Fall in einer Meldung. Geben Sie bei Verbindungsproblemen zur Sicherheit den Host an. Das Timeout-Intervall ist in Millisekunden angegeben, und kann

endscs [-waitForCompletion:<boolean>]

-waitForCompletion:<boolean> Auf Ende aller Requests warten. Default: true.

5.2               Automatischer Start

Um den CORBA-Server direkt beim Semiramis Application Server mitzustarten, stehen folgende Properties zur Verfügung, die bei Bedarf in die Datei „server.properties“ des Semiramis Application Servers eingetragen werden können:

• cisag.sys.kernel.corba.CorbaServerAutostart=true, false, Default false
  Gibt an, ob der CORBA-Server automatisch gestartet werden soll.
• cisag.sys.kernel.corba.CorbaServerHost=<Host>
  Host des CORBA-Servers bei automatischem Start
• cisag.sys.kernel.corba.CorbaServerPort=<Port>
  Port des CORBA-Servers bei automatischem Start
• cisag.sys.kernel.corba.CorbaServerTimeoutIntervalSeconds=<Zeit>, Default 30, Dauer des Intervalls in Sekunden, nach dem geprüft wird, ob der Client, der eine Session geöffnet hat, noch erreichbar ist. Dieser Wert ist ebenfall nur beim automatischen Start relevant.

Nähere Informationen zu den genannten und weiteren Properties finden Sie in der Dokumentation Semiramis-Properties.

5.3               Verwendbare Ports

Auf jedem Betriebsystem existieren Restriktionen bzgl. der für den Semiramis-CORBA-Server verwendbaren Ports. Diese müssen bei der Wahl der Ports beachtet werden.

Siehe auch http://java.sun.com/j2se/1.4.2/docs/guide/idl/tutorial/GScompile.html, Stand: März 2006.

6                     Semiramis-CORBA-Schnittstelle

CORBA-Clients können die Semiramis-CORBA-Schnittstelle benutzen, um über CORBA Funktionen in Semiramis aufzurufen. Es können sowohl im Standard ausgelieferte als auch im Rahmen von Adaptierungen entstandene Hintergrundanwendungen aufgerufen werden.

6.1               IDL-Schnittstellenbeschreibung

Die IDL der Semiramis-CORBA-Schnittstelle ist als Entwicklungsobjekt vom Typ Datei unter dem Namen com.cisag.pgm.external.corba.Corba-IDL abgelegt. Im Dateisystem einer Semiramis-Installation befindet sich die IDL in der folgenden Datei: $SEMIRAMIS_HOME/files/com/cisag/pgm/external/corba/Corba.idl

In der Semiramis System Engine befinden sich die aus der IDL erzeugten Java-Klassen im Namensraum com.cisag.pgm.external.corba. Diese Klassen können Sie für einen in Java geschriebenen externen CORBA-Client verwenden, der mit der mit Semiramis ausgelieferten Version von JacORB arbeitet. Bei der Verwendung anderer ORB-Implementierungen oder Versionen müssen aus der IDL neue Klassen generiert werden. Dazu gibt es in der jeweils verwendeten ORB-Implementierung entsprechende Tools. Für andere Programmiersprachen als Java müssen Sie den Anleitungen der jeweiligen ORB-Implementierung folgen.

Die IDL enthält die technische Beschreibung der CORBA-Schnittstelle und ist Ausgangspunkt für die Entwicklung eines externen CORBA-Clients.

Die IDL ist innerhalb eines Semiramis Releases sehr stabil. Zukünftige Änderungen an dieser Schnittstelle werden hauptsächlich Erweiterungen und Performance-Anpassungen sein und keine Änderungen am grundsätzlichen Vorgehen (SessionManager, Session, Application) darstellen.

6.2               Abbildung von Datentypen

Die CORBA-Schnittstelle unterstützt einen Teil der Datentypen, die Semieramis serverseitig für aufrufbare Hintergrund-Anwendungen unterstützt.

Hintergrund-Anwendungen, die eigens für den externen Aufruf entwickelt werden, dürfen daher nur die unterstützten Datentypen verwenden. Bereits vorhandene Hintergrund-Anwendungen können nur dann sinnvoll extern aufgerufen werden, wenn die Datentypen aller benötigten Parameter unterstützt werden.

Die unterstützen Datentypen für den Aufruf von Hintergrundanwendungen über CORBA und ihre Abbildung in IDL bzw. für einen CORBA-Java-Client sind wie folgt:

Semiramis	CORBA IDL-Datentyp	CORBA-Java-Client
boolean	boolean	boolean
short	short	short
int	long	int
long	long long	long
String	wstring	String
Binary (byte[])	OctetSeq	byte[]
GUID (byte[])	CorbaGuid	byte[]
Valueset (short)	short	short
CisParameterList	CorbaParameterList	CorbaParameterList
CisObject (nur transient)	CisObjectRepresentation	CisObjectRepresentation
List<? extends CisObject> (nur transient)	CisObjectRepresentationList	CisObjectRepresentationList

Die clientseitigen Datentypen, soweit nicht in IDL bzw. Java vordefiniert, liegen im Package com.cisag.pgm.external.corba.

Nicht aufgeführte Datentypen werden in der Semiramis-CORBA-Schnittstelle nicht unterstützt, auch wenn Sie serverseitig als Parameter in Hintergrund-Anwendungen verwendet werden.

Beachten Sie auch, dass Null-Werte grundsätzlich nicht verwendet werden können (z.B. null als GUID). Bei der Übertragung von Semiramis zum Client werden Parameter mit null-Werten entfernt, so dass der Parameter auf Client-Seite nicht mehr vorhanden ist. (Ausnahme sind die Rückgabeparameter von Anwendungsaufrufen, siehe weiter unten.)

Zeitstempel

Zeitstempel (primitiver Semiramis-Datentyp TimeStamp) können auf der CORBA-Seite als IDL-Datentyp „long long“ dargestellt werden. Serverseitig ist jedoch keine automatische Abbildung in den Java-Datentyp „java.util.Date“ vorhanden, der in Semiramis als Zeitstempel verwendet wird. Die Abbildung gemäß der Java-Methode „currentTimeMillis()“ muss in Semiramis individuell in der Hintergrund-Anwendung durchgeführt werden.

Zu Semiramis passende Konstanten für +∞, -∞ und den ungültigen Zeitstempel sind am IDL-Interface CorbaDatatypeConstants definiert.

CisObjects und Parts

CisObjectRepresentation und CisObjectRepresentationList stehen ab Semiramis 4.4-PC-01 zur Verfügung. Sie dienen dazu, Hintergrund-Anwendungen aufzurufen, die transiente CisObjects und Parts als Parameter verwenden. CisOjbectRepresentation dient der Übertragung eines CisObjects oder Parts. CisObjectRepresentationList dient der Übertragung einer geordneten Kollektion von CisObjects oder Parts.

Beispiel: Die CisObjectRepresentationList kann dazu verwendet werden, eine Liste von OrderKey für die Anwendung „Kommision erzeugen“ zu übergeben.

Durch die Übertragung von CisObjects und Parts über CORBA entsteht eine Kopie, die die Attributwerte des CisObjects oder Parts zum Zeitpunkt der Übertragung enthält.

Eine Instanz von CisObjectRepresentation besteht aus dem Namen des entsprechenden Entwicklungsobjekts und den Attributen der Instanz:

• className: Vollständiger Name des Entwicklungsobjekts (Business Object oder Part)
• values: Attributnamen und –werte in Form einer CorbaParameterList.

Bei CisObjects, die Parts beinhalten, ist der entsprechende Attributwert in der CorbaParameterList values wiederum eine Instanz von CisObjectRepresentation, die den Part repräsentiert.

Bei der Übertragung vom Client zu Semiramis werden die angegebenen Attribute übertragen. Nicht angegebene Attribute werden in Semiramis durch technische Vorgabewerte ersetzt und in dieser Form an die Hintergrund-Anwendung übergeben. Bei der Übertragung an den Client ist es ausschließlich von der Hintergrund-Anwendung abhängig, inwieweit Attribute im CisObject angegeben sind.

Datentypen, die die CORBA-Schnittstelle nicht unterstützt, können auch als Attributwerte von CisObjects oder Parts nicht übertragen werden.

Beachten Sie auch, dass in CisObjects und Parts enthaltene GUIDs bei der Übertragung als CisObjectRepresentation nicht automatisch in eine lesbare Identifikation umgewandelt werden.

Die Schnittstelle einer neu zu entwickelnden Hintergrund-Anwendung kann schmal gehalten werden, indem spezielle Parts anstatt von Business-Object-Instanzen verwendet werden, die nur die benötigten Attribute enthalten.

6.3               Arbeitsweise eines CORBA-Clients

Für die Implementierung eines CORBA-Clients können Sie die mit Semiramis ausgelieferten Beispiel-Clients als Referenz verwenden. Im Folgenden sind die Schritte zum Aufbau einer CORBA-Verbindung und zum Aufrufen von Hintergrundanwendungen beschrieben.

6.3.1          Verbindungsaufbau

Bevor eine Verbindung zum Semiramis-CORBA-Server aufgebaut werden kann, muss zunächst der ORB initialisiert werden. Danach wird die Verbindung aufgebaut, in dem eine Referenz zum CorbaSessionManager-Objekt aufgebaut wird. Dazu muss eine „corbaloc:“-Adresse verwendet werden, die ein String in folgendem Format ist:

corbaloc::<host>:<port><SEMIRAMIS_CORBA_SESSION_MANAGER>

Die Bestandteile host und port sind Hostname und Port des Semiramis-CORBA-Servers, zu dem die Verbindung hergestellt werden soll. Der dritte Parameter ist der Wert der Konstanten

CorbaConstants.SEMIRAMIS_CORBA_SESSION_MANAGER

aus der IDL.

6.3.2          Session und Authentifizierung

Am CorbaSessionManager kann die Anmeldung an Semiramis erfolgen. Dabei wird in Semiramis eine Session erzeugt. Die Signatur ist folgende:

CorbaSessionManager::createSession( client, sessionParameters)

Der Parameter client ist ein Objekt, das auf der Seite des CORBA-Client erzeugt wird und das Interface CorbaClient aus der IDL implementiert. Dieses Objekt wird von Semiramis aus auf dem CORBA-Client aufgerufen, um festzustellen, ob die CORBA-Verbindung noch besteht. Damit diese Prüfung funktioniert, muss insbesondere sichergestellt sein, dass der CORBA-Server den CORBA-Client über die ihm vom CORBA-Client übermittelte IP-Adresse wieder erreichen kann.

Im Parameter sessionParameters müssen Benutzername, das Kennwort des Benutzers und die OLTP-Datenbank angegeben werden, an die die Anmeldung erfolgen soll. Benutzername und Kennwort werden wie bei einer interaktiven Anmeldung geprüft. Dies bedeutet insbesondere, dass der Benutzer dem System zugeordnet und dort mit entsprechenden Berechtigungen ausgestatt sein muss.

Das Ergebnis enthält ein CorbaSession-Objekt, das die Session für den Client repräsentiert, sowie evtl. aufgetretene Meldungen.

Das Abmelden einer Session geschieht mit der Methode

CorbaSessionManager::logoutSession()

Hinweis:
Die jeweils an Semiramis angemeldeten CORBA-Sessions können Sie in der Anwendung „Systemcockpit“ abfragen.

6.3.3          Aufruf von Anwendungen

Aus dem CorbaSession-Objekt erhält man ein CorbaApplicationManager-Objekt, mit dem Hintergrundanwendungen in Semiramis aufgerufen werden können.

Parameter werden über CorbaParameterList-Objekte übertragen. Um Aufrufparameter übergeben zu können, muss zunächst ein CorbaParameterList-Objekt neu erzeugt werden:

CorbaSession::createParameterList()

in das die Aufrufparameter gesetzt werden müssen.

Soll eine Hintergrundanwendung in Semiramis zustandslos aufgerufen werden, reicht ein einzelner Aufruf der Methode

CorbaApplicationManager::callApplication()

Rückgabe der Methode ist eine Parameterliste mit Rückgabewerten, sowie Meldungen. Ist die Parameterliste null, so bedeutet dies per Konvention, dass der Aufruf fehlgeschlagen ist. Aufschluss über die Ursachen geben die Meldungen. Ist die Parameterliste nicht null, ist die Bedeutung von der aufgerufenen Hintergrund-Anwendung abhängig. Dies kann grundsätzlich ebenfalls bedeuten,  dass der Aufruf nicht erfolgreich war. Das kann der Fall sein, wenn die aufgerufene Hintergundanwendung detailierte Informationen über die Fehlersituation übermittelt.

Für zustandsbehaftete Aufrufe muss zunächst die Anwendung erzeugt werden:

CorbaApplicationManager::createApplication()

und kann danach mehrmals mit neuen Parametern aufgerufen werden:

CorbaApplicationManager::runApplication()

Zustandsbehaftete Aufrufe geben wie die zustandslosen Aufrufe eine Parameterliste mit Rückgabewerten zurück. Die Bedeutung von null und der Meldungen ist analog.

Wird die zustandsbehaftet aufgerufene Anwendung nicht mehr benötigt, muss sie mit

CorbaApplicationManager::releaseApplication()

freigegeben werden.

Die genauen Signaturen und die Verwendung der Methoden können Sie der IDL und den Beispiel-Clients entnehmen.

Ob eine Hintergrundanwendung zustandlos oder zustandsbehaftet aufgrufen werden muss, hängt von der konkreten Implementierung der Anwendung ab. Für einfache Anwendungsfälle, die wenige Parameter und Resourcen benötigen und zurückliefern, z. B. eine Fremdschlüsselprüfung oder das Speichern eines einfachen Objektes, reichen zustandlose Anwendungen aus.

Wenn große Datenmengen übertragen werden sollen, kann mit Hilfe einer zustandsbehafteten Anwendung z. B. die Abfrage der Daten über mehrere Aufrufe hinweg in Blöcke aufgeteilt werden. Dieses Vorgehen wird beispielsweise für den Aufruf der Export- und Import-Anwendungen verwendet.

6.3.4          Freigabe von serverseitigen CORBA-Objekten

In CORBA wird die Lebenzeit von über CORBA erreichbaren Objekten nicht durch die CORBA-Implementierung gesteuert, sondern erfolgt anwendungsspezifisch im jeweiligen CORBA-Server.

In der Semiramis-CORBA-Schnittstelle ist hierfür eine explizite Freigabe von nicht mehr benötigten CORBA-Objekten vorgesehen, die durch den Client erfolgen muss. Hierfür gibt es die folgenden Methoden:

CorbaParameterList::release()	Gibt die CorbaParameterList und alle darin enthaltenen CorbaParameterLists frei. Eine Freigabe ist erforderlich für alle durch den Client erzeugten CorbaParameterLists, sowie von der CORBA-Schnittstelle zurückgegebenen CorbaParameterLists, soweit sie nicht in anderen CorbaParameterLists enthalten sind. Nach dem Aufruf kann auf die gesamte CorbaParameterList nicht mehr zugegriffen werden.
CorbaMessageQueue::release()	Gibt die CorbaMessageQueue frei. Eine Freigabe ist erforderlich für alle CorbaMessageQueues, die von der CORBA-Schnittstelle zurückgegeben werden. Nach dem Aufruf kann auf die CorbaMessageQueue und alle enthaltenen Meldungen nicht mehr zugegriffen werden.
CorbaApplicationManager:: releaseApplication()	Gibt die angegebene Anwendung frei.

Die Objekte dürfen erst dann freigegeben werden, wenn der Client sie nicht mehr braucht.

Zusätzlich werden beim Schließen von CORBA-Sessions alle CORBA-Objekte dieser Session automatisch freigegeben. Dies ist für CORBA-Sessions, die nur sehr kurze Zeit angemeldet bleiben, auch ausreichend. Clients, die jedoch Sessions über eine lange Zeit geöffnet halten, müssen die serverseitigen Objekte explizit freigeben, um Speicherlecks zu vermeiden.

6.4               Entfernte BIS-Schnittstelle über CORBA

Die entfernte BIS-Schnittstelle besteht aus drei Hintergrund-Anwendungen, die über die CORBA-Schnittstelle aufgerufen werden können. Für den Aufruf dieser Hintergrund-Anwendungen verwenden Sie die CORBA-Schnittstelle.

6.4.1          Anwendungsfälle

Die Hintergrund-Anwendungen des entfernten BIS sind für den Fall optimiert, das sowohl das Auslösen des eigentlichen Vorgangs als auch die Übertragung ausschließlich über CORBA erfolgt. Dies ist immer dann notwendig, wenn die Nutzdaten auf keinem anderen Weg zwischen dem CORBA-Client und dem CORBA-Server ausgetauscht werden können.

Die Hintergrund-Anwendungen sind in den folgenden Abschnitten beschrieben.

Wenn jedoch der CORBA-Client und der CORBA-Server beispielsweise Zugriff auf ein gemeinsames Dateisystem oder den Knowledge Store besitzen, kann ein Vorteil sein, die Nutzdaten direkt dort abzulegen oder wieder abzuholen. Vorteile dieser Vorgehensweise sind:

• Die CORBA-Verbindung wird entlastet, indem weniger Daten übertragen werden müssen.
• Die Übertragung der Nutzerdaten kann asynchron zum eigentlichen Vorgang erfolgen.
• Verknüpfte Dateien können importiert werden, z. B. Dateien für Attribute vom Typ BLOB.

Um diese Art des Aufrufs zu verwenden, können Sie die Hintergrund-Anwendungen, die in der Dokumentation Programmier-Schnittstellen für den Datenaustausch beschrieben sind, zustandslos über CORBA aufrufen. direkt über die Methode „callApplication“ des CorbaApplicationManager aufrufen.

6.4.2          Hintergrund-Anwendungen

Im Folgenden sind die Actions, Parameter und Rückgabeparameter für die Hintergrund-Anwendungen des entfernten BIS beschrieben.

Ein Vorgang im entfernten BIS, unabhängig, ob es sich um den Import, Export oder eine Suche handelt, besteht aus mehreren Anwendungsaufrufen, die an dieselbe Anwendungsinstanz gehen (zustandsbehaftete Aufrufe). Bei der blockweisen Übertragung der Daten werden beim ersten Aufruf die Eingangsparameter spezifiziert und der erste Ergebnisblock zurückübertragen. Alle folgenden Aufrufe liefern dann jeweils einen weiteren Block.

Die Anwendungsinstanz muss vorher erzeugt werden. In der CORBA-IDL gibt es dazu die Konstanten

• APPLICATION_NAME,
• APPLICATION_NAME und
• APPLICATION_NAME,

die bei der Erzeugung der Anwendungsinstanz als Anwendungsname angegeben werden müssen.

Die Actions, Parameternamen und Valueset-Konstanten für die Anwendungen sind in der CORBA-IDL ebenfalls als Konstanten enthalten. Sie befinden sich in den IDL-Interfaces

• CorbaRemoteImport,
• CorbaRemoteExport und

Bei der Entwicklung von CORBA-Clients sollten diese Konstanten verwendet werden.

In der nachfolgenden Schnittstellenbeschreibung sind die Parameter-Datentypen als Java- bzw. Semiramis-Datentypen angegeben. Für einen CORBA-Client müssen die jeweiligen Client-seitigen Datentypen verwendet werden. Daraus ergibt sich für einen CORBA-Client, der in Java entwickelt wird, dass statt des Typs „CisParameterList“ der Typ  „CorbaParameterList“ verwendet werden muss.

Hinweis:
Wenn die Rückgabe eines Anwendungsaufrufes der Wert „null“ anstatt einer Parameterliste ist, dann ist ein grundsätzlicher Fehler in der Anwendung aufgetreten, wie z. B. unzulässige Actions oder unbekannte Parameter. Prüfen Sie in diesem Fall auch die zurückgegebenen Meldungen.

Wenn ein Vorgang abgeschlossen ist oder explizit beendet wurde, dann können mit derselben Anwendungsinstanz weitere Vorgänge gestartet werden. Die Aufrufe zu unterschiedlichen Vorgängen können allerdings nicht zeitlich überlappend aufgerufen werden.

 

6.4.3          Entfernter Import mit CORBA

Für einen Importvorgang werden die Importdaten als XML-Dokument blockweise an Semiramis übergeben. Für die Blockgröße der Importdaten ist beim Import zu bedenken, dass der CORBA-Client bestimmt, wie groß die Blöcke sind, die an Semiramis übertragen werden. Sinnvolle Werte liegen zwischen 250 kB und 1000 kB. Die Blockgröße darf keinesfalls zu groß gewählt werden, damit der Hauptspeicher des Semiramis Application Servers nicht zu stark beansprucht wird. Eine kleinere Bockgröße führt zu vielen Roundtrips und auf Grund der Latzenz damit zu starkt erhöhten Übertragungszeiten.

Für den Fall, dass Importfehler auftreten, können Sie festlegen, ob die Korrektur der fehlerhaften Daten in Semiramis erfolgen soll, oder ob eine Fehler-Datei an den Client zurückübertragen wird. Für eine Korrektur in Semiramis wird die Benachrichtigung über das Workflow-Management verwendet, die in der Dokumentation Einführung: Datenaustausch beschrieben ist.

Bei einer Korrektur in Semiramis wird die Fehler-Datei im Knowledge Store in den Ordner „kstore://<Arbeitsbereich>/Import/RemoteErrorFiles“ erzeugt. Als Arbeitsbereich wird der Standard-Arbeitsbereich der Datenbank, in die die Daten importiert wurden, verwendet. Der Ordner sollte nicht für andere Zwecke verwendet werden.

Ein Filter, der für einen Importvorgang verwendet werden soll, muss in der Anwendung „Daten importieren“ erstellt und gespeichert worden sein. Angegeben wird der Name des Filters. Weitere Informationen finden Sie in der Dokumentation Daten importieren.

6.4.3.1      Actions und Parameter

Die Hintergrund-Anwendung für den Import kann mit folgenden Actions aufgerufen werden:

Action	Bedeutung
PROCESS	Importdaten des ersten Blocks und sonstige Parameter werden übergeben.
PROCESS_NEXT_BLOCK	Importdaten für weitere Blöcke werden übergeben.
PROCESS_LAST_BLOCK	Signalisiert das Ende der Importdaten. Der letzte Block kann mit übergeben werden, falls er nicht schon im vorigen Aufruf übergeben wurde. Mit dieser Action können Sie feststellen, ob Fehler beim Import aufgetreten sind.
GET_ERROR_FILE_NEXT_BLOCK	Gibt nach einem erfolgten Import die Fehler-Datei zurück. Die Rückgabe erfolgt blockweise, daher muss auch diese Action mehrfach aufgerufen werden.
CLOSE	Bricht einen Importvorgang vorzeitig ab, oder beendet den Import, ohne die Fehler-Datei abzuholen.

Die Vorgehensweise eines Imports mit Rückgabe der Fehler-Datei ist wie folgt:

1. Der Importvorgang wird mit der Action PROCESS begonnen.
2. Für weitere Blöcke wird so oft wie nötig PROCESS_NEXT_BLOCK aufgerufen.
3. Zum Abschluss des Imports wird PROCESS_LAST_BLOCK aufgerufen. Falls kein Fehler beim Import aufgetreten ist, ist der Vorgang abgeschlossen.
4. Falls Fehler beim Import aufgetreten sind und eine Fehler-Datei zur Verfügung steht, wird die Fehler-Datei mit der Action GET_ERROR_FILE_NEXT_BLOCK blockweise zurückgegeben. Wenn Sie die Fehler-Datei dennoch nicht übertragen möchten, rufen Sie stattdessen einmalig CLOSE auf.

Im Folgenden sind die Parameter der Actions beschrieben.

6.4.3.2      Action PROCESS

Die folgenden Parameter stehen zur Verfügung:

Parameter	Bedeutung
ObjectType (String)	Vollständiger Name des zu importierenden Business Entitys.
Database (String)	Datenbank-Alias. Verwenden Sie Konstanten des IDL-Interfaces „CorbaTransactionManager“.
FilterName (String)	Name des beim Import zu verwendenden persistenten Filter, der in der Anwendung „Daten importieren“ gespeichert wurde (optional). Wenn kein Filter angegeben wird, dann stehen alle Attribute und Assoziationen des Business Entitys zur Verfügung.
FilterXML	Nicht unterstützt.
NLSMode (short/Valueset)	Spracheinstellung für den Import ohne angegebenen Filter. Optional. Mögliche Werte: „NLS_MODE_SINGLE_LANGUAGE“ für „Einsprachig“ (Vorgabewert), „NLS_MODE_MULTI_LANGUAGE“ für „Mehrsprachig“. Verwenden Sie diesen Parameter nicht zusammen mit dem Parameter „FilterName“.
Content (byte[]/Binary)	Daten
WarningsMode (short/Valueset)	Gibt an, wie mit Warnungen, die beim Import auftreten, umgegangen wird. Mit dem Wert „WARNINGS_MODE_CONFIRM_NONE“ führen Warnungen zu Importfehlern und werden in die Fehler-Datei geschrieben. Mit dem Wert „WARNINGS_MODE_CONFIRM_ALL“ werden alle Warnungen, die bei diesem Importvorgang auftreten, ignoriert.
CorrectionMode (short/Valueset)	Gibt an, ob eine Korrektur fehlerhafter Daten in Semiramis erfolgen soll. Mit dem Wert „CORRECTION_MODE_NONE“ geben Sie an, dass keine Korrektur in Semiramis erfolgen soll. Die Fehler-Datei kann bei Bedarf über CORBA an den Client übertragen werden. Mit dem Wert „CORRECTION_MODE_WORKFLOW“ geben Sie an, dass eine Korrektur in Semiramis nach der Benachrichtigung durch den Workflow erfolgen kann. OhDie Fehler-Datei wird nicht an den Client übertragen. Bei ausgeschalteter Protokollierung (ProcessLogLevel) wird sie im Knowledge Store in den Ordner „kstore://<Arbeitsbereich>/Import/ RemoteErrorFiles“ abgelegt; als Arbeitsbereich wird der Standard-Arbeitsbereich der Datenbank, in die die Daten importiert wurden, verwendet. Bei eingeschalteter Protokollierung wird sie im Protokoll abgelegt. Beachten Sie, dass die Benachrichtigung durch den Workflow unabhängig von diesem Parameter erfolgen kann.
ProcessLogLevel	Gibt an, ob der Import protokolliert werden soll. Mit dem Wert „PROCESS_LOG_LEVEL_DISABLED“ ist die Protokollierung ausgeschaltet; dies ist auch der Vorgabewert. Mit dem Wert „PROCESS_LOG_LEVEL_ENABLED“ wird die Protokollierung eingeschaltet.

Rückgabe: Leere Parameterliste

Ein Fehler ist aufgetreten, wenn die zurückgebene Parameterliste null ist oder die Methode requiresAttention() an der „CorbaMessageQueue“ den Wert „true“ liefert. Dann kann der Importvorgang nicht weiter fortgeführt werden.

6.4.3.3      Action PROCESS_NEXT_BLOCK

Der folgende Parameter steht zur Verfügung:

Parameter	Bedeutung
Content (byte[]/Binary)	Daten

Rückgabe: Leere Parameterliste

Ein Fehler ist aufgetreten, wenn die zurückgebene Parameterliste null ist oder die Methode requiresAttention() an der „CorbaMessageQueue“ den Wert „true“ liefert. Dann kann der Importvorgang nicht weiter fortgeführt werden.

6.4.3.4      Action PROCESS_LAST_BLOCK

Der folgende Parameter steht zur Verfügung:

Parameter	Bedeutung
Content (byte[]/Binary)	Daten (optional)

Die Rückgabewerte im Einzelnen:

Wert	Bedeutung
ImportedObjectCount (int)	Anzahl erfolgereich importierter Objekte.
InvalidObjectCount (int)	Anzahl fehlerhafter, und daher nicht importierter Objekte.
NotCorrigibleObjectCount (int)	Anzahl der fehlerhaften Objekte, die nicht in einer Korrektur-Anwendung korrigiert werden können.
HasErrorFile (boolean)	„true“, falls eine Fehler-Datei zur Übertragung an den Client zur Verfügung steht.

Ob der Importvorgang erfolgreich war, kann durch Aufruf der Methode requiresAttention() an der CorbaMessageQueue festgestellt werden. Die CorbaMessageQueue enthält die Meldungen, die Teil der Rückgabe des Anwendungsaufrufes sind.

• Wenn die Methode requiresAttention()den Wert „false“ liefert, dann ist der Import erfolgreich gelaufen. Der Importvorgang ist beendet.
• Wenn die Methode requiresAttention()den Wert „true“ liefert, dann ist ein Fehler beim Import aufgetreten.
• Beachten Sie die zurückgegebenen Meldungen.
• An den zurückgegebenen Anzahlen können Sie verschiedene Fehlerfälle unterscheiden. Dies ist in der Dokumentation Einführung: Datenaustausch
• An den Rückgabeparametern können Sie erkennen, ob eine Fehler-Datei zur Übertragung an den Client zur Verfügung steht. Die Fehler-Datei kann mit nachfolgenden Aufrufen mit der Action GET_ERROR_FILE_NEXT_BLOCK übertragen werden.

Hinweis:

Beachten Sie, dass die zurückgelieferten Anzahlen unter bestimmten Umständen nicht exakt sind. Dies ist auch der Dokumentation Einführung: Datenaustausch beschrieben.

6.4.3.5      Action GET_ERROR_FILE_NEXT_BLOCK

Aufruf mit leerer Parameterliste.

Rückgabe:

Wert	Bedeutung
Content (byte[])	Daten, aktueller Block, falls vorhanden (optional).
ContentLength (int)	Länge der Daten dieses Blocks in Bytes (optional, falls Daten vorhanden).
HasNextBlock (boolean)	Wenn „true“, erneut aufrufen für den nächsten Block.

Falls keine Fehler-Datei vorhanden ist, ist der Rückgabewert null anstatt der Parameterliste.

Es ist möglich, dass der letzte Block der Fehler-Datei keine Daten enthält. Daher ist der Parameter „Content“ optional, und ein Client muss prüfen, ob er in der zurückgegebenen Parameterliste vorhanden ist.

6.4.3.6      Action CLOSE

Aufruf und Rückgabe: leere Parameterliste.

6.4.4          Entfernter Export mit CORBA

Für einen Exportvorgang wird der Name des zu exportierenden Business Entitys, die Datenbank, aus der die Daten exportiert werden sollen, optional ein Filter und Parametern für die Eingrenzung angegeben. Die Auswahl bestimmt die Menge der zu exportierenden Business-Entity-Instanzen und kann entweder durch eine OQL-Suche mit Auswahlparametern und Sortierung angegeben werden oder durch einen Dynamic OQL String, der denselben Zweck erfüllt.

Einen Filter, der für einen Exportvorgang verwendet werden soll, muss in der Anwendung „Daten exportieren“ (oder „Daten importieren“) erstellt und gespeichert worden sein. Angegeben wird der Name des Filters. Weitere Informationen finden Sie in den Dokumentationen Daten importieren und Daten exportieren.

Das XML-Dokument mit den exportierten Business-Entity-Instanzen wird blockweise an den Client übertragen. Die Blockgröße liegt bei ca. 500 kB.

6.4.4.1      Actions und Parameter

Die Hintergrund-Anwendung für den Export kann mit folgenden Actions aufgerufen werden:

Action	Bedeutung
EXPORT	Exportiert den ersten Block.
EXPORT_NEXT_BLOCK	Exportiert den 2. Block und alle weiteren Blöcke.
GET_SCHEMA	Liefert das XML-Schema. Das Schema wird in einem einzigen Block übertragen.
GET_FILTER_XML	Nicht unterstützt.
CLOSE	Bricht einen Export ab.

Die Vorgehensweise für den Export ist wie folgt:

1. Mit der Action EXPORT die Parameter für den Export übergeben. Das Ergebnis ist der erste Block.
2. Solange es weitere Blöcke gibt, werden diese mit der Action EXPORT_NEXT_BLOCK übertragen. Wenn es keinen weiteren Block gibt, ist der Exportvorgang abgeschlossen.

Um das XML-Schema zu exportieren, reicht es aus, einmal die Action GET_SCHEMA aufzurufen.

6.4.4.2      Action EXPORT

Die folgenden Parameter stehen zur Verfügung:

Parameter	Bedeutung
ObjectType (String)	Vollständiger Name des zu exportierenden Business Entitys.
Database (String)	Datenbank-Alias. Verwenden Sie Konstanten des IDL-Interfaces „CorbaTransactionManager“.
FilterName (String)	Name des beim Export zu verwendenden Filters, der in der Anwendung „Daten importieren“ gespeichert wurde. Optional. Wird kein Filter angegeben, stehen alle Attribute und Assoziationen des Business Entitys zur Verfügung. Bei großen Business Entitys sollte zur Begrenzung der Datenmenge ein Filter verwendet werden.
FilterXML	Nicht unterstützt.
NLSMode (short/Valueset)	Spracheinstellung für den Import ohne angegebenem Filter. Optional. Mögliche Werte:  „NLS_MODE_SINGLE_LANGUAGE“ für „Einsprachig“ (Vorgabewert), „NLS_MODE_MULTI_LANGUAGE“ für „Mehrsprachig“. Verwenden Sie diesen Parameter nicht zusammen mit dem Parameter „FilterName“.
SearchName (String)	Vollständiger Name der OQL-Suche. Wenn Sie keine OQL-Suche, sondern einen Dynamic OQL String verwenden, geben Sie hier nichts an.
SearchParameters (CisParameterList)	Suchparameter für die Eingrenzung mit OQL-Suche. Optional. Vorgabewert sind keine Suchparameter. Der Wert ist eine Parameterliste, die die Suchparameter enthält. Parametername ist jeweils der Name des Suchfeldes aus der OQL-Suche, Parameterwert ist jeweils der Selection-String. Geben Sie diejenigen Suchparameter an, die Sie für die Eingrenzung verwenden möchten. Die möglichen Selection-Strings sind vom Datentyp des Suchfeldes abhängig und im Dokument „Datenaustausch-Programmierschnittstellen“, Abschnitt „Format für Selection Strings“ beschrieben. Für eine Eingrenzung mit einer OQL-Anweisung wird dieser Parameter nicht verwendet.
SearchSortOrder (String)	Sortierung der exportierten Instanzen für die Eingrenzung mit OQL-Suche. Optional. Vorgabewert ist die in der OQL-Suche eingetragene Standardsortierung. Die Syntax der Sortierung ist im Dokument „Datenaustausch-Programmierschnittstellen“, Abschnitt „Format für die Sortierung“ beschrieben. Für eine Eingrenzung mit einer OQL-Anweisung wird dieser Parameter nicht verwendet.
DynamicOQLSearch (String)	Dynamic OQL String (alternativ zu OQL-Suche)
MaxObjects	Nicht unterstützt.
ProcessLogLevel	Gibt an, ob der Export protokolliert werden soll. Mit dem Wert „PROCESS_LOG_LEVEL_DISABLED“ ist die Protokollierung ausgeschaltet; dies ist auch der Vorgabewert. Mit dem Wert „PROCESS_LOG_LEVEL_ENABLED“ wird die Protokollierung eingeschaltet.

Rückgabe:

Wert	Bedeutung
Content (byte[])	Die Daten des ersten Blocks (optional).
ContentLength (int)	Länge der Daten dieses Blocks in Bytes (optional).
HasNextBlock (boolean)	Wenn true, gibt es weitere Blöcke, die mit weiteren Aufrufen mit der Action EXPORT_NEXT_BLOCK zurückgeliefert werden.
ExportedObjectCount (int)	Anzahl insgesamt exportierter Objekte (über alle Blöcke dieses Exports). Wird nur beim letzten Block zurückgeliefert.

Ein Fehler ist aufgetreten, wenn die zurückgebene Parameterliste null ist oder die Methode requiresAttention() an der CorbaMessageQueue true liefert. Dann kann der Exportvorgang nicht weiter fortgeführt werden.

Falls keine Business-Entity-Instanz exportiert werden konnte, weil z. B. keine Instanz den Suchparametern entsprach, sind die Rückgabeparameter Content und ContentLength nicht vorhanden.

6.4.4.3      Action EXPORT_NEXT_BLOCK

Aufruf: Leere Parameterliste

Rückgabe:

Wert	Bedeutung
Content (byte[]/Binary)	Daten, aktueller Block, falls vorhanden (optional).
ContentLength (int)	Länge der Daten des aktuellen Blocks in Bytes (optional).
HasNextBlock (boolean)	Wenn true, gibt es weitere Blöcke, die mit weiteren Aufrufen mit der Action EXPORT_NEXT_BLOCK zurückgeliefert werden.
ExportedObjectCount (int)	Anzahl insgesamt exportierter Objekte (über alle Blöcke dieses Exports). Wird nur beim letzten Block zurückgeliefert.

Es ist möglich, dass der letzte Block keine Daten enthält. Daher ist der Parameter Content optional und ein Client muss prüfen, ob er in der zurückgegebenen Parameterliste vorhanden ist.

Alle möglichen Fehlerfälle müssen genau so geprüft werden wie bei der Action EXPORT (siehe Abschnitt Action EXPORT).

6.4.4.4      Action GET_SCHEMA

Die folgenden Parameter stehen zur Verfügung:

Parameter	Bedeutung
ObjectType (String)	Vollständiger Name des Business Entitys
FilterName (String)	Name eines Filters, auf dessen Basis das Schema erzeugt wird. Optional. Vorgabewert: Schema mit allen Attribute und Beziehungen.
NLSMode (short/Valueset)	Spracheinstellung für das Schema ohne angegebenem Filter. Optional. Mögliche Werte: „NLS_MODE_SINGLE_LANGUAGE“für „Einsprachig“ (Vorgabewert), „NLS_MODE_MULTI_LANGUAGE“ für „Mehrsprachig“. Verwenden Sie diesen Parameter nicht zusammen mit dem Parameter „FilterName“.

Rückgabe:

Wert	Bedeutung
Content (byte[]/Binary)	Daten
ContentLength (int)	Länge der Daten in Byte.

Ein Fehler ist aufgetreten, wenn die zurückgebene Parameterliste null ist oder die Methode requiresAttention() an der CorbaMessageQueue true liefert. Dann kann der Vorgang nicht weiter fortgeführt werden.

6.4.4.5      Action CLOSE

Aufruf und Rückgabe: leere Parameterliste

6.4.5          Entfernte Suche mit CORBA

Die Suchfunktion basiert auf einer OQL-Suche. Zur Eingrenzung des Suchergebnisses können die Selektionsfelder der OQL-Suche verwendet werden. Die Sortierung des Ergebnisses kann ebenfalls angegeben werden. Das Ergebnis der Suche besteht für jede Ergebniszeile aus den Rückgabefeldern der OQL-Suche.

Das Suchergebnis wird seitenweise übertragen, wobei jede Seite durch einen eigenen Anwendungsaufruf übertragen wird.

Die Suche bietet im Gegensatz zum Import bzw. Export sowohl ein benutzerspezifisches als auch ein technisches Format für die Selektionsparameter und die Suchergebnisse an.

6.4.5.1      Actions und Parameter

Die folgenden Actions stehen zur Verfügung:

Action	Bedeutung
SEARCH	Suche nach passenden Datensätzen, Rückgabe als XML.
SEARCH_NEXT_PAGE	Suche wiederaufsetzen, nächsten Block.
EXISTS	Abfrage, ob mindestens ein Datensatz passend zur Abfrage existiert (Existenzprüfung). Wenn ja, werden die Attribute dieses Datensatzes zurückgeliefert.
CLOSE	Schließt eine Suche vor Erreichen der letzten Ergebnisseite ab.

Vorgehensweise für eine Suche mit Rückgabe aller Suchseiten:

1. Aufruf mit Action SEARCH und der Angabe der Suchparameter. Zurückgegeben wird die erste Ergebnisseite.
2. Alle weiteren Ergebnisseiten mit der Action SEARCH_NEXT_PAGE abfragen.

6.4.5.2      Action SEARCH

Die folgenden Parameter stehen zur Verfügung:

Parameter	Bedeutung
SearchName (String)	Vollständiger Name der OQL-Suche.
SearchParameters (CisParameterList)	Suchparameter für die Eingrenzung mit OQL-Suche. Optional. Vorgabewert sind keine Suchparameter. Der Wert ist eine Parameterliste, die die Suchparameter enthält. Parametername ist jeweils der Name des Suchfeldes aus der OQL-Suche, Parameterwert ist jeweils der Selection-String. Geben Sie diejenigen Suchparameter an, die Sie für die Eingrenzung verwenden möchten. Die möglichen Selection-Strings sind vom Datentyp des Suchfeldes abhängig und sind in diesem Dokument, Abschnitt „Datentypen in der Suche“ beschrieben.
SearchSortOrder (String)	Sortierung der exportierten Instanzen für die Eingrenzung mit OQL-Suche. Optional. Vorgabewert ist die in der OQL-Suche eingetragene Standardsortierung. Die Syntax der Sortierung ist im Dokument „Datenaustausch-Programmierschnittstellen“, Abschnitt „Format für die Sortierung“ beschrieben.
Database (String)	Datenbank-Alias. Verwenden Sie Konstanten des IDL-Interfaces „CorbaTransactionManager“.
SearchParametersFormat (int)	Gibt an, in welchem Format Suchparameter angegeben sind. Verwenden Sie die Konstanten des IDL-Interfaces „CorbaRemoteSearch“.
SearchResultFormat (int)	Gibt an, in welchem Format Attribute in den Suchergebnissen zurückgegeben werden. Verwenden Sie die Konstanten des IDL-Interfaces „CorbaRemoteSearch“.
PageSize (int)	Anzahl Zeilen pro Ergebnisseite. Optional, Vorgabewert: 10

Für die beiden Parameter zur Formatierung gibt es die folgenden Konstanten:

• FORMAT_USER_DEPENDENT: Benutzerspezifisches Format
• FORMAT_TECHNICAL: Technisches Format

Rückgabe:

Wert	Bedeutung
Content (byte[]/Binary)	Suchergebnis (erste Ergebnisseite) als XML-Dokument.
HasNextPage (boolean)	True, wenn es weitere Ergebnisseiten gibt.
CurrentPageNumber (int)	Nummer der aktuell übertragenen Seite.
CurrentObjectCount (int)	Anzahl der bisher insgesamt übertragenen Datensätze.

Ein Fehler ist aufgetreten, wenn die zurückgebene Parameterliste null ist oder die Methode requiresAttention() an der CorbaMessageQueue true liefert. Dann kann der Suchvorgang nicht weiter fortgeführt werden.

6.4.5.3      Action SEARCH_NEXT_PAGE

Aufruf mit leerer Parameterliste

Rückgabe:

Wert	Bedeutung
Content (byte[]/Binary)	Suchergebnis (aktuelle Ergebnisseite) als XML-Dokument.
HasNextPage (boolean)	True, wenn es weitere Ergebnisseiten gibt.
CurrentPageCount (int)	Nummer der aktuell übertragenen Seite.
CurrentObjectCount (int)	Anzahl der bisher insgesamt übertragenen Datensätze.

Ein Fehler ist aufgetreten, wenn die zurückgebene Parameterliste null ist oder die Methode requiresAttention() an der CorbaMessageQueue true liefert. Dann kann der Suchvorgang nicht weiter fortgeführt werden.

6.4.5.4      Action EXISTS

Die folgenden Parameter stehen zur Verfügung:

Parameter	Bedeutung
SearchName (String)	Vollständiger Name der OQL-Suche.
SearchParameters (CisParameterList)	Suchparameter für die Eingrenzung mit OQL-Suche. Optional. Vorgabewert sind keine Suchparameter. Der Wert ist eine Parameterliste, die die Suchparameter enthält. Parametername ist jeweils der Name des Suchfeldes aus der OQL-Suche, Parameterwert ist jeweils der Selection-String. Geben Sie diejenigen Suchparameter an, die Sie für die Eingrenzung verwenden möchten. Die möglichen Selection-Strings sind vom Datentyp des Suchfeldes abhängig und in diesem Dokument, Abschnitt „Datentypen für die Suche“ dokumentiert.
Database (String)	Datenbank-Alias. Verwenden Sie Konstanten des IDL-Interfaces „CorbaTransactionManager“.
SearchParametersFormat (int)	Gibt an, in welchem Format Suchparameter angegeben sind. Verwenden Sie die Konstanten des IDL-Interfaces „CorbaRemoteSearch“.

Rückgabe:

Wert	Bedeutung
ResultObject (CisParameterList)	Gefundenes Objekt als weitere Parameterliste, die die Attribute des Objekts enthält. Die Attribute des gefundenen Objekts sind als native Datentypen in der Parameterliste enthalten. Komplexe Datentypen werden nicht unterstützt. Wurde kein Objekt gefunden, ist dieser Parameter nicht angegeben, d.h. die Methode „containsParameter()“ liefert den Wert „false“).

Ein Fehler ist aufgetreten, wenn die zurückgebene Parameterliste null ist oder die Methode requiresAttention() an der CorbaMessageQueue „true“ liefert. Dann kann der Suchvorgang nicht weiter fortgeführt werden.

6.4.5.5      Action CLOSE

Aufruf und Rückgabe: leere CisParameterList.

7                     Beispiel-Clients

Mit Semiramis werden Test-Clients ausgeliefert, die die Verwendung der entfernten BIS-Schnittstellen demonstrieren. Die Testclients sind Bestandteil des Semiramis-Anwendungscodes. Der Sourcecode ist ebenfalls enthalten, wenn Sie das Semiramis Software Development Kit (SDK) lizenziert haben.

Die Test-Clients können sowohl von der Toolshell als auch unabhängig vom Semiramis Application Server aufgerufen werden. Folgen Sie dazu der Anleitung in im Kapitel Start des Test-Clients und ersetzen Sie dabei den Toolnamen bzw. Klassennamen entsprechend durch die im Folgenden angegebenen Namen.

Einige Test-Clients haben weitere Parameter, die über die in der Dokumentation „CORBA-Schnittstelle“ beschriebenen Parameter hinausgehen. Diese Parameter sind im Sourcecode und im JavaDoc dokumentiert.

Folgende Test-Clients stehen zur Verfügung:

• Export

Toolname:    CorbaRemoteExportTestClient

Java-Klasse: com.cisag.app.system.corba.log.CorbaRemoteExportTestClient

• Schema-Export

Toolname:    CorbaRemoteSchemaExportTestClient

Java-Klasse: com.cisag.app.system.corba.log.CorbaRemoteSchemaExport-
TestClient

• Import

Toolname:    CorbaRemoteImportTestClient

Java-Klasse: com.cisag.app.system.corba.log.CorbaRemoteImportTestClient

Hinweis:
Dieser Testclient schreibt Daten in die OLTP-Datenbank, an die er mittels der Parameter angemeldet wird. Daher sollten Sie ihn nicht für OLTP-Datenbanken im Produktivbetrieb verwenden. Im Sourcecode ist die Funktionsweise des Clients dokumentiert.

• Suche

Toolname:    CorbaRemoteSearchTestClient

Java-Klasse: com.cisag.app.system.corba.log.CorbaRemoteSearchTestClient

Der Sourcecode für den in Java geschriebenen CORBA-Test-Client ist über die Anwendung „Entwicklungsobjekte“ verfügbar

Die Klassen sind im Sourcecode ausführlich dokumentiert. Zu beachten ist, dass die Beispiel-Implementierungen die generierten Klassen aus der Semiramis System Engine sowie einige Klassen der PGM-Schnisttstelle verwenden, damit sie möglichst einfach sowohl auf der Toolshell als auch ohne eine Toolshell aufgerufen werden können. Für die Erstellung eines alleinstehenden CORBA-Clients kann auf diese Bestandteile verzichtet werden.

7.1               Vorgehen

Um den Test-Client auszuführen, folgen Sie dieser Anleitung.

7.1.1          Start des Servers

In der Semiramis Toolshell: strscs –host:localhost –port:2000

7.1.2          Start des Test-Clients

Der Test-Client ist als eine Menge von Entwicklungsobjekte in der Standardauslieferung enthalten. Neben den Java-Klassen ist für ihn eine Anwendung vom Typ „Tool“ definiert. Der Start des Test-Clients erfolgt auf der Toolshell durch

CorbaTestClient -host:localhost -port:2000 -userName:<Benutzer> -password:<Kennwort> -oltpDatabaseName:<OLTP-Datenbank>

Die vom Test-Client entfernt aufgerufene Hintergrundanwendung übergibt die eingehenden Anwendungsparameter als Rückgabewerte im Aufrufergebnis. Zusätzlich sendet sie eine Meldung vom Typ Fehler. Rückgabewerte und Fehlermeldung werden auf der Konsole ausgegeben.

Sie können den Test-Client auch außerhalb der Toolshell aufrufen. Dafür müssen Sie lediglich JacORB (jacorb.jar, avalon-framework.jar und logkit.jar), die Semiramis-System-Engine und den Anwendungscode in den Klassenpfad aufnehmen. Der Aufruf ist dann wie folgt:

java com.cisag.app.system.corba.log.CorbaTestClient
-Dorg.omg.CORBA.ORBClass=org.jacorb.orb.ORB
-Dorg.omg.CORBA.ORBSingletonClass=org.jacorb.orb.ORBSingleton
-cp <Klassenpfad>
-host:<host>
-port:<port>
–userName:<Benutzer>
-password:<Kennwort>
-oltpDatabaseName:<OLTP-Datenbank>

7.1.3          Fehlermeldungen

Sollten Sie eine Fehlermeldung der Form “org.omg.CORBA.COMM_FAILURE:   vmcid: SUN  minor code: 201  completed: No” erhalten, so prüfen Sie Parameter von CORBA-Server und CORBA-Client sowie die Kommunikation zwischen beiden. Falls Fehler beim Anmelden des CORBA-Clients oder bei der Ausführung der Hintergrundanwendungen auf dem Semiramis Application Server auftreten, werden diese abhängig von ihrer Schwere auch in den Meldungsprotokollen gespeichert und können dort eingesehen werden.

Hinweis:

Microsoft Word konvertiert bei den Operationen Kopieren (Strg+C) und Paste (Strg+V) das Zeichen – (Minus) unter Umständen nach – (Bindestrich). Da manche Programme keine Prüfung auf den angegebenen Parametern durchführen, kann dies dazu führen, dass die Programme mit anderen als den tatsächlich angegebenen Parametern laufen und so beispielsweise keine Kommunikation mit dem ORB möglich ist. Prüfen Sie in diesem Fall die Eingabe in der Kommandozeile.

 

8                     CORBA und Firewalls

CORBA realisiert eine objektorientierte und damit zustandsbasierte Architektur. Hierbei stellt die Unabhängigkeit eines Objektes von dem konkreten Ort, an dem es zur Verfügung gestellt wird, ein Grundprinzip dar. Daraus ergeben sich im Wesentlichen zwei Anforderungen an die Kommunikation zwischen einem CORBA-Server und einem CORBA-Client:

• Da Client und Server welchselseitig Objektreferenzen austauschen, muss der Client Aufrufe aktiv auf den Server weiterreichen können und umgekehrt der Server auch aktiv Aufrufe auf den Client weiterreichen können. Die Rollen „Client“ und „Server“ sind somit nach dem initialen Aufbau einer Verbindung praktisch irrelevant.
• Objektreferenzen und die darüber adressierten Objekte stellen per Definition einen Zustand dar. Damit ist die Verwendung eines zustandsbehafteten Kommunikationsprotokolls notwendig.

Probleme bei der Kommunikation zwischen CORBA-Clients und –Servern werden häufig durch Firewalls verursacht, die im Netzwerk auf dem Weg zwischen Client und Server positioniert sind. Firewalls lassen häufig nur bestimmte Netzwerkprotokolle passieren, sodass zwar eine Dialog-Anmeldung an Semiramis über „https://“ möglich ist, aber ein CORBA-Client nicht über „iiop://“ auf Semiramis zugreifen kann.

Das Passieren von Firewalls ist bei CORBA teilweise problematischer als bei anderen Netzwerkprotokollen. Das liegt am verwendeten Protokoll und hat folgende Ursachen:

• CORBA-Implementierungen vergeben selbst Portnummern zur Laufzeit. Da diese Portnummern nicht vorhersagbar sind, können sie auch nicht in portbasierten Firewalls als zugelassene Ports konfiguriert werden.
• Objektreferenzen enthalten eine IP-Adresse und eine Portnummer, wenn sie über das Netzwerk übertragen werden, damit die ORB-Implementierung auf Empfängerseite das jeweilige Objekt direkt ansprechen kann. Die Verwendung von NAT (Network Address Translation) auf einem Router bzw. Firewall führt jedoch dazu, dass ein Rechner in verschiedenen Netzwerksegmenten mit unterschiedlichen Adressen ansprechbar ist und damit eine im Protokoll übertragene IP-Adresse auf Empfängerseite nicht mehr gültig ist.
• CORBA verwendet häufig Callbacks vom Server zum Client. Dafür muss der Client auch für den Server erreichbar sein, was in vielen Firewalls verhindert wird.

Auf die Verwendung von Firewalls sollte aus Sicherheitsgründen keinesfalls verzichtet werden. Um die oben genannten Probleme zu lösen, bieten verschiedene Hersteller sogenannte „Application Security Gateways“ an. Diese stellen speziell auf CORBA zugeschnittene Produkte dar, die nicht auf der Ebene von IP-Adressen, sondern auf der Ebene von CORBA-Objektreferenzen Authentifzierungs-, Sicherheits- und Routing-Mechanismen anbieten.

9                     Schutz gegen Ressourcenengpässe

Jede Session, die ein Client über CORBA auf einem Semiramis-System öffnet, verbraucht Ressourcen wie Speicher, Rechenzeit und Datenbankverbindungen auf dem Application-Server, zu dem sich der Client verbindet. Falls für ein Szenario sehr viele Clients erforderlich sind, die alle ständig mit dem CORBA-Server verbunden sind, kann es zu Engpässen an Ressourcen kommen. Kritische Ressourcen sind in diesem Fall vor allem die CORBA-Sessions (und die Datenbankverbindungen). Jede CORBA-Session belegt ab dem Zeitpunkt ihrer Erzeugung einen Semiramis-Thread, d. h. Heap-Speicher für den Threadstack und native Ressourcen je nach Betriebssystem. Während der Abarbeitung einer CORBA-Anfrage verwendet der ORB einen Thread aus seinem Pool, um die Anfrage entgegen zu nehmen, und leitet diese an den Semiramis-Thread weiter. Wenn für die Bearbeitung der CORBA-Anfrage Daten von der Datenbank gelesen werden müssen, werden zusätzlich zeitweise Datenbankverbindungen belegt.

Speicher, Threads und Datenbankverbindungen sind auf dem Application-Server begrenzte Ressourcen. Ein Ressourcenengpass führt zu längeren Bearbeitungszeiten eines CORBA-Aufrufes. Im schlimmsten Fall kann die Stabilität des Application-Servers insgesamt gefährdet sein.

Um Ressourcenengpässe zu vermeiden, gibt es mehrere Möglichkeiten. Die Grundidee dabei ist, den Zugriff auf kritische Ressourcen zu koordinieren, um zu viele gleichzeitige Zugriffe zu vermeiden.

In der ersten Lösungsmöglichkeit (Abbildung 1) werden mehrere CORBA-Server, d. h. Semiramis Application Server verwendet, auf die die Zugriffe der Clients verteilt werden. Dadurch wird der Speicherverbrauch pro Application-Server verringert. Allerdings kann es bei dieser Lösung zu einer hohen Beanspruchung der Datenbank kommen, falls viele Anfragen zur selben Zeit an die Application Server gelangen.

Abbildung 1: Mehrere CORBA-Server

In der 2. Lösungsmöglichkeit (Abbildung 2) wird ein eigenständiger, von Semiramis unabhängiger Prozess („CORBA Proxy Queue“) verwendet. Die Anfragen der Clients gehen zunächst an diesen Prozess, der sie in eine Warteschlange einreiht und dann eine begrenzte Anzahl von ihnen gleichzeitig an Semiramis weitergibt. Damit sind die Zahl von CORBA-Sessions und die Zahl der Datenbankverbindungen in Semiramis begrenzt. Die „CORBA Proxy Queue“ agiert sowohl als CORBA-Server als auch als –Client. Die Implementierung einer solchen Queue kann daher in einer beliebigen Sprache erfolgen, die auf den Anwendungsfall abgestimmt ist.

 

Abbildung 2: CORBA Proxy Queue

Bei beiden vorgestellten Lösungen wird davon ausgegangen, dass jeder Prozess auf einem eigenen Rechner läuft und dessen begrenzte Ressourcen damit exklusiv zur Verfügung hat. Auch eine „CORBA Proxy Queue“ sollte immer auf einem eigenen Rechner laufen.

Schon bei der Entwicklung einer Anbindung an Semiramis über CORBA sollten Tests unter Berücksichtigung der zu erwartenden Anzahl an Clients durchgeführt werden. Dabei können Sie feststellen, ob Maßnahmen zum Ressourcenschutz im konkreten Fall notwendig sind.