Perforce Chronicle 2012.2/486814
API Documentation
Public Member Functions | Static Public Member Functions | Public Attributes | Protected Member Functions | Static Protected Member Functions | Static Protected Attributes

P4_Job Class Reference

Abstracts operations against Perforce jobs. More...

Inheritance diagram for P4_Job:
P4_Spec_PluralAbstract P4_SpecAbstract P4_ModelAbstract P4_ConnectedAbstract P4_ModelInterface P4_ConnectedInterface

List of all members.

Public Member Functions

 getDate ()
 Returns the date this job was created.
 getDescription ()
 Returns the description for this job.
 getStatus ()
 Returns the status of this job.
 getUser ()
 Returns the user who created this job.
 getValue ($field)
 Get field value.
 save ()
 Override parent to set id to 'new' if unset and capture id returned by save.
 setDescription ($description)
 Update the decription for this job.
 setStatus ($status)
 Update the status of this job.
 setUser ($user)
 Update the user who created this job.
 setValue ($field, $value)
 Set field value.

Static Public Member Functions

static exists ($id, P4_Connection_Interface $connection=null)
 Determine if the given job id exists.
static fetchAll ($options=array(), P4_Connection_Interface $connection=null)
 Get all Jobs from Perforce.

Public Attributes

const FETCH_BY_FILTER = 'filter'
const FETCH_DESCRIPTION = 'descriptions'

Protected Member Functions

 _fieldCodeToName ($code)
 Given a field code this function will return the associated field name.
 _fieldNameToCode ($name)
 Given a field name this function will return the associated field code.

Static Protected Member Functions

static _fromSpecListEntry ($listEntry, $flags, P4_Connection_Interface $connection)
 Extends parent to control description inclusion based on FETCH options.
static _getFetchAllFlags ($options)
 Produce set of flags for the spec list command, given fetch all options array.
static _isValidId ($id)
 Check if the given id is in a valid format for this spec type.

Static Protected Attributes

static $_accessors
static $_idField = 'Job'
static $_mutators
static $_specType = 'job'

Detailed Description

Abstracts operations against Perforce jobs.

License:
Please see LICENSE.txt in top-level folder of this distribution.
Version:
2012.2/486814

Member Function Documentation

P4_Job::_fieldCodeToName ( $  code) [protected]

Given a field code this function will return the associated field name.

Parameters:
int | string$codeInt or string representing value between 101-199 inclusive.
Returns:
string The field name associated with the passed code
Exceptions:
InvalidArgumentExceptionIf passed an invalid or non-existent field code 
    {
        // if we are passed a string, and casting through int doesn't change it,
        // it is purely numeric, cast to an int.
        if (is_string($code) &&
            $code === (string)(int)$code) {
            $code = (int)$code;
        }

        // if we made it this far, fail unless we have an int
        if (!is_int($code)) {
            throw new InvalidArgumentException('Field must be a purely numeric string or int.');
        }

        // job spec defines this is the valid range for field id's
        if ($code < 101 || $code > 199) {
            throw new InvalidArgumentException('Field code must be between 101 and 199 inclusive.');
        }

        $fields = $this->getSpecDefinition()->getFields();

        foreach ($fields as $name => $field) {
            if ($field['code'] == $code) {
                return $name;
            }
        }

        throw new InvalidArgumentException('Specified field code does not exist.');
    }
P4_Job::_fieldNameToCode ( $  name) [protected]

Given a field name this function will return the associated field code.

Parameters:
string$nameString representing the field's name.
Returns:
int The field code associated with the passed name. 
    {
        $field = $this->getSpecDefinition()->getField($name);

        return (int) $field['code'];
    }
static P4_Job::_fromSpecListEntry ( $  listEntry,
$  flags,
P4_Connection_Interface $  connection 
) [static, protected]

Extends parent to control description inclusion based on FETCH options.

Parameters:
array$listEntrya single spec entry from spec list output.
array$flagsthe flags that were used for this 'fetchAll' run.
P4_Connection_Interface$connectiona specific connection to use.
Returns:
P4_Job a (partially) populated instance of this spec class.

Reimplemented from P4_Spec_PluralAbstract.

    {
        // discard the description if it isn't the 'long' version
        if (!in_array('-l', $flags)) {
            unset($listEntry['Description']);
        }

        return parent::_fromSpecListEntry($listEntry, $flags, $connection);
    }
static P4_Job::_getFetchAllFlags ( $  options) [static, protected]

Produce set of flags for the spec list command, given fetch all options array.

Extends parent to add support for filter option.

Parameters:
array$optionsarray of options to augment fetch behavior. see fetchAll for documented options.
Returns:
array set of flags suitable for passing to spec list command.

Reimplemented from P4_Spec_PluralAbstract.

    {
        $flags = parent::_getFetchAllFlags($options);

        if (isset($options[static::FETCH_BY_FILTER])) {
            $filter = $options[static::FETCH_BY_FILTER];

            if (!is_string($filter) || trim($filter) === "") {
                throw new InvalidArgumentException(
                    'Fetch by Filter expects a non-empty string as input'
                );
            }

            $flags[] = '-e';
            $flags[] = $filter;
        }

        // if they have not specified FETCH_DESCRIPTION or
        // they have and its true; include full descriptions
        if (!isset($options[static::FETCH_DESCRIPTION]) ||
            $options[static::FETCH_DESCRIPTION]) {
            $flags[] = '-l';
        }

        return $flags;
    }
static P4_Job::_isValidId ( $  id) [static, protected]

Check if the given id is in a valid format for this spec type.

Parameters:
string | int$idthe id to check
Returns:
bool true if id is valid, false otherwise

Reimplemented from P4_Spec_PluralAbstract.

    {
        $validator = new P4_Validate_SpecName;
        $validator->allowPurelyNumeric(true);
        return $validator->isValid($id);
    }
static P4_Job::exists ( $  id,
P4_Connection_Interface $  connection = null 
) [static]

Determine if the given job id exists.

Parameters:
string | int$idthe id to check for.
P4_Connection_Interface$connectionoptional - a specific connection to use.
Returns:
bool true if the given id matches an existing job.

Reimplemented from P4_Spec_PluralAbstract.

    {
        // check id for valid format
        if (!static::_isValidId($id)) {
            return false;
        }

        $jobs = static::fetchAll(
            array(
                static::FETCH_BY_FILTER => static::_getIdField() .'='. $id,
                static::FETCH_MAXIMUM   => 1
            ),
            $connection
        );

        return (bool) count($jobs);
    }
static P4_Job::fetchAll ( $  options = array(),
P4_Connection_Interface $  connection = null 
) [static]

Get all Jobs from Perforce.

Adds filtering options.

Parameters:
array$optionsoptional - array of options to augment fetch behavior. supported options are:

FETCH_MAXIMUM - set to integer value to limit to the first 'max' number of entries. FETCH_BY_FILTER - set to jobview filter FETCH_DESCRIPTION - description will be fetched if true, left for later lazy loading if false. * defaults to true if not specified

Parameters:
P4_Connection_Interface$connectionoptional - a specific connection to use.
Returns:
P4_Model_Iterator all records of this type.

Reimplemented from P4_Spec_PluralAbstract.

    {
        // simply return parent - method exists to document options.
        return parent::fetchAll($options, $connection);
    }
P4_Job::getDate ( )

Returns the date this job was created.

This will return the value of field 104 even if the field name has been changed in the jobspec.

Returns:
string|null Date this job was created or null if unset. 
    {
        return $this->_getValue($this->_fieldCodeToName(104));
    }
P4_Job::getDescription ( )

Returns the description for this job.

This will return the value of field 105 even if the field name has been changed in the jobspec.

Returns:
string|null Description for this job or null if unset. 
    {
        return $this->_getValue($this->_fieldCodeToName(105));
    }
P4_Job::getStatus ( )

Returns the status of this job.

This will return the value of field 102 even if the field name has been changed in the jobspec.

Out of the box valid status options are: open/suspended/closed or null. Modifying the jobspec can change the list of valid options.

Returns:
string|null Status of this job or null if unset. 
    {
        return $this->_getValue($this->_fieldCodeToName(102));
    }
P4_Job::getUser ( )

Returns the user who created this job.

This will return the value of field 103 even if the field name has been changed in the jobspec.

Returns:
string|null User who created this job or null if unset. 
    {
        return $this->_getValue($this->_fieldCodeToName(103));
    }
P4_Job::getValue ( $  field)

Get field value.

If a custom field accessor exists, it will be used. Extends parent to add support for accessors keyed on field code instead of name.

Parameters:
string$fieldthe name of the field to get the value of.
Returns:
mixed the value of the field.
Exceptions:
P4_Spec_Exceptionif the field does not exist.

Reimplemented from P4_SpecAbstract.

    {
        // if field has custom accessor based on field code, use it.
        $fieldCode = $this->_fieldNameToCode($field);
        if (isset(static::$_accessors[$fieldCode])) {
            return $this->{static::$_accessors[$fieldCode]}();
        }

        return parent::getValue($field);
    }
P4_Job::save ( )

Override parent to set id to 'new' if unset and capture id returned by save.

Returns:
P4_Job provides a fluent interface

Reimplemented from P4_SpecAbstract.

    {
        $values = $this->_getValues();
        if ($this->getId() === null) {
            $values[static::_getIdField()] = "new";
        }

        // ensure all required fields have values.
        $this->_validateRequiredFields($values);

        $result = $this->getConnection()->run(static::_getSpecType(), "-i", $values);

        // Saved job Id is returned as a string, capture it.
        $data = $result->getData(0);

        if (!preg_match('/^Job ([^ ]+) saved\./', $data, $match)) {
            throw new P4_Spec_Exception('Cannot find ID for saved Job.');
        }

        // Store the retrieved ID
        $this->setId($match[1]);

        // should re-populate (server may change values).
        $this->_deferPopulate(true);

        return $this;
    }
P4_Job::setDescription ( $  description)

Update the decription for this job.

This will update the value of field 105 even if the field name has been changed in the jobspec.

Parameters:
string | null$descriptionDescription for this job, or null
Returns:
P4_Job provides a fluent interface.
Exceptions:
InvalidArgumentExceptionFor input which isn't a string or null 
    {
        if (!is_null($description) && !is_string($description)) {
            throw new InvalidArgumentException('Description must be a string or null');
        }

        return $this->_setValue($this->_fieldCodeToName(105), $description);
    }
P4_Job::setStatus ( $  status)

Update the status of this job.

This will update the value of field 102 even if the field name has been changed in the jobspec.

Parameters:
string | null$statusStatus of this job or null
Returns:
P4_Job provides a fluent interface.
Exceptions:
InvalidArgumentExceptionFor input which isn't a string or null 
    {
        if (!is_string($status) && !is_null($status)) {
            throw new InvalidArgumentException('Status must be a string or null');
        }

        return $this->_setValue($this->_fieldCodeToName(102), $status);
    }
P4_Job::setUser ( $  user)

Update the user who created this job.

This will update the value of field 103 even if the field name has been changed in the jobspec.

Parameters:
string | P4_User | null$userUser who created this job, or null
Returns:
P4_Job provides a fluent interface.
Exceptions:
InvalidArgumentExceptionFor input which isn't a string, P4_User or null 
    {
        if ($user instanceof P4_User) {
            $user = $user->getId();
        }

        if (!is_null($user) && !is_string($user)) {
            throw new InvalidArgumentException('User must be a string, P4_User or null');
        }

        return $this->_setValue($this->_fieldCodeToName(103), $user);
    }
P4_Job::setValue ( $  field,
$  value 
)

Set field value.

If a custom field mutator exists, it will be used. Extends parent to add support for mutators keyed on field code instead of name.

Parameters:
string$fieldthe name of the field to set the value of.
mixed$valuethe value to set in the field.
Returns:
P4_SpecAbstract provides a fluent interface

Reimplemented from P4_SpecAbstract.

    {
        // if field has custom mutator based on field code, use it.
        $fieldCode = $this->_fieldNameToCode($field);
        if (isset(static::$_mutators[$fieldCode])) {
            return $this->{static::$_mutators[$fieldCode]}($value);
        }

        return parent::setValue($field, $value);
    }

Member Data Documentation

P4_Job::$_accessors [static, protected]
Initial value:
 array(
        102             => 'getStatus',
        103             => 'getUser',
        104             => 'getDate',
        105             => 'getDescription',
    )

Reimplemented from P4_SpecAbstract.

P4_Job::$_idField = 'Job' [static, protected]

Reimplemented from P4_Spec_PluralAbstract.

P4_Job::$_mutators [static, protected]
Initial value:
 array(
        102             => 'setStatus',
        103             => 'setUser',
        105             => 'setDescription',
    )

Reimplemented from P4_SpecAbstract.

P4_Job::$_specType = 'job' [static, protected]

Reimplemented from P4_SpecAbstract.

const P4_Job::FETCH_BY_FILTER = 'filter'
const P4_Job::FETCH_DESCRIPTION = 'descriptions'
The documentation for this class was generated from the following file: