jetbrains.buildServer.serverSide
Interface BuildAgentManager

public interface BuildAgentManager

Provides an ability to operate TeamCity agents.

Nested Class Summary

static class

BuildAgentManager.RunConfigurationPolicy Policies to check if the is allowed to run the configuration.

Method Summary

<T extends SBuildAgent> T	findAgentById(int agentId, boolean searchUnregistered) Searches for an agent with specified id among registered and unregistered agents.
<T extends SBuildAgent> T	findAgentByName(java.lang.String agentName, boolean searchUnregistered) Searches for an agent with specified name among registered and unregistered agents.
<T extends SBuildAgent> java.util.List<AgentCompatibility>	getAgentCompatibilities(T agent) Returns build configuration compatibility information for the specified agent
<T extends SBuildAgent> java.util.Set<java.lang.String>	getCanRunConfigurations(T agent) Returns list of build configurations this agent can potentially run.
<T extends SBuildAgent> int	getNumberOfCompatibleConfigurations(T agent) Returns number of configurations compatible with specified agent
<T extends SBuildAgent> int	getNumberOfIncompatibleConfigurations(T agent) Returns number of configurations incompatible with specified agent
<T extends SBuildAgent> java.util.List<T>	getRegisteredAgents() Returns all registered authorized agents.
<T extends SBuildAgent> java.util.List<T>	getRegisteredAgents(boolean includeUnauthorized) Returns all registered agents.
<T extends SBuildAgent> BuildAgentManager.RunConfigurationPolicy	getRunConfigurationPolicy(T agent) Returns run confgiration policy for an agent.
<T extends SBuildAgent> java.util.List<T>	getUnregisteredAgents() Returns list of all currently unregistered agents, i.e.
<T extends SBuildAgent> boolean	isCanRunConfiguration(T agent, java.lang.String buildTypeId) Returns true if specified agent can run specified build configuration.
void	removeAgent(SBuildAgent agent, SUser user) Removes specified agent and cleans up this agent state from the database.
<T extends SBuildAgent> void	setCanRunConfiguration(T agent, java.lang.String buildTypeId, boolean canRun) If BuildAgentManager.RunConfigurationPolicy.SELECTED_COMPATIBLE_CONFIGURATIONS policy is selected for the agent, sets whether configuration with specified id can or can't run on the agent.
<T extends SBuildAgent> void	setCanRunConfigurations(T agent, java.lang.String[] buildTypeIds, boolean canRun) If BuildAgentManager.RunConfigurationPolicy.SELECTED_COMPATIBLE_CONFIGURATIONS policy is selected for the agent, sets whether configurations with specified ids can or can't run on the agent.
<T extends SBuildAgent> void	setRunConfigurationPolicy(T agent, BuildAgentManager.RunConfigurationPolicy policy) Sets build configuration run policy for an agent.

Method Detail

getRegisteredAgents

<T extends SBuildAgent> java.util.List<T> getRegisteredAgents()

Returns all registered authorized agents. Registered means connected at the moment of call.

Returns:

see above

getRegisteredAgents

<T extends SBuildAgent> java.util.List<T> getRegisteredAgents(boolean includeUnauthorized)

Returns all registered agents. Registered means connected at the moment of call.

Parameters:

includeUnauthorized - if true, unauthorized agents, i.e. agents which cannot run builds until authorized by admin

Returns:

see above

getUnregisteredAgents

<T extends SBuildAgent> java.util.List<T> getUnregisteredAgents()

Returns list of all currently unregistered agents, i.e. agents registered on server some time ago, but currently unregistered by server because they are either not responding, or upgrading. This list doesn't include unauthorized agents. The list is sorted by agent registration date in reverse order.

Returns:

list of all currently unregistered agents

findAgentById

@Nullable
<T extends SBuildAgent> T findAgentById(int agentId,
                                                 boolean searchUnregistered)

Searches for an agent with specified id among registered and unregistered agents.

Parameters:

agentId - id of the agent to search

searchUnregistered - true if unregistered agents should be searched too

Returns:

found agent or null

findAgentByName

@Nullable
<T extends SBuildAgent> T findAgentByName(java.lang.String agentName,
                                                   boolean searchUnregistered)

Searches for an agent with specified name among registered and unregistered agents.

Parameters:

agentName - name of the agent to search

searchUnregistered - true if unregistered agents should be searched too

Returns:

found agent or null

removeAgent

void removeAgent(@NotNull
                 SBuildAgent agent,
                 @Nullable
                 SUser user)
                 throws AgentCannotBeRemovedException

Removes specified agent and cleans up this agent state from the database. Only unregistered agents can be removed.

Parameters:

agent - agent

user - user who removes agent (can be null)

Throws:

AgentCannotBeRemovedException - if agent is connected/registered

setRunConfigurationPolicy

<T extends SBuildAgent> void setRunConfigurationPolicy(T agent,
                                                       BuildAgentManager.RunConfigurationPolicy policy)

Sets build configuration run policy for an agent. Possible values are:

• BuildAgentManager.RunConfigurationPolicy.ALL_COMPATIBLE_CONFIGURATIONS - all compatible configurations can run on this agent
• BuildAgentManager.RunConfigurationPolicy.SELECTED_COMPATIBLE_CONFIGURATIONS - only selected configurations can run on this agent (configuration needs to be compatible too)

Parameters:

agent - the agent

policy - policy to set

getRunConfigurationPolicy

<T extends SBuildAgent> BuildAgentManager.RunConfigurationPolicy getRunConfigurationPolicy(T agent)

Returns run confgiration policy for an agent.

Parameters:

agent - the agent

Returns:

current run configuration policy

setCanRunConfiguration

<T extends SBuildAgent> void setCanRunConfiguration(T agent,
                                                    java.lang.String buildTypeId,
                                                    boolean canRun)

If BuildAgentManager.RunConfigurationPolicy.SELECTED_COMPATIBLE_CONFIGURATIONS policy is selected for the agent, sets whether configuration with specified id can or can't run on the agent.

Parameters:

agent - the agent

buildTypeId - id of the configuration

canRun - if true then this configuration can run on the agent, if false it can't

setCanRunConfigurations

<T extends SBuildAgent> void setCanRunConfigurations(T agent,
                                                     java.lang.String[] buildTypeIds,
                                                     boolean canRun)

If BuildAgentManager.RunConfigurationPolicy.SELECTED_COMPATIBLE_CONFIGURATIONS policy is selected for the agent, sets whether configurations with specified ids can or can't run on the agent.

Parameters:

agent - the agent

buildTypeIds - ids of the configurations

canRun - if true then these configurations can run on the agent, if false it can't

isCanRunConfiguration

<T extends SBuildAgent> boolean isCanRunConfiguration(T agent,
                                                      java.lang.String buildTypeId)

Returns true if specified agent can run specified build configuration.

Parameters:

agent - the agent

buildTypeId - build configuration id

Returns:

true if BuildAgentManager.RunConfigurationPolicy.ALL_COMPATIBLE_CONFIGURATIONS policy selected or configuration was explicitly marked as accessible by the agent. Please note that compatibility check is not performed.

getCanRunConfigurations

<T extends SBuildAgent> java.util.Set<java.lang.String> getCanRunConfigurations(T agent)

Returns list of build configurations this agent can potentially run.

Parameters:

agent - the agent

Returns:

list of ids of potentially available for this agent configurations

getNumberOfCompatibleConfigurations

<T extends SBuildAgent> int getNumberOfCompatibleConfigurations(T agent)

Returns number of configurations compatible with specified agent

Parameters:

agent - agent

Returns:

number of compatible configurations

getNumberOfIncompatibleConfigurations

<T extends SBuildAgent> int getNumberOfIncompatibleConfigurations(T agent)

Returns number of configurations incompatible with specified agent

Parameters:

agent - agent

Returns:

number of incompatible configurations

getAgentCompatibilities

<T extends SBuildAgent> java.util.List<AgentCompatibility> getAgentCompatibilities(T agent)

Returns build configuration compatibility information for the specified agent

Parameters:

agent - agent

Returns:

build configuration compatibility information