0
# Oracle XE Testcontainers
1
2
Oracle XE Testcontainers provides lightweight, throwaway instances of Oracle XE database for integration testing. Built on the Testcontainers framework, it automatically manages Docker containers with Oracle XE database, supporting both JDBC and R2DBC connectivity with pre-configured defaults optimized for testing workflows.
3
4
## Package Information
5
6
- **Package Name**: org.testcontainers:oracle-xe
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**:
10
```xml
11
<dependency>
12
<groupId>org.testcontainers</groupId>
13
<artifactId>oracle-xe</artifactId>
14
<version>1.21.3</version>
15
</dependency>
16
```
17
18
## Core Imports
19
20
```java
21
import org.testcontainers.containers.OracleContainer;
22
```
23
24
For R2DBC support:
25
26
```java
27
import org.testcontainers.containers.OracleR2DBCDatabaseContainer;
28
import org.testcontainers.containers.OracleR2DBCDatabaseContainerProvider;
29
```
30
31
For SPI-based container creation:
32
33
```java
34
import org.testcontainers.containers.OracleContainerProvider;
35
```
36
37
## Basic Usage
38
39
```java
40
import org.testcontainers.containers.OracleContainer;
41
import org.testcontainers.junit.jupiter.Container;
42
import org.testcontainers.junit.jupiter.Testcontainers;
43
import org.junit.jupiter.api.Test;
44
45
import java.sql.Connection;
46
import java.sql.DriverManager;
47
import java.sql.ResultSet;
48
import java.sql.Statement;
49
50
@Testcontainers
51
public class OracleIntegrationTest {
52
53
@Container
54
static OracleContainer oracle = new OracleContainer("gvenzl/oracle-xe:18.4.0-slim")
55
.withDatabaseName("testdb")
56
.withUsername("testuser")
57
.withPassword("testpass");
58
59
@Test
60
void testOracleConnection() throws Exception {
61
String jdbcUrl = oracle.getJdbcUrl();
62
String username = oracle.getUsername();
63
String password = oracle.getPassword();
64
65
try (Connection conn = DriverManager.getConnection(jdbcUrl, username, password)) {
66
Statement stmt = conn.createStatement();
67
ResultSet rs = stmt.executeQuery("SELECT 1 FROM DUAL");
68
69
assertTrue(rs.next());
70
assertEquals(1, rs.getInt(1));
71
}
72
}
73
}
74
```
75
76
## Architecture
77
78
Oracle XE Testcontainers is built around several key components:
79
80
- **OracleContainer**: Main container class extending JdbcDatabaseContainer with Oracle-specific configuration
81
- **Connection Modes**: Supports both application user connections (to PDB) and SID-based connections (to CDB)
82
- **Container Lifecycle**: Automatic Docker container management with health checks and initialization scripts
83
- **Multi-Protocol Support**: Both JDBC and R2DBC connectivity through dedicated wrappers
84
- **SPI Integration**: Automatic container discovery via Java Service Provider Interface
85
86
The container provides pre-configured Oracle XE defaults including database name (xepdb1), SID (xe), ports (1521, 8080), and test user credentials, while supporting extensive customization for specific testing requirements.
87
88
## Capabilities
89
90
### Container Configuration
91
92
Core container setup including image selection, database configuration, user credentials, and connection modes. Provides both default configurations for quick setup and extensive customization options for complex testing scenarios.
93
94
```java { .api }
95
public OracleContainer(String dockerImageName);
96
public OracleContainer(DockerImageName dockerImageName);
97
public OracleContainer(Future<String> dockerImageName);
98
99
public OracleContainer withDatabaseName(String databaseName);
100
public OracleContainer withUsername(String username);
101
public OracleContainer withPassword(String password);
102
public OracleContainer usingSid();
103
```
104
105
[Container Configuration](./container-configuration.md)
106
107
### JDBC Connectivity
108
109
Standard JDBC database connectivity with Oracle-specific connection URLs, driver management, and database operations. Provides seamless integration with JUnit testing frameworks and connection pooling libraries.
110
111
```java { .api }
112
public String getJdbcUrl();
113
public String getDriverClassName();
114
public String getUsername();
115
public String getPassword();
116
public String getTestQueryString();
117
public Connection createConnection(String queryString) throws SQLException, NoDriverFoundException;
118
public Driver getJdbcDriverInstance() throws NoDriverFoundException;
119
```
120
121
[JDBC Connectivity](./jdbc-connectivity.md)
122
123
### R2DBC Connectivity
124
125
Reactive database connectivity using R2DBC for non-blocking database operations. Provides factory methods and configuration options for reactive programming patterns with Oracle databases.
126
127
```java { .api }
128
public static ConnectionFactoryOptions getOptions(OracleContainer container);
129
public ConnectionFactoryOptions configure(ConnectionFactoryOptions options);
130
public R2DBCDatabaseContainer createContainer(ConnectionFactoryOptions options);
131
```
132
133
[R2DBC Connectivity](./r2dbc-connectivity.md)
134
135
## Types
136
137
```java { .api }
138
public class OracleContainer extends JdbcDatabaseContainer<OracleContainer> {
139
public static final String NAME = "oracle";
140
static final String DEFAULT_TAG = "18.4.0-slim";
141
static final String IMAGE = "gvenzl/oracle-xe";
142
static final int ORACLE_PORT = 1521;
143
static final String DEFAULT_DATABASE_NAME = "xepdb1";
144
static final String DEFAULT_SID = "xe";
145
static final String APP_USER = "test";
146
static final String APP_USER_PASSWORD = "test";
147
}
148
149
public class OracleContainerProvider extends JdbcDatabaseContainerProvider {
150
// SPI implementation for JDBC container creation
151
}
152
153
public class OracleR2DBCDatabaseContainer implements R2DBCDatabaseContainer {
154
// R2DBC wrapper implementation
155
}
156
157
public class OracleR2DBCDatabaseContainerProvider implements R2DBCDatabaseContainerProvider {
158
static final String DRIVER = "oracle";
159
}
160
```