Add ContainerState#getHost replacing getContainerIpAddress (#2742)

* Add `ContainerState#getHost` replacing `getContainerIpAddress`

* post-merge fixes

* Ignore `METHOD_NEW_DEFAULT` in japicmp

* Update docs/features/networking.md

Co-authored-by: Richard North <[email protected]>

* Add a tip about `getContainerIpAddress()`

* Fix the codeincludes

Co-authored-by: Richard North <[email protected]>

Author: bsideup

core/build.gradle

@@ -84,20 +84,14 @@ task japicmp(type: me.champeau.gradle.japicmp.JapicmpTask) {
     failOnModification = true
     failOnSourceIncompatibility = true
 
-    // TODO cleanup excludes after we release the version based on docker-java 3.2.0
-
     packageExcludes = [
         "com.github.dockerjava.*",
         "org.testcontainers.shaded.*",
     ]
 
-    classExcludes = [
-        // 'METHOD_REMOVED_IN_SUPERCLASS'
-        "org.testcontainers.containers.output.FrameConsumerResultCallback",
-        "org.testcontainers.dockerclient.LogToStringContainerCallback",
-
-        // 'METHOD_RETURN_TYPE_CHANGED', exposed `com.github.dockerjava.core.command.PullImageResultCallback` to the public API
-        "org.testcontainers.images.TimeLimitedLoggedPullImageResultCallback",
+    methodExcludes = [
+        // METHOD_NEW_DEFAULT
+        "org.testcontainers.containers.ContainerState#getHost()"
     ]
 
     onlyBinaryIncompatibleModified = true

core/src/main/java/org/testcontainers/containers/ComposeServiceWaitStrategyTarget.java

@@ -54,8 +54,8 @@ public Integer getMappedPort(int originalPort) {
      * {@inheritDoc}
      */
     @Override
-    public String getContainerIpAddress() {
-        return proxyContainer.getContainerIpAddress();
+    public String getHost() {
+        return proxyContainer.getHost();
     }
 
     /**

core/src/main/java/org/testcontainers/containers/ContainerState.java

@@ -43,8 +43,18 @@ public interface ContainerState {
      * Get the IP address that this container may be reached on (may not be the local machine).
      *
      * @return an IP address
+     * @see #getHost()
      */
     default String getContainerIpAddress() {
+        return getHost();
+    }
+
+    /**
+     * Get the host that this container may be reached on (may not be the local machine).
+     *
+     * @return a host
+     */
+    default String getHost() {
         return DockerClientFactory.instance().dockerHostIpAddress();
     }
 
@@ -107,6 +117,7 @@ default InspectContainerResponse getCurrentContainerInfo() {
 
     /**
      * Get the actual mapped port for a first port exposed by the container.
+     * Should be used in conjunction with {@link #getHost()}.
      *
      * @return the port that the exposed port is mapped to
      * @throws IllegalStateException if there are no exposed ports
@@ -121,6 +132,7 @@ default Integer getFirstMappedPort() {
 
     /**
      * Get the actual mapped port for a given port exposed by the container.
+     * Should be used in conjunction with {@link #getHost()}.
      *
      * @param originalPort the original TCP port that is exposed
      * @return the port that the exposed port is mapped to, or null if it is not exposed

core/src/main/java/org/testcontainers/containers/DockerComposeContainer.java

@@ -402,7 +402,7 @@ public SELF waitingFor(String serviceName, @NonNull WaitStrategy waitStrategy) {
      * @return a host IP address or hostname that can be used for accessing the service container.
      */
     public String getServiceHost(String serviceName, Integer servicePort) {
-        return ambassadorContainer.getContainerIpAddress();
+        return ambassadorContainer.getHost();
     }
 
     /**

core/src/main/java/org/testcontainers/containers/GenericContainer.java

@@ -1244,7 +1244,7 @@ public SELF withCopyFileToContainer(MountableFile mountableFile, String containe
      */
     @Deprecated
     public String getIpAddress() {
-        return getContainerIpAddress();
+        return getHost();
     }
 
     /**

core/src/main/java/org/testcontainers/containers/PortForwardingContainer.java

@@ -40,7 +40,7 @@ private Connection createSSHSession() {
             );
         container.start();
 
-        Connection connection = new Connection(container.getContainerIpAddress(), container.getMappedPort(22));
+        Connection connection = new Connection(container.getHost(), container.getMappedPort(22));
 
         connection.setTCPNoDelay(true);
         connection.connect(
@@ -60,7 +60,7 @@ private Connection createSSHSession() {
     public void exposeHostPort(int port) {
         exposeHostPort(port, port);
     }
-    
+
     @SneakyThrows
     public void exposeHostPort(int hostPort, int containerPort) {
     	if (exposedPorts.add(new AbstractMap.SimpleEntry<>(hostPort, containerPort))) {

core/src/main/java/org/testcontainers/containers/wait/internal/ExternalPortListeningCheck.java

@@ -18,7 +18,7 @@ public class ExternalPortListeningCheck implements Callable<Boolean> {
 
     @Override
     public Boolean call() {
-        String address = containerState.getContainerIpAddress();
+        String address = containerState.getHost();
 
         externalLivenessCheckPorts.parallelStream().forEach(externalPort -> {
             try {

core/src/main/java/org/testcontainers/containers/wait/strategy/HostPortWaitStrategy.java

@@ -46,7 +46,7 @@ protected void waitUntilReady() {
 
         } catch (TimeoutException e) {
             throw new ContainerLaunchException("Timed out waiting for container port to open (" +
-                    waitStrategyTarget.getContainerIpAddress() +
+                    waitStrategyTarget.getHost() +
                     " ports: " +
                     externalLivenessCheckPorts +
                     " should be listening)");

core/src/main/java/org/testcontainers/containers/wait/strategy/HttpWaitStrategy.java

@@ -225,7 +225,7 @@ protected void waitUntilReady() {
      */
     private URI buildLivenessUri(int livenessCheckPort) {
         final String scheme = (tlsEnabled ? "https" : "http") + "://";
-        final String host = waitStrategyTarget.getContainerIpAddress();
+        final String host = waitStrategyTarget.getHost();
 
         final String portSuffix;
         if ((tlsEnabled && 443 == livenessCheckPort) || (!tlsEnabled && 80 == livenessCheckPort)) {

core/src/test/java/org/testcontainers/containers/wait/internal/ExternalPortListeningCheckTest.java

@@ -29,7 +29,7 @@ public void setUp() throws Exception {
         nonListeningSocket.close();
 
         mockContainer = mock(WaitStrategyTarget.class);
-        when(mockContainer.getContainerIpAddress()).thenReturn("127.0.0.1");
+        when(mockContainer.getHost()).thenReturn("127.0.0.1");
     }
 
     @Test

core/src/test/java/org/testcontainers/images/ImagePullPolicyTest.java

@@ -33,7 +33,7 @@ public class ImagePullPolicyTest {
 
     @BeforeClass
     public static void beforeClass() throws Exception {
-        String testRegistryAddress = registry.getContainerIpAddress() + ":" + registry.getFirstMappedPort();
+        String testRegistryAddress = registry.getHost() + ":" + registry.getFirstMappedPort();
         String testImageName = testRegistryAddress + "/image-pull-policy-test";
         String tag = UUID.randomUUID().toString();
         imageName = testImageName + ":" + tag;

core/src/test/java/org/testcontainers/junit/DockerfileContainerTest.java

@@ -31,7 +31,7 @@ public class DockerfileContainerTest {
 
     @Test
     public void simpleDslTest() throws IOException {
-        String address = String.format("http://%s:%s", dslContainer.getContainerIpAddress(), dslContainer.getMappedPort(80));
+        String address = String.format("http://%s:%s", dslContainer.getHost(), dslContainer.getMappedPort(80));
 
         CloseableHttpClient httpClient = HttpClientBuilder.create().build();
         HttpGet get = new HttpGet(address);

core/src/test/java/org/testcontainers/junit/FixedHostPortContainerTest.java

@@ -85,7 +85,7 @@ private String readResponse(GenericContainer container, Integer port) throws IOE
             final BufferedReader reader = Unreliables.retryUntilSuccess(10, TimeUnit.SECONDS,
                 () -> {
                     Uninterruptibles.sleepUninterruptibly(1, TimeUnit.SECONDS);
-                    final Socket socket = new Socket(container.getContainerIpAddress(), port);
+                    final Socket socket = new Socket(container.getHost(), port);
                     return new BufferedReader(new InputStreamReader(socket.getInputStream()));
                 }
             )

core/src/test/java/org/testcontainers/junit/GenericContainerRuleTest.java

@@ -162,7 +162,7 @@ public void withTmpFsTest() throws Exception {
     @Test
     public void simpleRabbitMqTest() throws IOException, TimeoutException {
         ConnectionFactory factory = new ConnectionFactory();
-        factory.setHost(rabbitMq.getContainerIpAddress());
+        factory.setHost(rabbitMq.getHost());
         factory.setPort(rabbitMq.getMappedPort(RABBITMQ_PORT));
         Connection connection = factory.newConnection();
 
@@ -194,7 +194,7 @@ public void handleDelivery(String consumerTag, Envelope envelope, AMQP.BasicProp
 
     @Test
     public void simpleMongoDbTest() {
-        MongoClient mongoClient = new MongoClient(mongo.getContainerIpAddress(), mongo.getMappedPort(MONGO_PORT));
+        MongoClient mongoClient = new MongoClient(mongo.getHost(), mongo.getMappedPort(MONGO_PORT));
         MongoDatabase database = mongoClient.getDatabase("test");
         MongoCollection<Document> collection = database.getCollection("testCollection");
 
@@ -366,7 +366,7 @@ private BufferedReader getReaderForContainerPort80(GenericContainer container) {
         return Unreliables.retryUntilSuccess(10, TimeUnit.SECONDS, () -> {
             Uninterruptibles.sleepUninterruptibly(1, TimeUnit.SECONDS);
 
-            Socket socket = new Socket(container.getContainerIpAddress(), container.getFirstMappedPort());
+            Socket socket = new Socket(container.getHost(), container.getFirstMappedPort());
             return new BufferedReader(new InputStreamReader(socket.getInputStream()));
         });
     }

core/src/test/java/org/testcontainers/utility/AuthenticatedImagePullTest.java

@@ -65,7 +65,7 @@ public static void setUp() throws InterruptedException {
         originalAuthLocatorSingleton = RegistryAuthLocator.instance();
         client = DockerClientFactory.instance().client();
 
-        String testRegistryAddress = authenticatedRegistry.getContainerIpAddress() + ":" + authenticatedRegistry.getFirstMappedPort();
+        String testRegistryAddress = authenticatedRegistry.getHost() + ":" + authenticatedRegistry.getFirstMappedPort();
         testImageName = testRegistryAddress + "/alpine";
         testImageNameWithTag = testImageName + ":latest";
 

docs/examples/junit4/generic/src/test/java/generic/MultiplePortsExposedTest.java

@@ -31,13 +31,13 @@ public void fetchFirstMappedPort() {
     }
 
     @Test
-    public void getContainerIpAddressOnly() {
-        String ipAddress = container.getContainerIpAddress();
+    public void getHostOnly() {
+        String ipAddress = container.getHost();
     }
 
     @Test
-    public void getContainerIpAddressAndMappedPort() {
+    public void getHostAndMappedPort() {
         String address =
-            container.getContainerIpAddress() + ":" + container.getMappedPort(2424);
+            container.getHost() + ":" + container.getMappedPort(2424);
     }
 }

docs/examples/junit4/redis/src/test/java/quickstart/RedisBackedCacheIntTest.java

@@ -21,7 +21,7 @@ public class RedisBackedCacheIntTest {
 
     @Before
     public void setUp() {
-        String address = redis.getContainerIpAddress();
+        String address = redis.getHost();
         Integer port = redis.getFirstMappedPort();
 
         // Now we have an address and port for Redis, no matter where it is running

docs/examples/junit5/redis/src/test/java/quickstart/RedisBackedCacheIntTest.java

@@ -24,7 +24,7 @@ public class RedisBackedCacheIntTest {
 
     @BeforeEach
     public void setUp() {
-        String address = redis.getContainerIpAddress();
+        String address = redis.getHost();
         Integer port = redis.getFirstMappedPort();
 
         // Now we have an address and port for Redis, no matter where it is running

docs/examples/spock/redis/src/test/groovy/quickstart/RedisBackedCacheIntTest.groovy

@@ -15,7 +15,7 @@ class RedisBackedCacheIntTest extends Specification {
     // }
 
     void setup() {
-        String address = redis.containerIpAddress
+        String address = redis.host
         Integer port = redis.firstMappedPort
 
         // Now we have an address and port for Redis, no matter where it is running

docs/features/networking.md

@@ -33,23 +33,27 @@ There is also a `getFirstMappedPort` method for convenience, for the fairly comm
 [Retrieving the first mapped port](../examples/junit4/generic/src/test/java/generic/MultiplePortsExposedTest.java) inside_block:fetchFirstMappedPort
 <!--/codeinclude-->
 
-## Getting the container IP address
+## Getting the container host
 
 When running with a local Docker daemon, exposed ports will usually be reachable on `localhost`.
 However, in some CI environments they may instead be reachable on a different host.
 
-As such, Testcontainers provides a convenience method to obtain an IP address on which the container should be reachable from the host machine.
+As such, Testcontainers provides a convenience method to obtain an address on which the container should be reachable from the host machine.
 
 <!--codeinclude-->
-[Getting the container IP address](../examples/junit4/generic/src/test/java/generic/MultiplePortsExposedTest.java) inside_block:getContainerIpAddressOnly
+[Getting the container host](../examples/junit4/generic/src/test/java/generic/MultiplePortsExposedTest.java) inside_block:getHostOnly
 <!--/codeinclude-->
 
-It is normally advisable to use `getContainerIpAddress` and `getMappedPort` together when constructing addresses - for example:
+It is normally advisable to use `getHost` and `getMappedPort` together when constructing addresses - for example:
 
 <!--codeinclude-->
-[Getting the container IP address and mapped port](../examples/junit4/generic/src/test/java/generic/MultiplePortsExposedTest.java) inside_block:getContainerIpAddressAndMappedPort
+[Getting the container host and mapped port](../examples/junit4/generic/src/test/java/generic/MultiplePortsExposedTest.java) inside_block:getHostAndMappedPort
 <!--/codeinclude-->
 
+!!! tip
+    `getHost()` is a replacement for `getContainerIpAddress()` and returns the same result.
+    `getContainerIpAddress()` is believed to be confusingly named, and will eventually be deprecated.
+
 ## Exposing host ports to the container
 
 In some cases it is necessary to make a network connection from a container to a socket that is listening on the host machine.
@@ -86,4 +90,4 @@ Docker provides the ability for you to create custom networks and place containe
 
 <!--codeinclude-->
 [Creating custom networks](../../core/src/test/java/org/testcontainers/containers/NetworkTest.java) inside_block:useCustomNetwork
-<!--/codeinclude-->
+<!--/codeinclude-->

docs/modules/vault.md

@@ -21,7 +21,7 @@ public class SomeTest {
 
        //There are many integration clients for Vault so let's just define a general one here:
        VaultClient client = new VaultClient(
-               vaultContainer.getContainerIpAddress(),
+               vaultContainer.getHost(),
                vaultContainer.getMappedPort(8200),
                "my-root-token");
 

docs/quickstart/junit_4_quickstart.md

@@ -65,10 +65,10 @@ We can do this in our test `setUp` method, to set up our component under test:
 <!--/codeinclude-->
 
 !!! tip
-    Notice that we also ask Testcontainers for the container's actual address with `redis.getContainerIpAddress();`, 
+    Notice that we also ask Testcontainers for the container's actual address with `redis.getHost();`, 
     rather than hard-coding `localhost`. `localhost` may work in some environments but not others - for example it may
     not work on your current or future CI environment. As such, **avoid hard-coding** the address, and use 
-    `getContainerIpAddress()` instead.
+    `getHost()` instead.
 
 ## 4. Run the tests!
 

docs/quickstart/junit_5_quickstart.md

@@ -94,10 +94,10 @@ We can do this in our test `setUp` method, to set up our component under test:
 <!--/codeinclude-->
 
 !!! tip
-    Notice that we also ask Testcontainers for the container's actual address with `redis.getContainerIpAddress();`, 
+    Notice that we also ask Testcontainers for the container's actual address with `redis.getHost();`, 
     rather than hard-coding `localhost`. `localhost` may work in some environments but not others - for example it may
     not work on your current or future CI environment. As such, **avoid hard-coding** the address, and use 
-    `getContainerIpAddress()` instead.
+    `getHost()` instead.
 
 ## 4. Run the tests!
 

modules/cassandra/src/main/java/org/testcontainers/containers/CassandraContainer.java

@@ -161,7 +161,7 @@ public Cluster getCluster() {
 
     public static Cluster getCluster(ContainerState containerState, boolean enableJmxReporting) {
         final Cluster.Builder builder = Cluster.builder()
-            .addContactPoint(containerState.getContainerIpAddress())
+            .addContactPoint(containerState.getHost())
             .withPort(containerState.getMappedPort(CQL_PORT));
         if (!enableJmxReporting) {
             builder.withoutJMXReporting();

modules/cassandra/src/test/java/org/testcontainers/containers/CassandraContainerTest.java

@@ -116,7 +116,7 @@ private void testInitScript(CassandraContainer cassandraContainer) {
 
     private ResultSet performQuery(CassandraContainer cassandraContainer, String cql) {
         Cluster explicitCluster = Cluster.builder()
-            .addContactPoint(cassandraContainer.getContainerIpAddress())
+            .addContactPoint(cassandraContainer.getHost())
             .withPort(cassandraContainer.getMappedPort(CassandraContainer.CQL_PORT))
             .build();
         return performQuery(explicitCluster, cql);

modules/clickhouse/src/main/java/org/testcontainers/containers/ClickHouseContainer.java

@@ -48,7 +48,7 @@ public String getDriverClassName() {
 
     @Override
     public String getJdbcUrl() {
-        return JDBC_URL_PREFIX + getContainerIpAddress() + ":" + getMappedPort(HTTP_PORT) + "/" + databaseName;
+        return JDBC_URL_PREFIX + getHost() + ":" + getMappedPort(HTTP_PORT) + "/" + databaseName;
     }
 
     @Override

modules/cockroachdb/src/main/java/org/testcontainers/containers/CockroachContainer.java

@@ -43,7 +43,7 @@ public String getDriverClassName() {
 
     @Override
     public String getJdbcUrl() {
-        return JDBC_URL_PREFIX + "://" + getContainerIpAddress() + ":" + getMappedPort(DB_PORT) + "/" + databaseName;
+        return JDBC_URL_PREFIX + "://" + getHost() + ":" + getMappedPort(DB_PORT) + "/" + databaseName;
     }
 
     @Override