com.buildforge.services.client.dbo
Class Build

java.lang.Object
  extended by com.buildforge.services.client.dbo.Build

public final class Build
extends java.lang.Object

An object representing a build within the Build Forge system. A build (also called a job) usually refers to a running instance of a project, a completed instance of a project, purge activity, or project clobber activity. The type of job can be identified using its getProcess() method.

These objects are not created explicitly by a user. Instead, they are generated automatically by the Build Forge system when a new job is requested using methods like fire(APIClientConnection, int), fire(APIClientConnection, int, String, String, boolean), purge(), and Project.clobber().


Field Summary
static java.lang.Class<Build> CLASS
           
 
Method Summary
 void cancel()
          Requests cancellation of a running job.
static java.util.List<Build> findAll(APIClientConnection conn)
          Finds all jobs defined within the system to which the user has access.
static java.util.List<Build> findArchived(APIClientConnection conn)
          Finds all archived jobs.
static java.util.List<Build> findBetween(APIClientConnection conn, java.util.Date beginDate, java.util.Date endDate)
          Finds all jobs with a start time that is between the specified begin and end dates, and to which the user has access.
static Build findById(APIClientConnection conn, int buildId)
          Finds the job with the specified ID.
static Build findById(APIClientConnection conn, int buildId, boolean withEnvironment)
          Finds the job with the specified ID.
static java.util.List<Build> findByProjectId(APIClientConnection conn, int projectId)
          Finds all jobs for the project with the specified ID to which the user has access.
static java.util.List<Build> findByState(APIClientConnection conn, BuildDBO.State state)
          Finds all jobs with the specified state that are defined within the system and to which the user has access.
static java.util.List<Build> findCompleted(APIClientConnection conn)
          Finds all completed jobs.
static java.util.List<Build> findLocked(APIClientConnection conn)
          Finds all locked jobs.
static java.util.List<Build> findRunning(APIClientConnection conn)
          Finds all running jobs.
static java.util.List<Build> findWaiting(APIClientConnection conn)
          Finds all waiting jobs.
static Build fire(APIClientConnection conn, int projectId)
          Creates a new job with the specified project's default selector and build class and engaging any linked adapters.
static Build fire(APIClientConnection conn, int projectId, java.lang.String selectorId, java.lang.String buildClassName, boolean runLink)
          Deprecated. Use fire(APIClientConnection, int, String, String, boolean, Environment) instead
static Build fire(APIClientConnection conn, int projectId, java.lang.String selectorId, java.lang.String buildClassName, boolean runLink, java.util.List<EnvironmentEntry> adHocEnvironmentOverrides)
          Fires a build with the specified project, overriding the project's default selector, build class, and adaptor linkage, and environment.
static Build fire(APIClientConnection conn, int projectId, java.lang.String selectorId, java.lang.String buildClassName, boolean runLink, java.util.List<EnvironmentEntry> adHocEnvironmentOverrides, java.lang.String tagOverride, int levelOverride)
          Fires a build with the specified project, overriding the project's default selector, build class, adaptor linkage, environment, build tag, and access group (the user must have access to the overriding access group).
 java.lang.String getBuildClass()
          Returns the descriptive name of the build class for this job.
 int getBuildId()
          Returns the unique identifier for this job.
 boolean getCancellation()
          Returns whether or not this job is marked to be cancelled.
 int getChainedBuildId()
          Returns the identifier of the build chained from this one, if a pass or fail chain was set on this Build.
 int getDuration()
          Returns the length of time that the build has taken thus far, in seconds.
 java.lang.String getEngineId()
          Returns the unique ID of the Build Forge engine that it assigned to this build.
 java.lang.String getEnvText()
          Returns the environment block of this build.
 int getFailChainId()
          Returns the identifier of the Project that will be executed in the event that this Build fails.
 int getFired()
          Returns the time at which this job was created as a timestamp.
 java.lang.String getGeoId()
          Returns the UUID of the geographic location at which this Build is slated to execute via GDD.
 int getJobId()
          Returns the process ID of the job management process on the engine that is running it.
 int getLevel()
          Returns the access group ID assigned to this build.
 int getPassChainId()
          Returns the identifier of the Project that will be executed in the event that this Build succeeds.
 BuildDBO.Process getProcess()
          Returns the type of job that this object represents.
 BuildDBO.Result getResult()
          Returns the result of this job.
 java.util.List<Result> getResults()
          Retrieves the step results for this job.
 java.lang.String getSelectorId()
          Returns the selector ID for this job.
 java.lang.String getStage()
          Returns the current stage of the job.
 int getStartTime()
          Returns the timestamp for when this job was picked up by an engine.
 BuildDBO.State getState()
          Returns the current state of this job.
 java.lang.String getTag()
          Returns the build tag for this job.
 int getTargetId()
          Returns the target of this job.
 int getUserId()
          Returns the user ID of the user that created this job.
 void lock()
          Locks this job.
 Build purge()
          Requests that this job and its associated results be purged from Build Forge.
 java.lang.String toString()
           
 void unlock()
          Unlocks this job.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

CLASS

public static final java.lang.Class<Build> CLASS
Method Detail

findAll

public static java.util.List<Build> findAll(APIClientConnection conn)
                                     throws java.io.IOException,
                                            ServiceException
Finds all jobs defined within the system to which the user has access. A user has access to all jobs for which the user has direct or indirect membership in the job's assigned access group.

Parameters:
conn - the API client connection to use for the request
Returns:
the list of jobs
Throws:
java.io.IOException - if an I/O error occurs
ServiceException - if the request fails

findById

public static Build findById(APIClientConnection conn,
                             int buildId)
                      throws java.io.IOException,
                             ServiceException
Finds the job with the specified ID. This is a convenience method for findById(APIClientConnection, int, boolean) with false specified for the last parameter.

Parameters:
conn - as for findById(APIClientConnection, int, boolean)
buildId - as for findById(APIClientConnection, int, boolean)
Returns:
as for findById(APIClientConnection, int, boolean)
Throws:
java.io.IOException - if an I/O error occurs
ServiceException - if the request fails

findById

public static Build findById(APIClientConnection conn,
                             int buildId,
                             boolean withEnvironment)
                      throws java.io.IOException,
                             ServiceException
Finds the job with the specified ID.

Parameters:
conn - the API client connection to use for the request
buildId - the ID of the job to find
withEnvironment - true to request the environment block of the job, or false for the default behavior, as provided by findById(APIClientConnection, int).
Returns:
the job, or null if the job does not exist or the user does not have direct or indirect membership in its assigned access group.
Throws:
java.io.IOException - if an I/O error occurs
ServiceException - if the request fails

findByProjectId

public static java.util.List<Build> findByProjectId(APIClientConnection conn,
                                                    int projectId)
                                             throws java.io.IOException,
                                                    ServiceException
Finds all jobs for the project with the specified ID to which the user has access. A user has access to all jobs for which the user has direct or indirect membership in the job's assigned access group.

Parameters:
conn - the API client connection to use for the request
projectId - the ID of the project for which to find matching jobs, which must be a project to which the user has access, as described in the entry for Project.findAll(APIClientConnection).
Returns:
the list of jobs
Throws:
java.io.IOException - if an I/O error occurs
ServiceException - if the request fails

findByState

public static java.util.List<Build> findByState(APIClientConnection conn,
                                                BuildDBO.State state)
                                         throws java.io.IOException,
                                                ServiceException
Finds all jobs with the specified state that are defined within the system and to which the user has access.

Parameters:
conn - the API client connection to use for the request
state - the build state of interest
Returns:
the list of jobs
Throws:
java.io.IOException - if an I/O error occurs
ServiceException - if the request fails

findBetween

public static java.util.List<Build> findBetween(APIClientConnection conn,
                                                java.util.Date beginDate,
                                                java.util.Date endDate)
                                         throws java.io.IOException,
                                                ServiceException
Finds all jobs with a start time that is between the specified begin and end dates, and to which the user has access.

Parameters:
conn - the API client connection to use for the request
beginDate - the Date from which to start collection of builds for the returned list
endDate - the Date which is to be the last Date of a build in the returned list
Returns:
the list of jobs
Throws:
java.io.IOException - if an I/O error occurs
ServiceException - if the request fails

findWaiting

public static java.util.List<Build> findWaiting(APIClientConnection conn)
                                         throws java.io.IOException,
                                                ServiceException
Finds all waiting jobs. This is a convenience method for findByState(APIClientConnection, BuildDBO.State) with WAITING specified for the state.

Throws:
java.io.IOException
ServiceException

findRunning

public static java.util.List<Build> findRunning(APIClientConnection conn)
                                         throws java.io.IOException,
                                                ServiceException
Finds all running jobs. This is a convenience method for findByState(APIClientConnection, BuildDBO.State) with RUNNING specified for the state.

Throws:
java.io.IOException
ServiceException

findCompleted

public static java.util.List<Build> findCompleted(APIClientConnection conn)
                                           throws java.io.IOException,
                                                  ServiceException
Finds all completed jobs. This is a convenience method for findByState(APIClientConnection, BuildDBO.State) with COMPLETED specified for the state.

Throws:
java.io.IOException
ServiceException

findLocked

public static java.util.List<Build> findLocked(APIClientConnection conn)
                                        throws java.io.IOException,
                                               ServiceException
Finds all locked jobs. This is a convenience method for findByState(APIClientConnection, BuildDBO.State) with LOCKED specified for the state.

Throws:
java.io.IOException
ServiceException

findArchived

public static java.util.List<Build> findArchived(APIClientConnection conn)
                                          throws java.io.IOException,
                                                 ServiceException
Finds all archived jobs. This is a convenience method for findByState(APIClientConnection, BuildDBO.State) with ARCHIVED specified for the state.

Throws:
java.io.IOException
ServiceException

getResults

public java.util.List<Result> getResults()
                                  throws java.io.IOException,
                                         ServiceException
Retrieves the step results for this job.

Returns:
the step results, or null if this is not an ordinary job
Throws:
java.io.IOException
ServiceException

unlock

public void unlock()
            throws java.io.IOException,
                   ServiceException
Unlocks this job. This request only makes sense for ordinary jobs that have previously been locked.

Throws:
java.io.IOException
ServiceException

lock

public void lock()
          throws java.io.IOException,
                 ServiceException
Locks this job. This request only makes sense for ordinary jobs that have completed.

Throws:
java.io.IOException
ServiceException

purge

public Build purge()
            throws java.io.IOException,
                   ServiceException
Requests that this job and its associated results be purged from Build Forge. This method does not wait for the purging process to complete, but instead returns the job that will do the purge. The caller may poll for the existence of this purge job using findById(APIClientConnection, int) to check on its progress.

When the purge has completed, the original job will either be deleted or moved to the ARCHIVED state, as determined by the purge type of the job's build class.

Returns:
the newly created purge job
Throws:
java.io.IOException
ServiceException

fire

public static Build fire(APIClientConnection conn,
                         int projectId)
                  throws java.io.IOException,
                         ServiceException
Creates a new job with the specified project's default selector and build class and engaging any linked adapters. To create a job with different settings for these parameters, use fire(APIClientConnection, int, String, String, boolean), instead.

Parameters:
conn - the connection to use for issuing the request
projectId - the project ID of the project to build
Throws:
java.io.IOException
ServiceException

fire

public static Build fire(APIClientConnection conn,
                         int projectId,
                         java.lang.String selectorId,
                         java.lang.String buildClassName,
                         boolean runLink)
                  throws java.io.IOException,
                         ServiceException
Deprecated. Use fire(APIClientConnection, int, String, String, boolean, Environment) instead

Fires a build with the specified project, overriding the project's default selector, build class, and adaptor linkage.

Throws:
java.io.IOException
ServiceException

fire

public static Build fire(APIClientConnection conn,
                         int projectId,
                         java.lang.String selectorId,
                         java.lang.String buildClassName,
                         boolean runLink,
                         java.util.List<EnvironmentEntry> adHocEnvironmentOverrides)
                  throws java.io.IOException,
                         ServiceException
Fires a build with the specified project, overriding the project's default selector, build class, and adaptor linkage, and environment.

Parameters:
conn - the connection to use for issuing the request
projectId - The identifier of the project to be executed
selectorId - The identifier of the selector to be used
buildClassName - The name of the build class to be used
runLink - Whether or not to also engage any linked adaptors
adHocEnvironmentOverrides - Any overriding environment values
Throws:
java.io.IOException
ServiceException

fire

public static Build fire(APIClientConnection conn,
                         int projectId,
                         java.lang.String selectorId,
                         java.lang.String buildClassName,
                         boolean runLink,
                         java.util.List<EnvironmentEntry> adHocEnvironmentOverrides,
                         java.lang.String tagOverride,
                         int levelOverride)
                  throws java.io.IOException,
                         ServiceException
Fires a build with the specified project, overriding the project's default selector, build class, adaptor linkage, environment, build tag, and access group (the user must have access to the overriding access group).

Parameters:
conn - the connection to use for issuing the request
projectId - The identifier of the project to be executed
selectorId - The identifier of the selector to be used
buildClassName - The name of the build class to be used
runLink - Whether or not to also engage any linked adaptors
adHocEnvironmentOverrides - Any overriding environment values
tagOverride - A static tag
Throws:
java.io.IOException
ServiceException

cancel

public void cancel()
            throws java.io.IOException,
                   ServiceException
Requests cancellation of a running job. This request is only valid for builds that are in the RUNNING or WAITING state.

Throws:
java.io.IOException
ServiceException

getBuildClass

public java.lang.String getBuildClass()
Returns the descriptive name of the build class for this job. The primary purpose of a build class is to control the purging behavior for a job.


getBuildId

public int getBuildId()
Returns the unique identifier for this job.


getCancellation

public boolean getCancellation()
Returns whether or not this job is marked to be cancelled. If the job is COMPLETED, then this indicates whether or not the job was cancelled.


getChainedBuildId

public int getChainedBuildId()
Returns the identifier of the build chained from this one, if a pass or fail chain was set on this Build.


getDuration

public int getDuration()
Returns the length of time that the build has taken thus far, in seconds.


getEngineId

public java.lang.String getEngineId()
Returns the unique ID of the Build Forge engine that it assigned to this build.


getEnvText

public java.lang.String getEnvText()
Returns the environment block of this build. This field will not be useful to most clients, so it is not sent by default. If this job object was returned by a method that does not retrieve this field, then null is returned instead of the correct value.


getFailChainId

public int getFailChainId()
Returns the identifier of the Project that will be executed in the event that this Build fails.

Returns:
the identifier of the Project that will be executed in the event that this Build fails.

getFired

public int getFired()
Returns the time at which this job was created as a timestamp.

Timestamps are stored as the number of seconds elapsed since midnight on January 1, 1970, UTC.


getGeoId

public java.lang.String getGeoId()
Returns the UUID of the geographic location at which this Build is slated to execute via GDD.


getJobId

public int getJobId()
Returns the process ID of the job management process on the engine that is running it.


getLevel

public int getLevel()
Returns the access group ID assigned to this build. Users that have neither direct nor indirect membership in this access group will not be able to see either the build or its results.


getPassChainId

public int getPassChainId()
Returns the identifier of the Project that will be executed in the event that this Build succeeds.

Returns:
the identifier of the Project that will be executed in the event that this Build succeeds.

getProcess

public BuildDBO.Process getProcess()
Returns the type of job that this object represents. The job types are described in their own entry.


getResult

public BuildDBO.Result getResult()
Returns the result of this job. The job result types are described in their own entry.


getSelectorId

public java.lang.String getSelectorId()
Returns the selector ID for this job. Selectors are used to determine which server to use for running a particular step. Steps may specify their own selector, but those that do not specify a selector default to using the selector that is specified in the build record. Special jobs (purges and clobbers) do not require a selector, as they do not run any steps, but normal jobs must specify a default selector.


getStage

public java.lang.String getStage()
Returns the current stage of the job. This is a free-form string that may be used to report on the job's progress.


getStartTime

public int getStartTime()
Returns the timestamp for when this job was picked up by an engine. As jobs do not launch instantaneously, and as they may have to wait for an engine to become available, this can be different from the getFired() timestamp.

Timestamps are stored as the number of seconds elapsed since midnight on January 1, 1970, UTC.


getState

public BuildDBO.State getState()
Returns the current state of this job. The job states are described in their own entry.


getTag

public java.lang.String getTag()
Returns the build tag for this job.


getTargetId

public int getTargetId()
Returns the target of this job. Normally, this is the project ID of the project for which this job was created. This applies to all jobs except purges, for which this returns the build ID that is to be purged by this job.


getUserId

public int getUserId()
Returns the user ID of the user that created this job. If the job was launched by a scheduler entry, then the user ID is set to the owner of the scheduler entry.


toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object