Signatur
Beschreibung
ZookeeperSessionException ist eine spezialisierte Ausnahme-Klasse aus der PHP-ZooKeeper-Erweiterung, die Fehler im Zusammenhang mit der Sitzungsverwaltung des ZooKeeper-Dienstes behandelt. Sie wird geworfen, wenn eine bestehende ZooKeeper-Sitzung abgelaufen ist, die Verbindung unterbrochen wurde oder die Sitzungs-ID ungültig geworden ist.
Diese Ausnahme erbt von ZookeeperException und steht am Ende der Vererbungskette unterhalb von RuntimeException. Sie ermöglicht es, Sitzungsfehler gezielt von anderen ZooKeeper-Fehlern zu unterscheiden und entsprechend zu behandeln.
Typische Szenarien, in denen diese Ausnahme auftritt, sind: Netzwerkunterbrechungen, die länger als das konfigurierte Sitzungs-Timeout dauern, explizit abgelaufene Sitzungen durch den ZooKeeper-Server oder der Versuch, auf eine bereits geschlossene Verbindung zuzugreifen. In verteilten Systemen ist es wichtig, diese Fehler korrekt zu behandeln, um Inkonsistenzen zu vermeiden.
Eine robuste Fehlerbehandlung sollte beim Abfangen dieser Ausnahme prüfen, ob die Sitzung neu aufgebaut werden muss, und alle Ephemeral Nodes sowie Watches neu registrieren, da diese beim Ablauf einer Sitzung automatisch gelöscht werden.
Beispiele
Sitzungsfehler gezielt abfangen und Verbindung neu aufbauen
<?php
function verbindeZooKeeper(string $host, int $timeout = 10000): Zookeeper
{
return new Zookeeper($host, null, $timeout);
}
$zk = null;
try {
$zk = verbindeZooKeeper('localhost:2181');
// Daten lesen – kann fehlschlagen, wenn Sitzung abgelaufen ist
$daten = $zk->get('/mein/pfad');
echo "Daten: " . $daten . PHP_EOL;
} catch (ZookeeperSessionException $e) {
echo "Sitzungsfehler: " . $e->getMessage() . PHP_EOL;
echo "Sitzung abgelaufen – versuche erneut zu verbinden..." . PHP_EOL;
try {
// Neue Sitzung aufbauen
$zk = verbindeZooKeeper('localhost:2181');
// Watches und Ephemeral Nodes neu registrieren!
echo "Verbindung erfolgreich wiederhergestellt." . PHP_EOL;
} catch (ZookeeperException $e) {
echo "Reconnect fehlgeschlagen: " . $e->getMessage() . PHP_EOL;
}
} catch (ZookeeperException $e) {
echo "Allgemeiner ZooKeeper-Fehler: " . $e->getMessage() . PHP_EOL;
}Differenzierte Fehlerbehandlung mit mehreren ZooKeeper-Ausnahmen
<?php
function leseKnoten(Zookeeper $zk, string $pfad): ?string
{
try {
$wert = $zk->get($pfad);
return $wert !== false ? $wert : null;
} catch (ZookeeperSessionException $e) {
// Sitzung abgelaufen – kritischer Fehler, der Neuverbindung erfordert
error_log('[ZK] Sitzung abgelaufen: ' . $e->getMessage());
throw $e; // weiterwerfen, damit Aufrufer reagieren kann
} catch (ZookeeperNoNodeException $e) {
// Knoten existiert nicht – kein kritischer Fehler
return null;
} catch (ZookeeperException $e) {
// Sonstige ZooKeeper-Fehler
error_log('[ZK] Fehler beim Lesen von ' . $pfad . ': ' . $e->getMessage());
return null;
}
}
try {
$zk = new Zookeeper('localhost:2181');
$konfigWert = leseKnoten($zk, '/app/config/db_host');
echo "DB-Host: " . ($konfigWert ?? 'nicht gesetzt') . PHP_EOL;
} catch (ZookeeperSessionException $e) {
echo "Kritisch: Sitzung ungültig, Neustart erforderlich." . PHP_EOL;
exit(1);
}// Wichtig · Fallstricke
Wichtiger Hinweis zu Ephemeral Nodes: Wenn eine ZooKeeper-Sitzung abläuft, werden alle Ephemeral Nodes, die diese Sitzung erstellt hat, automatisch gelöscht. Nach dem Aufbau einer neuen Sitzung müssen diese Knoten explizit neu erstellt werden, da sie nicht automatisch wiederhergestellt werden.
Watches werden ebenfalls invalidiert: Beim Sitzungsablauf werden alle registrierten Watches ungültig. Sie müssen nach dem Neuaufbau der Sitzung manuell neu registriert werden, um wieder Benachrichtigungen über Änderungen zu erhalten.
Die PHP-ZooKeeper-Erweiterung ist eine PECL-Erweiterung und muss separat installiert werden. Die Versionierung folgt nicht der PHP-Hauptversion.