io.fabric8.maven.docker.util

Class VolumeBindingUtil

java.lang.Object

io.fabric8.maven.docker.util.VolumeBindingUtil

public class VolumeBindingUtil
extends Object

Utility methods for working with Docker volume bindings.

This class provides explicit support for relative binding paths. This means that the plugin configuration or docker compose file can specify a relative path when configuring a volume binding. Methods in this class will examine volume binding strings in a RunVolumeConfiguration and resolve any relative paths in the host portion of volume bindings. Examples of relative bindings include:

A host path relative to the current working directory

./relative/path:/absolute/container/path

A host path relative to the current working directory

relative/path/:/absolute/container/path

A host path relative to the parent of the current working directory

../relative/path:/absolute/container/path

A host path equal to the current user's home directory

~:/absolute/container/path

A host path relative to the current user's home directory

~/relative/path:/absolute/container/path

Understand that the following is not considered a relative binding path, and is instead interpreted as a named volume:

rel is interpreted as a named volume. Use ./rel or rel/ to have it interpreted as a relative path.

rel:/absolute/container/path

Volume bindings that specify an absolute path for the host portion are preserved and returned unmodified.

Constructor Summary

Constructors

Constructor and Description
VolumeBindingUtil()

Method Summary

Modifier and Type	Method and Description
static String	resolveRelativeVolumeBinding(File baseDir, String bindingString) Resolves relative paths in the supplied bindingString, and returns a binding string that has relative paths replaced with absolute paths.
static void	resolveRelativeVolumeBindings(File baseDir, RunVolumeConfiguration volumeConfiguration) Iterates over each binding in the volumeConfiguration, and resolves any relative paths in the binding strings using resolveRelativeVolumeBinding(File, String).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

VolumeBindingUtil

public VolumeBindingUtil()

Method Detail

resolveRelativeVolumeBinding

public static String resolveRelativeVolumeBinding(File baseDir,
                                                  String bindingString)

Resolves relative paths in the supplied bindingString, and returns a binding string that has relative paths replaced with absolute paths. If the supplied bindingString does not contain a relative path, it is returned unmodified.

Discussion:

Volumes may be defined inside of service blocks as documented here:

 volumes:
 # Just specify a path and let the Engine create a volume
 - /var/lib/mysql

 # Specify an absolute path mapping
 - /opt/data:/var/lib/mysql

 # Path on the host, relative to the Compose file
 - ./cache:/tmp/cache

 # User-relative path
 - ~/configs:/etc/configs/:ro

 # Named volume
 - datavolume:/var/lib/mysql"
 

This method only operates on volume strings that are relative: beginning with ./, ../, or ~. Relative paths beginning with ./ or ../ are absolutized relative to the supplied baseDir, which must be absolute. Paths beginning with ~ are interpreted relative to new File(System.getProperty("user.home")), and baseDir is ignored.

Volume strings that do not begin with a ./, ../, or ~ are returned as-is.

Examples:

Given baseDir equal to "/path/to/basedir" and a bindingString string equal to "./reldir:/some/other/dir", this method returns /path/to/basedir/reldir:/some/other/dir

Given baseDir equal to "/path/to/basedir" and a bindingString string equal to "../reldir:/some/other/dir", this method returns /path/to/reldir:/some/other/dir

Given baseDir equal to "/path/to/basedir" and a bindingString string equal to "~/reldir:/some/other/dir", this method returns /home/user/reldir:/some/other/dir

Given baseDir equal to "/path/to/basedir" and a bindingString equal to "src/test/docker:/some/other/dir", this method returns /path/to/basedir/src/test/docker:/some/other/dir

Given a bindingString equal to "foo:/some/other/dir", this method returns foo:/some/other/dir, because foo is considered to be a named volume, not a relative path.

Parameters:

baseDir - the base directory used to resolve relative paths (e.g. beginning with ./, ../, ~) present in the bindingString; must be absolute

bindingString - the volume string from the docker-compose file

Returns:

the volume string, with any relative paths resolved as absolute paths

Throws:

IllegalArgumentException - if the supplied baseDir is not absolute

resolveRelativeVolumeBindings

public static void resolveRelativeVolumeBindings(File baseDir,
                                                 RunVolumeConfiguration volumeConfiguration)

Iterates over each binding in the volumeConfiguration, and resolves any relative paths in the binding strings using resolveRelativeVolumeBinding(File, String). The volumeConfiguration is modified in place, with any relative paths replaced with absolute paths.

Relative paths are resolved relative to the supplied baseDir, which must be absolute.

Parameters:

baseDir - the base directory used to resolve relative paths (e.g. beginning with ./, ../, ~) present in the binding string; must be absolute

volumeConfiguration - the volume configuration that may contain volume binding specifications

Throws:

IllegalArgumentException - if the supplied baseDir is not absolute