public class GenericContainer<SELF extends GenericContainer<SELF>> extends FailureDetectingExternalResource implements Container<SELF>, AutoCloseable
Modifier and Type | Class and Description |
---|---|
static class |
GenericContainer.AbstractWaitStrategy
Convenience class with access to non-public members of GenericContainer.
|
Container.ExecResult
Modifier and Type | Field and Description |
---|---|
static int |
CONTAINER_RUNNING_TIMEOUT_SEC |
protected String |
containerId |
protected String |
containerName |
protected com.github.dockerjava.api.DockerClient |
dockerClient |
protected com.github.dockerjava.api.model.Info |
dockerDaemonInfo |
protected WaitStrategy |
waitStrategy
The approach to determine if the container is ready.
|
Constructor and Description |
---|
GenericContainer() |
GenericContainer(Future<String> image) |
GenericContainer(String dockerImageName) |
Modifier and Type | Method and Description |
---|---|
void |
addEnv(String key,
String value)
Add an environment variable to be passed to the container.
|
void |
addExposedPort(Integer port)
Add an exposed port.
|
void |
addExposedPorts(int... ports)
Add exposed ports.
|
void |
addFileSystemBind(String hostPath,
String containerPath,
BindMode mode)
Adds a file system binding.
|
protected void |
addFixedExposedPort(int hostPort,
int containerPort)
Add a container port that should be bound to a fixed port on the docker host.
|
void |
addLink(LinkableContainer otherContainer,
String alias)
Add a link to another container.
|
void |
close() |
protected void |
configure() |
protected void |
containerIsStarted(com.github.dockerjava.api.command.InspectContainerResponse containerInfo) |
protected void |
containerIsStarting(com.github.dockerjava.api.command.InspectContainerResponse containerInfo) |
protected Path |
createVolumeDirectory(boolean temporary)
Creates a directory on the local filesystem which will be mounted as a volume for the container.
|
Container.ExecResult |
execInContainer(Charset outputCharset,
String... command)
Run a command inside a running container, as though using "docker exec".
|
Container.ExecResult |
execInContainer(String... command)
Run a command inside a running container, as though using "docker exec", and interpreting
the output as UTF8.
|
com.github.dockerjava.api.model.Info |
fetchDockerDaemonInfo() |
protected void |
finished(org.junit.runner.Description description) |
void |
followOutput(Consumer<OutputFrame> consumer)
Follow container output, sending each frame (usually, line) to a consumer.
|
void |
followOutput(Consumer<OutputFrame> consumer,
OutputFrame.OutputType... types)
Follow container output, sending each frame (usually, line) to a consumer.
|
String |
getContainerIpAddress()
Get the IP address that this container may be reached on (may not be the local machine).
|
String |
getDockerImageName()
Get image name.
|
String |
getIpAddress()
Deprecated.
please use getContainerIpAddress() instead
|
protected Integer |
getLivenessCheckPort() |
Integer |
getMappedPort(int originalPort)
Get the actual mapped port for a given port exposed by the container.
|
String |
getTestHostIpAddress()
Get the IP address that containers (e.g.
|
protected WaitStrategy |
getWaitStrategy()
The
WaitStrategy to use to determine if the container is ready. |
Boolean |
isRunning() |
protected org.slf4j.Logger |
logger()
Provide a logger that references the docker image name.
|
void |
setCommand(String... commandParts)
Set the command that should be run in the container.
|
void |
setCommand(String command)
Set the command that should be run in the container.
|
void |
setDockerImageName(String dockerImageName)
Resolve Docker image and set it.
|
void |
start()
Starts the container using docker, pulling an image if necessary.
|
protected void |
starting(org.junit.runner.Description description) |
void |
stop()
Stops the container.
|
SELF |
waitingFor(WaitStrategy waitStrategy)
Specify the
WaitStrategy to use to determine if the container is ready. |
protected void |
waitUntilContainerStarted()
Wait until the container has started.
|
SELF |
withClasspathResourceMapping(String resourcePath,
String containerPath,
BindMode mode)
Map a resource (file or directory) on the classpath to a path inside the container.
|
SELF |
withCommand(String... commandParts)
Set the command that should be run in the container
|
SELF |
withCommand(String cmd)
Set the command that should be run in the container
|
SELF |
withCreateContainerCmdModifier(Consumer<com.github.dockerjava.api.command.CreateContainerCmd> modifier)
Allow low level modifications of
CreateContainerCmd after it was pre-configured in tryStart(Profiler) . |
SELF |
withEnv(Map<String,String> env)
Add environment variables to be passed to the container.
|
SELF |
withEnv(String key,
String value)
Add an environment variable to be passed to the container.
|
SELF |
withExposedPorts(Integer... ports)
Set the ports that this container listens on
|
SELF |
withExtraHost(String hostname,
String ipAddress)
Add an extra host entry to be passed to the container
|
SELF |
withFileSystemBind(String hostPath,
String containerPath,
BindMode mode)
Adds a file system binding.
|
SELF |
withLogConsumer(Consumer<OutputFrame> consumer)
Attach an output consumer at container startup, enabling stdout and stderr to be followed, waited on, etc.
|
SELF |
withMinimumRunningDuration(Duration minimumRunningDuration)
Only consider a container to have successfully started if it has been running for this duration.
|
SELF |
withNetworkMode(String networkMode)
Set the network mode for this container, similar to the
--net <name>
option on the docker CLI. |
SELF |
withPrivilegedMode(boolean mode)
Set the privilegedMode mode for the container
|
SELF |
withStartupAttempts(int attempts)
Allow container startup to be attempted more than once if an error occurs.
|
SELF |
withStartupCheckStrategy(StartupCheckStrategy strategy)
Set the startup check strategy used for checking whether the container has started.
|
SELF |
withStartupTimeout(Duration startupTimeout)
Set the duration of waiting time until container treated as started.
|
SELF |
withVolumesFrom(Container container,
BindMode mode)
Adds container volumes.
|
SELF |
withWorkingDirectory(String workDir)
Set the working directory that the container should use on startup.
|
apply, failed, succeeded
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
getBinds, getCommandParts, getContainerId, getContainerInfo, getContainerName, getDockerClient, getDockerDaemonInfo, getEnv, getExposedPorts, getExtraHosts, getImage, getLinkedContainers, getPortBindings, self, setBinds, setCommandParts, setContainerId, setContainerInfo, setContainerName, setDockerClient, setDockerDaemonInfo, setEnv, setExposedPorts, setExtraHosts, setImage, setLinkedContainers, setPortBindings, setWaitStrategy
public static final int CONTAINER_RUNNING_TIMEOUT_SEC
protected com.github.dockerjava.api.DockerClient dockerClient
protected com.github.dockerjava.api.model.Info dockerDaemonInfo
protected String containerId
protected String containerName
@NonNull protected WaitStrategy waitStrategy
public GenericContainer()
public GenericContainer(@NonNull String dockerImageName)
public void start()
public void stop()
protected org.slf4j.Logger logger()
protected Path createVolumeDirectory(boolean temporary)
temporary
- is the volume directory temporary? If true, the directory will be deleted on JVM shutdown.protected void configure()
protected void containerIsStarting(com.github.dockerjava.api.command.InspectContainerResponse containerInfo)
protected void containerIsStarted(com.github.dockerjava.api.command.InspectContainerResponse containerInfo)
protected Integer getLivenessCheckPort()
public SELF waitingFor(@NonNull WaitStrategy waitStrategy)
WaitStrategy
to use to determine if the container is ready.waitingFor
in interface Container<SELF extends GenericContainer<SELF>>
waitStrategy
- the WaitStrategy to useWait.defaultWaitStrategy()
protected WaitStrategy getWaitStrategy()
WaitStrategy
to use to determine if the container is ready.
Defaults to Wait.defaultWaitStrategy()
.WaitStrategy
to useprotected void waitUntilContainerStarted()
WaitStrategy
waitingFor(WaitStrategy)
public void setCommand(@NonNull String command)
Container.withCommand(String)
for building a container in a fluent style.setCommand
in interface Container<SELF extends GenericContainer<SELF>>
command
- a command in single string format (will automatically be split on spaces)public void setCommand(@NonNull String... commandParts)
Container.withCommand(String...)
for building a container in a fluent style.setCommand
in interface Container<SELF extends GenericContainer<SELF>>
commandParts
- a command as an array of string partspublic void addEnv(String key, String value)
Container.withEnv(String, String)
for building a container in a fluent style.addEnv
in interface Container<SELF extends GenericContainer<SELF>>
key
- environment variable keyvalue
- environment variable valuepublic void addFileSystemBind(String hostPath, String containerPath, BindMode mode)
Container.withFileSystemBind(String, String, BindMode)
for building a container in a fluent style.addFileSystemBind
in interface Container<SELF extends GenericContainer<SELF>>
hostPath
- the file system path on the hostcontainerPath
- the file system path inside the containermode
- the bind modepublic SELF withFileSystemBind(String hostPath, String containerPath, BindMode mode)
withFileSystemBind
in interface Container<SELF extends GenericContainer<SELF>>
hostPath
- the file system path on the hostcontainerPath
- the file system path inside the containermode
- the bind modepublic SELF withVolumesFrom(Container container, BindMode mode)
withVolumesFrom
in interface Container<SELF extends GenericContainer<SELF>>
container
- the container to add volumes frommode
- the bind modepublic void addLink(LinkableContainer otherContainer, String alias)
Container
addLink
in interface Container<SELF extends GenericContainer<SELF>>
otherContainer
- the other container object to link toalias
- the alias (for the other container) that this container should be able to usepublic void addExposedPort(Integer port)
Container
Container.withExposedPorts(Integer...)
for building a container in a fluent style.addExposedPort
in interface Container<SELF extends GenericContainer<SELF>>
port
- a TCP portpublic void addExposedPorts(int... ports)
Container
Container.withExposedPorts(Integer...)
for building a container in a fluent style.addExposedPorts
in interface Container<SELF extends GenericContainer<SELF>>
ports
- an array of TCP portsprotected void starting(org.junit.runner.Description description)
starting
in class FailureDetectingExternalResource
protected void finished(org.junit.runner.Description description)
finished
in class FailureDetectingExternalResource
public SELF withExposedPorts(Integer... ports)
withExposedPorts
in interface Container<SELF extends GenericContainer<SELF>>
ports
- an array of TCP portsprotected void addFixedExposedPort(int hostPort, int containerPort)
Note that this method is protected scope to discourage use, as clashes or instability are more likely when
using fixed port mappings. If you need to use this method from a test, please use FixedHostPortGenericContainer
instead of GenericContainer.
hostPort
- containerPort
- public SELF withEnv(String key, String value)
withEnv
in interface Container<SELF extends GenericContainer<SELF>>
key
- environment variable keyvalue
- environment variable valuepublic SELF withEnv(Map<String,String> env)
withEnv
in interface Container<SELF extends GenericContainer<SELF>>
env
- map of environment variablespublic SELF withCommand(String cmd)
withCommand
in interface Container<SELF extends GenericContainer<SELF>>
cmd
- a command in single string format (will automatically be split on spaces)public SELF withCommand(String... commandParts)
withCommand
in interface Container<SELF extends GenericContainer<SELF>>
commandParts
- a command as an array of string partspublic SELF withExtraHost(String hostname, String ipAddress)
withExtraHost
in interface Container<SELF extends GenericContainer<SELF>>
hostname
- hostname to use for this hosts file entryipAddress
- IP address to use for this hosts file entrypublic SELF withNetworkMode(String networkMode)
Container
--net <name>
option on the docker CLI.withNetworkMode
in interface Container<SELF extends GenericContainer<SELF>>
networkMode
- network mode, e.g. including 'host', 'bridge', 'none' or the name of an existing named network.public SELF withClasspathResourceMapping(String resourcePath, String containerPath, BindMode mode)
withClasspathResourceMapping
in interface Container<SELF extends GenericContainer<SELF>>
resourcePath
- path to the resource on the classpath (relative to the classpath root; should not start with a leading slash)containerPath
- path this should be mapped to inside the containermode
- access mode for the filepublic SELF withStartupTimeout(Duration startupTimeout)
withStartupTimeout
in interface Container<SELF extends GenericContainer<SELF>>
startupTimeout
- timeoutWaitStrategy.waitUntilReady(GenericContainer)
public SELF withPrivilegedMode(boolean mode)
Container
withPrivilegedMode
in interface Container<SELF extends GenericContainer<SELF>>
mode
- booleanpublic String getContainerIpAddress()
getContainerIpAddress
in interface Container<SELF extends GenericContainer<SELF>>
public SELF withMinimumRunningDuration(Duration minimumRunningDuration)
withMinimumRunningDuration
in interface Container<SELF extends GenericContainer<SELF>>
minimumRunningDuration
- duration this container should run for if started successfullypublic SELF withStartupCheckStrategy(StartupCheckStrategy strategy)
withStartupCheckStrategy
in interface Container<SELF extends GenericContainer<SELF>>
strategy
- startup check strategypublic SELF withWorkingDirectory(String workDir)
withWorkingDirectory
in interface Container<SELF extends GenericContainer<SELF>>
workDir
- path to the working directory inside the container@Deprecated public String getIpAddress()
public Boolean isRunning()
isRunning
in interface Container<SELF extends GenericContainer<SELF>>
public Integer getMappedPort(int originalPort)
getMappedPort
in interface Container<SELF extends GenericContainer<SELF>>
originalPort
- the original TCP port that is exposedpublic void setDockerImageName(@NonNull String dockerImageName)
setDockerImageName
in interface Container<SELF extends GenericContainer<SELF>>
dockerImageName
- image name@NonNull public String getDockerImageName()
getDockerImageName
in interface Container<SELF extends GenericContainer<SELF>>
public String getTestHostIpAddress()
For example, if a web server is running on port 8080 on this local machine, the containerized web driver needs to be pointed at "http://" + getTestHostIpAddress() + ":8080" in order to access it. Trying to hit localhost from inside the container is not going to work, since the container has its own IP address.
getTestHostIpAddress
in interface Container<SELF extends GenericContainer<SELF>>
public void followOutput(Consumer<OutputFrame> consumer)
followOutput
in interface Container<SELF extends GenericContainer<SELF>>
consumer
- consumer that the frames should be sent topublic void followOutput(Consumer<OutputFrame> consumer, OutputFrame.OutputType... types)
followOutput
in interface Container<SELF extends GenericContainer<SELF>>
consumer
- consumer that the frames should be sent totypes
- types that should be followed (one or both of STDOUT, STDERR)public SELF withLogConsumer(Consumer<OutputFrame> consumer)
More than one consumer may be registered.
withLogConsumer
in interface Container<SELF extends GenericContainer<SELF>>
consumer
- consumer that output frames should be sent topublic com.github.dockerjava.api.model.Info fetchDockerDaemonInfo() throws IOException
fetchDockerDaemonInfo
in interface Container<SELF extends GenericContainer<SELF>>
IOException
public Container.ExecResult execInContainer(String... command) throws UnsupportedOperationException, IOException, InterruptedException
execInContainer
in interface Container<SELF extends GenericContainer<SELF>>
UnsupportedOperationException
IOException
InterruptedException
Container.execInContainer(Charset, String...)
public Container.ExecResult execInContainer(Charset outputCharset, String... command) throws UnsupportedOperationException, IOException, InterruptedException
This functionality is not available on a docker daemon running the older "lxc" execution driver. At the time of writing, CircleCI was using this driver.
execInContainer
in interface Container<SELF extends GenericContainer<SELF>>
outputCharset
- the character set used to interpret the output.command
- the parts of the command to runUnsupportedOperationException
- if the docker daemon you're connecting to doesn't support "exec".IOException
- if there's an issue communicating with DockerInterruptedException
- if the thread waiting for the response is interruptedpublic SELF withStartupAttempts(int attempts)
attempts
- number of attemptspublic void close()
close
in interface AutoCloseable
public SELF withCreateContainerCmdModifier(Consumer<com.github.dockerjava.api.command.CreateContainerCmd> modifier)
CreateContainerCmd
after it was pre-configured in tryStart(Profiler)
.
Invocation happens eagerly on a moment when container is created.
Warning: this does expose the underlying docker-java API so might change outside of our control.modifier
- Consumer
of CreateContainerCmd
.Copyright © 2017. All rights reserved.