Bamboo API Changes for 5.0

Points of interest

This entire class has been deprecated.    The functionality has instead been split into two classes.  AdministrationConfigurationAccessor and AdministrationConfigurationPersister. Generally you should only be needing the accessor.

The persister is now only available on the server.

New version of Atlassian Process Utils

Bamboo 5.0 relies on Atlassian Process Utils 1.5.9-bamboo1, which is binary incompatible with the version used up to Bamboo 4.4. Plugins using the library to manage external processes need to be updated.

Page Objects have had package changes

If you were using our page objects for your own integration tests, they have moved.  Should just be a matter or importing them from their new location.

New CachedPlanManager (replacing PlanManager)

Bamboo now has a cache available for plans to avoid unnecessary database hits.  Any calls to PlanManager should be re-assessed and changed to use the CachedPlanManager if possible.

ResultSummary.getPlan() is deprecated.  Instead use getImmutablePlan()

Switching to getImmutablePlan() should be straight forward.  We do not expect plugins to be accessing a plan this way and mutating it.  If you do need to edit, use the PlanManager to retrieve a mutable version of the plan.

Introduction of Key and ResultKey

With the introduction of deployments we needed common identifiers for both deployments and builds.  As such there is now a super-interface to PlanKey (Key) and PlanResultKey (ResultKey).  Many methods have been updated or deprecated to accommodate this change.

Deployments

Deployments is a brand new feature in Bamboo 5.0 with a lot of new concepts.  See: Introduction to 5.0 - Deployments  Tasks have remained a core feature of Deployments, as such there have been many methods/interfaces which have been updated/created to accommodate share functionality between deployments and jobs.

Rest Pagination

Previously when accessing specific pages of REST the max-results=X argument was used.  This parameter has been deprecated.  Instead please use max-result=X (notice the missing 's').

New Plugin Points

TaskType extension: RuntimeTaskDataProvider

This is still an experimental API, but in 5.0 we have provided an easy way to grab server-side data needed for the execution of a Job or Deployment just before it goes to the agent.

RuntimeTaskDataProvider

Removal of Deprecated Methods

com.atlassian.bamboo.variable.VariableDefinitionManager

1
2
/**
 * Delete variable definition
 * @param id  id of {@link VariableDefinition} object
 * @deprecated since 4.0 use {@link #deleteVariableDefinition(VariableDefinition)}
 */
@Deprecated
void deleteVariableDefinition(long id);


/**
 * Create variable context for manual variables based on simple key/value map
 * This context contains *ONLY* manually overridden variables (used for passing manual changes set on chain level to job level contexts)
 *
 * @param variables
 * @return
 * 
 * @deprecated since 4.0 use {@link #createVariableContextBuilder} instead
 */
@Deprecated
@NotNull
VariableContext getVariableContext(@Nullable Map<String, String> variables);

/**
 * Prepare effective variables map - variables are set and optionally overridden (if set in later stage) in following order
 *   global
 *   manual
 *
 * @param manualVariables
 * @return
 *
 * @deprecated since 4.0 use {@link #createVariableContextBuilder} instead
 */
@Deprecated
@NotNull
Map<String, VariableDefinitionContext> getGlobalVariableDefinitionMap(@Nullable Map<String, String> manualVariables);

/**
 * Prepare effective variables map - variables are set and optionally overridden (if set in later stage) in following order
 *   global
 *   plan
 *   job (if will be supported)
 *   manual
 *
 * @param plan
 * @param manualVariables
 * @return
 *
 * @deprecated since 4.0 use {@link #createVariableContextBuilder} instead
 */
@Deprecated
@NotNull
Map<String, VariableDefinitionContext> getVariableDefinitionMap(@NotNull Plan plan, @Nullable Map<String, String> manualVariables);

com.atlassian.bamboo.variable.VariableValidationService

1
2
/**
 * Validate String against Bamboo general rules for global variable value
 *
 * @param validationAware the object to add errors to if any are found
 * @param fieldName the name of the field to add the errors to
 * @param variableValue the actual value to validate
 * @deprecated since 3.3 Use {@link #validateValueForVariable}
 */
@Deprecated
void validateValueForGlobalVariable(@NotNull ValidationAware validationAware, @NotNull String fieldName, @Nullable String variableValue);

/**
 * Validate String against Bamboo general rules for plan variable value
 *
 * @param validationAware the object to add errors to if any are found
 * @param fieldName the name of the field to add the errors to
 * @param variableValue the actual value to validate
 * @deprecated since 3.3 Use {@link #validateValueForVariable}
 */
@Deprecated
void validateValueForPlanVariable(@NotNull ValidationAware validationAware, @NotNull String fieldName, @Nullable String variableValue);

com.atlassian.bamboo.webrepository.WebRepositoryViewer

1
2
/**
 * Renders the html to display a summary of the commits on the Build Results Summary tab.
 *
 * @param resultsSummary         the summary to show commits for
 * @param repositoryData   the commits belong to aka the plans repository
 * @return Html to displayed on the UI in the Build Results Summary Tab.
 * @deprecated since 3.4 use {@link WebRepositoryViewer#getHtmlForCommitsSummary(ResultsSummary, RepositoryChangeset, RepositoryData, int)}
 */
@Deprecated
String getHtmlForCommitsSummary(@NotNull ResultsSummary resultsSummary, @NotNull final RepositoryChangeset repositoryChangeset, @NotNull final RepositoryDefinition repositoryDefinition);
/**
 * Renders the html to display the full commits on the changes tab.
 *
 * @param resultsSummary        the summary to show commits for
 * @param repositoryData         the commits belong to aka the plans repository
 * @return Html to be displayed on the UI in the Changes Tab.
 * @deprecated since 4.0 use {@link #getHtmlForCommitsFull(ResultsSummary, RepositoryChangeset, RepositoryData)}
 */
@Deprecated
String getHtmlForCommitsFull(@NotNull ResultsSummary resultsSummary, @NotNull final RepositoryChangeset repositoryChangeset, @NotNull final RepositoryDefinition repositoryData);
/**
 * Renders the html to display a summary of the commits on the Build Results Summary tab.
 * @param resultsSummary         the summary to show commits for
 * @param repositoryData   the commits belong to aka the plans repository
 * @param maxChanges             maximum number of commits to be shown. Negative value means that all commits should be shown.
 * @return Html to displayed on the UI in the Build Results Summary Tab.
 * @deprecated since 4.0 use {@link #getHtmlForCommitsSummary(ResultsSummary, RepositoryChangeset, RepositoryData, int)}
 */
@Deprecated
String getHtmlForCommitsSummary(@NotNull ResultsSummary resultsSummary, @NotNull final RepositoryChangeset repositoryChangeset, @NotNull final RepositoryDefinition repositoryData, final int maxChanges);

com.atlassian.bamboo.task.BuildTaskRequirementSupport

1
2
/**
 * Populates the {@link RequirementSet} needed based off of the {@link TaskDefinition}
 *
 * @param taskDefinition
 * @param buildable
 * @return requirements
 *
 * @deprecated since 4.0 use {@link #calculateRequirements(TaskDefinition, Job)}
 */
@Deprecated
@NotNull
Set<Requirement> calculateRequirements(@NotNull TaskDefinition taskDefinition, @NotNull Buildable buildable); 

Newly Deprecated Classes

BuildExecutionUpdateManager & BuildExecutionManager

BuildExecutionUpdateManager has been deprecated.  For logging methods please use the BuildLoggerManager and for timing calls see the ExecutionPhaseService. 

BuildExecutionManager also implements BuildExecutionUpdateManager so many methods that were available via this interface are also deprecated.

Newly deprecated Methods

Methods of high usage

TaskResultBuilder

1
2
/**
 * Creates a new TaskResultBuilder for a {@link CommonTaskContext}
 *
 * @param taskContext of the executing {@link TaskType}
 * @return evaluator
 * @deprecated since 5.0 use {@link #newBuilder(CommonTaskContext)}
 */
@Deprecated
public static TaskResultBuilder create(@NotNull TaskContext taskContext)
{
    return new TaskResultBuilder(taskContext);
}

PlanManager

1
2
/**
    * Returns all {@link TopLevelPlan}'s
    *
    * @deprecated since 5.0 please use ${@link com.atlassian.bamboo.plan.cache.CachedPlanManager}
    * @return plans
    */
   @NotNull
   @Deprecated
   List<TopLevelPlan> getAllPlans();

ProcessService

1
2
  /**
    * Create a new {@link ExternalProcess} that logs to the {@link BuildLogger} for the given {@link PlanResultKey}
    *
    * Processes created with this method will be decorated by any applicable {@link TaskProcessCommandDecorator}
    *
    * @param taskContext
    * @param processBuilder
    * @return externalProcess
    * @deprecated since 5.0 use {@link #createExternalProcess(CommonTaskContext, ExternalProcessBuilder)}
    */
   @NotNull
   @Deprecated
   ExternalProcess createProcess(@NotNull TaskContext taskContext, @NotNull ExternalProcessBuilder processBuilder);

/**
    * Create and execute {@link ExternalProcess} that logs to the {@link BuildLogger} for the given {@link PlanResultKey}
    *
    * Processes created with this method will be decorated by any applicable {@link TaskProcessCommandDecorator}
    *
    * @param taskContext
    * @param processBuilder
    * @return externalProcess
    * @deprecated since 5.0 use {@link #executeExternalProcess(CommonTaskContext, ExternalProcessBuilder)}
    */
   @NotNull
   @Deprecated
   ExternalProcess executeProcess(@NotNull TaskContext taskContext, @NotNull ExternalProcessBuilder processBuilder);

ResultsSummary and family

1
2
/**
     * Gets the {@link com.atlassian.bamboo.plan.Plan} that this result belongs directly belongs to
     *
     * @return the owning plan for the result
     *
     * @throws {@link IllegalStateException} if the plan doesn't exist.
     * @deprecated since 5.0 use {@link #getImmutablePlan()}
     */
    @NotNull
    @Deprecated
    Plan getPlan();  

/* @deprecated since 5.0 use CommentService.getCommentsForEntity(getId())
     *
     * @return
     */
    @NotNull
    @Deprecated
    List<Comment> getComments();

BuildLoggerManager

1
2
/**
  * Returns a {@link com.atlassian.bamboo.build.logger.BuildLogger} for the given plan
  *
  * @param key
  * @deprecated since 5.0 use ${@link #getLogger(com.atlassian.bamboo.Key)} instead
  */
 @NotNull
 @Deprecated
 BuildLogger getBuildLogger(@NotNull PlanKey key);
 /**
  * Returns a {@link com.atlassian.bamboo.build.logger.BuildLogger} for the given result
  * @deprecated since 5.0 use ${@link #getLogger(com.atlassian.bamboo.ResultKey)} instead
  * @param resultKey
  * @return
  */
 @NotNull
 @Deprecated
 BuildLogger getBuildLogger(@NotNull PlanResultKey resultKey);

ErrorUpdateHandler

1
2
        /**
     * Record a build error against a build
     *
     * @param buildKey    key of the build
     * @param buildNumber number of the build - can be null
     * @param context     message
     * @param throwable   error
     * @deprecated since 5.0. Use {@link #recordError(ResultKey, String, Throwable)}
     */
    @Deprecated
    void recordError(String buildKey, int buildNumber, String context, @Nullable Throwable throwable);
    /**
     * Record a build error against a build
     *
     * @param buildKey
     * @param context
     * @param throwable
     * @deprecated since 5.0.  Use {@link #recordError(Key, String, Throwable}
     */
    @Deprecated
    void recordError(String buildKey, String context, Throwable throwable);
  /**
     * Record a build error against a build
     *
     * @param buildKey
     * @param context
     * @deprecated since 5.0.  Use {@link #recordError(Key, String)}
     */
    @Deprecated
    void recordError(String buildKey, String context);
/**
     * @deprecated since 5.0 use {@link #recordError(ResultKey, String, Throwable)} instead.
     */
    @Deprecated
    void recordError(@Nullable BuildContext buildContext, @NotNull String context, @Nullable Throwable throwable);
    /**
     * Adds all the error messages in the errorCollection to the build
     *
     * @param buildKey
     * @param errors
     * @deprecated since 5.0 use {@link #addErrorCollection(ResultKey, ErrorCollection)}
     */
    @Deprecated
    void addErrorCollection(String buildKey, ErrorCollection errors);

Methods of medium usage

CustomVariableContext

1
2
  /* @deprecated since 5.0 use {@link #getVariables(CommonContext)}
   */
  @NotNull
  @Deprecated
  Map<String, String> getVariables(@Nullable final BuildContext buildContext);

* @deprecated since 5.0 use {@link #substituteString(String, CommonContext, BuildLogger)}
   */
  @Nullable
  @Deprecated
  String substituteString(@Nullable String value, @Nullable BuildContext buildContext, @Nullable BuildLogger buildLogger);

ArtifactLinkManager

1
2
/* @deprecated since 5.0 use ${@link #getArtifactLinks(com.atlassian.bamboo.resultsummary.ResultsSummary, String)}
  */
 @NotNull
 Collection<ArtifactLink> getArtifactLinksForLinkType(@NotNull ResultsSummary resultsSummary, @NotNull String linkType);

  /* @deprecated since 5.0, use {@link #removeArtifactLinks(com.atlassian.bamboo.chains.ChainResultsSummary)}
  */
 @Deprecated
 void removeArtifactLinks(@NotNull ChainResultsSummary chainResultsSummary, @Nullable Plan plan);

CommentManager and CommentService

1
2
/**
     * @deprecated since 5.0 use addComment(content, user, resultsSummary.getId)
     */
    Comment addComment(String content, ResultsSummary resultsSummary, User user);
    /**
     * @deprecated since 5.0 use deleteComment(comment)
     */
    void deleteComment(Comment comment, ResultsSummary resultsSummary);

AgentManager - methods moved to ExecutableAgentsHelper

1
2
Collection<BuildAgent> getExecutableAgents(RequirementSet requirementSet, boolean includeDisabled);
Collection<BuildAgent> getExecutableAgents(RequirementSet requirements, DisabledAgentsInclusion includeDisabled, OfflineAgentsInclusion includeOffline);
ExecutableAgentsMatrix getExecutableAgentsMatrix(@NotNull RequirementSet requirementSet, boolean includeDisabled);
ExecutableAgentsMatrix getExecutableAgentsMatrix(@NotNull RequirementSet requirementSet, DisabledAgentsInclusion includeDisabled, OfflineAgentsInclusion includeOffline);
Collection<ElasticImageConfiguration> getExecutableImages(@NotNull RequirementSet requirementSet);
Collection<ElasticImageConfiguration> getExecutableImages(@NotNull RequirementSet requirementSet, boolean includeDisabled);

BuildExecutionManager

1
2
/**
    * @deprecated since 5.0 use ${@link #getCurrentlyBuilding(com.atlassian.bamboo.Key)}
    * @param planKey
    * @return
    */
   @NotNull
   @Deprecated
   List<CurrentlyBuilding> getCurrentlyBuilding(@NotNull String planKey);

/**
    * @deprecated since 5.0 use ${@link #removeCurrentlyBuilding(com.atlassian.bamboo.ResultKey)}
    */
   @Deprecated
   @Nullable
   CurrentlyBuilding removeCurrentlyBuilding(@NotNull String planKey);

BuildContextEvent, BuildQueuedEvent, BuildTriggeredEvent, PostBuildCompletedEvent

1
2
/**
    * @deprecated since 5.0 use {@link #getContext()}
    */
   @NotNull
   public BuildContext getBuildContext()

BambooUrl

1
2
/**
   * @param administrationConfiguration
   * @deprecated since 5.0 use {@link #BambooUrl(AdministrationConfigurationAccessor)}
   */
  @Deprecated
  public BambooUrl(final AdministrationConfiguration administrationConfiguration)

BuildContextHelper

1
2
/**
    * @deprecated Since 5.0 use {@link #getBuildWorkingDirectory(CommonContext)} instead
    */
   @Deprecated
   public static File getBuildWorkingDirectory(final BuildContext buildContext)

Methods of low usage

• We have not listed them here as there are too many.  Please see the java docs to find information on what to use as a replacement to each deprecated method call.