1 /*
2 * Licensed to The Apereo Foundation under one or more contributor license
3 * agreements. See the NOTICE file distributed with this work for additional
4 * information regarding copyright ownership.
5 *
6 *
7 * The Apereo Foundation licenses this file to you under the Educational
8 * Community License, Version 2.0 (the "License"); you may not use this file
9 * except in compliance with the License. You may obtain a copy of the License
10 * at:
11 *
12 * http://opensource.org/licenses/ecl2.txt
13 *
14 * Unless required by applicable law or agreed to in writing, software
15 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
16 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
17 * License for the specific language governing permissions and limitations under
18 * the License.
19 *
20 */
21
22 package org.opencastproject.serviceregistry.api;
23
24 import org.opencastproject.job.api.Incident;
25 import org.opencastproject.job.api.IncidentTree;
26 import org.opencastproject.job.api.Job;
27 import org.opencastproject.util.NotFoundException;
28 import org.opencastproject.util.data.Tuple;
29
30 import java.util.Date;
31 import java.util.List;
32 import java.util.Locale;
33 import java.util.Map;
34
35 /** Manages storing and retrieving of job incidents. */
36 public interface IncidentService {
37 /**
38 * Identifier for service registration and location
39 */
40 String JOB_TYPE = "org.opencastproject.incident";
41
42 /**
43 * Stores a new job incident.
44 *
45 * @throws IllegalStateException
46 * if no job related job exists
47 * @throws IncidentServiceException
48 * if there is a problem communicating with the underlying data store
49 */
50 Incident storeIncident(Job job, Date timestamp, String code, Incident.Severity severity,
51 Map<String, String> descriptionParameters, List<Tuple<String, String>> details)
52 throws IncidentServiceException, IllegalStateException;
53
54 /**
55 * Gets a job incident by a given incident identifier.
56 *
57 * @param id
58 * the incident indentifier
59 * @return the job incident
60 * @throws IncidentServiceException
61 * if there is a problem communicating with the underlying data store
62 * @throws NotFoundException
63 * if there is no job incident with this incident identifier
64 */
65 Incident getIncident(long id) throws IncidentServiceException, NotFoundException;
66
67 /**
68 * Get the hierarchy of incidents for a given job identifier.
69 *
70 * @param jobId
71 * the job identifier
72 * @param cascade
73 * if true, return the incidents of the given job and those of of its descendants; if false, just return the
74 * incidents of the given job, which means that the list returned by
75 * {@link org.opencastproject.job.api.IncidentTree#getDescendants()} will always be empty
76 * @return the list of incidents
77 * @throws NotFoundException
78 * if there is no incident with this job identifier
79 * @throws IncidentServiceException
80 * if there is a problem communicating with the underlying data store
81 */
82 IncidentTree getIncidentsOfJob(long jobId, boolean cascade) throws NotFoundException, IncidentServiceException;
83
84 /**
85 * Get the directly related incidents of all given jobs and return them concatenated into a single list. No incidents
86 * of any descendants will be returned.
87 *
88 * @param jobIds
89 * the job identifiers
90 * @return the concatenated list of directly related incidents
91 * @throws IncidentServiceException
92 * if there is a problem communicating with the underlying data store
93 */
94 List<Incident> getIncidentsOfJob(List<Long> jobIds) throws IncidentServiceException;
95
96 /**
97 * Gets the localized texts for an incident by a given incident identifier and locale. If there are no localized texts
98 * of the given locale, the default localized texts are returned.
99 *
100 * @param id
101 * the incident identifier
102 * @param locale
103 * the locale
104 * @return the incident localization
105 * @throws NotFoundException
106 * if there is no job incident with this incident identifier
107 * @throws IncidentServiceException
108 * if there is a problem communicating with the underlying data store
109 */
110 IncidentL10n getLocalization(long id, Locale locale) throws IncidentServiceException, NotFoundException;
111 }