com.google.jenkins.plugins.storage

Class AbstractUpload

java.lang.Object

com.google.jenkins.plugins.storage.AbstractUpload

All Implemented Interfaces:

hudson.ExtensionPoint, hudson.model.Describable<AbstractUpload>, Serializable

Direct Known Subclasses:

AbstractBucketLifecycleManager, ClassicUpload, StdoutUpload

public abstract class AbstractUpload
extends Object
implements hudson.model.Describable<AbstractUpload>, hudson.ExtensionPoint, Serializable

This new extension point is used for surfacing different kinds of Google Cloud Storage (GCS) uploads. The most obvious implementations are provided as:

See Also:

ClassicUpload, We provide the following hooks for implementations to inject additional functionality:

• Required {@link #getDetails}: provides detail information for the GCS upload report.
• Required {@link #getInclusions}: surfaces the set of {@link UploadSpec} for the base class to upload to GCS.
• Optional {@link #forResult}: determines the build states for which uploading should be performed.
• Optional {@link #getMetadata}: allows the implementation to surface additional metadata on the storage object
• Optional {@link #annotateObject}: allows the implementation to ~arbitrarily rewrite parts of the object prior to insertion.

, Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	AbstractUpload.UploadSpec This tuple is used to return the modified workspace and collection of FilePaths to upload to perform(com.google.jenkins.plugins.credentials.oauth.GoogleRobotCredentials, hudson.model.AbstractBuild<?, ?>, hudson.model.TaskListener).

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

hudson.ExtensionPoint.LegacyInstancesAreScopedToHudson

Field Summary

Fields

Modifier and Type	Field and Description
protected UploadModule	module The module to use for providing dependencies.

Constructor Summary

Constructors

Constructor and Description
AbstractUpload(String bucket, boolean sharedPublicly, boolean forFailedJobs, String pathPrefix, UploadModule module) Construct the base upload from a handful of universal properties.

Method Summary

Methods

Modifier and Type	Method and Description
static hudson.DescriptorExtensionList<AbstractUpload,AbstractUploadDescriptor>	all() Boilerplate, see: https://wiki.jenkins-ci.org/display/JENKINS/Defining+a+new+extension+point
protected void	annotateObject(com.google.api.services.storage.model.StorageObject object, hudson.model.TaskListener listener) This hook is intended to give implementations the opportunity to further annotate the StorageObject with metadata before uploading it to cloud storage.
boolean	forResult(hudson.model.Result result) Determine whether we should upload the pattern for the given build result.
String	getBucket() The bucket name specified by the user, which potentially contains unresolved symbols, such as $JOB_NAME and $BUILD_NUMBER.
AbstractUploadDescriptor	getDescriptor() Boilerplate, see: https://wiki.jenkins-ci.org/display/JENKINS/Defining+a+new+extension+point
abstract String	getDetails() Provide detail information summarizing this download for the GCS upload report.
protected abstract AbstractUpload.UploadSpec	getInclusions(hudson.model.AbstractBuild<?,?> build, hudson.FilePath workspace, hudson.model.TaskListener listener) Implementations override this interface in order to surface the set of FilePaths the core logic should upload.
protected Map<String,String>	getMetadata(hudson.model.AbstractBuild<?,?> build) Retrieves the metadata to attach to the storage object.
protected com.google.api.services.storage.model.Bucket	getOrCreateBucket(com.google.api.services.storage.Storage service, com.google.jenkins.plugins.credentials.oauth.GoogleRobotCredentials credentials, com.google.jenkins.plugins.util.Executor executor, String bucketName) Fetches or creates an instance of the bucket with the given name with the specified storage service.
String	getPathPrefix() The path prefix that will be stripped from uploaded files.
static String	getRelative(hudson.FilePath include, hudson.FilePath workspace) Compute the relative path of the given file inclusion, relative to the given workspace.
boolean	isForFailedJobs() Whether to attempt the upload, even if the job failed.
boolean	isSharedPublicly() Whether to surface the file being uploaded to anyone with the link.
void	perform(com.google.jenkins.plugins.credentials.oauth.GoogleRobotCredentials credentials, hudson.model.AbstractBuild<?,?> build, hudson.model.TaskListener listener) The main action entrypoint of this extension.

Methods inherited from class java.lang.Object

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

Field Detail

module

protected final UploadModule module

The module to use for providing dependencies.

Constructor Detail

AbstractUpload

public AbstractUpload(String bucket,
              boolean sharedPublicly,
              boolean forFailedJobs,
              @Nullable
              String pathPrefix,
              @Nullable
              UploadModule module)

Construct the base upload from a handful of universal properties.

Parameters:

bucket - The unresolved name of the storage bucket within which to store the resulting objects.

sharedPublicly - Whether to publicly share the objects being uploaded

forFailedJobs - Whether to perform the upload regardless of the build's outcome

pathPrefix - Path prefix to strip from uploaded files when determining the filename in GCS. Null indicates no stripping. Filenames that do not start with this prefix will not be modified. Trailing slash is automatically added if it is missing.

Method Detail

perform

public final void perform(com.google.jenkins.plugins.credentials.oauth.GoogleRobotCredentials credentials,
           hudson.model.AbstractBuild<?,?> build,
           hudson.model.TaskListener listener)
                   throws UploadException

The main action entrypoint of this extension. This uploads the contents included by the implementation to our resolved storage bucket.

Throws:

UploadException

getInclusions

@Nullable
protected abstract AbstractUpload.UploadSpec getInclusions(hudson.model.AbstractBuild<?,?> build,
                                               hudson.FilePath workspace,
                                               hudson.model.TaskListener listener)
                                                    throws UploadException

Implementations override this interface in order to surface the set of FilePaths the core logic should upload.

Throws:

UploadException

See Also:

for further details.

getDetails

public abstract String getDetails()

Provide detail information summarizing this download for the GCS upload report.

annotateObject

protected void annotateObject(com.google.api.services.storage.model.StorageObject object,
                  hudson.model.TaskListener listener)
                       throws UploadException

This hook is intended to give implementations the opportunity to further annotate the StorageObject with metadata before uploading it to cloud storage. NOTE: The base implementation does not do anything, so calling super.annotateObject() is unnecessary.

Throws:

UploadException

getMetadata

protected Map<String,String> getMetadata(hudson.model.AbstractBuild<?,?> build)

Retrieves the metadata to attach to the storage object. NOTE: This can be overriden to surface additional (or less) information.

forResult

public boolean forResult(hudson.model.Result result)

Determine whether we should upload the pattern for the given build result.

getBucket

public String getBucket()

The bucket name specified by the user, which potentially contains unresolved symbols, such as $JOB_NAME and $BUILD_NUMBER.

isSharedPublicly

public boolean isSharedPublicly()

Whether to surface the file being uploaded to anyone with the link.

isForFailedJobs

public boolean isForFailedJobs()

Whether to attempt the upload, even if the job failed.

getPathPrefix

@Nullable
public String getPathPrefix()

The path prefix that will be stripped from uploaded files. May be null if no path prefix needs to be stripped.

all

public static hudson.DescriptorExtensionList<AbstractUpload,AbstractUploadDescriptor> all()

Boilerplate, see: https://wiki.jenkins-ci.org/display/JENKINS/Defining+a+new+extension+point

getDescriptor

public AbstractUploadDescriptor getDescriptor()

Boilerplate, see: https://wiki.jenkins-ci.org/display/JENKINS/Defining+a+new+extension+point

Specified by:

getDescriptor in interface hudson.model.Describable<AbstractUpload>

getOrCreateBucket

protected com.google.api.services.storage.model.Bucket getOrCreateBucket(com.google.api.services.storage.Storage service,
                                                             com.google.jenkins.plugins.credentials.oauth.GoogleRobotCredentials credentials,
                                                             com.google.jenkins.plugins.util.Executor executor,
                                                             String bucketName)
                                                                  throws UploadException

Fetches or creates an instance of the bucket with the given name with the specified storage service.

Parameters:

credentials - The credentials with which to fetch/create the bucket

bucketName - The top-level bucket name to ensure exists

Returns:

an instance of the named bucket, created or retrieved.

Throws:

UploadException - if any issues are encountered

getRelative

public static String getRelative(hudson.FilePath include,
                 hudson.FilePath workspace)
                          throws UploadException

Compute the relative path of the given file inclusion, relative to the given workspace. If the path is absolute, it returns the root-relative path instead.

Parameters:

include - The file whose relative path we are computing

workspace - The workspace containing the included file.

Returns:

The unix-style relative path of file.

Throws:

UploadException - when the input is malformed