0
# Container Configuration
1

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

4
## Capabilities
5

6
### Container Creation
7

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

10
```java { .api }
11
public OracleContainer(String dockerImageName);
12
public OracleContainer(DockerImageName dockerImageName);
13
public OracleContainer(Future<String> dockerImageName);
14
```
15

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

21
**Usage Example:**
22
```java
23
// Using string image name
24
OracleContainer container1 = new OracleContainer("gvenzl/oracle-xe:18.4.0-slim");
25

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

31
// Using Future for dynamic image selection
32
Future<String> futureImage = CompletableFuture.supplyAsync(() -> 
33
    selectOracleImage()
34
);
35
OracleContainer container3 = new OracleContainer(futureImage);
36
```
37

38
### Database Configuration
39

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

42
```java { .api }
43
public OracleContainer withDatabaseName(String databaseName);
44
public OracleContainer usingSid();
45
public String getDatabaseName();
46
public String getSid();
47
protected boolean isUsingSid();
48
```
49

50
**Parameters:**
51
- `databaseName (String)`: Custom database name (cannot be "xepdb1" - reserved)
52

53
**Returns:**
54
- `OracleContainer`: Fluent interface for method chaining
55

56
**Usage Example:**
57
```java
58
OracleContainer container = new OracleContainer("gvenzl/oracle-xe:18.4.0-slim")
59
    .withDatabaseName("myapp_test")  // Custom database name
60
    .usingSid();  // Use SID-based connection instead of PDB
61

62
// Query configuration
63
String dbName = container.getDatabaseName();
64
String sid = container.getSid();  // Always returns "xe"
65
boolean usingSid = container.isUsingSid();
66
```
67

68
**Notes:**
69
- Default database name is "xepdb1" 
70
- SID mode connects to container database (CDB) instead of pluggable database (PDB)
71
- SID-based connections use system user instead of application user
72

73
### User Credentials
74

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

77
```java { .api }
78
public OracleContainer withUsername(String username);
79
public OracleContainer withPassword(String password);
80
public String getUsername();
81
public String getPassword();
82
```
83

84
**Parameters:**
85
- `username (String)`: Application username (cannot be "system" or "sys")
86
- `password (String)`: Application password (cannot be null or empty)
87

88
**Returns:**
89
- `OracleContainer`: Fluent interface for method chaining
90
- `String`: Current username/password values
91

92
**Throws:**
93
- `IllegalArgumentException`: If username/password is null, empty, or reserved
94

95
**Usage Example:**
96
```java
97
OracleContainer container = new OracleContainer("gvenzl/oracle-xe:18.4.0-slim")
98
    .withUsername("appuser")
99
    .withPassword("securepass123");
100

101
// Get current credentials
102
String user = container.getUsername();
103
String pass = container.getPassword();
104

105
// Invalid usage - throws IllegalArgumentException
106
container.withUsername("system");  // Reserved user
107
container.withPassword("");        // Empty password
108
```
109

110
### Port Configuration
111

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

114
```java { .api }
115
public Integer getOraclePort();
116
public Integer getWebPort();
117
public Set<Integer> getLivenessCheckPortNumbers();
118
```
119

120
**Returns:**
121
- `Integer`: Mapped host port for Oracle database (1521 internal)
122
- `Integer`: Mapped host port for APEX web interface (8080 internal)
123
- `Set<Integer>`: Ports used for container health checks
124

125
**Usage Example:**
126
```java
127
OracleContainer container = new OracleContainer("gvenzl/oracle-xe:18.4.0-slim");
128
container.start();
129

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

134
// Health check configuration
135
Set<Integer> healthPorts = container.getLivenessCheckPortNumbers();
136
```
137

138
### Container Lifecycle
139

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

142
```java { .api }
143
public OracleContainer withStartupTimeoutSeconds(int startupTimeoutSeconds);
144
public OracleContainer withConnectTimeoutSeconds(int connectTimeoutSeconds);
145
public OracleContainer withInitScript(String initScriptPath);
146
public OracleContainer withInitScripts(String... initScriptPaths);
147
public OracleContainer withInitScripts(Iterable<String> initScriptPaths);
148
public String getTestQueryString();
149
```
150

151
**Parameters:**
152
- `startupTimeoutSeconds (int)`: Maximum time to wait for container startup (default: 240)
153
- `connectTimeoutSeconds (int)`: Maximum time to wait for database connection (default: 120)
154
- `initScriptPath (String)`: Path to SQL initialization script
155
- `initScriptPaths (String[])`: Multiple initialization script paths
156
- `initScriptPaths (Iterable<String>)`: Iterable of script paths
157

158
**Returns:**
159
- `OracleContainer`: Fluent interface for method chaining
160

161
**Usage Example:**
162
```java
163
OracleContainer container = new OracleContainer("gvenzl/oracle-xe:18.4.0-slim")
164
    .withStartupTimeoutSeconds(300)        // 5 minute startup timeout
165
    .withConnectTimeoutSeconds(60)         // 1 minute connect timeout
166
    .withInitScript("classpath:schema.sql") // Single init script
167
    .withInitScripts(                      // Multiple init scripts
168
        "classpath:schema.sql",
169
        "classpath:data.sql",
170
        "classpath:procedures.sql"
171
    );
172
```
173

174
### URL Parameters
175

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

178
```java { .api }
179
public OracleContainer withUrlParam(String paramName, String paramValue);
180
```
181

182
**Parameters:**
183
- `paramName (String)`: URL parameter name
184
- `paramValue (String)`: URL parameter value
185

186
**Throws:**
187
- `UnsupportedOperationException`: Always thrown - Oracle driver doesn't support URL parameters
188

189
**Usage Example:**
190
```java
191
OracleContainer container = new OracleContainer("gvenzl/oracle-xe:18.4.0-slim");
192

193
// This will throw UnsupportedOperationException
194
try {
195
    container.withUrlParam("useSSL", "true");
196
} catch (UnsupportedOperationException e) {
197
    // Oracle driver doesn't support URL parameters
198
    System.out.println("URL parameters not supported: " + e.getMessage());
199
}
200
```
201

202
## Constants
203

204
```java { .api }
205
public static final String NAME = "oracle";
206
private static final DockerImageName DEFAULT_IMAGE_NAME = DockerImageName.parse("gvenzl/oracle-xe");
207
static final String DEFAULT_TAG = "18.4.0-slim";
208
static final String IMAGE = "gvenzl/oracle-xe";
209
static final int ORACLE_PORT = 1521;
210
private static final int APEX_HTTP_PORT = 8080;
211
static final String DEFAULT_DATABASE_NAME = "xepdb1";
212
static final String DEFAULT_SID = "xe";
213
static final String DEFAULT_SYSTEM_USER = "system";
214
static final String DEFAULT_SYS_USER = "sys";
215
static final String APP_USER = "test";
216
static final String APP_USER_PASSWORD = "test";
217
private static final int DEFAULT_STARTUP_TIMEOUT_SECONDS = 240;
218
private static final int DEFAULT_CONNECT_TIMEOUT_SECONDS = 120;
219
```