NAME

BuildForge::Services::DBO::Project


SYNOPSIS

        use BuildForge::Services;
        $conn = new BuildForge::Services::Connection($hostname);
        $token = $conn->authUser($user, $pass);
        
        # Getting existing projects
        $allProjects = BuildForge::Services::DBO::Project->findAll($conn);
        $oldproject = BuildForge::Services::DBO::Project->findById($conn, $pid);
        $oldproject2 = BuildForge::Services::DBO::Project->findByName($conn, 'MyProject');
        # Getter / setter functions
        $id = $oldproject->getProjectId();
        $name = $oldproject->getName();
        $isActive = $oldproject->getActive();
        $class = $oldproject->getBuildClass();
        $envId = $oldproject->getEnvironmentId();
        $maxRuns = $oldproject->getRunLimit();
        $accessGroupId = $oldproject->getLevel();
        $maxThreads = $oldproject->getMaxThread();
        $selectorId = $oldproject->getSelectorId();
        $isSticky = $oldproject->getSticky();
        $tagFormat = $oldproject->getTag();
        $tagSyncProjectId = $oldproject->getTagSync();
        $startNotifyAccessGroupId = $oldproject->getStartNotify();
        $failNotifyAccessGroupId = $oldproject->getFailNotify();
        $passNotifyAccessGroupId = $oldproject->getPassNotify();
        $allSteps = $oldproject->getSteps();
        $step1 = $oldproject->getStep(2);
        $step2 = $oldproject->getStep($stepUID);
        $allProjectBuilds = $oldproject->getBuilds();
        $isProjectInUseByOtherObjects = $oldproject->inUse();
        $passChainId = $oldproject->getPassChain();
        $failChainId = $oldproject->getFailChain();
        $geoId = $oldproject->getGeoId();
        
        $oldproject->setName('New Project Name');
        $oldproject->setActive(1);
        $oldproject->setBuildClass('ClassName');
        $oldproject->setEnvironmentId($envId);
        $oldproject->setRunLimit(5);
        $oldproject->setLevel($accessGroupId);
        $oldproject->setMaxThread(10);
        $oldproject->setSelectorId('SelectorName');
        $oldproject->setSticky(1);
        $oldproject->setTag('BF_$B');
        $oldproject->setTagSync($pid);
        $oldproject->setStartNotify($accessGroupId);
        $oldproject->setFailNotify($accessGroupId);
        $oldproject->setPassNotify($accessGroupId);
        $oldproject->setPassChain($projectId);
        $oldproject->setFailChain($projectId);
        $oldproject->setGeoId($geoId);
        $oldproject->update();
        
        # Project creation, updating, deletion
        $newproject = new BuildForge::Services::DBO::Project($conn);
        $newproject->setName('New Build Project');
        $newproject->setBuildClass('ClassName');
        $newproject->setLevel($accessGroupId);
        $newproject->create();
        
        $newproject2 = $newproject->clone();
        $newproject->setName('Duplicate');
        $newproject2->create();
        $newproject->setName('Different Name');
        $newproject->update();
        
        $newproject->deactivate();
        $newproject->activate();
        
        $step = new BuildForge::Services::DBO::Step($conn);
        $step->setDescription('Step Name');
        $step->setCommandText('echo hi');
        $newproject->addStep($step);
        $newproject->copyStep(0, 1);
        $newproject->moveStep(1, 0);
        $newproject->removeStep(1);
        $newproject->removeStep($step->getUid());
        $newproject->removeStep($step);
        
        $oldproject->delete();
        $newproject->clobber();
                
        $conn->logout;
        $conn->close;


DESCRIPTION

Project allows you to create, access, and delete BuildForge Project projects.


METHODS

new BuildForge::Services::DBO::Project(connection, {ProjectParamsHashRef})

Returns a new instance of a Project object.

connection

A connected BuildForge::Services::Connection object.

ProjectParamsHashRef

An optional reference to a hash containing any or all of the following fields.

description

The name of the project.

level

The access group ID (from $accessGroup->getLevel()) of the access group this project belongs to. Users not in the class can not view, edit, or use this project.

buildClass

The class ID (from $class->getName()) of the class that new builds of the project belong to by default.

selectorId

The selector ID (from $selector->getSelectorId()) of the selector that new builds of the project belong to by default. If this is left blank, the project is actually a library and will appear in that section of the GUI.

tag

The tag format for builds of this project. By default, this is set to 'BUILD_$B'.

environmentId

The environment ID (from $envGroup->getEnvGroupId()) for the environment group that is applied to builds of this project.

active

When this evaluates to true, the project is active (the default). When this evaluates to false, the project is inactive and cannot be executed until it is activated.

startNotify

The access group ID (from $accessGroup->getLevel()) for the access group which gets notified when a build of the project is kicked off. Set this to 0 (the default) to have no such notification sent.

passNotify

The access group ID (from $accessGroup->getLevel()) for the access group which gets notified when a build of the project completes successfully. Set this to 0 (the default) to have no such notification sent.

failNotify

The access group ID (from $accessGroup->getLevel()) for the access group which gets notified when a build of the project fails. Set this to 0 (the default) to have no such notification sent.

maxThread

The maximum number of threaded steps the project is allowed to start simultaneously. The default value of 0 allows unlimited threads to be run.

runLimit

The maximum number of simultaneous builds of this project allowed to be running. The default value of 0 allows unlimited concurrent builds.

tagSync

The project ID (from $project->getProjectId()) of the project this project is tag synced to (or 0, the default, for no tag syncing). Normally, auto-increment tag variables increase whenever a build of a project starts up. When project A is tag synced to project B, however, if a build of either project A _or_ project B occurs, any tag variables that they share that are auto-increment increase.

sticky

If this evaluates to true, steps that use the project default selector will all run on the same server. If this evaluates to false (the default), each such step will be chosen from the available servers in the project selector, and so may or may not use the same servers.

passChainId

The project ID (from $project->getProjectId()) of a project to get kicked off if a build of this project completes successfully. If this is set to 0 (the default), no project gets kicked off.

failChainId

The project ID (from $project->getProjectId()) of a project to get kicked off if a build of this project fails. If this is set to 0 (the default), no project gets kicked off.

geoId

For GDD-aware projects only, this is the geo ID of the console on which the project runs by default. If this is set to the empty string (the default), it assumes the system is a non-GDD-aware system.

BuildForge::Services::DBO::Project->findAll(connection)

Returns a reference to an array of BuildForge::Services::DBO::Project objects corresponding to all projects in the database that the user has access to. These objects will not contain their Step subobjects. To get the steps, use BuildForge::Services::DBO::Project->findById() or findByName() with the project's ID/name.

connection

A connected BuildForge::Services::Connection object.

BuildForge::Services::DBO::Project->findById(connection, projectId)

Returns the BuildForge::Services::DBO::Project object corresponding to the given projectId, or undef if no such project exists.

connection

A connected BuildForge::Services::Connection object.

projectId

The ID of the desired project (from $project->getProjectId()).

BuildForge::Services::DBO::Project->findByName(connection, projectName)

Returns the BuildForge::Services::DBO::Project object corresponding to the given project name, or undef if no such project exists.

connection

A connected BuildForge::Services::Connection object.

projectId

The name of the desired project (from $project->getName()).

$project->create()

Creates an entry for the project in the database with the current object settings.

$project->clone()

Returns a BuildForge::Services::DBO::Project object that is a copy of the current project. The new project copy will not exist in the database unless created with $copy->create().

$project->update()

Updates the database with the current project settings.

$project->addStep(step, index)

Adds a step to the project in the database.

step

The BuildForge::Services::DBO::Step object to be added to the project.

index

The optional location at which to add the new step. 0 makes the step the first step, 1 makes it the second, etc. If left unset, the step is added at the end of the step list.

$project->moveStep(from, to)

Moves a step within the step list.

from

The index of the step to be moved. 0 moves the first step, 1 the second step, etc.

to

The index of the location to move the step to. 0 makes it the first step, 1 the second step, etc.

$project->copyStep(from, to)

Copies a step within the step list.

from

The index of the step to be copied. 0 copies the first step, 1 the second step, etc.

to

The index of the location to copy the step to. 0 makes the copy the first step, 1 the second step, etc.

$project->removeStep(step)

Removes a step from the step list.

step

This may either be the index of the step to be deleted (0 to delete the first step, 1 the second, etc.), the step ID of the step to be deleted (from $step->getUid()), or the BuildForge::Services::DBO::Step to be removed.

$project->activate()

Activates the project within the database.

$project->deactivate()

Deactivates the project within the database. Deactivated projects cannot be run until they are activated.

$project->delete()

Deletes the project from the database. This will only work if there are no current builds of the project existing in the database.

$project->clobber()

Starts a clobber project action. After it is called, the engine will clobber the project by deleting it and all its project from the database when all builds of the project are complete and when the engine has resources available to do so. The function will return when the clobbering has been readied to occur - it may be some time after that before the project is actually clobbered.

$project->getProjectId()

Returns the ID of the project.

$project->getName()

Returns the name of the project.

$project->getActive()

Returns 1 if the project is active or 0 if it is inactive.

$project->getBuildClass()

Returns the class ID (from $class->getName()) of the class that new builds of the project belong to by default.

$project->getEnvironmentId()

Returns the environment ID (from $envGroup->getEnvGroupId()) for the environment group that is applied to builds of this project, or 0 if no environment is assigned.

$project->getRunLimit()

Returns the maximum number of simultaneous builds of this project allowed to be running. The default value of 0 allows unlimited concurrent builds.

$project->getLevel()

Returns the access group ID (from $accessGroup->getLevel()) of the access group this project belongs to. Users not in the class can not view, edit, or use this project.

$project->getMaxThread()

Returns the maximum number of threaded steps the project is allowed to start simultaneously. The default value of 0 allows unlimited threads to be run.

$project->getSelectorId()

Returns the selector ID (from $selector->getSelectorId()) of the selector that new builds of the project belong to by default. If this is an empty string, the project is actually a library and will appear in that section of the GUI.

$project->getSticky()

If this returns 1, steps that use the project default selector will all run on the same server. If this returns 0, each such step will be chosen from the available servers in the project selector, and so may or may not use the same servers.

$project->getTag()

Returns the tag format for builds of this project.

$project->getTagSync()

Returns the project ID (from $project->getProjectId()) of the project this project is tag synced to (or 0 for no tag syncing). Normally, auto-increment tag variables increase whenever a build of a project starts up. When project A is tag synced to project B, however, if a build of either project A _or_ project B occurs, any tag variables that they share that are auto-increment increase.

$project->getStartNotify()

Returns the access group ID (from $accessGroup->getLevel()) for the access group which gets notified when a build of the project is kicked off or 0 if no such notification is sent.

$project->getPassNotify()

Returns the access group ID (from $accessGroup->getLevel()) for the access group which gets notified when a build of the project completes successfully or 0 if no such notification is sent.

$project->getFailNotify()

Returns the access group ID (from $accessGroup->getLevel()) for the access group which gets notified when a build of the project fails or 0 if no such notification is sent.

$project->getPassChain()

Returns the project ID (from $project->getProjectId()) of a project to get kicked off if a build of this project completes successfully or 0 if no such project is kicked off.

$project->getFailChain()

Returns the project ID (from $project->getProjectId()) of a project to get kicked off if a build of this project fails or 0 if no such project is kicked off.

$project->getGeoId()

This returns the geo ID of the console on which the project runs by default. It returns the empty string for non-GDD-aware projects.

$project->getSteps()

Returns a reference to an array of BuildForge::Services::DBO::Step objects for all the steps in the project.

$project->getStep(step)

Returns the BuildForge::Services::DBO::Step object for the requested step.

step

This may either be the index of the step to be returned (0 for the first step, 1 the second, etc.), or the step's step ID (from $step->getUid()).

$project->getBuilds()

Returns a reference to an array of BuildForge::Services::DBO::Build objects for all builds of the project.

$project->inUse()

If the project is linked to by other objects (for example, if a class is set to kick off this project when builds of the class are purged), returns 'YES', indicating that it cannot be deleted. If the project is not being linked by other objects, but another project or step does chain the project, returns 'CHAIN'. Otherwise, returns 'NO'.

$project->setName(projectName)

Sets the name of the project. $project->update() must be run before changes are replicated in the database.

projectName

The new project name.

$project->setActive(isActive)

Sets whether or not the project is active. If it is inactive, it cannot be executed until it is activated. $project->update() must be run before changes are replicated in the database.

isActive

The project becomes active if this evaluates to true or inactive if this evaluates to false.

$project->setBuildClass(className)

Sets the class that new builds of the project belong to by default. $project->update() must be run before changes are replicated in the database.

className

The class ID (from $class->getName()).

$project->setEnvironmentId(envGroupId)

Sets the environment group that is applied to builds of this project. $project->update() must be run before changes are replicated in the database.

envGroupId

The environment group ID (from $envGroup->getEnvGroupId()).

$project->setRunLimit(runLimit)

Sets the maximum number of simultaneous builds of this project allowed to be running. $project->update() must be run before changes are replicated in the database.

runLimit

The number of allowed builds. Setting it to 0 allows unlimited concurrent builds.

$project->setLevel(accessGroupId)

Sets the access group this project belongs to. Users not in the class can not view, edit, or use this project. $project->update() must be run before changes are replicated in the database.

accessGroupId

The access group ID (from $accessGroup->getLevel()).

$project->setMaxThread(maxThreads)

Sets the maximum number of threaded steps the project is allowed to start simultaneously. $project->update() must be run before changes are replicated in the database.

maxThreads

The maximum number of threads. Setting it to 0 allows unlimited threads to be run.

$project->setSelectorId(selectorId)

Sets the selector that new builds of the project belong to by default. $project->update() must be run before changes are replicated in the database.

selectorId

The selector ID (from $selector->getSelectorId()). If this is set to 0, the project is actually a library and will appear in that section of the GUI.

$project->setSticky(isSticky)

Sets whether or not the project is sticky. If it is sticky, steps that use the project default selector will all run on the same server. If not, each such step will be chosen from the available servers in the project selector, and so may or may not use the same servers. $project->update() must be run before changes are replicated in the database.

isSticky

The project becomes sticky if this evaluates to true and unsticky if this evaluates to false.

$project->setTag(tagFormat)

Sets the tag format for builds of this project. $project->update() must be run before changes are replicated in the database.

tagFormat

The new tag format.

$project->setTagSync(projectId)

Sets the project this project is tag synced to (or 0, the default, for no tag syncing). Normally, auto-increment tag variables increase whenever a build of a project starts up. When project A is tag synced to project B, however, if a build of either project A _or_ project B occurs, any tag variables that they share that are auto-increment increase. $project->update() must be run before changes are replicated in the database.

projectId

The project ID (from $project->getProjectId()) of the synced project.

$project->setStartNotify(accessGroupId)

Sets the access group which gets notified when a build of the project is kicked off. $project->update() must be run before changes are replicated in the database.

accessGroupId

The access group ID (from $accessGroup->getLevel()), or 0 to have no such notification sent.

$project->setPassNotify(accessGroupId)

Sets the access group which gets notified when a build of the project completes successfully. $project->update() must be run before changes are replicated in the database.

accessGroupId

The access group ID (from $accessGroup->getLevel()), or 0 to have no such notification sent.

$project->setFailNotify(accessGroupId)

Sets the access group which gets notified when a build of the project fails. $project->update() must be run before changes are replicated in the database.

accessGroupId

The access group ID (from $accessGroup->getLevel()), or 0 to have no such notification sent.

$project->setPassChain(projectId)

Sets the project to get kicked off if a build of this project completes successfully. $project->update() must be run before changes are replicated in the database.

projectId

The project ID (from $project->getProjectId()) to be started, or 0 for no project to get started.

$project->setFailChain(projectId)

Sets the project to get kicked off if a build of this project fails. $project->update() must be run before changes are replicated in the database.

projectId

The project ID (from $project->getProjectId()) to be started, or 0 for no project to get started.

$project->setGeoId(geoId)

For GDD-aware projects only, this sets the geo ID of the console on which the project runs by default. $project->update() must be run before changes are replicated in the database.

geoId

The ID of the console to use. If this is set to the empty string, it assumes the system is a non-GDD-aware system.


COPYRIGHT

Copyright (c)2006-2007 International Business Machines, Inc. All rights reserved.