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