hudson
Class FileSystemProvisioner

java.lang.Object
  hudson.FileSystemProvisioner

All Implemented Interfaces:

ExtensionPoint, Describable<FileSystemProvisioner>

Direct Known Subclasses:

FileSystemProvisioner.Default, ZFSProvisioner

public abstract class FileSystemProvisioner
extends Object
implements ExtensionPoint, Describable<FileSystemProvisioner>

Prepares and provisions workspaces for AbstractProjects.

STILL A WORK IN PROGRESS. SUBJECT TO CHANGE! DO NOT EXTEND. TODO: is this per Computer? Per Job? -> probably per slave.

Design Problems

1. Garbage collection of snapshots. When do we discard snapshots? In one use case, it would be convenient to keep the snapshot of the last promoted/successful build. So we need to define a mechanism to veto GC of snapshot? like an interface that Action can implement? Snapshot should be obtained per user's direction. That would be a good moment for the user to specify the retention policy.
2. Configuration mechanism. Should we auto-detect FileSystemProvisioner per OS? (but for example, zfs support would require the root access.) People probably needs to be able to disable this feature, which means one more configuration option. It's especially tricky because during the configuration we don't know the OS type. OTOH special slave type like the ones for network.com grid can hide this.

Recap

To recap, - when a slave connects, we auto-detect the file system provisioner. (for example, ZFS FSP would check the slave root user prop and/or attempt to "pfexec zfs create" and take over.) - the user may configure jobs for snapshot collection, along with the retention policy. - keep workspace snapshots that correspond to the permalinks In ZFS, use a user property to remember the build and the job. Can't the 2nd step happen automatically, when someone else depends on the workspace snapshot of the upstream? Yes, by using RunListener. So this becomes like a special SCM type.

Design take 2

The first piece of this is the custom SCM, which inherits the workspace of another job. When this executes, it picks up WorkspaceSnapshot from the other job and use it to obtain the workspace.

Then there's RunListener, which creates a snapshot if someone else is interested in using a snapshot later.

TODOs

• Garbage collection of workspace snapshots.

Since:

1.235

Author:

Kohsuke Kawaguchi

Nested Class Summary

static class

FileSystemProvisioner.Default Default implementation that doesn't rely on any file system specific capability, and thus can be used anywhere that Hudson runs.

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Field Summary

static FileSystemProvisioner

DEFAULT Default implementation.

Constructor Summary

FileSystemProvisioner()

Method Summary

static DescriptorExtensionList<FileSystemProvisioner,FileSystemProvisionerDescriptor>	all() Returns all the registered FileSystemProvisioner descriptors.
abstract void	discardWorkspace(AbstractProject<?,?> project, FilePath ws) When a project is deleted, this method is called to undo the effect of prepareWorkspace(AbstractBuild, FilePath, TaskListener).
FileSystemProvisionerDescriptor	getDescriptor() Gets the descriptor for this instance.
abstract void	prepareWorkspace(AbstractBuild<?,?> build, FilePath ws, TaskListener listener) Called very early in the build (before a build places any files in the workspace, such as SCM checkout) to provision a workspace for the build.
abstract WorkspaceSnapshot	snapshot(AbstractBuild<?,?> build, FilePath ws, String glob, TaskListener listener) Obtains the snapshot of the workspace of the given build.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT

public static final FileSystemProvisioner DEFAULT

Default implementation.

Constructor Detail

FileSystemProvisioner

public FileSystemProvisioner()

Method Detail

prepareWorkspace

public abstract void prepareWorkspace(AbstractBuild<?,?> build,
                                      FilePath ws,
                                      TaskListener listener)
                               throws IOException,
                                      InterruptedException

Called very early in the build (before a build places any files in the workspace, such as SCM checkout) to provision a workspace for the build.

This method can prepare the underlying file system in preparation for the later #snapshot(AbstractBuild, FilePath, TaskListener). TODO : the method needs to be able to see the snapshot would be later needed. In fact, perhaps we should only call this method when Hudson knows that a snapshot is later needed?

Parameters:

ws - New workspace should be prepared in this location. This is the same value as build.getProject().getWorkspace() but passed separately for convenience.

Throws:

IOException

InterruptedException

discardWorkspace

public abstract void discardWorkspace(AbstractProject<?,?> project,
                                      FilePath ws)
                               throws IOException,
                                      InterruptedException

When a project is deleted, this method is called to undo the effect of prepareWorkspace(AbstractBuild, FilePath, TaskListener).

Parameters:

project - Project whose workspace is being discarded.

ws - Workspace to be discarded. This workspace is on the node this FileSystemProvisioner is provisioned for.

Throws:

IOException

InterruptedException

snapshot

public abstract WorkspaceSnapshot snapshot(AbstractBuild<?,?> build,
                                           FilePath ws,
                                           String glob,
                                           TaskListener listener)
                                    throws IOException,
                                           InterruptedException

Obtains the snapshot of the workspace of the given build.

The state of the build when this method is invoked depends on the project type. Most would call this at the end of the build, but for example MatrixBuild would call this after SCM check out so that the state of the fresh workspace can be then propagated to elsewhere.

If the implementation of this method needs to store data in a file system, do so under Run.getRootDir(), since the lifecycle of the snapshot is tied to the life cycle of a build.

Parameters:

ws - New workspace should be prepared in this location. This is the same value as build.getWorkspace() but passed separately for convenience.

glob - Ant-style file glob for files to include in the snapshot. May not be pertinent for all implementations.

Throws:

IOException

InterruptedException

getDescriptor

public FileSystemProvisionerDescriptor getDescriptor()

Description copied from interface: Describable

Gets the descriptor for this instance.

Descriptor is a singleton for every concrete Describable implementation, so if a.getClass()==b.getClass() then a.getDescriptor()==b.getDescriptor() must hold.

Specified by:

getDescriptor in interface Describable<FileSystemProvisioner>

all

public static DescriptorExtensionList<FileSystemProvisioner,FileSystemProvisionerDescriptor> all()

Returns all the registered FileSystemProvisioner descriptors.