Package hudson

Class FilePath

java.lang.Object
hudson.FilePath
All Implemented Interfaces:
Serializable, org.jenkinsci.remoting.SerializableOnlyOverRemoting
public final class FilePath extends Object implements org.jenkinsci.remoting.SerializableOnlyOverRemoting
File like object with remoting support.

Unlike File, which always implies a file path on the current computer, FilePath represents a file path on a specific agent or the controller. Despite that, FilePath can be used much like File. It exposes a bunch of operations (and we should add more operations as long as they are generally useful), and when invoked against a file on a remote node, FilePath executes the necessary code remotely, thereby providing semi-transparent file operations.

Using FilePath smartly

The transparency makes it easy to write plugins without worrying too much about remoting, by making it works like NFS, where remoting happens at the file-system layer.

But one should note that such use of remoting may not be optional. Sometimes, it makes more sense to move some computation closer to the data, as opposed to move the data to the computation. For example, if you are just computing a MD5 digest of a file, then it would make sense to do the digest on the host where the file is located, as opposed to send the whole data to the controller and do MD5 digesting there.

FilePath supports this "code migration" by in the act(FileCallable) method. One can pass in a custom implementation of FilePath.FileCallable, to be executed on the node where the data is located. The following code shows the example: 

 void someMethod(FilePath file) {
     // make 'file' a fresh empty directory.
     file.act(new Freshen());
 }
 // if 'file' is on a different node, this FileCallable will
 // be transferred to that node and executed there.
 private static final class Freshen implements FileCallable<Void> {
     private static final long serialVersionUID = 1;
     @Override public Void invoke(File f, VirtualChannel channel) {
         // f and file represent the same thing
         f.deleteContents();
         f.mkdirs();
         return null;
     }
 }

When FilePath.FileCallable is transferred to a remote node, it will be done so by using the same Java serialization scheme that the remoting module uses. See Channel for more about this.

FilePath itself can be sent over to a remote node as a part of Callable serialization. For example, sending a FilePath of a remote node to that node causes FilePath to become "local". Similarly, sending a FilePath that represents the local computer causes it to become "remote."

Author:
Kohsuke Kawaguchi
See Also: