Improved documentation on jobs API, deprecated a few functions

tripal/api/tripal.DEPRECATED.api.inc

@@ -0,0 +1,113 @@
+<?php
+/**
+ * Returns the end time for a given job
+ *
+ * @param $job
+ *   An object describing the job
+ *
+ * @return
+ *   The end time of the job if it was already run and empty otherwise
+ *
+ * @ingroup tripal_jobs_api
+ */
+function tripal_get_job_end($job) {
+  tripal_report_error('tripal_deprecated', TRIPAL_NOTICE,
+    "DEPRECATED: %function has been removed from the API the end date " .
+    "is now accessible via the %property property. Please update your code.",
+    array(
+      '%old_function' => 'tripal_jobs_get_end_time',
+      '%property' => '\$job->end_time_string',
+    )
+  );
+
+  if ($job->end_time > 0) {
+    $end = format_date($job->end_time);
+  }
+  else {
+    $end = '';
+  }
+
+  return $end;
+}
+
+/**
+ * Returns the start time for a given job
+ *
+ * @param $job
+ *   An object describing the job
+ *
+ * @return
+ *   The start time of the job if it was already run and either "Cancelled" or "Not Yet Started" otherwise
+ *
+ * @ingroup tripal_jobs_api
+ */
+function tripal_get_job_start($job) {
+
+  tripal_report_error('tripal_deprecated', TRIPAL_NOTICE,
+    "DEPRECATED: %function has been removed from the API the end date " .
+    "is now accessible via the %property property. Please update your code.",
+    array(
+      '%old_function' => 'tripal_get_job_start',
+      '%property' => '\$job->start_time_string',
+    )
+  );
+
+  if ($job->start_time > 0) {
+    $start = format_date($job->start_time);
+  }
+  else {
+    if (strcmp($job->job_status, 'Cancelled')==0) {
+      $start = 'Cancelled';
+    }
+    else {
+      $start = 'Not Yet Started';
+    }
+  }
+  return $start;
+}
+
+/**
+ * Returns the date the job was added to the queue
+ *
+ * @param $job
+ *   An object describing the job
+ *
+ * @return
+ *   The date teh job was submitted
+ *
+ * @ingroup tripal_jobs_api
+ */
+function tripal_get_job_submit_date($job) {
+
+  tripal_report_error('tripal_deprecated', TRIPAL_NOTICE,
+      "DEPRECATED: %function has been removed from the API the end date " .
+      "is now accessible via the %property property. Please update your code.",
+      array(
+        '%old_function' => 'tripal_get_job_submit_date',
+        '%property' => '\$job->submit_date_string',
+      )
+  );
+  return format_date($job->submit_date);
+}
+
+
+/**
+ * @deprecated Restructured API to make naming more readable and consistent.
+ * Function was deprecated in Tripal 3.0 and will be removed a later release.
+ * This function has been replaced by tripal_get_running_jobs().
+ *
+ * @see chado_get_id_from_nid()
+ */
+function tripal_is_job_running() {
+
+  tripal_report_error('tripal_deprecated',TRIPAL_NOTICE,
+    "DEPRECATED: %old_function has been replaced with %new_function. The arguments have been changed slightly (ie: $nid instead of $node). Please update your code.",
+    array(
+      '%old_function'=>'tripal_is_job_running',
+      '%new_function' => 'tripal_get_running_jobs'
+    )
+  );
+
+  //New API Function
+  return tripal_get_running_jobs();
+}

tripal/api/tripal.jobs.api.inc

@@ -160,15 +160,23 @@ function tripal_add_job($job_name, $modulename, $callback, $arguments, $uid,
  *   The unique identifier of the job
  *
  * @return
- *   An object describing the job
+ *   An object describing the job if a job is found or FALSE on failure.
  *
  * @ingroup tripal_jobs_api
  */
 function tripal_get_job($job_id) {
+  if (!$job_id or !is_numeric($job_id)) {
+    watchdog('tripal', "Must provide a numeric \$job_id to the tripal_cancel_job() function.");
+    return FALSE;
+  }
 
   $job = db_query('SELECT j.* FROM {tripal_jobs} j WHERE j.job_id=:job_id', array(':job_id' => $job_id))
     ->fetchObject();
 
+  $job->submit_date_string = format_date($job->submit_date);
+  $job->start_time_string = format_date($job->start_time);
+  $job->end_time_string = format_date($job->end_time);
+
   return $job;
 }
 
@@ -180,7 +188,7 @@ function tripal_get_job($job_id) {
  *
  * @ingroup tripal_jobs_api
  */
-function tripal_is_job_running() {
+function tripal_get_running_jobs() {
 
   // iterate through each job that has not ended
   // and see if it is still running. If it is not
@@ -211,55 +219,9 @@ function tripal_is_job_running() {
   return FALSE;
 }
 
-/**
- * Returns the start time for a given job
- *
- * @param $job
- *   An object describing the job
- *
- * @return
- *   The start time of the job if it was already run and either "Cancelled" or "Not Yet Started" otherwise
- *
- * @ingroup tripal_jobs_api
- */
-function tripal_get_job_start($job) {
-
-  if ($job->start_time > 0) {
-    $start = format_date($job->start_time);
-  }
-  else {
-    if (strcmp($job->job_status, 'Cancelled')==0) {
-      $start = 'Cancelled';
-    }
-    else {
-      $start = 'Not Yet Started';
-    }
-  }
-  return $start;
-}
 
-/**
- * Returns the end time for a given job
- *
- * @param $job
- *   An object describing the job
- *
- * @return
- *   The end time of the job if it was already run and empty otherwise
- *
- * @ingroup tripal_jobs_api
- */
-function tripal_get_job_end($job) {
 
-  if ($job->end_time > 0) {
-    $end = format_date($job->end_time);
-  }
-  else {
-    $end = '';
-  }
 
-  return $end;
-}
 /**
  * Set a job to be re-ran (ie: add it back into the job queue)
  *
@@ -510,17 +472,4 @@ function tripal_get_active_jobs($modulename = NULL) {
   return $jobs;
 }
 
-/**
- * Returns the date the job was added to the queue
- *
- * @param $job
- *   An object describing the job
- *
- * @return
- *   The date teh job was submitted
- *
- * @ingroup tripal_jobs_api
- */
-function tripal_get_job_submit_date($job) {
-  return format_date($job->submit_date);
-}
+

tripal/tripal.module

@@ -566,6 +566,7 @@ function tripal_import_api() {
   module_load_include('inc', 'tripal', 'api/tripal.jobs.api');
   module_load_include('inc', 'tripal', 'api/tripal.notice.api');
   module_load_include('inc', 'tripal', 'api/tripal.variables.api');
+  module_load_include('inc', 'tripal', 'api/tripal.DEPRECATED.api');
 }
 
 /**