Fork me on GitHub

Introduction

The Maven VFS Plugin is wrapper of Apache Common Virtual File System with extensive use of the popular ANT's 'FileSet' to manipulate ( list, copy, move, remove, etc ) resources across virtual file systems that support directory listing such as ftp, ftps, sftp, file, webdav.

The follow sections show you how to configure your VFS credential and examples on various operations.

Functional examples are also available at https://svn.codehaus.org/mojo/trunk/mojo/vfs/vfs-maven-plugin/src/examples

Authentication Settings

In order to access remote resource, very likely you will need to provide your authentication credential to Maven via your local settings.xml file. Below contains a couple of examples. For password encryption, see Maven Password Encryption for details.

    <server>
      <id>some.server.id</id>
      <username>username</username>
      <password>clear-text-password</password>
    </server>

    <server>
      <id>vfstest</id>
      <username>vfstest</username>
      <password>{rFKiZpcq1e0Hg79iA6LwZFSCG3fZIFCNiJLFTPf7CNM=}</password>
    </server>

There is one built-in convenient server settings with id 'ftp.anonymous' to allow anonymous access to ftp servers.

    <!--this is a built-in settings that allows anonymous ftp authentication -->
    <server>
      <id>ftp.anonymous</id>
      <username>anonymous</username>
      <password>anonymous@anonymous.com</password>
    </server>

List Goal

You can use vfs:list goal from command line to verify the remote resource file list.

The below example shows how to list a remote directory using FTP protocol at ftp://ftp.osuosl.org/pub/centos.

        mvn vfs:list -DsourceId=ftp.anonymous -Dsource=ftp://ftp.osuosl.org/.1/centos/6.0/ -Dincludes="*"

Note:

  • sourceId=ftp.anonymous is built-in with this plugin.
  • use your source,includes, and excludes arguments wisely to reduce the number to recursive directory scanning on remote resource to reduce scanning time. For example the following command will take a very very long time.
        mvn vfs:list -DsourceId=ftp.anonymous -Dsource=ftp://ftp.osuosl.org/.1/centos -Dincludes="**"

Copy Goal

The below example shows how to copy a directory content, non recursive, from a FTP server to a SFTP server

<project>
  [...]
  <build>

    <plugin>
      <groupId>org.codehaus.mojo</groupId>
      <artifactId>vfs-maven-plugin</artifactId>
      <version>1.0.1</version>
      <executions>
        <execution>
          <id>download-test-data</id>
          <phase>pre-integration-test</phase>
          <goals>
            <goal>copy</goal>
          </goals>
          <configuration>
            <fileset>
              <sourceId>your.ftp.settings.server.id</sourceId>
              <source>ftp://your.ftp.host/path/to/a/directory</source>
              <includes>
                <include>*</include>
              </includes>
              <destinationId>your.sftp.settings.server.id</destinationId>
              <destination>sftp://sftp.host/path/to/a/directory</fromDir>
            </fileset>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </build>
  [...]
</project>

Since http/https are not supported, only single file copy is allowed.

<project>
  [...]
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>vfs-maven-plugin</artifactId>
        <version>1.0.1</version>
        <executions>
          <execution>
            <id>http2file</id>
            <phase>test</phase>
            <goals>
              <goal>copy</goal>
            </goals>
            <configuration>
              <fileset>
                <source>http://repo1.maven.org/maven2/org/apache/maven/plugins</source>
                <includes>
                  <include>maven-metadata.xml</include>
                  <include>maven-metadata.xml.md5</include>
                </includes>
                <destination>file://${project.build.directory}/test</destination>
              </fileset>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  [...]
</project>

Move Goal

The below example shows how to move ( copy then remove ) a directory content, non recursive, from a WEBDav server to a SFTP server.

<project>
  [...]
  <build>

    <plugin>
      <groupId>org.codehaus.mojo</groupId>
      <artifactId>vfs-maven-plugin</artifactId>
      <version>1.0.1</version>
      <executions>
        <execution>
          <id>download-test-data</id>
          <phase>pre-integration-test</phase>
          <goals>
            <goal>move</goal>
          </goals>
          <configuration>
            <fileset>
              <sourceId>your.webdav.settings.server.id</sourceId>
              <source>webdav://your.webdap.host/path/to/a/directory</source>
              <includes>
                <include>*</include>
              </includes>
              <destinationId>your.sftp.settings.server.id</destinationId>
              <destination>sftp://sftp.host/path/to/a/directory</fromDir>
            </fileset>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </build>
  [...]
</project>

Remove Goal

The below example shows how to remove a directory content, non recursive, from a FTP server.

<project>
  [...]
  <build>

    <plugin>
      <groupId>org.codehaus.mojo</groupId>
      <artifactId>vfs-maven-plugin</artifactId>
      <version>1.0.1</version>
      <executions>
        <execution>
          <id>download-test-data</id>
          <phase>pre-integration-test</phase>
          <goals>
            <goal>remove</goal>
          </goals>
          <configuration>
            <fileset>
              <sourceId>your.ftp.settings.server.id</sourceId>
              <source>ftp://your.ftp.host/path/to/a/directory</source>
              <includes>
                <include>*</include>
              </includes>
            </fileset>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </build>
  [...]
</project>

Merge Maven Repositories Goal

If your Maven repository manager (MRM) does not provide a repositories merging feature (ex Nexus Open Source Edition), this goal is an alternative solution where you can configure your Maven deploy plugin to deploy released artifacts to a temporary/staged released repository at your MRM. Once your staging repository contents are blessed/validated, use this plugin to merge the staged content to the actual release repository.

Here is an example how to merge a staging repository to main repository through local file system at your MRM.

  mvn vfs:merge-maven-repositories -Dsource=file:///path/to/your/staging/directory \
      -Ddestination=file:///path/to/your/main/release/directory \
      -DstagingDirectory=/tmp/staging -DdryRun=false

You can enable dryRun flag to review merged contents under stagingDirectory before it is pushed into destination directory

You can also merge the repositories using other protocols supported by VFS ( ie sftp, ftp, webdav, etc ) except http/https since it does support directory file scanning required during merge.