NAME

BuildForge::Services::DBO::Cron


SYNOPSIS

        use BuildForge::Services;
        $conn = new BuildForge::Services::Connection($hostname);
        $token = $conn->authUser($user, $pass);
        
        # Getting existing schedules
        $allCrons = BuildForge::Services::DBO::Cron->findAll($conn);
        $oldCron = BuildForge::Services::DBO::Cron->findById($conn, 2);
        $anotherCron = BuildForge::Services::DBO::Cron->findByName($conn, 'MyCron');
        # Getter / setter functions
        $id = $cron->getCronId();
        $isActive = $cron->getActive();
        $class = $cron->getBuildClass();
        $description = $cron->getDescription();
        $owner = $cron->getOwnerId();
        $projectId = $cron->getProjectId();
        $selectorId = $cron->getSelectorId();
        $minute = $cron->getMinute();
        $hour = $cron->getHour();
        $dow = $cron->getDayOfWeek();
        $month = $cron->getMonth();
        $dom = $cron->getDayOfMonth();
        $envGroupId = $cron->getEnvironmentGroupId();
        $envGroupId = $cron->getEnvGroupId();
        $envText = $cron->getEnvironmentText();
        $envText = $cron->getEnvText();
        $lastFiredTimestamp = $cron->getFired();
        $nextFiredTimestamp = $cron->getNextRun();
        
        $cron->setActive('YES');
        $cron->setBuildClass('ClassName');
        $cron->setDescription('Schedule Description');
        $cron->setProjectId($projectId);
        $cron->setSelectorId($selectorId);
        $cron->setMinute('5');
        $cron->setHour('*');
        $cron->setDayOfWeek('1-5');
        $cron->setMonth('*/2');
        $cron->setDayOfMonth('1-6/3,29');
        $cron->setEnvironmentGroupId($envGroupId);
        $cron->setEnvGroupId($envGroupId);
        $cron->setEnvText($envText);
        $cron->setEnvironmentText($envText);
        $cron->update();
        
        # Schedule creation, modification, deletion
        $project = new BuildForge::Services::DBO::Project($conn);
        $project->setName('Test Project');
        $project->create();
        
        $newcron = new BuildForge::Services::DBO::Cron($conn);
        $newcron->setDescription('New Cron');
        $newcron->setProjectId($project->getProjectId());
        $newcron->create();
        $newcron->setDescription('New Cron Description');       
        $newcron->update();
        
        $newcron->activate();
        $newcron->oneShot();
        $newcron->deactivate();
        $newcron->delete();
        BuildForge::Services::DBO::Cron->deleteById($conn, $cron->getCronId());
                
        $conn->logout;
        $conn->close;


DESCRIPTION

Cron allows you to create, modify, and delete schedules in the BuildForge engine.


METHODS

new BuildForge::Services::DBO::Cron(connection, {CronParamsHashRef})

Returns a new instance of a Cron object.

connection

A connected BuildForge::Services::Connection object.

CronParamsHashRef

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

active

Whether the schedule is active ('YES', the default), inactive ('NO'), or run once only ('ONCE').

buildClass

The class of the build that is run via the schedule, gotten from $class->getName(). If this is left unset or set to an empty string, the class of the scheduled project is used. If this is a class purge schedule, a class must be set.

description

The description of the schedule.

projectId

The project ID of the project to run (from $project->getProjectId()), or 0 to make this a class purge schedule (the default).

selectorId

The selector ID of the selector (from $selector->getSelectorId()) to run the scheduled build with. If this is 0 or is not set, the build uses the selector of the project being scheduled. If this is a class purge schedule, this value is ignored.

minute

The minute(s) at which to run this schedule in crontab format. Defaults to '0'.

hour

The hour(s) at which to run this schedule in crontab format. Defaults to '0'.

dayOfWeek

The day(s) of the week in which to run this schedule in crontab format. Defaults to '*'.

month

The month(s) in which to run this schedule in crontab format. Defaults to '*'.

dayOfMonth

The day(s) of the month in which to run this schedule in crontab format. Defaults to '*'.

environmentGroupId

The environment group ID (from $environment->getEnvironmentGroupId()) to run the scheduled builds with. The project's environment group is also applied - first the project's environment group, then the schedule's environment group, so that the schedule's settings override the project's settings if necessary. Set this to 0 (the default) for no schedule-specific environment group to be used.

environmentText

In order to set variables specifically in the schedule rather than in the environment group, set this to a string consisting of newline-delimited S:VARIABLE_NAME:New variable value strings. This is the empty string by default.

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

Returns a reference to an array of BuildForge::Services::DBO::Cron objects corresponding to all schedules in the database that the user has access to.

connection

A connected BuildForge::Services::Connection object.

BuildForge::Services::DBO::Cron->findById(connection, cronId)

Returns the BuildForge::Services::DBO::Cron object corresponding to the given schedule ID, or undef if no such object exists.

connection

A connected BuildForge::Services::Connection object.

cronId

The schedule ID for the desired schedule, from $cron->getCronId().

BuildForge::Services::DBO::Cron->findByName(connection, cronName)

Returns the BuildForge::Services::DBO::Cron object corresponding to the given description, or undef if no such object exists.

connection

A connected BuildForge::Services::Connection object.

cronId

The schedule description for the desired schedule, from $cron->getDescription().

$cron->create()

Creates the cron object within the database.

$cron->update()

Updates the database cron object with the current object settings.

$cron->activate()

Activates the schedule within the database.

$cron->oneShot()

Makes the schedule within the database a run once schedule.

$cron->deactivate()

Deactivates the schedule within the database.

$cron->delete()

Deletes the schedule from the database.

BuildForge::Services::DBO::Cron->deleteById(connection, cronId)

Deletes the schedule with the given ID from the database.

connection

A connected BuildForge::Services::Connection object.

cronId

The schedule ID (from $cron->getCronId()) to delete.

$cron->getCronId()

Returns the ID of the schedule.

$cron->getActive()

Returns 'YES' if this is an active schedule, 'NO' if this is an inactive schedule, or 'ONCE' if this is a run once schedule.

$cron->getBuildClass()

Returns the class of the build being scheduled or '' to use the class of the scheduled project for project schedules or the class of build to purge for class purge schedules.

$cron->getDescription()

Returns the description of the schedule.

$cron->getOwnerId()

Returns the user ID of the owner of the schedule. Builds kicked off by the schedule will run as if they had been run by that user.

$cron->getProjectId()

Returns the project ID of the project that the schedule will create a build of, or 0 for class purge schedules.

$cron->getSelectorId()

Returns the selector ID of the selector that builds from this schedule will use. An empty string will cause the builds to use the scheduled project's selector.

$cron->getMinute()

Returns the crontab string for the minute(s) in which the schedule will run.

$cron->getHour()

Returns the crontab string for the hour(s) in which the schedule will run.

$cron->getDayOfWeek()

Returns the crontab string for the day(s) of the week in which the schedule will run.

$cron->getMonth()

Returns the crontab string for the month(s) in which the schedule will run.

$cron->getDayOfMonth()

Returns the crontab string for the day(s) of the month in which the schedule will run.

$cron->getEnvironmentGroupId()

Returns the environment group ID for the environment that the schedule will use. The project's environment group is also applied - first the project's environment group, then the schedule's environment group, so that the schedule's settings override the project's settings if necessary.

$cron->getEnvGroupId()

An alias for $cron->getEnvironmentGroupId(). Returns the environment group ID for the environment that the schedule will use. The project's environment group is also applied - first the project's environment group, then the schedule's environment group, so that the schedule's settings override the project's settings if necessary.

$cron->getEnvironmentText()

Returns the text of the schedule's specific environment. If this is used, it'll consist of a string with newline-delimited S:VARIABLE_NAME:New variable value strings.

$cron->getEnvText()

An alias for $cron->getEnvironmentText(). Returns the text of the schedule's specific environment. If this is used, it'll consist of a string with newline-delimited S:VARIABLE_NAME:New variable value strings.

$cron->getFired()

Returns the timestamp for the time that the scheduled build was last kicked off.

$cron->getNextRun()

Returns the timestamp for the time that the scheduled build will next be kicked off. This may take 15 seconds or so to update from the time that schedule settings are changed. A value of 0 means that the next run time has not yet been calculated, -1 means that one or more of the date / time fields have invalid values, and -2 means that the date / time will never be matched - for example, if $cron->getMonth() == 2 and $cron->getDayOfMonth() == 31.

$cron->setActive(active)

Sets whether the schedule is active, inactive, or run once. $cron->update() must be run before changes are replicated in the database.

active

May be 'YES' for active, 'NO' for inactive, or 'ONCE' for run once.

$cron->setBuildClass(className)

Sets the class of builds kicked off by this schedule for project schedules or the class of builds to be purged for class purge schedules. $cron->update() must be run before changes are replicated in the database.

className

The name/ID of the class (from $class->getName()), or '' to use the class of the project being kicked off. This cannot be set to '' for class purge schedules.

$cron->setDescription(desc)

Sets the description of the schedule. $cron->update() must be run before changes are replicated in the database.

desc

The new schedule description.

$cron->setProjectId(projectId)

Sets the project ID of the project to be kicked off by the schedule or makes this a class purge schedule. $cron->update() must be run before changes are replicated in the database.

projectId

The project ID for project schedules (from $project->getProjectId()), or 0 to make this a class purge schedule.

$cron->setSelectorId(selectorId)

Sets the selector that the kicked off builds will use. This setting is ignored for class purge schedules. $cron->update() must be run before changes are replicated in the database.

selectorId

The selector ID to use (from $selector->getSelectorId()), or '' to use the selector of the project being scheduled.

$cron->setMinute(minute)

Sets the minute(s) in which to run this schedule. $cron->update() must be run before changes are replicated in the database.

minute

The minute in which to run this schedule in crontab format.

$cron->setHour(hour)

Sets the hour(s) in which to run this schedule. $cron->update() must be run before changes are replicated in the database.

hour

The hour in which to run this schedule in crontab format.

$cron->setDayOfWeek(dow)

Sets the day(s) of the week in which to run this schedule. $cron->update() must be run before changes are replicated in the database.

dow

The day(s) of the week in which to run this schedule in crontab format.

$cron->setMonth(month)

Sets the month(s) in which to run this schedule. $cron->update() must be run before changes are replicated in the database.

month

The month(s) in which to run this schedule in crontab format.

$cron->setDayOfMonth(dom)

Sets the day(s) of the month in which to run this schedule. $cron->update() must be run before changes are replicated in the database.

dom

The day(s) of the month in which to run this schedule in crontab format.

$cron->setEnvironmentGroupId(envGroupId)

Sets the environment group that the kicked off build will use. The project's environment group is also applied - first the project's environment group, then the schedule's environment group, so that the schedule's settings override the project's settings if necessary. $cron->update() must be run before changes are replicated in the database.

envGroupId

The ID of the environment group to use (from $environment->getEnvGroupId()), or 0 to not use a schedule-specific environment group.

$cron->setEnvGroupId(envGroupId)

An alias for $cron->setEnvironmentGroupId(envGroupId). Sets the environment group that the kicked off build will use. The project's environment group is also applied - first the project's environment group, then the schedule's environment group, so that the schedule's settings override the project's settings if necessary. $cron->update() must be run before changes are replicated in the database.

envGroupId

The ID of the environment group to use (from $environment->getEnvGroupId()), or 0 to not use a schedule-specific environment group.

$cron->setEnvironmentText(envText)

Sets the schedule-specifc environment text of the schedule, if having a schedule-specific environment is not desired. $cron->update() must be run before changes are replicated in the database.

envText

Set this to '' to use the environment group from $cron->getEnvironmentGroupId()). In order to set variables specifically in the schedule rather than in the environment group, set this to a string consisting of newline-delimited S:VARIABLE_NAME:New variable value strings.

$cron->setEnvText(envText)

An alias for $cron->setEnvironmentText(envText). Sets the schedule-specifc environment text of the schedule, if having a schedule-specific environment is not desired. $cron->update() must be run before changes are replicated in the database.

envText

Set this to '' to use the environment group from $cron->getEnvironmentGroupId()). In order to set variables specifically in the schedule rather than in the environment group, set this to a string consisting of newline-delimited S:VARIABLE_NAME:New variable value strings.


COPYRIGHT

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