Package io.fabric8.maven.docker.util

Class 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 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