jetbrains.buildServer.serverSide

Interface BuildHistory

public interface BuildHistory

Provides ability to operate with TeamCity finished builds.

Method Summary

Modifier and Type	Method and Description
java.util.Collection<SFinishedBuild>	findEntries(java.util.Collection<java.lang.Long> buildIds) Returns collection of finished builds corresponding to the specified build ids.
java.util.Collection<SFinishedBuild>	findEntries(java.util.Collection<java.lang.Long> buildIds, boolean addToCache) Same as findEntries(Collection) but with additional parameter which controls whether the found builds should be cached or not.
java.util.List<SFinishedBuild>	findEntries(java.lang.String buildTypeId, java.lang.String buildNumber) Returns list of finished builds with specified build number belonging to specified build configuration ordered by changes (the most recent first).
SFinishedBuild	findEntry(long buildId) Finds entry with the specified id and cache the data internally.
SFinishedBuild	findEntry(long buildId, boolean addToCache) Finds entry with the specified id and optionally cache it.
SFinishedBuild	findEntry(java.lang.String buildTypeId, java.lang.String buildNumber) Finds the most recent by changes entry inside specified configuration with specified build number.
java.util.List<SFinishedBuild>	getEntries(boolean includeCanceled) Return whole build history for all build configurations of all projects.
java.util.List<SFinishedBuild>	getEntriesBefore(SBuild beforeThisBuild, boolean successfulOnly) Returns builds of the specified configuration started before the specified build (excluding the specified build).
java.util.List<SFinishedBuild>	getEntriesSince(SBuild sinceBuildInclusive, BuildType buildType) Returns builds of the specified configuration started after the specified build (including the specified build), ordered by changes.
java.util.List<SFinishedBuild>	getHistoryByAgent(SBuildAgent agent, User user, boolean includeCanceled) Returns the build history filtered by the agent.
java.util.Date	getLastFinishedBuildDateOnAgent(SBuildAgent agent, java.util.Date finishTimeAfter) Return last finished build that was started on the agent.
void	processEntries(ItemProcessor<SFinishedBuild> itemProcessor) Invokes the given ItemProcessor for all history records existing in the system.
void	processEntries(java.lang.String buildTypeId, User user, boolean includePersonalBuildsIfUserNotSpecified, boolean includeCanceled, boolean orderByChanges, ItemProcessor<SFinishedBuild> processor) Process build history for the specified build configuration.
boolean	removeEntry(long buildId) Removes finished build from the history.
void	removeEntry(SFinishedBuild finishedBuild) Removes finished build from build history.
void	removeEntry(SFinishedBuild finishedBuild, java.lang.String comment) Removes finished build from build history.
void	removeEntry(SFinishedBuild finishedBuild, java.lang.String comment, CleanupLevel cleanupLevel) Removes finished build from build history.

Method Detail

getEntries

@NotNull
java.util.List<SFinishedBuild> getEntries(boolean includeCanceled)

Return whole build history for all build configurations of all projects. Personal builds are not included. Build ordering is by start time.

Parameters:

includeCanceled - true if cancelled builds should be included into result

Returns:

list of builds, most recent first

processEntries

void processEntries(java.lang.String buildTypeId,
                    @Nullable
                    User user,
                    boolean includePersonalBuildsIfUserNotSpecified,
                    boolean includeCanceled,
                    boolean orderByChanges,
                    @NotNull
                    ItemProcessor<SFinishedBuild> processor)

Process build history for the specified build configuration. Personal builds are included if user is specified. Builds are processed using given processor.

Parameters:

buildTypeId - internal id of build configuration

user - if not null, personal builds of this user will be included into result

includePersonalBuildsIfUserNotSpecified - if true and user==null, all personal builds will be included into results

includeCanceled - true if cancelled builds should be included into result

orderByChanges - if true, builds are ordered by changes, i.e. most recent build with recent changes goes first; if false, most recent builds go first, regardless change order

processor - processor for builds

getEntriesSince

@NotNull
java.util.List<SFinishedBuild> getEntriesSince(@Nullable
                                                        SBuild sinceBuildInclusive,
                                                        @NotNull
                                                        BuildType buildType)

Returns builds of the specified configuration started after the specified build (including the specified build), ordered by changes. History builds which contain changes older than in sinceBuildInclusive are not included.

Parameters:

sinceBuildInclusive - boundary for returning builds (inclusive), may be null - in this case all builds are returned

buildType - specified configuration.

Returns:

see above

getEntriesBefore

@NotNull
java.util.List<SFinishedBuild> getEntriesBefore(@NotNull
                                                         SBuild beforeThisBuild,
                                                         boolean successfulOnly)

Returns builds of the specified configuration started before the specified build (excluding the specified build). Personal builds are included, canceled builds are excluded. Returned builds are sorted by containing changes and than by build start time (if contain same changes). Recent builds go first.

Parameters:

beforeThisBuild - returns build before this one

successfulOnly - if only successful builds should be included.

Returns:

see above

findEntries

@NotNull
java.util.Collection<SFinishedBuild> findEntries(@NotNull
                                                          java.util.Collection<java.lang.Long> buildIds)

Returns collection of finished builds corresponding to the specified build ids. The collection will contain existing builds only. NOTE: RETURNED COLLECTION WILL NOT MAINTAIN REQUESTED ORDER!

Parameters:

buildIds - id list to find builds with these ids.

Returns:

collection of finished builds corresponding to the specified build ids.

findEntries

@NotNull
java.util.Collection<SFinishedBuild> findEntries(@NotNull
                                                          java.util.Collection<java.lang.Long> buildIds,
                                                          boolean addToCache)

Same as findEntries(Collection) but with additional parameter which controls whether the found builds should be cached or not.

Parameters:

buildIds - id list to find builds with these ids.

addToCache - whether to put found builds in cache or not

Returns:

collection of finished builds corresponding to the specified build ids.

Since:

2017.2

findEntry

@Nullable
SFinishedBuild findEntry(long buildId)

Finds entry with the specified id and cache the data internally. Same as findEntry(buildId, true).

Parameters:

buildId - specified build id.

Returns:

entry with the specified id, null if it does not exist or invisible for the current user.

Throws:

AccessDeniedException - if the current authority holder doesn't have an access to the build with the given id.

findEntry

@Nullable
SFinishedBuild findEntry(long buildId,
                                   boolean addToCache)

Finds entry with the specified id and optionally cache it.

Parameters:

buildId - specified build id.

addToCache - if true, the build will be added to internal caches

Returns:

entry with the specified id, null if it does not exist or invisible for the current user.

Throws:

AccessDeniedException - if the current authority holder doesn't have an access to the build with the given id.

Since:

9.0

findEntry

@Nullable
SFinishedBuild findEntry(@NotNull
                                   java.lang.String buildTypeId,
                                   @NotNull
                                   java.lang.String buildNumber)

Finds the most recent by changes entry inside specified configuration with specified build number.

Parameters:

buildTypeId - specified build configuration id.

buildNumber - specified build number.

Returns:

entry with the specified number in the specified configuration, null if it does not exist or invisible for the current user.

findEntries

@NotNull
java.util.List<SFinishedBuild> findEntries(@NotNull
                                                    java.lang.String buildTypeId,
                                                    @NotNull
                                                    java.lang.String buildNumber)

Returns list of finished builds with specified build number belonging to specified build configuration ordered by changes (the most recent first).

Parameters:

buildTypeId - build configuration id

buildNumber - build number

Returns:

collection of found builds

Since:

5.1.5

removeEntry

void removeEntry(@NotNull
                 SFinishedBuild finishedBuild,
                 @Nullable
                 java.lang.String comment,
                 @NotNull
                 CleanupLevel cleanupLevel)

Removes finished build from build history. If action is performed by authenticated user, provided comment will be written in audit. CleanupLevel could be used to specify action strictness. See CleanupLevel for more details.

Since:

9.0

removeEntry

void removeEntry(@NotNull
                 SFinishedBuild finishedBuild,
                 @Nullable
                 java.lang.String comment)

Removes finished build from build history. If action is performed by authenticated user, provided comment will be written in audit.

Since:

8.0

removeEntry

void removeEntry(@NotNull
                 SFinishedBuild finishedBuild)

Removes finished build from build history.

removeEntry

boolean removeEntry(long buildId)

Removes finished build from the history.

The removing build must be an instance of SFinishedBuild.

Parameters:

buildId - build identifier of the finished build.

Returns:

true if the build was successfully removed

processEntries

void processEntries(@NotNull
                    ItemProcessor<SFinishedBuild> itemProcessor)

Invokes the given ItemProcessor for all history records existing in the system. Entries are pushed into the processor in the most-recent-first order.

Parameters:

itemProcessor - processor for history entries

getHistoryByAgent

@NotNull
java.util.List<SFinishedBuild> getHistoryByAgent(@NotNull
                                                          SBuildAgent agent,
                                                          @Nullable
                                                          User user,
                                                          boolean includeCanceled)

Returns the build history filtered by the agent.

Parameters:

agent - the build agent

user - if set the result will contain only builds by user

includeCanceled - if set the result will include canceled builds as well

Returns:

build history

Since:

5.0

getLastFinishedBuildDateOnAgent

@Nullable
java.util.Date getLastFinishedBuildDateOnAgent(@NotNull
                                                         SBuildAgent agent,
                                                         @NotNull
                                                         java.util.Date finishTimeAfter)

Return last finished build that was started on the agent.

Parameters:

agent - agent

finishTimeAfter - finish time lower bound

Returns:

found build or null