hudson
Class FileSystemProvisioner

java.lang.Object
  extended by 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

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
equals, 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.getProject().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.



Copyright © 2004-2013 Hudson. All Rights Reserved.