Package com.atlassian.bamboo.v2.build.requirement

Interface RequirementService

All Known Implementing Classes:

RequirementServiceImpl

@ExperimentalApi
public interface RequirementService

Service to provide actions on Job Requirements

Since:

v5.6

Method Summary

Modifier and Type	Method	Description
@NotNull ImmutableRequirement	addRequirement(@NotNull PlanKey jobKey, @NotNull String key, ImmutableRequirement.MatchType matchType, @Nullable String matchValue)	Add new requirement to a job.
@NotNull ExecutableAgentsMatrix	getExecutableAgentMatrixForJob(@NotNull PlanKey jobKey)	retrieve all executable agents for a particular job.
@NotNull ImmutableRequirement	getRequirementForJob(@NotNull PlanKey jobKey, long requirementId)	Get a single requirement for a job.
@NotNull ImmutableRequirement	getRequirementForJobWithConsistencyGuarantee(@NotNull PlanKey jobKey, long requirementId)	Get a single requirement for a job.
@NotNull List<? extends ImmutableRequirement>	getRequirementsForJob(@NotNull PlanKey jobKey)	Get all requirements for jobs.
void	removeRequirement(@NotNull PlanKey jobKey, long requirementId)	Remove a specific requirement
@NotNull ImmutableRequirement	updateRequirement(@NotNull PlanKey jobKey, long requirementId, @NotNull String key, ImmutableRequirement.MatchType matchType, @Nullable String matchValue)	Update an existing requirement.
@NotNull ErrorCollection	validateRequirementForAdd(@NotNull PlanKey jobKey, @Nullable String key, ImmutableRequirement.MatchType matchType, @Nullable String matchValue)	Validate requirement details.
@NotNull ErrorCollection	validateRequirementForUpdate(@NotNull PlanKey jobKey, long requirementId, @Nullable String key, ImmutableRequirement.MatchType matchType, @Nullable String matchValue)	Validate requirement details

Method Detail

getRequirementsForJob

@NotNull
@NotNull List<? extends ImmutableRequirement> getRequirementsForJob(@NotNull
                                                                    @NotNull PlanKey jobKey)
                                                             throws WebValidationException

Get all requirements for jobs. If a branch job, will get master requirements.

Parameters:

jobKey - of job

Returns:

RequirementSet for job

Throws:

WebValidationException - if job key invalid

getRequirementForJob

@NotNull
@NotNull ImmutableRequirement getRequirementForJob(@NotNull
                                                   @NotNull PlanKey jobKey,
                                                   long requirementId)

Get a single requirement for a job. If a branch job, will retrieve requirement from master. In clustered mode, there is NO consistency guarantee.

Parameters:

jobKey - of job

requirementId - of requirement

Returns:

requirement

Throws:

NotFoundException - if job key is invalid or requirement doesn't exist

getRequirementForJobWithConsistencyGuarantee

@NotNull
@NotNull ImmutableRequirement getRequirementForJobWithConsistencyGuarantee(@NotNull
                                                                           @NotNull PlanKey jobKey,
                                                                           long requirementId)

Get a single requirement for a job. If a branch job, will retrieve requirement from master. There is a guarantee that the data will be up-to-date.

Parameters:

jobKey - of job

requirementId - of requirement

Returns:

requirement

Throws:

NotFoundException - if job key is invalid or requirement doesn't exist

validateRequirementForAdd

@NotNull
@NotNull ErrorCollection validateRequirementForAdd(@NotNull
                                                   @NotNull PlanKey jobKey,
                                                   @Nullable
                                                   @Nullable String key,
                                                   @Nullable
                                                   ImmutableRequirement.MatchType matchType,
                                                   @Nullable
                                                   @Nullable String matchValue)

Validate requirement details. Assumes details will be used to add a new requirement

Parameters:

jobKey - of job requirement will be added to

key - of requirement to match with the capability

matchType - e.g. exists, regex match, equals

matchValue - for regex and equals the value the requirement should match

Returns:

error collection containing any validation errors

addRequirement

@NotNull
@NotNull ImmutableRequirement addRequirement(@NotNull
                                             @NotNull PlanKey jobKey,
                                             @NotNull
                                             @NotNull String key,
                                             @NotNull
                                             ImmutableRequirement.MatchType matchType,
                                             @Nullable
                                             @Nullable String matchValue)
                                      throws WebValidationException

Add new requirement to a job. Can only add requirements to the master job.

Parameters:

jobKey - of job to add to, must not be a branch

key - of requirement to match with the capability

matchType - e.g. exists, regex match, equals

matchValue - for regex and equals the value the requirement should match

Returns:

Created requirement

Throws:

WebValidationException - for any data related error.

validateRequirementForUpdate

@NotNull
@NotNull ErrorCollection validateRequirementForUpdate(@NotNull
                                                      @NotNull PlanKey jobKey,
                                                      long requirementId,
                                                      @Nullable
                                                      @Nullable String key,
                                                      @Nullable
                                                      ImmutableRequirement.MatchType matchType,
                                                      @Nullable
                                                      @Nullable String matchValue)

Validate requirement details

Parameters:

jobKey - of job requirement belongs to

requirementId - if of the requirement being updated

key - of requirement to match with the capability

matchType - e.g. exists, regex match, equals

matchValue - for regex and equals the value the requirement should match

Returns:

error collection containing any validation errors

updateRequirement

@NotNull
@NotNull ImmutableRequirement updateRequirement(@NotNull
                                                @NotNull PlanKey jobKey,
                                                long requirementId,
                                                @NotNull
                                                @NotNull String key,
                                                @NotNull
                                                ImmutableRequirement.MatchType matchType,
                                                @Nullable
                                                @Nullable String matchValue)
                                         throws WebValidationException

Update an existing requirement. Can only update requirements of master jobs

Parameters:

jobKey - of job requirement belongs to

requirementId - if of the requirement being updated

key - of requirement to match with the capability

matchType - e.g. exists, regex match, equals

matchValue - for regex and equals the value the requirement should match

Returns:

Created requirement

Throws:

WebValidationException - for any data related error.

removeRequirement

void removeRequirement(@NotNull
                       @NotNull PlanKey jobKey,
                       long requirementId)
                throws WebValidationException

Remove a specific requirement

Parameters:

jobKey - requirement belongs to

requirementId - of requirement to remove

Throws:

WebValidationException - if requirement is not allowed to be removed

getExecutableAgentMatrixForJob

@NotNull
@NotNull ExecutableAgentsMatrix getExecutableAgentMatrixForJob(@NotNull
                                                               @NotNull PlanKey jobKey)
                                                        throws WebValidationException

retrieve all executable agents for a particular job. Includes all disabled and offline.

Parameters:

jobKey -

Returns:

executableAgentMatrix (requirements to matching agents and images)

Throws:

WebValidationException