Package com.atlassian.bamboo.build.artifact

Interface ArtifactHandler

All Superinterfaces:

BambooPluginModule

All Known Subinterfaces:

RepublishingArtifactHandler

All Known Implementing Classes:

AbstractArtifactHandler, AbstractLocalArtifactHandler, AbstractRepublishingArtifactHandler, AgentLocalArtifactHandler, ArtifactHandlerDecoratorSupport, ArtifactHandlerPackagingDecorator, BambooRemoteArtifactHandler, RemoteTransferFallbackArtifactHandler, S3ArtifactHandler, ServerLocalArtifactHandler

public interface ArtifactHandler
extends BambooPluginModule

Handles artifact storage. Should provide 'local' (i.e. per plan basis) and 'global' storage. Artifacts in 'global' storage should not be removed when producing result (plan) is removed.

Field Summary

Fields

Modifier and Type	Field	Description
static int	LAN_SPEED
static int	LOCAL_SPEED
static long	NEVER_ARCHIVE	A value to be used within getMaxUnarchivedFilesPerArtifact(Map) to completely disable archiving of artifacts.
static int	WAN_SPEED

Method Summary

Modifier and Type	Method	Description
boolean	canHandleArtifact(ArtifactDefinitionContext artifact, Map<String,String> artifactHandlersConfiguration)
@Nullable ArtifactLinkDataProvider	getArtifactLinkDataProvider(Artifact artifact, @NotNull ArtifactHandlerConfigProvider artifactHandlerConfigProvider)
@Nullable ArtifactLinkDataProvider	getArtifactLinkDataProvider(ArtifactLink artifactLink, @NotNull ArtifactHandlerConfigProvider artifactHandlerConfigProvider)
@NotNull Map<String,String>	getDefaultConfiguration()
long	getMaxUnarchivedFilesPerArtifact(@NotNull Map<String,String> artifactHandlersConfiguration)	Returns the maximum number of files that can exist per artifact which will not be compressed and combined into a single archive.
@NotNull ArtifactHandlerModuleDescriptor	getModuleDescriptor()
int	getSpeed(@NotNull Map<String,String> artifactHandlersConfiguration)	Return approximate transfer speed of this artifact handler in bytes per second for the specified configuration.
@NotNull Set<AgentType>	getSupportedAgents()
boolean	moveArtifactToGlobalStorage(@NotNull Artifact artifact, @NotNull ArtifactHandlerConfigProvider artifactHandlerConfigProvider)	Move artifact to a 'global storage'.
default @NotNull ArtifactHandlerPublishingResult	publish(@NotNull ResultKey resultKey, @NotNull ArtifactDefinitionContext artifact, @NotNull ArtifactPublishingConfig artifactPublishingConfig)	Deprecated. since 8.1 use publish(ResultKey, ArtifactDefinitionContext, ArtifactPublishingConfig, BuildLogger)
@NotNull ArtifactHandlerPublishingResult	publish(@NotNull ResultKey resultKey, @NotNull ArtifactDefinitionContext artifact, @NotNull ArtifactPublishingConfig artifactPublishingConfig, @Nullable BuildLogger buildLogger)
default void	removeAllArtifactsOfChain(@NotNull PlanKey planKey, @NotNull ArtifactHandlerConfigProvider artifactHandlerConfigProvider)	Removes artifact files for all results of a single chain.
void	removeArtifactFromStorage(@NotNull Artifact artifact, @NotNull ArtifactHandlerConfigProvider artifactHandlerConfigProvider)	Removes artifact files for a single artifact.
void	removeArtifactFromStorage(@NotNull PlanResultKey planResultKey, @NotNull ImmutableArtifactDefinitionBase artifact, @NotNull ArtifactHandlerConfigProvider artifactHandlerConfigProvider)	Removes artifact files for a single artifact.
void	removeArtifactFromStorage(@NotNull ResultKey resultKey, @NotNull ImmutableArtifactDefinitionBase artifact, @NotNull ArtifactHandlerConfigProvider artifactHandlerConfigProvider)	Removes artifact files for a single artifact.
void	removeArtifactsFromStorage(@NotNull PlanKey planKey, @NotNull ArtifactHandlerConfigProvider artifactHandlerConfigProvider)	Removes artifact files for all results of a single chain or job.
void	removeArtifactsFromStorage(@NotNull PlanResultKey planResultKey, @NotNull ArtifactHandlerConfigProvider artifactHandlerConfigProvider)	Removes artifact files for a single plan result.
@NotNull ArtifactRetrievalStatus	retrieve(@NotNull ResultKey clientKey, @NotNull Artifact artifact, @NotNull ArtifactSubscriptionContext artifactSubscription, @NotNull ArtifactRetrievalConfig artifactRetrievalConfig)	Retrieve arbitrary Artifact.

Field Detail

NEVER_ARCHIVE

static final long NEVER_ARCHIVE

A value to be used within getMaxUnarchivedFilesPerArtifact(Map) to completely disable archiving of artifacts.

See Also:

Constant Field Values

LOCAL_SPEED

static final int LOCAL_SPEED

See Also:

Constant Field Values

LAN_SPEED

static final int LAN_SPEED

See Also:

Constant Field Values

WAN_SPEED

static final int WAN_SPEED

See Also:

Constant Field Values

Method Detail

publish

@Deprecated
@NotNull
default @NotNull ArtifactHandlerPublishingResult publish(@NotNull
                                                         @NotNull ResultKey resultKey,
                                                         @NotNull
                                                         @NotNull ArtifactDefinitionContext artifact,
                                                         @NotNull
                                                         @NotNull ArtifactPublishingConfig artifactPublishingConfig)
                                                  throws Exception

Deprecated.

since 8.1 use publish(ResultKey, ArtifactDefinitionContext, ArtifactPublishingConfig, BuildLogger)

Throws:

Exception

publish

@NotNull
@NotNull ArtifactHandlerPublishingResult publish(@NotNull
                                                 @NotNull ResultKey resultKey,
                                                 @NotNull
                                                 @NotNull ArtifactDefinitionContext artifact,
                                                 @NotNull
                                                 @NotNull ArtifactPublishingConfig artifactPublishingConfig,
                                                 @Nullable
                                                 @Nullable BuildLogger buildLogger)
                                          throws Exception

Throws:

Exception

retrieve

@NotNull
@NotNull ArtifactRetrievalStatus retrieve(@NotNull
                                          @NotNull ResultKey clientKey,
                                          @NotNull
                                          @NotNull Artifact artifact,
                                          @NotNull
                                          @NotNull ArtifactSubscriptionContext artifactSubscription,
                                          @NotNull
                                          @NotNull ArtifactRetrievalConfig artifactRetrievalConfig)
                                   throws Exception

Retrieve arbitrary Artifact. Artifact is found by the information in artifact parameter.

Parameters:

clientKey - identifier of plan or deployment doing the download

artifact - artifact information

artifactSubscription - download details (e.g. target path, copy pattern)

artifactRetrievalConfig - handler specific configuration

Throws:

Exception

getSupportedAgents

@NotNull
@NotNull Set<AgentType> getSupportedAgents()

getModuleDescriptor

@NotNull
@NotNull ArtifactHandlerModuleDescriptor getModuleDescriptor()

canHandleArtifact

boolean canHandleArtifact(ArtifactDefinitionContext artifact,
                          Map<String,String> artifactHandlersConfiguration)

getDefaultConfiguration

@NotNull
@NotNull Map<String,String> getDefaultConfiguration()

getSpeed

int getSpeed(@NotNull
             @NotNull Map<String,String> artifactHandlersConfiguration)

Return approximate transfer speed of this artifact handler in bytes per second for the specified configuration. Result of this method might be taken into account when deciding which artifact handler to use if multiple handlers are enabled.

Parameters:

artifactHandlersConfiguration - artifact handler configuration

Returns:

approximate transfer speed in Bps, for example: LOCAL_SPEED, LAN_SPEED, WAN_SPEED

removeArtifactFromStorage

void removeArtifactFromStorage(@NotNull
                               @NotNull Artifact artifact,
                               @NotNull
                               @NotNull ArtifactHandlerConfigProvider artifactHandlerConfigProvider)

Removes artifact files for a single artifact.

removeArtifactFromStorage

void removeArtifactFromStorage(@NotNull
                               @NotNull PlanResultKey planResultKey,
                               @NotNull
                               @NotNull ImmutableArtifactDefinitionBase artifact,
                               @NotNull
                               @NotNull ArtifactHandlerConfigProvider artifactHandlerConfigProvider)

Removes artifact files for a single artifact. Called when removing ArtifactLink Should not remove artifacts that were moved to global storage.

removeArtifactFromStorage

void removeArtifactFromStorage(@NotNull
                               @NotNull ResultKey resultKey,
                               @NotNull
                               @NotNull ImmutableArtifactDefinitionBase artifact,
                               @NotNull
                               @NotNull ArtifactHandlerConfigProvider artifactHandlerConfigProvider)

Removes artifact files for a single artifact. Called when removing ArtifactLink Should not remove artifacts that were moved to global storage.

removeArtifactsFromStorage

void removeArtifactsFromStorage(@NotNull
                                @NotNull PlanResultKey planResultKey,
                                @NotNull
                                @NotNull ArtifactHandlerConfigProvider artifactHandlerConfigProvider)

Removes artifact files for a single plan result. Called when removing ResultsSummary Should not remove artifacts that were moved to global storage.

removeArtifactsFromStorage

void removeArtifactsFromStorage(@NotNull
                                @NotNull PlanKey planKey,
                                @NotNull
                                @NotNull ArtifactHandlerConfigProvider artifactHandlerConfigProvider)

Removes artifact files for all results of a single chain or job. Called when removing Plan Calling it for chain removes only the shared artifacts. Should not remove artifacts that were moved to global storage.

removeAllArtifactsOfChain

default void removeAllArtifactsOfChain(@NotNull
                                       @NotNull PlanKey planKey,
                                       @NotNull
                                       @NotNull ArtifactHandlerConfigProvider artifactHandlerConfigProvider)

Removes artifact files for all results of a single chain. Called when removing Chain Should not remove artifacts that were moved to global storage.

Since:

9.2

moveArtifactToGlobalStorage

boolean moveArtifactToGlobalStorage(@NotNull
                                    @NotNull Artifact artifact,
                                    @NotNull
                                    @NotNull ArtifactHandlerConfigProvider artifactHandlerConfigProvider)
                             throws IOException

Move artifact to a 'global storage'. Artifacts in 'global storage' should only be removed when removeArtifactFromStorage(Artifact, ArtifactHandlerConfigProvider) is called. It is not a requirement to physically move the files as long as the above contract is fulfilled.

Parameters:

artifact -

Returns:

true if move successful

Throws:

IOException

Since:

5.0

getArtifactLinkDataProvider

@Nullable
@Nullable ArtifactLinkDataProvider getArtifactLinkDataProvider(ArtifactLink artifactLink,
                                                               @NotNull
                                                               @NotNull ArtifactHandlerConfigProvider artifactHandlerConfigProvider)

getArtifactLinkDataProvider

@Nullable
@Nullable ArtifactLinkDataProvider getArtifactLinkDataProvider(Artifact artifact,
                                                               @NotNull
                                                               @NotNull ArtifactHandlerConfigProvider artifactHandlerConfigProvider)

getMaxUnarchivedFilesPerArtifact

long getMaxUnarchivedFilesPerArtifact(@NotNull
                                      @NotNull Map<String,String> artifactHandlersConfiguration)

Returns the maximum number of files that can exist per artifact which will not be compressed and combined into a single archive. If the threshold is exceeded, artifacts will be packaged into a single file before publishing.

ArtifactHandler does not need to treat archived artifacts differently - from ArtifactHandler perspective the packaging is transparent. Artifact files will be compressed before invoking #publish method and decompressed after invoking #retrieve method.

This method should return NEVER_ARCHIVE if packaging of artifacts is disabled, to always send files unarchived.

Parameters:

artifactHandlersConfiguration - artifact handler configuration

Returns:

maximum number of files per artifact that should not be packaged into a single file