Beschreibung der optionalen Parameter

<database>.jdbc.SCHEMA

Dieser Parameter definiert das von FirstSpirit zu verwendende Schema auf dem DBMS (Datenbank-Management-System). Ein Schema wird häufig auch als „Datenbank“ bezeichnet. Unter Oracle entspricht es einem normalen Benutzerkonto, bei anderen DBMS, z. B. PostgreSQL, kann ein normales Benutzerkonto auch mehrere Schemata umfassen.

Sofern dieser Parameter definiert ist, handelt es sich um einen Standard-Layer. In einem FirstSpirit-Projekt, dem ausschließlich Standard-Layer zugeordnet sind, kann ein FirstSpirit-Benutzer keine neuen zusätzlichen Schemata anlegen. Nur der FirstSpirit-Administrator kann dem Projekt weitere Layer hinzufügen.

Um das Anlegen weiterer Schemata auch FirstSpirit-Benutzern zu ermöglichen, wird ein sogenannter DBA-Layer benötigt, der bei den meisten DBMS aber DBA-Rechte (DBA = Database Administrator) benötigt. Bei einem DBA-Layer ist der SCHEMA-Parameter nicht eingetragen. Über einen DBA-Layer kann der FirstSpirit-Benutzer dann selbständig neue Standard-Layer erzeugen.

Weitere Details zu den Unterschieden von Standard-Layer und DBA-Layer sowie deren Vor- und Nachteilen entnehmen Sie bitte Schema hinzufügen (→Online Dokumentation FirstSpirit).

Beispiel:

database.jdbc.SCHEMA=warendatenbank		

<database>.jdbc.POOLMAX

FirstSpirit nutzt für jede Verwendung, z. B. einen Schema-Knoten in einem Projekt, eine deployte Web-Applikation (z. B. FirstSpirit DynamicDatabaseAccess) usw., eine eigene Pool-Instanz.
POOLMAX definiert die Anzahl der maximal parallel offenen Verbindungen zur Datenbank.

content1.jdbc.POOLMAX=15

POOLMAX muss mindestens der Wert von POOLMIN + 4 sein. Trifft dies nicht zu, wird der Wert automatisch angepasst und eine entsprechende Warnung geloggt.

<database>.jdbc.POOLMIN

POOLMIN definiert die minimale Anzahl der vorgehaltenen DB-Verbindungen pro Pool.

content1.jdbc.POOLMIN=10

Ist kein Wert angegeben, werden 5 DB-Verbindungen pro Pool vorgehalten.

<database>.jdbc.FETCH_CONNECTION_TIMEOUT

Ist der Wert von POOLMAX erreicht, wird standardmäßig 5 Sekunden auf eine freie Verbindung gewartet. Danach kommt es zu einer Exception an der verwendenden Stelle (z. B. Client, Generierung). Die Zeitspanne, die auf eine freie Verbindung gewartet wird, kann über den Parameter FETCH_CONNECTION_TIMEOUT konfiguriert werden (Angabe in Millisekunden).

content1.jdbc.FETCH_CONNECTION_TIMEOUT=6000

<database>.jdbc.POOLCYCLE

Mit dem Parameter POOLCYCLE wird das Zeitintervall (in Sekunden) definiert, mit dem FirstSpirit abgelaufene DB-Verbindung aus dem Pool entfernt. Eine DB-Verbindung wird als abgelaufen betrachtet, wenn entweder POOLTIMEOUT oder CONNECTIONTIMEOUT abgelaufen ist. Wird kein Wert angegeben, wird der kleinste von FirstSpirit akzeptierte Wert – 90 Sekunden – gesetzt.

content1.jdbc.POOLCYCLE=120

<database>.jdbc.POOLTIMEOUT

Mit dem Parameter POOLTIMEOUT wird das Zeitintervall (in Sekunden) definiert, die der FirstSpirit-Server eine DB-Verbindung nutzen kann. Falls er die Verbindung nach Ablauf dieser Zeit nicht freigegeben hat, wird sie automatisch geschlossen. Wird kein Wert angegeben, wird standardmäßig der Wert "180" gesetzt.

content1.jdbc.POOLTIMEOUT=240

<database>.jdbc.CONNECTIONTIMEOUT

Mit dem Parameter CONNECTIONTIMEOUT wird das Zeitintervall (in Sekunden) definiert, nachdem eine DB-Verbindung vom FirstSpirit-Server als veraltet betrachtet und geschlossen wird. Wird kein Wert angegeben, wird standardmäßig ein Timeout von 30 Minuten (Wert 1800) verwendet. Bei einem Wert <= 0 wird der Timeout deaktiviert. Dieser Wert muss immer kleiner sein als das Idle-Timeout des Datenbank-Servers, das normalerweise einige Stunden beträgt.
Beispiel, um den Timeout auf 15 Minuten einzustellen:

content1.jdbc.CONNECTIONTIMEOUT=900

<database>.jdbc.CONNECTIONRETRY

Beim Ausführen einer SQL-Abfrage, versucht FirstSpirit eine Verbindung aus dem Connection-Pool zu benutzen. Falls keine freien Verbindungen vorhanden sind, wird versucht eine neue Verbindung zur Datenbank aufzubauen. Dabei können Anfragen abgewiesen werden (z. B. aufgrund der Datenbank-Konfiguration). Mit dem Parameter CONNECTIONRETRY wird die Anzahl der Verbindungsversuche zur Datenbank definiert. Wird die Anzahl überschritten, bricht ein fehlgeschlagener Verbindungsversuch mit einer Fehlermeldung ab. Wird kein Wert angegeben, wird standardmäßig der Wert "5" gesetzt.

content1.jdbc.CONNECTIONRETRY=3

<database>.jdbc.CONNECTIONRETRYCYCLE

Nach einem fehlgeschlagenen Versuch, eine Verbindung zur Datenbank aufzubauen, wartet der ORMapper die in CONNECTIONRETRYCYCLE angegebene Zeit (in ms), bevor er einen neuen Versuch startet. Wird kein Wert angegeben, wird standardmäßig der Wert "300" gesetzt.

content1.jdbc.CONNECTIONRETRYCYCLE=500

<database>.jdbc.MAXSTRINGLENGTH

Der Parameter MAXSTRINGLENGTH legt die maximale Anzahl der Zeichen einer VARCHAR-Spalte beim Erstellen einer neuen Datenbank-Tabelle fest. Wenn für ein String-Attribut ein größerer Wert angegeben wird, als über den Parameter MAXSTRINGLENGTH definiert, wird ein anderer Datentyp (z. B. BLOB, CLOB oder TEXT) zur Speicherung in der Datenbank genutzt. Ist hier kein Wert gesetzt, wird abhängig von der verwendeten Datenbank ein Standardwert gesetzt.

content1.jdbc.MAXSTRINGLENGTH=8191

Der Parameter MAXSTRINGLENGTH wird für die folgenden Datenbanken unterstützt:

• PostgreSQL
• Oracle 19c

Für PostgreSQL gilt:

• Standardwert: Ist kein Wert über MAXSTRINGLENGTH definiert, wird der Standardwert 255 verwendet.
• Maximalwert: Von einer Definition von Werten größer als 65534 wird abgeraten

Für Oracle 19c gilt:

• Standardwert: Ist kein Wert über MAXSTRINGLENGTH definiert, wird der Standardwert 2000 verwendet.
• Empfehlung: Je nach Zeichensatz (Parameter jdbc.oracle.CHARACTERSET), ist eine Anpassung der Zeichenlänge sinnvoll. Für Oracle 19c wird z.B. der Zeichensatz AL32UTF8 mit der Zeichenlänge 8191 empfohlen. Der empfohlene Wert für den jeweiligen Zeichensatz kann der nachfolgenden Tabelle entnommen werden.
• Voraussetzung: Damit überhaupt mehr als 4000 Bytes (bei AL32UTF8 mit bis zu 4 Bytes pro Zeichen im ungünstigsten Fall nur 1000 Zeichen) pro Spalte gespeichert werden können, muss in der Datenbank der Wert MAX_STRING_SIZE auf EXTENDED gesetzt sein.
• Maximalwert: Werden Werte für den Parameter angegeben, die größer als der empfohlene Wert des angegebenen Zeichensatzes (Parameter jdbc.oracle.CHARACTERSET) sind, so wird eine entsprechende Meldung im Server-Log protokolliert. Der Maximalwert für den jeweiligen Zeichensatz kann der nachfolgenden Tabelle entnommen werden.
  • Bei Werten, die größer als der Maximalwert des angegebenen Zeichensatzes sind, wird ein ERROR geloggt und der Wert auf den Maximalwert verringert.
  • Bei Werten, die größer als der empfohlene Wert und kleiner als der Maximalwert des angegebenen Zeichensatzes sind, wird eine entsprechende WARN Meldung geloggt, in der die empfohlene Größe ausgegeben wird.

Werte für Oracle 19c (abhängig vom Zeichensatz):

<database>.jdbc.JNDI

Läuft der ORMapper innerhalb eines Web-Containers oder innerhalb eines Applikation-Servers, kann eine Datenbankverbindung über einen DataSource geholt werden. Damit nutzt der ORMapper die Pooling-Kapazität des Web-Containers. Der Parameter JNDI legt den JNDI-Namen des benutzten DataSource fest.

database.jdbc.JNDI=java:comp/env/jdbc/ORMapper

<database>.jdbc.isolation

Durch parallel laufende Transaktionen, die Änderungen an Daten der Datenbank vornehmen, können undefinierte Zustände entstehen. Um zu vermeiden, dass eine laufende Transaktion durch eine parallel ablaufende Transaktion (durch eine Änderung der verwendeten Daten) in einen undefinierten Zustand versetzt wird, sollte eine Transaktionsisolation konfiguriert werden. Mithilfe des Parameters können unterschiedliche Isolationslevel konfiguriert werden. Generell unterstützt werden:

• READ_COMMITTED: Niedrigstes Isolationslevel.
• REPEATABLE_READ: Mittleres Isolationslevel.
• SERIALIZABLE: Höchstes Isolationslevel (Standardwert).

Hinweis: Nicht jedes Datenbankmanagementsystem unterstützt alle Isolationslevel. So unterstützt beispielsweise eine OracleDB 11 nur die beiden Isolationslevel READ_COMMITTED und SERIALIZABLE, nicht aber REPEATABLE_READ. Im Einzelfall sollte die Dokumentation der entsprechenden Datenbank zu Rate gezogen werden.

database.jdbc.isolation=READ_COMMITTED

<database>.jdbc.property

Mit verschiedenen jdbc.property-Parametern können weitere Verbindungseinstellungen vorgenommen werden. Beispiele:

Es gibt auch datenbankspezifische Properties, wie z.B. für PostgreSQL:

jdbc.property.defaultRowFetchSize=5000

oder für Oracle Database:

jdbc.property.oracle.net.ssl_version=1.2

<database>.jdbc.property.defaultRowFetchSize (nur PostGreSQL)

Zur Optimierung der Speicherverwaltung bei der Nutzung einer PostGreSQL-Datenbank wird dem Treiber eine defaultRowFetchSize von 5000 übergeben.

Dieser Standardwert kann bei Bedarf in der Datenbankkonfiguration (im ServerManager unter Servereigenschaften - Datenbanken) über den Parameter jdbc.property.defaultRowFetchSize geändert werden.

Der Parameter jdbc.property.defaultRowFetchSize definiert die Anzahl der Zeilen, die von der Datenbank in einem Trip geliefert werden.

Hohe Werte sind bei großen Datenbankanfragen performanter, benötigen aber auch mehr Speicher in der Java VM und können zu Speicherproblemen bis zu OutOfMemory Exceptions führen.

Weitere Informationen siehe: https://jdbc.postgresql.org/documentation/head/connect.html

module

Wird ein FirstSpirit-Modul als JDBC-Treiber verwendet, muss über diesen Parameter der Name des JDBC-Treiber-Moduls angegeben werden.

database.module=JDBC_PostgreSQL_9_3