0
# Container Management
1

2
Core functionality for creating, configuring, and managing Cassandra Docker containers with proper lifecycle management and resource cleanup.
3

4
## Capabilities
5

6
### CassandraContainer Class
7

8
Main container class that provides specialized Cassandra container management extending the base GenericContainer functionality.
9

10
```java { .api }
11
/**
12
 * Testcontainers implementation for Apache Cassandra.
13
 * Supported image: cassandra
14
 * Exposed ports: 9042
15
 */
16
public class CassandraContainer extends GenericContainer<CassandraContainer> {
17
    /**
18
     * Create Cassandra container with Docker image name string
19
     * @param dockerImageName Docker image name (e.g., "cassandra:3.11.2")
20
     */
21
    public CassandraContainer(String dockerImageName);
22
    
23
    /**
24
     * Create Cassandra container with DockerImageName object
25
     * @param dockerImageName DockerImageName instance for version management
26
     */
27
    public CassandraContainer(DockerImageName dockerImageName);
28
}
29
```
30

31
**Usage Examples:**
32

33
```java
34
import org.testcontainers.cassandra.CassandraContainer;
35
import org.testcontainers.utility.DockerImageName;
36

37
// Simple container creation with string
38
CassandraContainer cassandra = new CassandraContainer("cassandra:3.11.2");
39

40
// Container creation with DockerImageName for version management
41
DockerImageName cassandraImage = DockerImageName.parse("cassandra").withTag("3.11.2");
42
CassandraContainer cassandra = new CassandraContainer(cassandraImage);
43

44
// Use in try-with-resources for automatic cleanup
45
try (CassandraContainer cassandra = new CassandraContainer("cassandra:3.11.2")) {
46
    cassandra.start();
47
    // Perform tests
48
} // Container automatically stopped and cleaned up
49
```
50

51
### Container Constants
52

53
The current implementation keeps the CQL port as a private constant. For accessing the port, use the inherited `getMappedPort()` method from GenericContainer.
54

55
```java
56
// Access the mapped CQL port
57
int mappedPort = cassandra.getMappedPort(9042);
58
```
59

60
Note: The deprecated `org.testcontainers.containers.CassandraContainer` class exposes `CQL_PORT` as a public constant, but the current implementation does not.
61

62
### Lifecycle Management
63

64
The container extends `GenericContainer` and inherits all standard Testcontainers lifecycle methods:
65

66
- `start()`: Starts the container and waits for it to be ready
67
- `stop()`: Stops and removes the container
68
- `close()`: Alias for stop(), enabling try-with-resources usage
69
- `isRunning()`: Check if container is currently running
70

71
**Container Startup Process:**
72

73
1. Creates Docker container with Cassandra image
74
2. Configures environment variables for optimal testing
75
3. Exposes port 9042 for CQL connections
76
4. Applies custom wait strategy to ensure Cassandra readiness
77
5. Executes configuration overrides if specified
78
6. Runs initialization scripts after container is ready
79

80
**Automatic Resource Management:**
81

82
```java
83
// Preferred pattern - automatic cleanup
84
try (CassandraContainer cassandra = new CassandraContainer("cassandra:3.11.2")) {
85
    cassandra.start();
86
    // Container automatically stopped when leaving try block
87
}
88

89
// Manual management (not recommended)
90
CassandraContainer cassandra = new CassandraContainer("cassandra:3.11.2");
91
cassandra.start();
92
try {
93
    // Perform tests
94
} finally {
95
    cassandra.stop(); // Manual cleanup required
96
}
97
```
98

99
### Error Handling
100

101
The container management system throws specific exceptions for different failure scenarios:
102

103
- `ContainerLaunchException`: Thrown when container fails to start or configure properly
104
- `IllegalArgumentException`: Thrown for invalid Docker image names or incompatible images
105
- `RuntimeException`: General container management errors
106

107
```java
108
try (CassandraContainer cassandra = new CassandraContainer("invalid-image")) {
109
    cassandra.start();
110
} catch (ContainerLaunchException e) {
111
    // Handle container startup failure
112
    logger.error("Failed to start Cassandra container", e);
113
}
114
```
115

116
## Deprecated Container Class
117

118
The legacy container class in the `org.testcontainers.containers` package is deprecated but still functional.
119

120
```java { .api }
121
import org.testcontainers.containers.CassandraContainer;
122
import org.testcontainers.containers.ContainerState;
123
import org.testcontainers.utility.DockerImageName;
124
import com.datastax.driver.core.Cluster;
125
import java.net.InetSocketAddress;
126

127
/**
128
 * @deprecated use org.testcontainers.cassandra.CassandraContainer instead
129
 */
130
@Deprecated
131
public class CassandraContainer<SELF extends CassandraContainer<SELF>> 
132
    extends GenericContainer<SELF> {
133
    
134
    // Public constants available in deprecated class
135
    public static final Integer CQL_PORT = 9042;
136
    @Deprecated
137
    public static final String IMAGE = "cassandra";
138
    
139
    /**
140
     * @deprecated use CassandraContainer(DockerImageName) instead
141
     */
142
    @Deprecated
143
    public CassandraContainer();
144
    
145
    public CassandraContainer(String dockerImageName);
146
    public CassandraContainer(DockerImageName dockerImageName);
147
    
148
    // Configuration methods
149
    public SELF withConfigurationOverride(String configLocation);
150
    public SELF withInitScript(String initScriptPath);
151
    public SELF withJmxReporting(boolean enableJmxReporting);
152
    
153
    // Connection methods  
154
    public String getUsername();
155
    public String getPassword();
156
    public InetSocketAddress getContactPoint();
157
    public String getLocalDatacenter();
158
    
159
    /**
160
     * @deprecated For Cassandra driver 3.x, use getHost() and getMappedPort(int) with
161
     * the driver's Cluster.Builder addContactPoint(String) and withPort(int) methods.
162
     * For Cassandra driver 4.x, use getContactPoint() and getLocalDatacenter() with
163
     * the driver's CqlSession.builder() methods.
164
     */
165
    @Deprecated
166
    public Cluster getCluster();
167
    
168
    @Deprecated
169
    public static Cluster getCluster(ContainerState containerState, boolean enableJmxReporting);
170
    
171
    @Deprecated  
172
    public static Cluster getCluster(ContainerState containerState);
173
}
174
```
175

176
### JMX Reporting Configuration
177

178
The deprecated class includes additional JMX reporting configuration not available in the current implementation:
179

180
```java
181
// Enable JMX reporting (deprecated class only)
182
CassandraContainer cassandra = new CassandraContainer("cassandra:3.11.2")
183
    .withJmxReporting(true);
184

185
// Access DataStax driver 3.x Cluster with JMX enabled
186
Cluster cluster = cassandra.getCluster(); // JMX controlled by withJmxReporting() setting
187
```