com.buildforge.services.client.dbo
Class Step

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

public class Step
extends java.lang.Object

Steps define a logical piece of an automated process. Any given Step should generally contain no more than a few closely related commands that accomplish a fundamental task that is part of the overall automated process or Project. Steps are child objects of Projects and much of the manipulation of Step objects will be done at the Project level (adding a Step to a Project, reordering Steps, etc.). However, some operations such as updating the commands within a Step removing a Step altogether, and activation or deactivation are located here.

In addition to the command itself, step objects define much of the context within which a command is executed and how that step may interact with other steps that surround it.


Field Summary
static java.lang.Class<Step> CLASS
           
 
Constructor Summary
Step(APIClientConnection conn)
          Define a new step object.
 
Method Summary
 void activate()
          Activates a step.
 void activate(boolean active)
          Either activates or deactivates a step.
 Step clone()
          Clones this Step object.
 void deactivate()
          Deactivates a step.
 boolean getAbsolute()
          Whether this step uses absolute or build-relative paths.
 boolean getActive()
          Whether or not this step is active.
 boolean getBroadcast()
          Whether or not this is a broadcast step.
 java.lang.String getCommandText()
          The command text for the step.
 java.lang.String getDescription()
          The descriptive name of the step, as provided by the user.
 java.lang.String getDirectory()
          The step directory.
 int getEnvironmentId()
          The environment group ID to apply as a step environment.
 int getFailChainId()
          The project ID of the fail chain project.
 java.lang.String getFailNotify()
          The access group ID of the access group to notify if this step fails.
 boolean getFailWait()
          Whether or not to wait for the fail chain to complete before continuing the build.
 int getFilterSetId()
          Returns the identifier of the associated Filter, if any.
 int getInlineChainId()
          The identifier of the Project to unconditionally execute along with this Step's commands (usually '.sleep 0' in the case of a Step used purely to call another Project).
 int getLevel()
          The access group ID for this step, if any.
 StepDBO.OnFail getOnFail()
          Returns the action that will be taken in the case of an unsuccessful execution of this Step's commands.
 int getPassChainId()
          The project ID of the pass chain project.
 java.lang.String getPassNotify()
          The access group ID of the access group to notify if this step passes.
 boolean getPassWait()
          Whether or not to wait for the pass chain to complete before continuing the build.
 int getProjectId()
          The project ID, as supplied by the Build Forge system during the creation of the project.
 java.lang.String getResource()
          Deprecated. Use getSelectorId() instead
 java.lang.String getSelectorId()
          The selector to use for this step.
 int getStepOrdinal()
          The position of this step in the project's step list.
 StepDBO.Threaded getThreaded()
          The threading behavior for this step.
 int getTimeout()
          The maximum length of time (in seconds) that the step is permitted to take to complete its work and return control to the agent.
 java.lang.String getUid()
          The system-assigned unique identifier for this step.
 void setAbsolute(boolean absolute)
          Changes whether this step uses an absolute or build-relative directory.
 void setActive(boolean active)
          Changes whether this step is active.
 void setBroadcast(boolean broadcast)
          Changes whether or not this is a broadcast step.
 void setCommandText(java.lang.String cmdText)
          Changes the command text for this step.
 void setDescription(java.lang.String description)
          Changes the descriptive name of the step, as provided by the user.
 void setDirectory(java.lang.String directory)
          Sets the step directory for this step.
 void setEnvironmentId(int environmentId)
          Sets the environment group ID to apply as a step environment.
 void setFailChainId(int failChainId)
          Sets the fail chain project for this step.
 void setFailNotify(java.lang.String failNotify)
          Sets the access group ID of the access group to notify if this step fails.
 void setFailWait(boolean failWait)
          Determines whether or not the build will wait for a fail chaing to complete before completing
 void setFilterSetId(int filterSetId)
          Associates a Filter with this Step
 void setInlineChainId(int inlineChainId)
          Adds a Project to be unconditionally executed as part of the execution of this Step
 void setLevel(int level)
          Sets the access group ID for this step.
 void setOnFail(StepDBO.OnFail onFail)
          Sets the behaviour for execution continuation (halt or continue) in the case of unsuccessful execution of this Step.
 void setPassChainId(int passChainId)
          Sets the pass chain project for this step.
 void setPassNotify(java.lang.String passNotify)
          Sets the access group ID of the access group to notify if this step passes.
 void setPassWait(boolean passWait)
          Defines whether (true) or not (false) to wait for the pass chain (if any is set) to complete its execution before continuing with any subsequent Steps of this Project.
 void setResource(java.lang.String resource)
          Deprecated. Use #setSelectorId() instead
 void setSelectorId(java.lang.String selectorId)
          Assigns a Selector to be used to locate Servers that may be used to execute this Step.
 void setThreaded(StepDBO.Threaded threaded)
          Sets the threading behavior for this step.
 void setTimeout(int timeout)
          Sets the maximum length of time (in seconds) that the step is permitted to take to complete its work and return control to the agent.
 java.lang.String toString()
           
 Step update()
          Updates this existing step to use the modified values in this object.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

CLASS

public static final java.lang.Class<Step> CLASS
Constructor Detail

Step

public Step(APIClientConnection conn)
Define a new step object. The step does not exist until it is added to a project using Project.addStep(Step) or Project.addStep(Step, int).

Parameters:
conn - the services layer connection that the step object should use when submitting requests
Method Detail

update

public Step update()
            throws java.io.IOException,
                   ServiceException
Updates this existing step to use the modified values in this object.

Restrictions: Requires Permission.UpdateProjectStep. The field requirements listed for Project#addStep() apply to this method, as well. If this step has not yet been attached to a Project, or if the project itself is not yet live, then this call will have no effect.

Returns:
the updated project
Throws:
java.io.IOException
ServiceException

deactivate

public void deactivate()
                throws java.io.IOException,
                       ServiceException
Deactivates a step. This is exactly equivalent to calling activate(false).

Throws:
java.io.IOException
ServiceException

activate

public void activate()
              throws java.io.IOException,
                     ServiceException
Activates a step. This is exactly equivalent to calling activate(true).

Throws:
java.io.IOException
ServiceException

activate

public void activate(boolean active)
              throws java.io.IOException,
                     ServiceException
Either activates or deactivates a step. A step that is deactivated is not included in builds of its project. The intent is to prevent the step from being used on a temporary basis, with the intent that it may eventually need to be restored. This change takes effect immediately; no independent call to update() is required. This object's active property state will be changed to reflect the modification. To combine this change with others in an update(), see setActive(boolean), instead.

Restrictions: Requires Privilege#UpdateProjectStep and direct or indirect membership in the step's assigned access group.

Throws:
java.io.IOException
ServiceException

getAbsolute

public boolean getAbsolute()
Whether this step uses absolute or build-relative paths. Suppose that the server path setting is /work/build, the project name is Cool Product 1.0, the build tag is BUILD_42, and the step directory is /src. If the step is set to relative, then the final directory that will be used for the step is /work/build/Cool_Product_1.0/BUILD_42/src. If the step is set to absolute, then the final directory will instead be /work/build/src.

Notes:

The use of absolute paths is generally discouraged, as multiple builds may contend for the state of the filesystem. Keeping the builds isolated in their own build directories helps prevent individual builds from interfering with each other unexpectedly.


getActive

public boolean getActive()
Whether or not this step is active. Inactive steps are always excluded from builds.


getBroadcast

public boolean getBroadcast()
Whether or not this is a broadcast step. Broadcast steps are replicated such that they have one entry for every server that matches a selector. In other words, if the step's selector returns three servers, then three copies of the step will be made, with each step assigned to a different server.

Notes: A broadcast step whose threading behavior is set to JOIN will only use it for the last generated step. The other generated steps will use YES, instead.


getCommandText

public java.lang.String getCommandText()
The command text for the step. This is the command (or sequence of commands) that will be executed on the server that runs this step.

Restrictions: This method will return null if the command text is not available. This will happen if the step has an access group assigned to it and the user has neither direct nor indirect membership to that access group.


getDescription

public java.lang.String getDescription()
The descriptive name of the step, as provided by the user.


getDirectory

public java.lang.String getDirectory()
The step directory. See getAbsolute() for a full description of how this value is combined with the #getPath() server path and (possibly) the build directory to produce the actual execution directory for the step.


getEnvironmentId

public int getEnvironmentId()
The environment group ID to apply as a step environment. The step environment is applied after the build environment to provide settings that are local to the step.

Parameters:
environmentId - the group ID of the environment block to apply as the step's environment

getFailChainId

public int getFailChainId()
The project ID of the fail chain project. The engine will automatically launch a build of the fail chain project if this step fails.

Returns:
the project ID of the fail chain project, or 0 if this step does not use a fail chain.

getFailNotify

public java.lang.String getFailNotify()
The access group ID of the access group to notify if this step fails. The engine will automatically send an e-mail message to every user that is a direct or indirect member of the specified access group whenever this step fails.

Returns:
the access group ID access group to be notified if this step fails, or 0 to disable such e-mails

getFailWait

public boolean getFailWait()
Whether or not to wait for the fail chain to complete before continuing the build. If this is true, then the step waits for the chained build to complete before allowing this build to continue executing.

Restrictions: If no fail chain is used, then this setting is ignored.


getFilterSetId

public int getFilterSetId()
Returns the identifier of the associated Filter, if any.


getInlineChainId

public int getInlineChainId()
The identifier of the Project to unconditionally execute along with this Step's commands (usually '.sleep 0' in the case of a Step used purely to call another Project).


getLevel

public int getLevel()
The access group ID for this step, if any. This value may be set to 0, in which case the step is accessible to all users that have access to its parent Project.

Restrictions: If the user does not have direct or indirect membership to this access group, then she will still see that the step exists; however, she will not be permitted to

Further, a user is not normally able to execute a step that he can not access (the behavior is similar to a step that is not active. However, if the user has Permission.ExecStepPerm, then the step executes. In no case, however, is the user able to retrieve its command text from here or from a step result, nor may the user retrieve its step log from.


getOnFail

public StepDBO.OnFail getOnFail()
Returns the action that will be taken in the case of an unsuccessful execution of this Step's commands. Usually this is either stopping the flow of execution or allowing it to continue.


getPassChainId

public int getPassChainId()
The project ID of the pass chain project. The engine will automatically launch a build of the pass chain project if this step completes successfully.

Returns:
the project ID of the pass chain project, or 0 if this step does not use a pass chain.

getPassNotify

public java.lang.String getPassNotify()
The access group ID of the access group to notify if this step passes. The engine will automatically send an e-mail message to every user that is a direct or indirect member of the specified access group whenever this step completes successfully.

Returns:
the access group ID access group to be notified if this step passes, or 0 to disable such e-mails

getPassWait

public boolean getPassWait()
Whether or not to wait for the pass chain to complete before continuing the build. If this is true, then the step waits for the chained build to complete before allowing this build to continue executing. If the pass chain fails, then the step's result status is changed from pass to fail.

If this setting is false, then the pass chain build executes independently and will not be monitored by this step. In this case, the status of the pass chain does not influence the final outcome of the step.

Restrictions: If no pass chain is used, then this setting is ignored.


getProjectId

public int getProjectId()
The project ID, as supplied by the Build Forge system during the creation of the project.

Restrictions: This field is immutable.


getSelectorId

public java.lang.String getSelectorId()
The selector to use for this step. If set to null, then the step will run using the default selector. The default selector is originally set to the same selector as the build itself, but this may be influenced by .bset selector, .bset server, or the sticky setting for the project. Please consult the Online Help in the Management Console for more information.


getResource

@Deprecated
public java.lang.String getResource()
Deprecated. Use getSelectorId() instead

This method should not be used.


getStepOrdinal

public int getStepOrdinal()
The position of this step in the project's step list. This is the 1-based index for the step, as determined by the step's creation and any subsequent modifications to the project's step sequence.

Restrictions: This field is immutable.


getThreaded

public StepDBO.Threaded getThreaded()
The threading behavior for this step. See StepDBO.Threaded for an explanation of the values. Also see getBroadcast() for information about how that setting can interact with threading.


getTimeout

public int getTimeout()
The maximum length of time (in seconds) that the step is permitted to take to complete its work and return control to the agent. The default is 300 seconds (5 minutes). If the step takes longer than this, then it will be forcibly terminated and the step will be assigned a failing result status. If the value is 0, then the step is allowed to run for an arbitrarily long time.


getUid

public java.lang.String getUid()
The system-assigned unique identifier for this step.


setAbsolute

public void setAbsolute(boolean absolute)
Changes whether this step uses an absolute or build-relative directory. Please see getAbsolute() for more information about this setting.

Restrictions: Does not take effect until update() has been called.

Parameters:
absolute - true to use an absolute path, or false to use a build-relative path

setActive

public void setActive(boolean active)
Changes whether this step is active. Inactive steps are always excluded from builds.

Restrictions: Does not take effect until update() has been called. The alternative methods listed below have write-through behavior.

Parameters:
active - true to activate the step, or false to deactivate it.
See Also:
#activate()}, #activate(boolean)}, #deactivate()}

setBroadcast

public void setBroadcast(boolean broadcast)
Changes whether or not this is a broadcast step. Please see getBroadcast() for more information.

Restrictions: Does not take effect until update() has been called.

Parameters:
broadcast - true to set this step to run as a broadcast step, or false to set it to run normally.

setCommandText

public void setCommandText(java.lang.String cmdText)
Changes the command text for this step. Please see getCommandText() for more information.

Restrictions: Does not take effect until update() has been called.

Parameters:
cmdText - the new command text for this step.

setDescription

public void setDescription(java.lang.String description)
Changes the descriptive name of the step, as provided by the user.

Restrictions: Does not take effect until update() has been called.

Parameters:
description - the new descriptive name for this step

setDirectory

public void setDirectory(java.lang.String directory)
Sets the step directory for this step. Please see getDirectory() and getAbsolute() for more information.

Restrictions: Does not take effect until update() has been called.

Parameters:
directory - the new step directory

setEnvironmentId

public void setEnvironmentId(int environmentId)
Sets the environment group ID to apply as a step environment. The step environment is applied after the build environment to provide settings that are localized to the step.

Restrictions: Does not take effect until update() has been called.

Parameters:
environmentId - the group ID of the environment block to apply as the step's environment

setFailChainId

public void setFailChainId(int failChainId)
Sets the fail chain project for this step. Please see getFailChainId() for more information.

Restrictions: Does not take effect until update() has been called. The value must refer to a Project to which the caller has access.

Parameters:
failChainId - the project ID of the fail chain to use, or 0 to disable this feature for this step.

setFailNotify

public void setFailNotify(java.lang.String failNotify)
Sets the access group ID of the access group to notify if this step fails. The engine will automatically send an e-mail message to every user that is a direct or indirect member of the specified access group whenever this step fails during a build.

Restrictions: Does not take effect until update() has been called. The value must refer to a an AccessGroup to which the caller has either direct or indirect membership.

Parameters:
failNotify - the access group ID access group to be notified if a build of this project fails, or 0 to disable such e-mails for this step.

setFailWait

public void setFailWait(boolean failWait)
Determines whether or not the build will wait for a fail chaing to complete before completing

Parameters:
failWait -

setFilterSetId

public void setFilterSetId(int filterSetId)
Associates a Filter with this Step

Parameters:
filterSetId -

setInlineChainId

public void setInlineChainId(int inlineChainId)
Adds a Project to be unconditionally executed as part of the execution of this Step

Parameters:
inlineChainId -

setLevel

public void setLevel(int level)
Sets the access group ID for this step. See getLevel() for more information about how this affects step behavior.

Restrictions: Does not take effect until update() has been called. The user must be a direct or indirect member of the access group.


setOnFail

public void setOnFail(StepDBO.OnFail onFail)
Sets the behaviour for execution continuation (halt or continue) in the case of unsuccessful execution of this Step.

Parameters:
onFail -

setPassChainId

public void setPassChainId(int passChainId)
Sets the pass chain project for this step. Please see getPassChainId() for more information.

Restrictions: Does not take effect until update() has been called. The value must refer to a Project to which the caller has access.

Parameters:
passChainId - the project ID of the pass chain to use, or 0 to disable this feature for this step.

setPassNotify

public void setPassNotify(java.lang.String passNotify)
Sets the access group ID of the access group to notify if this step passes. The engine will automatically send an e-mail message to every user that is a direct or indirect member of the specified access group whenever this step completes successfully during a build.

Parameters:
passNotify - the access group ID access group to be notified if this step completes successfully, or 0 to disable such e-mails for this step.

setPassWait

public void setPassWait(boolean passWait)
Defines whether (true) or not (false) to wait for the pass chain (if any is set) to complete its execution before continuing with any subsequent Steps of this Project.

Parameters:
passWait -

setSelectorId

public void setSelectorId(java.lang.String selectorId)
Assigns a Selector to be used to locate Servers that may be used to execute this Step. This setting will override the Selector defined in the Project to which this Step belongs.

Parameters:
selectorId -

setResource

@Deprecated
public void setResource(java.lang.String resource)
Deprecated. Use #setSelectorId() instead

This method should not be used.

Parameters:
resource -

setThreaded

public void setThreaded(StepDBO.Threaded threaded)
Sets the threading behavior for this step. See StepDBO.Threaded for an explanation of the values. Also see getBroadcast() for information about how that setting can interact with threading.

Restrictions: Does not take effect until update() has been called. May not be null.


setTimeout

public void setTimeout(int timeout)
Sets the maximum length of time (in seconds) that the step is permitted to take to complete its work and return control to the agent.

Restrictions: Does not take effect until update() has been called. The value may not be negative. A value of 0 disables the timeout, allowing the step to take an arbitrarily long time to complete its work.


toString

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

clone

public Step clone()
Clones this Step object. The newly created Step object will have no parent reference and its UUID will be nulled, ready for addition to another Project.

Overrides:
clone in class java.lang.Object