jetbrains.buildServer.serverSide
Interface BuildHistory


public interface BuildHistory

Provides ability to operate with TeamCity finished builds.


Method Summary
 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.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.
 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.
 

Method Detail

getEntries

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

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

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

java.util.Collection<SFinishedBuild> findEntries(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.

findEntry

@Nullable
SFinishedBuild findEntry(long buildId)
Finds entry with the specified id.

Parameters:
buildId - specified build id.
Returns:
entry with the specified id, null if it does not exist or invisible for the current user.

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)
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