com.buildforge.services.client.dbo
Class Project

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

public class Project
extends java.lang.Object

Projects bring together all the elements that make up an automated process. They contain a collection of Steps describing the execution of the process as well as links to the Environment that should be used for execution, links to other Projects to execute in the case of a successful or unsuccessful result, and many other pieces of metadata that define the behaviour of the process at runtime. Typically, a project might describe how a piece of software is built or how to stage the binary image of a completed build.


Field Summary
static java.lang.Class<Project> CLASS
           
 
Constructor Summary
Project(APIClientConnection conn)
          Define a new project object.
 
Method Summary
 void activate()
          Activates this project, such that it is available for running builds.
 void activate(boolean active)
          Changes whether or not a project is active.
 void addStep(Step newStep)
          Adds a new step to this project's step list.
 void addStep(Step newStep, int index)
          Adds a new step object to this project at the specified, index into the current list of steps.
 void clobber()
          Requests that a project be clobbered.
 Project clone()
          Clones this project.
 void copyStep(int fromIndex, int toIndex)
          Makes a copy of an existing step at a new location in the step list.
 Project create()
          Creates a new project as defined by this object.
 void deactivate()
          Deactivates this project, such that it is no longer available for running builds.
 void delete()
          Removes this project from the system.
static java.util.List<Project> findAll(APIClientConnection conn)
          Finds all project objects in the system to which the user has access.
static java.util.Map<java.lang.String,java.lang.Integer> findAllNames(APIClientConnection conn)
          Finds the names and IDs of all project objects in the system to which the user has access.
static Project findById(APIClientConnection conn, int projectId)
          Finds the project with the specified ID.
static Project findByName(APIClientConnection conn, java.lang.String projectName)
          Finds the project with the specified name.
 Build fire()
          Creates a new build of this project.
 Build fire(java.lang.String selectorId, java.lang.String buildClassName, boolean runLink)
          Deprecated. Use fire(String, String, boolean, Environment) instead
 Build fire(java.lang.String selectorId, java.lang.String buildClassName, boolean runLink, java.util.List<EnvironmentEntry> adHocEnvironmentOverrides)
          Creates a new build of this project.
 Build fire(java.lang.String selectorId, java.lang.String buildClassName, boolean runLink, java.util.List<EnvironmentEntry> adHocEnvironmentOverrides, java.lang.String tagOverride, int accessGroupIdentifierOverride)
          Creates a new build of this project using a custom selector or build class.
 boolean getActive()
          Whether or not the project is active.
 java.lang.String getBuildClass()
          The name of this project's default build class.
 java.util.List<Build> getBuilds()
           
 int getEnvironmentId()
          The environment group ID of the default build environment for this project.
 int getFailChainId()
          The project ID of the fail chain project.
 int getFailNotify()
          The access group ID of the access group to notify about failed builds.
 java.lang.String getGeoId()
          Return the geographic identifer for use with Globally Distributed Development
 int getLevel()
          The level (access group ID) assigned to this class.
 int getMaxThread()
          The maximum number of threaded steps that this project will attempt to run concurrently.
 java.lang.String getName()
          The descriptive name of this project, as provided by the user during its creation.
 int getPassChainId()
          The project ID of the pass chain project.
 int getPassNotify()
          The access group ID of the access group to notify about passed builds.
 int getProjectId()
          The system-generated unique identifier for this project.
 int getRunLimit()
          The number of concurrent builds that are permitted for this project.
 java.lang.String getSelectorId()
          The selector ID of the default selector to be used when building this project.
 int getStartNotify()
          The access group ID of the access group to notify about started builds.
 Step getStep(int index)
          Retrieves a step by index.
 Step getStep(java.lang.String stepUid)
          Retrieves a step by its system-generated unique identifier.
 java.util.List<Step> getSteps()
          Retrieves a list of the steps that are defined for this project.
 boolean getSticky()
          Whether or not server assignment is sticky for this project.
 java.lang.String getTag()
          The build tag format used by this project.
 int getTagSync()
          The project ID of the project against which this project should synchronize its tag variables.
 ProjectDBO.InUse inUse()
          Reports whether or not a project is references by other items that would interfere with its deletion.
 ProjectDBO.InUse inUse(java.util.List<Message> list)
          Reports whether or not a project is references by other items that would interfere with its deletion.
 ProjectDBO.InUse inUse(java.util.List<Message> list, boolean all)
          Reports whether or not a project is references by other items that would interfere with its deletion.
 void moveStep(int fromIndex, int toIndex)
          Moves an existing step to a new location in the step list.
 void removeStep(int index)
          Removes the specified step from this project and deletes it.
 void removeStep(java.lang.String stepUid)
          Removes the specified step from this project and deletes it.
 void setActive(boolean active)
          Changes whether or not the project is active.
 void setBuildClass(java.lang.String buildClassName)
          Changes the default build class for this project.
 void setEnvironmentId(int environmentId)
          Sets the project's default build environment's group ID.
 void setFailChainId(int newChain)
          Sets the project ID to identify the fail chain project.
 void setFailNotify(int notify)
          Sets the access group ID of the access group to notify about failed builds.
 void setGeoId(java.lang.String newGeoId)
          Sets the geographic identifer for use with Globally Distributed Development
 void setLevel(int level)
          Sets the level (access group ID) assigned to this class.
 void setMaxThread(int maxThread)
          Sets the maximum number of threaded steps that this project will attempt to run concurrently.
 void setName(java.lang.String name)
          Changes the descriptive name of this project.
 void setPassChainId(int newChain)
          Sets the project ID to identify the pass chain project.
 void setPassNotify(int notify)
          Sets the access group ID of the access group to notify about passed builds.
 void setRunLimit(int newRunLimit)
          Sets the number of concurrent builds that are permitted for this project.
 void setSelectorId(java.lang.String selectorId)
          Sets the selector ID of the default selector to be used when building this project.
 void setStartNotify(int notify)
          Sets the access group ID of the access group to notify about started builds.
 void setSticky(boolean sticky)
          Sets whether or not server assignment is sticky for this project.
 void setTag(java.lang.String tag)
          Sets the build tag format used by this project.
 void setTagSync(int tagSync)
          Sets the project ID of the project against which this project should synchronize its tag variables.
 java.lang.String toString()
           
 Project update()
          Updates this existing project 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<Project> CLASS
Constructor Detail

Project

public Project(APIClientConnection conn)
Define a new project object. The project does not exist until after it has been created using the create() method.

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

findAllNames

public static java.util.Map<java.lang.String,java.lang.Integer> findAllNames(APIClientConnection conn)
                                                                      throws java.io.IOException,
                                                                             ServiceException
Finds the names and IDs of all project objects in the system to which the user has access. A user has access to all projects for which the user has direct or indirect membership in the project's assigned access group.

Parameters:
conn - the API client connection to use for the request
Returns:
a mapping of project names to their project IDs
Throws:
java.io.IOException
ServiceException

findAll

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

Parameters:
conn - the API client connection to use for the request
Returns:
the list of projects
Throws:
java.io.IOException
ServiceException

findById

public static Project findById(APIClientConnection conn,
                               int projectId)
                        throws java.io.IOException,
                               ServiceException
Finds the project with the specified ID.

Parameters:
conn - the API client connection to use for the request
name - The system-assigned project ID of the project to find
Returns:
The project, or null if none could be found
Throws:
java.io.IOException
ServiceException

findByName

public static Project findByName(APIClientConnection conn,
                                 java.lang.String projectName)
                          throws java.io.IOException,
                                 ServiceException
Finds the project with the specified name.

Parameters:
conn - the API client connection to use for the request
name - The descriptive name of the project to find
Returns:
The project, or null if none could be found
Throws:
java.io.IOException
ServiceException

getBuilds

public java.util.List<Build> getBuilds()
                                throws java.io.IOException,
                                       ServiceException
Throws:
java.io.IOException
ServiceException

clobber

public void clobber()
             throws java.io.IOException,
                    ServiceException
Requests that a project be clobbered. Clobbering a project forcefully deletes it by first resolving any dependencies that would otherwise have prevented deletion. Specifically:

Restrictions: Requires Permission.ClobberProject. All existing builds must be in one of the following states:

Throws:
java.io.IOException
ServiceException

create

public Project create()
               throws java.io.IOException,
                      ServiceException
Creates a new project as defined by this object.

Restrictions: Requires Permission.AddProject. Also:

Returns:
the newly created project class
Throws:
java.io.IOException
ServiceException

update

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

Restrictions: Requires Permission.UpdateProject. The field requirements listed for create() apply to this method, as well.

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

delete

public void delete()
            throws java.io.IOException,
                   ServiceException
Removes this project from the system.

Restrictions: Requires Permission.DeleteProject or Permission.ClobberProject. The caller must be a direct or indirect member of all access groups that have been set for individual steps. The project can not be referenced by any object except the project's own steps, tags, and registers, which will all be deleted with the project. Specifically, none of the following may exist:

Throws:
java.io.IOException
ServiceException

fire

public Build fire()
           throws java.io.IOException,
                  ServiceException
Creates a new build of this project. This is a convenience method for fire(String, String, boolean) that uses the project's default settings and true for the runLink parameter. This method is the equivilant of a quick start in the user interface.

Restrictions: As for fire(String, String, boolean).

Returns:
the newly created build object
Throws:
java.io.IOException
ServiceException

fire

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

Creates a new build of this project using a custom selector or build class.

Restrictions: Requires Permission.RunBuild.

Returns:
the newly created build object
Throws:
java.io.IOException
ServiceException

fire

public Build fire(java.lang.String selectorId,
                  java.lang.String buildClassName,
                  boolean runLink,
                  java.util.List<EnvironmentEntry> adHocEnvironmentOverrides)
           throws java.io.IOException,
                  ServiceException
Creates a new build of this project. This is a convenience method for #fire(String, String, boolean, List, String, int) that uses the project's default tag and AccessGroup settings.

Parameters:
selectorId - the selector ID or the selector to use, or null to use the project's default selector
buildClassName - build class name of the build class to use, or null to use the project's default build class.
runLink - should normally be set to true, in which case this project's source Adaptor runs normally. If runLink is false, then the source adaptor is skipped. If the project does not have an adaptor link, then this value has no effect.
adHocEnvironmentOverrides - A (usually dead) Environment block that will be appended to the build's initial environment, possibly (and usually) overriding any values defined in the Project's environment. If this value is set to null, then the default environment is used without modification.
Returns:
the newly created build object
Throws:
java.io.IOException
ServiceException

fire

public Build fire(java.lang.String selectorId,
                  java.lang.String buildClassName,
                  boolean runLink,
                  java.util.List<EnvironmentEntry> adHocEnvironmentOverrides,
                  java.lang.String tagOverride,
                  int accessGroupIdentifierOverride)
           throws java.io.IOException,
                  ServiceException
Creates a new build of this project using a custom selector or build class.

Restrictions: Requires Permission.RunBuild. Also:

Parameters:
selectorId - the selector ID or the selector to use, or null to use the project's default selector
buildClassName - build class name of the build class to use, or null to use the project's default build class.
runLink - should normally be set to true, in which case this project's source Adaptor runs normally. If runLink is false, then the source adaptor is skipped. If the project does not have an adaptor link, then this value has no effect.
adHocEnvironmentOverrides - A (usually dead) Environment block that will be appended to the build's initial environment, possibly (and usually) overriding any values defined in the Project's environment. If this value is set to null, then the default environment is used without modification.
tagOverride - An overriding build tag string, or null to use the default Project tag.
accessGroupIdentifierOverride - An overriding AccessGroup identifier, or any negative value (or zero) to use the Project's default.
Returns:
the newly created build object
Throws:
java.io.IOException
ServiceException

deactivate

public void deactivate()
                throws java.io.IOException,
                       ServiceException
Deactivates this project, such that it is no longer available for running builds. The project must be made active again before it may be built. This method is equivilant to activate(false).

Restrictions: As for activate(boolean)

Throws:
java.io.IOException
ServiceException

activate

public void activate()
              throws java.io.IOException,
                     ServiceException
Activates this project, such that it is available for running builds. A deactivated project must be made active again before it may be built. This method is equivilant to activate(true).

Restrictions: As for activate(boolean)

Throws:
java.io.IOException
ServiceException

activate

public void activate(boolean active)
              throws java.io.IOException,
                     ServiceException
Changes whether or not a project is active. This method has an immediate effect; no update() call is needed. A project may not be built unless it is active.

Restrictions: Requires Permission.ActivateProject or Permission.UpdateProject.

Parameters:
active - true to activate the project, or false to deactivate it.
Throws:
java.io.IOException
ServiceException

inUse

public ProjectDBO.InUse inUse()
                       throws java.io.IOException,
                              ServiceException
Reports whether or not a project is references by other items that would interfere with its deletion. Only the status is returned; no information is provided about precisely how the project is being used. If that information is needed, use inUse(List) or inUse(List, boolean), instead.

Note: These methods will report on in-use status accurately, even if the project is referenced by an item to which the user does not have access.

Returns:
the in-use state of the project.
Throws:
java.io.IOException
ServiceException

inUse

public ProjectDBO.InUse inUse(java.util.List<Message> list)
                       throws java.io.IOException,
                              ServiceException
Reports whether or not a project is references by other items that would interfere with its deletion. The list will be populated with messages describing how the project is currently being used. If the list is null, this this method is equivilant to inUse(); otherwise, this method is equivilant to inuse(list, true).

Note: These methods will report on in-use status accurately, even if the project is referenced by an item to which the user does not have access. Currently, items can appear in this list that would not otherwise be visible to the user. This may change in the future.

Parameters:
list - the list to populate with messages that describe how the project is being used, or null if those messages are not desired.
Returns:
the in-use state of the project.
Throws:
java.io.IOException
ServiceException

inUse

public ProjectDBO.InUse inUse(java.util.List<Message> list,
                              boolean all)
                       throws java.io.IOException,
                              ServiceException
Reports whether or not a project is references by other items that would interfere with its deletion. The list will be populated with messages describing how the project is currently being used. If the caller is not concerned with an explanation and only wants the status, then inUse() may be used for efficiency. Similarly, if only one message will actually be rendered, consider using inuse(list, false), instead.

Note: These methods will report on in-use status accurately, even if the project is referenced by an item to which the user does not have access. Currently, items can appear in this list that would not otherwise be visible to the user. This may change in the future.

Parameters:
list - the list to populate with messages that describe how the project is being used
all - if true, then
Returns:
the in-use state of the project.
Throws:
java.io.IOException
ServiceException

clone

public Project clone()
Clones this project. The clone's project identifier is cleared, so it may be used immediately to create a new project.

Overrides:
clone in class java.lang.Object
Returns:
the cloned project

toString

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

getActive

public boolean getActive()
Whether or not the project is active. A project must be active for it to be used to run builds.


getBuildClass

public java.lang.String getBuildClass()
The name of this project's default build class. The actual build class may be loaded by using BuildClass.findByName(APIClientConnection, String).

Returns:
the name of the default build class for this project

getEnvironmentId

public int getEnvironmentId()
The environment group ID of the default build environment for this project. The value may be 0, indicating that no environment group is assigned; otherwise, Environment.findById(APIClientConnection, int) may be used to load the environment group.

Returns:
the environment group ID, of the project's default build environment for this project, or 0 if no environment group has been assigned.

getRunLimit

public int getRunLimit()
The number of concurrent builds that are permitted for this project.

Returns:
the project's run limit, or 0 if the number of concurrent builds is not restricted for this project.

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 a build of this project fails.

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

getGeoId

public java.lang.String getGeoId()
Return the geographic identifer for use with Globally Distributed Development

Returns:
the geographic identifer for use with Globally Distributed Development

getFailNotify

public int getFailNotify()
The access group ID of the access group to notify about failed builds. 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 a build of this project fails.

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

getLevel

public int getLevel()
The level (access group ID) assigned to this class. Users that are not a direct or indirect member of this access group will not be able to use this project.


getMaxThread

public int getMaxThread()
The maximum number of threaded steps that this project will attempt to run concurrently. The engine will not start processing a step, even if a thread block would include it, if doing so would exceed the limit set by this parameter.

Returns:
the maximum number of concurrent threads that a build of this project may start, or 0 if the number of threads is not restricted at this level

getName

public java.lang.String getName()
The descriptive name of this project, as provided by the user during its creation.


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 a build of this project completes successfully.

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

getPassNotify

public int getPassNotify()
The access group ID of the access group to notify about passed builds. 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 a build of this project completes without any fatal errors.

Returns:
the access group ID access group to be notified if a build of this project completes without any fatal errors, or 0 to disable such e-mails.

getProjectId

public int getProjectId()
The system-generated unique identifier for this project.

Restrictions: This value is provided by the Build Forge system; users can not modify it.

Returns:
the system-generated project ID

getSelectorId

public java.lang.String getSelectorId()
The selector ID of the default selector to be used when building this project.

Returns:
the selector ID, or an empty string if this is a library project

getStartNotify

public int getStartNotify()
The access group ID of the access group to notify about started builds. 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 a build of this project is started. If the build includes the use of an adaptor link, then this notice is not sent until after the adaptor has reported changes.

Returns:
the access group ID access group to be notified hen a build of this project is launched, or 0 to disable such e-mails

getSticky

public boolean getSticky()
Whether or not server assignment is sticky for this project. The sticky flag influences how servers are selected for use by the steps of a project.

The semantics of this flag can be complicated, particularly when it interacts with inlines, chains, and the .bset command. Please refer to these subjects in the Build Forge Management Console's online help system for more information.


getTag

public java.lang.String getTag()
The build tag format used by this project. The value returned is not substituted; that is, it contains the tag variable references, not their substituted values.


getTagSync

public int getTagSync()
The project ID of the project against which this project should synchronize its tag variables. If this project does not synchronize its tag variables against those of another project, then 0 is returned. The exact behavior depends both on the existence of the variable in both projects and its auto-increment setting in both places, as follows:
This ProjectTagSync Project Behavior
UndefinedAny The tag variable is not defined for this project. Its value will not be made available when constructing the build tag.
NormalUndefined The project's tag variable is used as-is
Auto-incrementUndefined The project's tag variable is used as-is, then incremented after the build is started.
NormalNormal This project's tag variable is set to the same value as is set for the TagSync project, then used to construct the build tag. The value in the TagSync project is not changed.
Auto-incNormal This project's tag variable is set to the same value as is set for the TagSync project, used to construct the build tag, then incremented. The value in the TagSync project is not changed.
NormalAuto-inc This project's tag variable is set to the same value as is set for the TagSync project, then used to construct the build tag. The value is then incremented for the TagSync project.
Auto-incAuto-inc This project's tag variable is set to the same value as is set for the TagSync project, used to construct the build tag, then incremented for both projects.


setActive

public void setActive(boolean active)
Changes whether or not the project is active. A project must be active for it to be used to run builds.

Restrictions: Requires a successful update(). The activate and deactivate methods should be considered if this it the only field that the caller is changing.

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

setBuildClass

public void setBuildClass(java.lang.String buildClassName)
Changes the default build class for this project.

Restrictions: Requires a successful update(). The specified build class name must be the name of an existing build class that is accessible to this user.

Parameters:
buildClassName - the name of an existing build class

setEnvironmentId

public void setEnvironmentId(int environmentId)
Sets the project's default build environment's group ID. Builds of this project will be initialized with these settings.

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

Parameters:
environmentId - the environment group ID of the environment to use, or 0 if no project-level environment is desired.

setRunLimit

public void setRunLimit(int newRunLimit)
Sets the number of concurrent builds that are permitted for this project.

Restrictions: Does not take effect until update() is called. The run limit may not be negative.

Parameters:
newRunLimit - the new run limit, or 0 if the number of concurrent builds should not be restricted for this project.

setFailChainId

public void setFailChainId(int newChain)
Sets the project ID to identify the fail chain project. The Build Forge engine will automatically launch a build of the fail chain project if a build of this project fails.

Restrictions: Does not take effect until update() is called. The specified value must be 0 or a valid project ID.

Parameters:
newChain - the project ID of the fail chain project, or 0 if this project will not use a fail chain.

setGeoId

public void setGeoId(java.lang.String newGeoId)
Sets the geographic identifer for use with Globally Distributed Development

Parameters:
newGeoId - the new Geo Id

setFailNotify

public void setFailNotify(int notify)
Sets the access group ID of the access group to notify about failed builds. The behavior of this field is described in detail by its getter.

Restrictions: Does not take effect until update() is called. The specified value must be 0 or the access group ID of a valid access group, of which the user must be a direct or indirect member.

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

setLevel

public void setLevel(int level)
Sets the level (access group ID) assigned to this class. Users that are not a direct or indirect member of this access group will not be able to use this project.

Restrictions: Does not take effect until update() is called. The specified value must be the access group ID of a valid access group of which the user must be a direct or indirect member.


setMaxThread

public void setMaxThread(int maxThread)
Sets the maximum number of threaded steps that this project will attempt to run concurrently. The engine will not start processing a step, even if a thread block would include it, if doing so would exceed the limit set by this parameter.

Restrictions: Does not take effect until update() is called. The specified value may not be negative.

Parameters:
maxThread - the maximum number of concurrent threads that a build of this project may start, or 0 if the number of threads is not to be restricted at this level

setName

public void setName(java.lang.String name)
Changes the descriptive name of this project.

Restrictions: Does not take effect until update() is called. The value may not be null or blank, and it must be unique.

Parameters:
name - the new descriptive name for this project

setPassChainId

public void setPassChainId(int newChain)
Sets the project ID to identify the pass chain project. The Build Forge engine will automatically launch a build of the pass chain project if a build of this project completes successfully.

Restrictions: Does not take effect until update() is called. The specified value must be 0 or a valid project ID.

Parameters:
newChain - the project ID of the pass chain project, or 0 if this project will not use a pass chain.

setPassNotify

public void setPassNotify(int notify)
Sets the access group ID of the access group to notify about passed builds. The behavior of this field is described in detail by its getter.

Restrictions: Does not take effect until update() is called. The specified value must be 0 or the access group ID of a valid access group, of which the user must be a direct or indirect member.

Parameters:
notify - the access group ID access group to be notified if a build of this project completes without fatal errors, or 0 to disable such e-mails.

setSelectorId

public void setSelectorId(java.lang.String selectorId)
Sets the selector ID of the default selector to be used when building this project.

Restrictions: Does not take effect until update() is called. If set to a non-empty string, then it must be a valid selector ID for a selector to which this user has access.


setStartNotify

public void setStartNotify(int notify)
Sets the access group ID of the access group to notify about started builds. 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 a build of this project is started. If the build includes the use of an adaptor link, then this notice is not sent until after the adaptor has reported changes.

Restrictions: Does not take effect until update() is called. The specified value must be 0 or the access group ID of a valid access group, of which the user must be a direct or indirect member.

Parameters:
notify - the access group ID access group to be notified hen a build of this project is launched, or 0 to disable such e-mails

setSticky

public void setSticky(boolean sticky)
Sets whether or not server assignment is sticky for this project. The sticky flag influences how servers are selected for use by the steps of a project.

The semantics of this flag can be complicated, particularly when it interacts with inlines, chains, and the .bset command. Please refer to these subjects in the Build Forge Management Console's online help system for more information.

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


setTag

public void setTag(java.lang.String tag)
Sets the build tag format used by this project. The value may contain tag variable refences in the form $VAR or ${VAR}. These values are substituted by Build Forge before the build is started, so there is no need to worry about differences between Unix and Windows shells. References to tag variables that do not exist are replaced with the tag variable name itself.

If the tag format does not include auto-increment tag variables, then multiple builds with the same tag may result, which is an inadvisable configuration. If the builds have the same tag, then it will be more difficult to distinguish them visually in the Management Console. Further, since they share the same same build directory when run on the same server, purging one build could remove the files of another build, possibly even while it is running. While permitted, any such configuration is strongly discouraged.

Restrictions: Does not take effect until update() is called. The tag format may not be set to null or an empty string.


setTagSync

public void setTagSync(int tagSync)
Sets the project ID of the project against which this project should synchronize its tag variables. If tag variable synchronization is not desired, the value 0 may be used. The exact behavior depends both on the existence of the variable in both projects and its auto-increment setting in both places, as described in the getter for this field.

Restrictions: Does not take effect until update() is called. The value must be 0 or the project ID of an existing project to which the user has access.


getSteps

public java.util.List<Step> getSteps()
Retrieves a list of the steps that are defined for this project.

Restrictions: The step list and/or the details of certain steps may not always be available.

Returns:
a list of project steps, or null if that information is not available, as described above

getStep

public Step getStep(java.lang.String stepUid)
Retrieves a step by its system-generated unique identifier.

Restrictions: As for getSteps().

Parameters:
stepUid - the unique identifier of the step to retrieve.
Returns:
the step, or null if the step is not found

getStep

public Step getStep(int index)
Retrieves a step by index.

Parameters:
index - the 0-based index of the step within the project's step list.
Returns:
the step, or null if the specified index is out-of-bounds

addStep

public void addStep(Step newStep)
             throws java.io.IOException,
                    ServiceException
Adds a new step to this project's step list. The step is added at the end of the current list of steps.

Restrictions (enforced for live projects only): Requires Permission.AddProjectStep and direct or indirect membership in the step's access group.

Parameters:
newStep - the new step to add
Throws:
java.io.IOException
ServiceException

addStep

public void addStep(Step newStep,
                    int index)
             throws java.io.IOException,
                    ServiceException
Adds a new step object to this project at the specified, index into the current list of steps.

Restrictions: As for addStep(Step)

Parameters:
newStep - the new step to add
index - the 0-based index at which to add the step. If the specified index is at or beyond the end of the list, then the new step is added at the end.
Throws:
java.io.IOException
ServiceException

moveStep

public void moveStep(int fromIndex,
                     int toIndex)
              throws java.io.IOException,
                     ServiceException
Moves an existing step to a new location in the step list.

Restrictions (enforced for live projects only): Requires Permission.MoveProjectStep and direct or indirect membership in the step's access group.

Parameters:
fromIndex - The original 0-based index of the step
toIndex - The new 0-based index for the step. If the specified value is the same as the fromIndex, then no changes are made. If toIndex is large enough to place the step past the end of the list, then it is moved to the end.
Throws:
java.io.IOException
ServiceException

copyStep

public void copyStep(int fromIndex,
                     int toIndex)
              throws java.io.IOException,
                     ServiceException
Makes a copy of an existing step at a new location in the step list.

Restrictions: As for addStep(Step).

Parameters:
fromIndex - The original 0-based index of the step
toIndex - The new 0-based index for the step. If toIndex is large enough to place the step past the end of the list, then it is placed at the end.
Throws:
java.io.IOException
ServiceException

removeStep

public void removeStep(int index)
                throws java.io.IOException,
                       ServiceException
Removes the specified step from this project and deletes it.

Restrictions (enforced for live projects only): Requires Permission.DeleteProjectStep and direct or indirect membership in the access group that is assigned to the step.

Parameters:
index - the 0-based index of the step to delete
Throws:
java.io.IOException
ServiceException

removeStep

public void removeStep(java.lang.String stepUid)
                throws java.io.IOException,
                       ServiceException
Removes the specified step from this project and deletes it.

Restrictions: as for removeStep(int).

Parameters:
stepUid - the unique identifier of the step to remove
Throws:
java.io.IOException
ServiceException