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
```