service_job.h
Go to the documentation of this file.
1 /*
2 ** Copyright 2014-2016 The Earlham Institute
3 **
4 ** Licensed under the Apache License, Version 2.0 (the "License");
5 ** you may not use this file except in compliance with the License.
6 ** You may obtain a copy of the License at
7 **
8 ** http://www.apache.org/licenses/LICENSE-2.0
9 **
10 ** Unless required by applicable law or agreed to in writing, software
11 ** distributed under the License is distributed on an "AS IS" BASIS,
12 ** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 ** See the License for the specific language governing permissions and
14 ** limitations under the License.
15 */
16 
21 /*
22  * service_job.h
23  *
24  * Created on: 25 Apr 2015
25  * Author: billy
26  */
27 
28 #ifndef SERVICE_JOB_H_
29 #define SERVICE_JOB_H_
30 
31 #include "typedefs.h"
33 #include "operation.h"
34 #include "jansson.h"
35 #include "linked_list.h"
36 #include "memory_allocations.h"
37 #include "linked_service.h"
38 
39 
40 #include "uuid/uuid.h"
41 
42 /* forward declarations */
43 struct Service;
44 struct ServiceJob;
45 struct LinkedService;
46 
47 
48 #ifndef DOXYGEN_SHOULD_SKIP_THIS
49 
50 #ifdef ALLOCATE_SERVICE_JOB_TAGS
51  #define SERVICE_JOB_PREFIX GRASSROOTS_SERVICE_API
52  #define SERVICE_JOB_VAL(x) = x
53 #else
54  #define SERVICE_JOB_PREFIX extern
55  #define SERVICE_JOB_VAL(x)
56 #endif
57 
58 #endif
59 
60 
62 SERVICE_JOB_PREFIX const char *SJ_DEFAULT_TYPE_S SERVICE_JOB_VAL ("default_service_job");
63 
64 
72 typedef struct ServiceJob
73 {
76 
78  uuid_t sj_id;
79 
82 
85 
87  char *sj_name_s;
88 
91 
95  json_t *sj_result_p;
96 
100  json_t *sj_metadata_p;
101 
106  json_t *sj_errors_p;
107 
108 
115 
116 
122  bool (*sj_update_fn) (struct ServiceJob *job_p);
123 
130  void (*sj_free_fn) (struct ServiceJob *job_p);
131 
132 
133 
139  bool (*sj_calculate_result_fn) (struct ServiceJob *job_p);
140 
141 
142 
147 
148 
155  char *sj_type_s;
156 } ServiceJob;
157 
158 
166 typedef struct ServiceJobNode
167 {
170 
173 
175 
176 
182 typedef struct ServiceJobSet
183 {
186 
189 
190 
191 } ServiceJobSet;
192 
193 
194 #ifdef __cplusplus
195 extern "C"
196 {
197 #endif
198 
199 
206 GRASSROOTS_SERVICE_API void FreeServiceJob (ServiceJob *job_p);
207 
208 
220 GRASSROOTS_SERVICE_API void FreeBaseServiceJob (ServiceJob *job_p);
221 
222 
248 GRASSROOTS_SERVICE_API ServiceJob *AllocateServiceJob (struct Service *service_p, const char *job_name_s, const char *job_description_s, bool (*update_fn) (struct ServiceJob *job_p), bool (*calculate_results_fn) (struct ServiceJob *job_p), void (*free_job_fn) (struct ServiceJob *job_p), const char *job_type_s);
249 
250 
251 
276 GRASSROOTS_SERVICE_API ServiceJob *CreateAndAddServiceJobToService (struct Service *service_p, const char *job_name_s, const char *job_description_s, bool (*update_fn) (struct ServiceJob *job_p), bool (*calculate_results_fn) (struct ServiceJob *job_p), void (*free_job_fn) (struct ServiceJob *job_p));
277 
278 
305 GRASSROOTS_SERVICE_API bool InitServiceJob (ServiceJob *job_p, struct Service *service_p, const char *job_name_s, const char *job_description_s, bool (*update_fn) (struct ServiceJob *job_p), bool (*calculate_results_fn) (struct ServiceJob *job_p), void (*free_job_fn) (struct ServiceJob *job_p), uuid_t *id_p, const char *job_type_s);
306 
307 
314 GRASSROOTS_SERVICE_API void ClearServiceJob (ServiceJob *job_p);
315 
316 
324 GRASSROOTS_SERVICE_API ServiceJob *CloneServiceJob (const ServiceJob *src_p);
325 
326 
335 GRASSROOTS_SERVICE_API bool CopyServiceJob (const ServiceJob *src_p, ServiceJob *dest_p);
336 
337 
345 GRASSROOTS_SERVICE_API struct Service *GetServiceFromServiceJob (ServiceJob *job_p);
346 
347 
357 GRASSROOTS_SERVICE_API ServiceJobNode *FindServiceJobNodeInServiceJobSet (const ServiceJobSet *job_set_p, const ServiceJob *job_p);
358 
359 
360 GRASSROOTS_SERVICE_API bool IsServiceJobInServiceJobSet (const ServiceJobSet *job_set_p, const ServiceJob *job_p);
361 
362 
372 GRASSROOTS_SERVICE_API ServiceJobNode *FindServiceJobNodeByUUIDInServiceJobSet (const ServiceJobSet *job_set_p, const uuid_t job_id);
373 
374 
386 GRASSROOTS_SERVICE_API bool RemoveServiceJobByUUIDFromServiceJobSet (ServiceJobSet *job_set_p, uuid_t job_id);
387 
388 
399 GRASSROOTS_SERVICE_API bool RemoveServiceJobFromServiceJobSet (ServiceJobSet *job_set_p, ServiceJob *job_p);
400 
401 
402 
412 GRASSROOTS_SERVICE_API bool SetServiceJobDescription (ServiceJob *job_p, const char * const description_s);
413 
414 
424 GRASSROOTS_SERVICE_API bool SetServiceJobName (ServiceJob *job_p, const char * const name_s);
425 
426 
435 GRASSROOTS_SERVICE_API ServiceJobSet *AllocateServiceJobSet (struct Service *service_p);
436 
437 
438 
450 GRASSROOTS_SERVICE_API ServiceJobSet *AllocateSimpleServiceJobSet (struct Service *service_p, const char *job_name_s, const char *job_description_s);
451 
452 
459 GRASSROOTS_SERVICE_API void FreeServiceJobSet (ServiceJobSet *job_set_p);
460 
461 
462 
470 GRASSROOTS_SERVICE_API ServiceJobNode *AllocateServiceJobNode (ServiceJob *job_p);
471 
472 
479 GRASSROOTS_SERVICE_API void FreeServiceJobNode (ListItem *service_job_node_p);
480 
481 
491 GRASSROOTS_SERVICE_API ServiceJob *GetServiceJobFromServiceJobSetById (const ServiceJobSet *jobs_p, const uuid_t job_id);
492 
493 
504 GRASSROOTS_SERVICE_API json_t *GetServiceJobSetAsJSON (const ServiceJobSet *jobs_p, bool omit_results_flag);
505 
506 
517 GRASSROOTS_SERVICE_API json_t *GetServiceJobAsJSON (ServiceJob * const job_p, bool omit_results_flag);
518 
519 
530 GRASSROOTS_SERVICE_API json_t *GetServiceJobStatusAsJSON (ServiceJob *job_p, bool omit_results_flag);
531 
532 
545 GRASSROOTS_SERVICE_API bool ProcessServiceJobSet (ServiceJobSet *jobs_p, json_t *res_p);
546 
547 
561 GRASSROOTS_SERVICE_API ServiceJob *CreateServiceJobFromJSON (const json_t *job_json_p, GrassrootsServer *grassroots_p);
562 
563 
573 GRASSROOTS_SERVICE_API bool InitServiceJobFromJSON (ServiceJob *job_p, const json_t *json_p, struct Service *service_p, GrassrootsServer *grassroots_p);
574 
575 
586 GRASSROOTS_SERVICE_API OperationStatus GetServiceJobStatus (ServiceJob *job_p);
587 
588 
601 GRASSROOTS_SERVICE_API OperationStatus GetCachedServiceJobStatus (const ServiceJob *job_p);
602 
603 
611 GRASSROOTS_SERVICE_API const char *GetServiceJobName (const ServiceJob *job_p);
612 
613 
624 GRASSROOTS_SERVICE_API bool CloseServiceJob (ServiceJob *job_p);
625 
626 
636 GRASSROOTS_SERVICE_API ServiceJob *GetServiceJobFromServiceJobSet (const ServiceJobSet *jobs_p, const uint32 index);
637 
645 GRASSROOTS_SERVICE_API uint32 GetServiceJobSetSize (const ServiceJobSet * const jobs_p);
646 
647 
659 GRASSROOTS_SERVICE_API void ClearServiceJobResults (ServiceJob *job_p, bool free_memory_flag);
660 
661 
676 GRASSROOTS_SERVICE_API char *SerialiseServiceJobToJSON (ServiceJob * const job_p, bool omit_results_flag);
677 
678 
696 GRASSROOTS_SERVICE_API ServiceJob *CreateServiceJobFromResultsJSON (const json_t *results_p, struct Service *service_p, const char *name_s, const char *description_s, OperationStatus status, const char *job_type_s);
697 
698 
699 
714 GRASSROOTS_SERVICE_API bool InitServiceJobFromResultsJSON (ServiceJob *job_p, const json_t *results_p, struct Service *service_p, const char *name_s, const char *description_s, OperationStatus status, const char *job_type_s);
715 
716 
728 GRASSROOTS_SERVICE_API bool AddParameterErrorMessageToServiceJob (ServiceJob *job_p, const char * const param_s, const ParameterType param_type, const char * const value_s);
729 
730 
741 GRASSROOTS_SERVICE_API bool AddGeneralErrorMessageToServiceJob (ServiceJob *job_p, const char * const value_s);
742 
743 
754 GRASSROOTS_SERVICE_API bool AddCompoundErrorToServiceJob (ServiceJob *job_p, const char *param_s, const ParameterType param_type, json_t *error_details_p);
755 
756 
757 GRASSROOTS_SERVICE_API bool AddTabularParameterErrorMessageToServiceJob (ServiceJob *job_p, const char * const param_s, const ParameterType param_type, const char * const value_s, const uint32 row, const char *column_s);
758 
759 
769 GRASSROOTS_SERVICE_API bool AddResultToServiceJob (ServiceJob *job_p, json_t *result_p);
770 
771 
772 
780 GRASSROOTS_SERVICE_API void SetServiceJobStatus (ServiceJob *job_p, OperationStatus status);
781 
782 
790 GRASSROOTS_SERVICE_API void SetServiceJobUpdateFunction (ServiceJob *job_p, bool (*update_fn) (ServiceJob *job_p));
791 
792 
800 GRASSROOTS_SERVICE_API void SetServiceJobFreeFunction (ServiceJob *job_p, void (*free_fn) (ServiceJob *job_p));
801 
802 
803 
811 GRASSROOTS_SERVICE_API void SetServiceJobCalculateResultFunction (ServiceJob *job_p, bool (*calculate_fn) (ServiceJob *job_p));
812 
813 
814 
828 GRASSROOTS_SERVICE_API bool UpdateServiceJob (ServiceJob *job_p);
829 
830 
838 GRASSROOTS_SERVICE_API uint32 GetNumberOfServiceJobResults (const ServiceJob *job_p);
839 
840 
851 GRASSROOTS_SERVICE_API bool ReplaceServiceJobResults (ServiceJob *job_p, json_t *results_p);
852 
853 
865 GRASSROOTS_SERVICE_API bool AddLinkedServiceToServiceJob (ServiceJob *job_p, struct LinkedService *linked_service_p);
866 
875 GRASSROOTS_SERVICE_API void ProcessLinkedServices (ServiceJob *job_p);
876 
877 
885 GRASSROOTS_SERVICE_API bool CalculateServiceJobResult (ServiceJob *job_p);
886 
887 
895 GRASSROOTS_SERVICE_API void SetServiceJobUUID (ServiceJob *job_p, const uuid_t new_job_id);
896 
897 
898 
899 GRASSROOTS_SERVICE_LOCAL int32 GetNumberOfLiveJobsFromServiceJobSet (const ServiceJobSet *jobs_p);
900 
901 
902 
903 GRASSROOTS_SERVICE_LOCAL bool GetOperationStatusFromServiceJobJSON (const json_t *value_p, OperationStatus *status_p);
904 
905 
906 #ifdef __cplusplus
907 }
908 #endif
909 
910 
911 
912 #endif /* SERVICE_JOB_H_ */
const char * GetServiceJobName(const ServiceJob *job_p)
Get the name of ServiceJob.
A doubly-linked node that points to its predecessor and successor.
Definition: linked_list.h:43
ParameterType
The different types that a Parameter can take.
Definition: parameter_type.h:35
char * sj_type_s
The type of ServiceJob.
Definition: service_job.h:155
bool sj_is_updating_flag
Is this ServiceJob in the process of updating itself?
Definition: service_job.h:146
ServiceJob * GetServiceJobFromServiceJobSet(const ServiceJobSet *jobs_p, const uint32 index)
Get the ServiceJob at a particular position in a ServiceJobSet.
bool(* sj_calculate_result_fn)(struct ServiceJob *job_p)
The callback function to use when a ServiceJob needs to generate its results This is useful for subcl...
Definition: service_job.h:139
json_t * sj_linked_services_p
A JSON array where each object contains the details of running a different Service based upon the res...
Definition: service_job.h:114
void FreeServiceJob(ServiceJob *job_p)
Free a ServiceJob.
json_t * GetServiceJobStatusAsJSON(ServiceJob *job_p, bool omit_results_flag)
Get the Current OperationStatus of a ServiceJob as JSON.
ServiceJob * CreateAndAddServiceJobToService(struct Service *service_p, const char *job_name_s, const char *job_description_s, bool(*update_fn)(struct ServiceJob *job_p), bool(*calculate_results_fn)(struct ServiceJob *job_p), void(*free_job_fn)(struct ServiceJob *job_p))
Allocate a ServiceJob and add it to a ServiceJobSet.
A datatype to represent a collection of ServiceJobs.
Definition: service_job.h:182
void ClearServiceJobResults(ServiceJob *job_p, bool free_memory_flag)
Clear the results associated with a ServiceJob.
bool AddParameterErrorMessageToServiceJob(ServiceJob *job_p, const char *const param_s, const ParameterType param_type, const char *const value_s)
Add a key-value pair error statement to a ServiceJob.
void ClearServiceJob(ServiceJob *job_p)
Clear a Service Job ready for reuse.
bool CalculateServiceJobResult(ServiceJob *job_p)
Calculate the results for the given ServiceJob.
struct Service * sjs_service_p
The Service that is running these jobs.
Definition: service_job.h:185
bool AddGeneralErrorMessageToServiceJob(ServiceJob *job_p, const char *const value_s)
Add a key-value pair error statement to a ServiceJob.
enum OperationStatus sj_status
Is the service currently in an open state?
Definition: service_job.h:81
SERVICE_JOB_PREFIX const char * SJ_DEFAULT_TYPE_S
The default type id for ServiceJobs.
Definition: service_job.h:62
OperationStatus GetCachedServiceJobStatus(const ServiceJob *job_p)
Get the last retrieved OperationStatus of a ServiceJob.
void SetServiceJobCalculateResultFunction(ServiceJob *job_p, bool(*calculate_fn)(ServiceJob *job_p))
Set the function that a ServiceJob will use to calculate its results.
bool SetServiceJobName(ServiceJob *job_p, const char *const name_s)
Set the name of ServiceJob.
bool RemoveServiceJobFromServiceJobSet(ServiceJobSet *job_set_p, ServiceJob *job_p)
Remove a ServiceJob from a ServiceJobSet.
bool CopyServiceJob(const ServiceJob *src_p, ServiceJob *dest_p)
Make a deep copy of one ServiceJob to another.
OperationStatus GetServiceJobStatus(ServiceJob *job_p)
Get the Current OperationStatus of a ServiceJob.
bool InitServiceJob(ServiceJob *job_p, struct Service *service_p, const char *job_name_s, const char *job_description_s, bool(*update_fn)(struct ServiceJob *job_p), bool(*calculate_results_fn)(struct ServiceJob *job_p), void(*free_job_fn)(struct ServiceJob *job_p), uuid_t *id_p, const char *job_type_s)
Initialise a ServiceJob.
A doubly-linked list.
ListItem sjn_node
The node used to hold this in a LinkedList.
Definition: service_job.h:169
ServiceJobNode * AllocateServiceJobNode(ServiceJob *job_p)
Allocate a ServiceJobNode.
bool AddCompoundErrorToServiceJob(ServiceJob *job_p, const char *param_s, const ParameterType param_type, json_t *error_details_p)
Add a key-value pair error statement to a ServiceJob.
json_t * sj_metadata_p
The JSON fragment for any extra information for this ServiceJob.
Definition: service_job.h:100
ServiceJob * AllocateServiceJob(struct Service *service_p, const char *job_name_s, const char *job_description_s, bool(*update_fn)(struct ServiceJob *job_p), bool(*calculate_results_fn)(struct ServiceJob *job_p), void(*free_job_fn)(struct ServiceJob *job_p), const char *job_type_s)
Allocate a ServiceJob.
bool UpdateServiceJob(ServiceJob *job_p)
Update, if appropriate, a given ServiceJob.
A datatype which defines an available service, its capabilities and its parameters.
Definition: service.h:153
A doubly-linked list that can be traversed in either direction.
Definition: linked_list.h:56
void SetServiceJobUpdateFunction(ServiceJob *job_p, bool(*update_fn)(ServiceJob *job_p))
Set the function that a ServiceJob will use to update itself.
json_t * GetServiceJobAsJSON(ServiceJob *const job_p, bool omit_results_flag)
Get a ServiceJob as JSON.
ServiceJob * CreateServiceJobFromJSON(const json_t *job_json_p, GrassrootsServer *grassroots_p)
Create a ServiceJob from a json_t object.
ServiceJob * sjn_job_p
The ServiceJob.
Definition: service_job.h:172
void FreeServiceJobNode(ListItem *service_job_node_p)
Free a ServiceJobNode.
ServiceJobSet * AllocateSimpleServiceJobSet(struct Service *service_p, const char *job_name_s, const char *job_description_s)
Allocate a ServiceJobSet and populate it with a single ServiceJob.
bool AddResultToServiceJob(ServiceJob *job_p, json_t *result_p)
Add a result to ServiceJob.
ServiceJob * CreateServiceJobFromResultsJSON(const json_t *results_p, struct Service *service_p, const char *name_s, const char *description_s, OperationStatus status, const char *job_type_s)
Create a ServiceJob from a JSON Resource fragment.
LinkedList * sjs_jobs_p
The ServiceJobs that are in use for the Service.
Definition: service_job.h:188
struct Service * sj_service_p
The Service that is running this job.
Definition: service_job.h:75
struct Service * GetServiceFromServiceJob(ServiceJob *job_p)
Get the owning Service for a given ServiceJob.
void FreeBaseServiceJob(ServiceJob *job_p)
Free a ServiceJob ignoring if it is a subclass.
bool SetServiceJobDescription(ServiceJob *job_p, const char *const description_s)
Set the description of ServiceJob.
ServiceJob * CloneServiceJob(const ServiceJob *src_p)
Create a deep copy of a ServiceJob.
OperationStatus
The current status of an Operation.
Definition: operation.h:98
json_t * sj_result_p
The JSON fragment for the results of this ServiceJob.
Definition: service_job.h:95
char * sj_description_s
The description of the ServiceJob.
Definition: service_job.h:90
bool InitServiceJobFromJSON(ServiceJob *job_p, const json_t *json_p, struct Service *service_p, GrassrootsServer *grassroots_p)
Get a ServiceJob from a json_t object.
ServiceJobSet * AllocateServiceJobSet(struct Service *service_p)
Allocate a ServiceJobSet.
A datatype to represent a running task.
Definition: service_job.h:72
char * sj_service_name_s
The name of the Service that this ServiceJob is for.
Definition: service_job.h:84
ServiceJobNode * FindServiceJobNodeInServiceJobSet(const ServiceJobSet *job_set_p, const ServiceJob *job_p)
Find the ServiceJobNode for a given ServiceJob within a ServiceJobSet.
bool CloseServiceJob(ServiceJob *job_p)
Close a ServiceJob.
ServiceJobNode * FindServiceJobNodeByUUIDInServiceJobSet(const ServiceJobSet *job_set_p, const uuid_t job_id)
Find the ServiceJobNode for a ServiceJob with a given uuid within a ServiceJobSet.
void SetServiceJobUUID(ServiceJob *job_p, const uuid_t new_job_id)
Replace the uuid for a given ServiceJob.
void FreeServiceJobSet(ServiceJobSet *job_set_p)
Free a ServiceJobSet.
void(* sj_free_fn)(struct ServiceJob *job_p)
The callback function to use when freeing this ServiceJob.
Definition: service_job.h:130
A datatype used to store a ServiceJob within a ServceJobSet using a LinkedList.
Definition: service_job.h:166
Definition: grassroots_server.h:44
bool RemoveServiceJobByUUIDFromServiceJobSet(ServiceJobSet *job_set_p, uuid_t job_id)
Remove a ServiceJob with a given uuid from a ServiceJobSet.
ServiceJob * GetServiceJobFromServiceJobSetById(const ServiceJobSet *jobs_p, const uuid_t job_id)
Search a ServiceJobSet for ServiceJob.
json_t * sj_errors_p
The JSON fragment for any errors that have occurred whilst running this ServiceJob.
Definition: service_job.h:106
uint32 GetServiceJobSetSize(const ServiceJobSet *const jobs_p)
Get the number of ServiceJobs in a ServiceJobSet.
void SetServiceJobStatus(ServiceJob *job_p, OperationStatus status)
Set the current OperationStatus for a given ServiceJob.
void SetServiceJobFreeFunction(ServiceJob *job_p, void(*free_fn)(ServiceJob *job_p))
Set the function that a ServiceJob will use to free itself.
bool ProcessServiceJobSet(ServiceJobSet *jobs_p, json_t *res_p)
Process all ServiceJobs within a ServiceJobSet.
uuid_t sj_id
The unique identifier for this job.
Definition: service_job.h:78
bool ReplaceServiceJobResults(ServiceJob *job_p, json_t *results_p)
Replace the set of results for a given ServiceJob.
bool AddLinkedServiceToServiceJob(ServiceJob *job_p, struct LinkedService *linked_service_p)
Add a LinkedService to ServiceJob.
This datatype stores the data needed to get the required information from the output of one Service t...
Definition: linked_service.h:50
bool(* sj_update_fn)(struct ServiceJob *job_p)
The callback function to use when checking the status of this ServiceJob.
Definition: service_job.h:122
char * SerialiseServiceJobToJSON(ServiceJob *const job_p, bool omit_results_flag)
Save the ServiceJob to a persistent format that allows the ServiceJob to be recreated in a potentiall...
json_t * GetServiceJobSetAsJSON(const ServiceJobSet *jobs_p, bool omit_results_flag)
Get the json representation of a ServiceJobSet.
bool InitServiceJobFromResultsJSON(ServiceJob *job_p, const json_t *results_p, struct Service *service_p, const char *name_s, const char *description_s, OperationStatus status, const char *job_type_s)
Fill in the data for a ServiceJob from a given JSON fragement.
uint32 GetNumberOfServiceJobResults(const ServiceJob *job_p)
Get the number of results stored on a ServiceJob.
void ProcessLinkedServices(ServiceJob *job_p)
Attempt to extract the relevant data for all LinkedServices that the ServiceJob's Service has and sto...
char * sj_name_s
The name of the ServiceJob.
Definition: service_job.h:87