CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-org-seleniumhq-selenium--selenium-session-map-jdbc

JDBC-backed session map implementation for Selenium Grid providing database-backed storage for distributed WebDriver sessions.

—

Pending
Overview
Eval results
Files

exceptions.mddocs/

Exception Handling

Custom exception types and error handling patterns for JDBC session map operations.

Capabilities

JDBC Exception

Custom exception class for JDBC session map related errors.

/**
 * Exception thrown for JDBC session map operations
 * Extends WebDriverException to integrate with Selenium's exception hierarchy
 */
public class JdbcException extends WebDriverException {
  /**
   * Creates a JDBC exception with no message
   */
  public JdbcException();
  
  /**
   * Creates a JDBC exception with a message
   * @param message The error message
   */
  public JdbcException(String message);
  
  /**
   * Creates a JDBC exception wrapping another exception
   * @param cause The underlying cause
   */
  public JdbcException(Throwable cause);
  
  /**
   * Creates a JDBC exception with message and cause
   * @param message The error message
   * @param cause The underlying cause
   */
  public JdbcException(String message, Throwable cause);
}

Exception Scenarios

Database Connection Errors

Thrown when database connections fail during session map operations.

Usage Example:

import org.openqa.selenium.grid.sessionmap.jdbc.JdbcException;

try {
    SessionMap sessionMap = JdbcBackedSessionMap.create(config);
    sessionMap.add(session);
} catch (JdbcException e) {
    System.err.println("Database operation failed: " + e.getMessage());
    
    // Check if it's a connection issue
    if (e.getCause() instanceof SQLException) {
        SQLException sqlException = (SQLException) e.getCause();
        System.err.println("SQL Error Code: " + sqlException.getErrorCode());
        System.err.println("SQL State: " + sqlException.getSQLState());
    }
}

Configuration Errors

Thrown when required configuration is missing or invalid.

Usage Example:

import org.openqa.selenium.grid.config.ConfigException;

try {
    // Missing JDBC URL will trigger configuration error
    Config config = new MapConfig(Map.of());
    SessionMap sessionMap = JdbcBackedSessionMap.create(config);
} catch (ConfigException e) {
    System.err.println("Configuration error: " + e.getMessage());
    // Expected message: "Missing JDBC Url value. Add sessions option value --jdbc-url <url-value>"
} catch (JdbcException e) {
    System.err.println("JDBC configuration error: " + e.getMessage());
}

Session Not Found Errors

Standard Selenium exception for missing sessions.

Usage Example:

import org.openqa.selenium.NoSuchSessionException;

try {
    SessionId unknownId = new SessionId("non-existent-session");
    Session session = sessionMap.get(unknownId);
} catch (NoSuchSessionException e) {
    System.err.println("Session not found: " + e.getMessage());
    // Handle missing session appropriately
    // This is the standard Selenium exception, not JdbcException
}

Error Handling Patterns

Robust Session Operations

public class RobustSessionManager {
    private final SessionMap sessionMap;
    private final Logger logger;
    
    public boolean safeAddSession(Session session) {
        try {
            return sessionMap.add(session);
        } catch (JdbcException e) {
            logger.error("Failed to add session " + session.getId() + " to database", e);
            return false;
        }
    }
    
    public Optional<Session> safeGetSession(SessionId id) {
        try {
            return Optional.of(sessionMap.get(id));
        } catch (NoSuchSessionException e) {
            logger.debug("Session " + id + " not found in database");
            return Optional.empty();
        } catch (JdbcException e) {
            logger.error("Database error retrieving session " + id, e);
            return Optional.empty();
        }
    }
    
    public void safeRemoveSession(SessionId id) {
        try {
            sessionMap.remove(id);
            logger.debug("Session " + id + " removed from database");
        } catch (JdbcException e) {
            logger.error("Failed to remove session " + id + " from database", e);
            // Continue - removal failures shouldn't break the flow
        }
    }
}

Connection Health Monitoring

public class SessionMapHealthChecker {
    private final JdbcBackedSessionMap sessionMap;
    
    public boolean isHealthy() {
        try {
            return sessionMap.isReady();
        } catch (Exception e) {
            logger.warn("Session map health check failed", e);
            return false;
        }
    }
    
    public void performHealthCheck() {
        if (!isHealthy()) {
            logger.error("Session map is not healthy - database connection issues");
            // Trigger alerts, attempt reconnection, etc.
        }
    }
}

Graceful Degradation

public class FallbackSessionManager {
    private final SessionMap primarySessionMap;
    private final SessionMap fallbackSessionMap; // e.g., in-memory session map
    
    public boolean add(Session session) {
        try {
            return primarySessionMap.add(session);
        } catch (JdbcException e) {
            logger.warn("Primary session map failed, using fallback", e);
            return fallbackSessionMap.add(session);
        }
    }
    
    public Session get(SessionId id) throws NoSuchSessionException {
        try {
            return primarySessionMap.get(id);
        } catch (JdbcException e) {
            logger.warn("Primary session map failed, trying fallback", e);
            return fallbackSessionMap.get(id);
        }
    }
}

Common Error Causes and Solutions

Database Connection Issues

Error: SQLException: Connection refused Cause: Database server is not running or not accessible Solution: Verify database server status and network connectivity

try {
    Connection connection = options.getJdbcConnection();
} catch (SQLException e) {
    if (e.getMessage().contains("Connection refused")) {
        logger.error("Database server appears to be down: " + options.getJdbcUrl());
        // Implement retry logic or fallback
    }
}

Missing Database Table

Error: JdbcException wrapping SQLException: Table 'sessions_map' doesn't exist Cause: Database schema not initialized Solution: Create the required table structure

CREATE TABLE sessions_map (
    session_ids VARCHAR(50),
    session_uri VARCHAR(30),
    session_stereotype VARCHAR(300),
    session_caps VARCHAR(300),
    session_start VARCHAR(128)
);

Authentication Failures

Error: SQLException: Access denied for user Cause: Invalid database credentials Solution: Verify JDBC username and password configuration

// Check configuration
String user = options.getJdbcUser();
if (user == null || user.isEmpty()) {
    logger.warn("JDBC user not configured - using default");
}

Connection Pool Exhaustion

Error: SQLException: Connection pool exhausted Cause: Too many concurrent connections Solution: Configure connection pooling or implement connection reuse

// Properly close connections
try (Connection connection = options.getJdbcConnection()) {
    // Use connection
} // Automatically closed here

Exception Integration with Grid Events

The JDBC session map integrates exceptions with Selenium Grid's event system and distributed tracing:

  • Trace Span Errors: Database exceptions are recorded in distributed traces
  • Event Attributes: Error details are added to Grid events
  • Monitoring Integration: Exceptions can trigger monitoring alerts
  • Graceful Degradation: Grid continues operating even with session map failures

This integration ensures that JDBC session map errors are properly observed and handled within the broader Grid infrastructure.

Install with Tessl CLI

npx tessl i tessl/maven-org-seleniumhq-selenium--selenium-session-map-jdbc

docs

configuration.md

exceptions.md

index.md

session-management.md

tile.json