Drupal\tripal\Services\TripalJob Class Reference

Public Member Functions
	__construct ()
	load ($job_id)
	create ($details)
	cancel ()
	run ()
	isRunning ()
	getJob ()
	getJobID ()
	getUID ()
	getJobName ()
	getModuleName ()
	getCallback ()
	getArguments ()
	getProgress ()
	setProgress ($percent_done)
	setTotalItems ($total_items)
	addItemsHandled ($num_handled)
	setItemsHandled ($total_handled)
	setInterval ($interval)
	getStatus ()
	getSubmitTime ()
	getStartTime ()
	getEndTime ()
	getLog ()
	getPID ()
	getPriority ()
	getMLock ()
	getLock ()
	getIncludes ()
	log ($message, $context=[])
	logMessage ($message, $variables=[], $severity=TRIPAL_INFO)

Protected Attributes
	$job_id = NULL
	$job = NULL
	$messenger = NULL

Constructor & Destructor Documentation

__construct()

Drupal\tripal\Services\TripalJob::__construct

(

)

Instantiates a new TripalJob object.

By default the job object is "empty". It must be associated with job details either by calling the load() function or the create() function.

Member Function Documentation

addItemsHandled()

Drupal\tripal\Services\TripalJob::addItemsHandled

(

$num_handled

)

Adds to the count of the total number of items that have been handled.

Parameters

$num_handled

cancel()

Drupal\tripal\Services\TripalJob::cancel

(

)

Cancels the job and prevents it from running.

create()

Drupal\tripal\Services\TripalJob::create

(

$details

)

Creates a new job.

Parameters

$details

An associative array of the job details or a single job_id. If the details are provided then the job is created and added to the database otherwise if a job_id is provided then the object is loaded from the database. The following keys are allowed: job_name: The human readable name for the job. modulename: The name of the module adding the job. callback: The name of a function to be called when the job is executed. arguments: An array of arguments to be passed on to the callback. uid: The uid of the user adding the job priority: The priority at which to run the job where the highest priority is 10 and the lowest priority is 1. The default priority is 10. includes: An array of paths to files that should be included in order to execute the job. Use the module_load_include function to get a path for a given file. ignore_duplicate: (Optional). Set to TRUE to ignore a job if it has the same name as another job which has not yet run. If TRUE and a job already exists then this object will reference the job already in the queue rather than a new submission. The default is TRUE.

Exceptions

Exception

On failure an exception is thrown.

Returns

Returns TRUE if the job was succesfully created. Returns FALSE otherwise. A return of FALSE does not mean the job creation failed. If the ignore_duplicate is set to false and the job already is present in the queue then the return value will be FALSE.

getArguments()

Drupal\tripal\Services\TripalJob::getArguments

(

)

Retrieves the array of arguments for the job.

getCallback()

Drupal\tripal\Services\TripalJob::getCallback

(

)

Retrieves the callback function for the job.

getEndTime()

Drupal\tripal\Services\TripalJob::getEndTime

(

)

Retieves the time the job completed execution (i.e. the end time).

getIncludes()

Drupal\tripal\Services\TripalJob::getIncludes

(

)

Get the list of files that must be included prior to job execution.

getJob()

Drupal\tripal\Services\TripalJob::getJob

(

)

Retrieve the job object as if from a database query.

getJobID()

Drupal\tripal\Services\TripalJob::getJobID

(

)

Retrieves the job ID.

getJobName()

Drupal\tripal\Services\TripalJob::getJobName

(

)

Retrieves the job name.

getLock()

Drupal\tripal\Services\TripalJob::getLock

(

)

Get the lock value of the job.

The lock value indicates if no other jobs from any module should be executed while this job is running.

getLog()

Drupal\tripal\Services\TripalJob::getLog

(

)

Retieves the log for the job.

Returns

A large string containing the text of the job log. It contains both status upates and errors.

getMLock()

Drupal\tripal\Services\TripalJob::getMLock

(

)

Get the MLock value of the job.

The MLock value indicates if no other jobs from a give module should be executed while this job is running.

getModuleName()

Drupal\tripal\Services\TripalJob::getModuleName

(

)

Retrieves the name of the module that submitted the job.

getPID()

Drupal\tripal\Services\TripalJob::getPID

(

)

Retrieves the process ID of the job.

getPriority()

Drupal\tripal\Services\TripalJob::getPriority

(

)

Retreieves the priority that is currently set for the job.

getProgress()

Drupal\tripal\Services\TripalJob::getProgress

(

)

Retrieves the current percent complete (i.e. progress) of the job.

getStartTime()

Drupal\tripal\Services\TripalJob::getStartTime

(

)

Retieves the time the job began execution (i.e. the start time).

getStatus()

Drupal\tripal\Services\TripalJob::getStatus

(

)

Retrieves the status of the job.

getSubmitTime()

Drupal\tripal\Services\TripalJob::getSubmitTime

(

)

Retrieves the time the job was submitted.

getUID()

Drupal\tripal\Services\TripalJob::getUID

(

)

Retrieves the user ID of the user that submitted the job.

isRunning()

Drupal\tripal\Services\TripalJob::isRunning

(

)

Inidcates if the job is running.

Returns

TRUE if the job is running, FALSE otherwise.

load()

Drupal\tripal\Services\TripalJob::load

(

$job_id

)

Loads a job for this object.

Parameters

$job_id

The ID of the job.

log()

Drupal\tripal\Services\TripalJob::log	(		$message,
			$context = []
	)

Adds a message to the job's log.

Consider using the \Drupal\tripal\Services\TripalLogger rather than this function as it supports logging to both the Job and to the Drupal system log at the same time.

However, if you prefer to log to Drupal and to the Log separately use this function only for logging to the job.

Parameters

$message	The message MUST be a string or object implementing __toString().
$context	The message MAY contain placeholders in the form: {foo} where foo will be replaced by the context data in key "foo". The context array can contain arbitrary data. The only assumption that can be made by implementors is that if an Exception instance is given to produce a stack trace, it MUST be in a key named "exception".

logMessage()

Drupal\tripal\Services\TripalJob::logMessage	(		$message,
			$variables = [],
			$severity = TRIPAL_INFO
	)

DEPRECATED

Logs a message for the job.

This function is deprecated in Tripal v4. It will be removed in a future release of Tripal. Please use the \Drupal\tripal\Services\TripalLogger class or the job function of this class. The preferred approach is the TripalLogger as it supports logging to both the job and to the Drupal logger.

There is no distinction between status messages and error logs. Any message that is intended for the user to review the status of the job can be provided here.

Messages that are are of severity TRIPAL_CRITICAL or TRIPAL_ERROR are also logged to the watchdog.

Logging works regardless if the job uses a transaction. If the transaction must be rolled back to to an error the error messages will persist.

If a function can be executed by the Tripal job system (and hence the job object is passed in) then you can directly use this function to log messages. However, if the function can be run via drush on the command-line, consider using the tripal_report_error() function which can accept a job object as an $option and will print to both the terminal and to the job object. If you use the tripal_report_error() be sure to set the 'watchdog' option only if you need log messages also going to the watchdog.

Parameters

$message	The message to store in the log. Keep $message translatable by not concatenating dynamic values into it! Variables in the message should be added by using placeholder strings alongside the variables argument to declare the value of the placeholders. See t() for documentation on how $message and $variables interact.
$variables	Array of variables to replace in the message on display or NULL if message is already translated or not possible to translate.
$severity	The severity of the message; one of the following values: TRIPAL_CRITICAL: Critical conditions. TRIPAL_ERROR: Error conditions. TRIPAL_WARNING: Warning conditions. TRIPAL_NOTICE: Normal but significant conditions. TRIPAL_INFO: (default) Informational messages. TRIPAL_DEBUG: Debug-level messages.

run()

Drupal\tripal\Services\TripalJob::run

(

)

Executes the job.

setInterval()

Drupal\tripal\Services\TripalJob::setInterval

(

$interval

)

Updates the percent interval when the job progress is updated.

Updating the job progress incurrs a database write which takes time and if it occurs to frequently can slow down the loader. This should be a value between 0 and 100 to indicate a percent interval (e.g. 1 means update the progress every time the num_handled increases by 1%).

Parameters

$interval

A number between 0 and 100.

setItemsHandled()

Drupal\tripal\Services\TripalJob::setItemsHandled

(

$total_handled

)

Sets the number of items that have been processed.

This should be called anytime the loader wants to indicate how many items have been processed. The amount of progress will be calculated using this number. If the amount of items handled exceeds the interval specified then the progress is reported to the user. If this loader is associated with a job then the job progress is also updated.

Parameters

$total_handled

The total number of items that have been processed.

setProgress()

Drupal\tripal\Services\TripalJob::setProgress

(

$percent_done

)

Sets the current percent complete of a job.

Parameters

$percent_done

A value between 0 and 100 indicating the percentage complete of the job.

setTotalItems()

Drupal\tripal\Services\TripalJob::setTotalItems

(

$total_items

)

Sets the total number if items to be processed.

This should typically be called near the beginning of the loading process to indicate the number of items that must be processed.

Parameters

$total_items

The total number of items to process.

Member Data Documentation

$job

Drupal\tripal\Services\TripalJob::$job = NULL

protected

Contains the job record for this job.

$job_id

Drupal\tripal\Services\TripalJob::$job_id = NULL

protected

The ID of the job.

---

The documentation for this class was generated from the following file:

• tripal/src/Services/TripalJob.php