tessl/maven-org-testcontainers--oracle-xe

Testcontainers module for Oracle XE database - provides lightweight, throwaway instances of Oracle XE database for integration testing

Overview

Eval results

Files

Container Configuration

Name: tessl/maven-org-testcontainers--oracle-xe
Author: tessl

Comprehensive container setup and configuration options for Oracle XE Testcontainers. Supports both default configurations for quick testing and extensive customization for complex integration scenarios.

Capabilities

Container Creation

Creates Oracle XE container instances with flexible image specification options supporting Docker image names, DockerImageName objects, and future-based lazy loading.

public OracleContainer(String dockerImageName);
public OracleContainer(DockerImageName dockerImageName);
public OracleContainer(Future<String> dockerImageName);

Parameters:

dockerImageName (String): Docker image name (e.g., "gvenzl/oracle-xe:18.4.0-slim")
dockerImageName (DockerImageName): Structured image name with validation
dockerImageName (Future<String>): Lazy-loaded image name for dynamic scenarios

Usage Example:

// Using string image name
OracleContainer container1 = new OracleContainer("gvenzl/oracle-xe:18.4.0-slim");

// Using DockerImageName for validation
OracleContainer container2 = new OracleContainer(
    DockerImageName.parse("gvenzl/oracle-xe").withTag("21.3.0-slim")
);

// Using Future for dynamic image selection
Future<String> futureImage = CompletableFuture.supplyAsync(() -> 
    selectOracleImage()
);
OracleContainer container3 = new OracleContainer(futureImage);

Database Configuration

Configures database-specific settings including database name, connection mode (PDB vs SID), and database initialization parameters.

public OracleContainer withDatabaseName(String databaseName);
public OracleContainer usingSid();
public String getDatabaseName();
public String getSid();
protected boolean isUsingSid();

Parameters:

databaseName (String): Custom database name (cannot be "xepdb1" - reserved)

Returns:

OracleContainer: Fluent interface for method chaining

Usage Example:

OracleContainer container = new OracleContainer("gvenzl/oracle-xe:18.4.0-slim")
    .withDatabaseName("myapp_test")  // Custom database name
    .usingSid();  // Use SID-based connection instead of PDB

// Query configuration
String dbName = container.getDatabaseName();
String sid = container.getSid();  // Always returns "xe"
boolean usingSid = container.isUsingSid();

Notes:

Default database name is "xepdb1"
SID mode connects to container database (CDB) instead of pluggable database (PDB)
SID-based connections use system user instead of application user

User Credentials

Manages database user authentication including application user credentials with validation to prevent system user conflicts.

public OracleContainer withUsername(String username);
public OracleContainer withPassword(String password);
public String getUsername();
public String getPassword();

Parameters:

username (String): Application username (cannot be "system" or "sys")
password (String): Application password (cannot be null or empty)

Returns:

OracleContainer: Fluent interface for method chaining
String: Current username/password values

Throws:

IllegalArgumentException: If username/password is null, empty, or reserved

Usage Example:

OracleContainer container = new OracleContainer("gvenzl/oracle-xe:18.4.0-slim")
    .withUsername("appuser")
    .withPassword("securepass123");

// Get current credentials
String user = container.getUsername();
String pass = container.getPassword();

// Invalid usage - throws IllegalArgumentException
container.withUsername("system");  // Reserved user
container.withPassword("");        // Empty password

Port Configuration

Manages container port mappings for Oracle database and APEX web interface with automatic port allocation and health checks.

public Integer getOraclePort();
public Integer getWebPort();
public Set<Integer> getLivenessCheckPortNumbers();

Returns:

Integer: Mapped host port for Oracle database (1521 internal)
Integer: Mapped host port for APEX web interface (8080 internal)
Set<Integer>: Ports used for container health checks

Usage Example:

OracleContainer container = new OracleContainer("gvenzl/oracle-xe:18.4.0-slim");
container.start();

// Get mapped ports (assigned dynamically)
int oraclePort = container.getOraclePort();  // e.g., 32768
int webPort = container.getWebPort();        // e.g., 32769

// Health check configuration
Set<Integer> healthPorts = container.getLivenessCheckPortNumbers();

Container Lifecycle

Controls container startup, shutdown, and health monitoring with configurable timeouts and initialization script support.

public OracleContainer withStartupTimeoutSeconds(int startupTimeoutSeconds);
public OracleContainer withConnectTimeoutSeconds(int connectTimeoutSeconds);
public OracleContainer withInitScript(String initScriptPath);
public OracleContainer withInitScripts(String... initScriptPaths);
public OracleContainer withInitScripts(Iterable<String> initScriptPaths);
public String getTestQueryString();

Parameters:

startupTimeoutSeconds (int): Maximum time to wait for container startup (default: 240)
connectTimeoutSeconds (int): Maximum time to wait for database connection (default: 120)
initScriptPath (String): Path to SQL initialization script
initScriptPaths (String[]): Multiple initialization script paths
initScriptPaths (Iterable<String>): Iterable of script paths

Returns:

OracleContainer: Fluent interface for method chaining

Usage Example:

OracleContainer container = new OracleContainer("gvenzl/oracle-xe:18.4.0-slim")
    .withStartupTimeoutSeconds(300)        // 5 minute startup timeout
    .withConnectTimeoutSeconds(60)         // 1 minute connect timeout
    .withInitScript("classpath:schema.sql") // Single init script
    .withInitScripts(                      // Multiple init scripts
        "classpath:schema.sql",
        "classpath:data.sql",
        "classpath:procedures.sql"
    );

URL Parameters

Oracle-specific behavior for connection URL parameters with appropriate error handling for unsupported operations.

public OracleContainer withUrlParam(String paramName, String paramValue);

Parameters:

paramName (String): URL parameter name
paramValue (String): URL parameter value

Throws:

UnsupportedOperationException: Always thrown - Oracle driver doesn't support URL parameters

Usage Example:

OracleContainer container = new OracleContainer("gvenzl/oracle-xe:18.4.0-slim");

// This will throw UnsupportedOperationException
try {
    container.withUrlParam("useSSL", "true");
} catch (UnsupportedOperationException e) {
    // Oracle driver doesn't support URL parameters
    System.out.println("URL parameters not supported: " + e.getMessage());
}

Constants

public static final String NAME = "oracle";
private static final DockerImageName DEFAULT_IMAGE_NAME = DockerImageName.parse("gvenzl/oracle-xe");
static final String DEFAULT_TAG = "18.4.0-slim";
static final String IMAGE = "gvenzl/oracle-xe";
static final int ORACLE_PORT = 1521;
private static final int APEX_HTTP_PORT = 8080;
static final String DEFAULT_DATABASE_NAME = "xepdb1";
static final String DEFAULT_SID = "xe";
static final String DEFAULT_SYSTEM_USER = "system";
static final String DEFAULT_SYS_USER = "sys";
static final String APP_USER = "test";
static final String APP_USER_PASSWORD = "test";
private static final int DEFAULT_STARTUP_TIMEOUT_SECONDS = 240;
private static final int DEFAULT_CONNECT_TIMEOUT_SECONDS = 120;

Install with Tessl CLI

npx tessl i tessl/maven-org-testcontainers--oracle-xe

docs

container-configuration.md

index.md

jdbc-connectivity.md

r2dbc-connectivity.md

tile.json

tessl/maven-org-testcontainers--oracle-xe