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.Job;
25 import org.opencastproject.job.api.Job.Status;
26 import org.opencastproject.serviceregistry.api.SystemLoad.NodeLoad;
27 import org.opencastproject.util.NotFoundException;
28
29 import java.util.List;
30 import java.util.Map;
31
32 /** Manages clustered services and the {@link Job}s they may create to enable asynchronous job handling. */
33 public interface ServiceRegistry {
34
35 /**
36 * Registers a host as a provider of Opencast services.
37 *
38 * @param host
39 * The base URL for this server
40 * @param address
41 * The IP address of this host
42 * @param nodeName
43 * Human readable description of this node
44 * @param memory
45 * The allocated memory of this host
46 * @param cores
47 * The available cores of this host
48 * @param maxLoad
49 * the maximum load this host can support
50 * @throws ServiceRegistryException
51 * if communication with the service registry fails
52 */
53 void registerHost(String host, String address, String nodeName, long memory, int cores, float maxLoad)
54 throws ServiceRegistryException;
55
56 /**
57 * Removes an Opencast server from service.
58 *
59 * @param host
60 * The base URL for this server
61 * @throws ServiceRegistryException
62 * if communication with the service registry fails
63 */
64 void unregisterHost(String host) throws ServiceRegistryException;
65
66 /**
67 * Enable an inactive host as a provider of Opencast services.
68 *
69 * @param host
70 * The base URL for this server
71 * @throws NotFoundException
72 * if the host does not exist
73 * @throws ServiceRegistryException
74 * if communication with the service registry fails
75 */
76 void enableHost(String host) throws ServiceRegistryException, NotFoundException;
77
78 /**
79 * Disables a Opencast server from service.
80 *
81 * @param host
82 * The base URL for this server
83 * @throws NotFoundException
84 * if the host does not exist
85 * @throws ServiceRegistryException
86 * if communication with the service registry fails
87 */
88 void disableHost(String host) throws ServiceRegistryException, NotFoundException;
89
90 /**
91 * Returns the maximum load that can be handled by the currently registered hosts.
92 * Note that this load is *not* 1-to-1 equivalent with number of jobs. A job may take up more than one load.
93 *
94 * @return the total load that can be processed concurrently
95 * @throws ServiceRegistryException
96 * if communication with the service registry fails
97 */
98 SystemLoad getMaxLoads() throws ServiceRegistryException;
99
100 /**
101 * Returns the maximum load that can be handled by a given node.
102 * Note that this load is *not* 1-to-1 equivalent with number of jobs. A job may take up more than one load.
103 *
104 * @param host
105 * The base URL for this server
106 *
107 * @return the total load that can be processed concurrently on that node
108 * @throws ServiceRegistryException
109 * if communication with the service registry fails
110 */
111 NodeLoad getMaxLoadOnNode(String host) throws ServiceRegistryException, NotFoundException;
112
113 /**
114 * Gets a map of hosts to the number of jobs currently loading that host
115 *
116 * @return the map of hosts to job counts
117 */
118 SystemLoad getCurrentHostLoads() throws ServiceRegistryException;
119
120 /**
121 * Gets the load value for the current host (ie, the host this service registry lives on
122 *
123 * @return the load value for this host
124 */
125 float getOwnLoad() throws ServiceRegistryException;
126
127 /**
128 * Registers a host to handle a specific type of job
129 *
130 * @param serviceType
131 * The job type
132 * @param host
133 * The base URL where the service that can handle this service type can be found
134 * @param path
135 * The path to the service endpoint
136 * @return the service registration
137 * @throws ServiceRegistryException
138 * if communication with the service registry fails
139 */
140 ServiceRegistration registerService(String serviceType, String host, String path) throws ServiceRegistryException;
141
142 /**
143 * Registers a host to handle a specific type of job
144 *
145 * @param serviceType
146 * The service type
147 * @param host
148 * The base URL where the service that can handle this job type can be found
149 * @param path
150 * The path to the service endpoint
151 * @param jobProducer
152 * Whether this service registration produces {@link Job}s to track long running operations
153 * @return the service registration
154 * @throws ServiceRegistryException
155 * if communication with the service registry fails
156 */
157 ServiceRegistration registerService(String serviceType, String host, String path, boolean jobProducer)
158 throws ServiceRegistryException;
159
160 /**
161 * Unregisters a host from handling a specific type of job
162 *
163 * @param serviceType
164 * The service type
165 * @param host
166 * The base URL where the service that can handle this job type can be found
167 * @throws ServiceRegistryException
168 * if communication with the service registry fails
169 */
170 void unRegisterService(String serviceType, String host) throws ServiceRegistryException;
171
172 /**
173 * Sets a registered host's maintenance status
174 *
175 * @param host
176 * The base URL where the service that can handle this service type can be found
177 * @param maintenance
178 * the new maintenance status for this service
179 * @throws ServiceRegistryException
180 * if communication with the service registry fails
181 * @throws NotFoundException
182 * if the host does not exist
183 */
184 void setMaintenanceStatus(String host, boolean maintenance) throws ServiceRegistryException, NotFoundException;
185
186 /**
187 * Create and store a new job that will be dispatched as soon as possible. This is equivalent to calling
188 * {@link #createJob(String, String, List, String, boolean)} with an empty argument list.
189 * <p>
190 * Note that this job will be linked to the current job as its parent.
191 * </p>
192 *
193 * @param type
194 * the type of service responsible for this job
195 * @param operation
196 * the operation for this service to run
197 * @return the job
198 * @throws ServiceRegistryException
199 * if there is a problem creating the job
200 */
201 Job createJob(String type, String operation) throws ServiceRegistryException;
202
203 /**
204 * Create and store a new job that will be dispatched as soon as possible. This is equivalent to calling
205 * {@link #createJob(String, String, List, String, boolean)}.
206 * <p>
207 * Note that this job will be linked to the current job as its parent.
208 * </p>
209 *
210 * @param type
211 * the type of service responsible for this job
212 * @param operation
213 * the operation for this service to run
214 * @param arguments
215 * the arguments to the operation
216 * @return the job
217 * @throws ServiceRegistryException
218 * if there is a problem creating the job
219 */
220 Job createJob(String type, String operation, List<String> arguments) throws ServiceRegistryException;
221
222 /**
223 * Create and store a new job that will be dispatched as soon as possible. This is equivalent to calling
224 * {@link #createJob(String, String, List, String, boolean)}.
225 * <p>
226 * Note that this job will be linked to the current job as its parent.
227 * </p>
228 *
229 * @param type
230 * the type of service responsible for this job
231 * @param operation
232 * the operation for this service to run
233 * @param arguments
234 * the arguments to the operation
235 * @param jobLoad
236 * the load caused by this job, roughly equivalent to the number of cores used this job
237 * @return the job
238 * @throws ServiceRegistryException
239 * if there is a problem creating the job
240 */
241 Job createJob(String type, String operation, List<String> arguments, Float jobLoad) throws ServiceRegistryException;
242
243 /**
244 * Create and store a new job. If <code>enqueueImmediately</code> is true, the job will be in the
245 * {@link Status#QUEUED} state and will be dispatched as soon as possible. Otherwise, it will be
246 * {@link Status#INSTANTIATED}.
247 * <p>
248 * Note that this job will be linked to the current job as its parent.
249 * </p>
250 *
251 * @param type
252 * the type of service responsible for this job
253 * @param operation
254 * the operation for this service to run
255 * @param arguments
256 * the arguments to the operation
257 * @param payload
258 * an optional initial payload
259 * @param queueable
260 * whether the job can be enqueued for dispatch. If false, the job's initial state will be
261 * {@link Status#INSTANTIATED} and will not be dispatched.
262 * @return the job
263 * @throws ServiceRegistryException
264 * if there is a problem creating the job
265 */
266 Job createJob(String type, String operation, List<String> arguments, String payload, boolean queueable)
267 throws ServiceRegistryException;
268
269 /**
270 * Create and store a new job. If <code>enqueueImmediately</code> is true, the job will be in the
271 * {@link Status#QUEUED} state and will be dispatched as soon as possible. Otherwise, it will be
272 * {@link Status#INSTANTIATED}.
273 * <p>
274 * Note that this job will be linked to the current job as its parent.
275 * </p>
276 *
277 * @param type
278 * the type of service responsible for this job
279 * @param operation
280 * the operation for this service to run
281 * @param arguments
282 * the arguments to the operation
283 * @param payload
284 * an optional initial payload
285 * @param queueable
286 * whether the job can be enqueued for dispatch. If false, the job's initial state will be
287 * {@link Status#INSTANTIATED} and will not be dispatched.
288 * @param jobLoad
289 * the load caused by this job, roughly equivalent to the number of cores used this job
290 * @return the job
291 * @throws ServiceRegistryException
292 * if there is a problem creating the job
293 */
294 Job createJob(String type, String operation, List<String> arguments, String payload, boolean queueable, Float jobLoad)
295 throws ServiceRegistryException;
296
297 /**
298 * Create and store a new job. If <code>enqueueImmediately</code> is true, the job will be in the
299 * {@link Status#QUEUED} state and will be dispatched as soon as possible. Otherwise, it will be
300 * {@link Status#INSTANTIATED}.
301 *
302 * @param type
303 * the type of service responsible for this job
304 * @param operation
305 * the operation for this service to run
306 * @param arguments
307 * the arguments to the operation
308 * @param payload
309 * an optional initial payload
310 * @param queueable
311 * whether the job can be enqueued for dispatch. If false, the job's initial state will be
312 * {@link Status#INSTANTIATED} and will not be dispatched.
313 * @param parentJob
314 * the parent job
315 * @param jobLoad
316 * the load caused by this job, roughly equivalent to the number of cores used this job
317 * @return the job
318 * @throws ServiceRegistryException
319 * if there is a problem creating the job
320 */
321 Job createJob(String type, String operation, List<String> arguments, String payload, boolean queueable, Job parentJob,
322 Float jobLoad)
323 throws ServiceRegistryException;
324
325 /**
326 * Update the job in the database
327 *
328 * @param job
329 * @return the updated job
330 * @throws NotFoundException
331 * if the job does not exist
332 * @throws ServiceRegistryException
333 * if there is a problem updating the job
334 */
335 Job updateJob(Job job) throws NotFoundException, ServiceRegistryException;
336
337 /**
338 * Gets a receipt by its ID, or null if not found
339 *
340 * @param id
341 * the job id
342 * @return the job or null
343 */
344 Job getJob(long id) throws NotFoundException, ServiceRegistryException;
345
346 /**
347 * Deletes the given jobs from the service registry
348 *
349 * @param ids
350 * the job ids
351 */
352 void removeJobs(List<Long> ids) throws NotFoundException, ServiceRegistryException;
353
354 /**
355 * Removes all jobs which do not have a parent job (except workflow instance jobs) and which have passed their
356 * lifetime.
357 *
358 * @param lifetime
359 * lifetime in days
360 * @throws ServiceRegistryException
361 * if removing the jobs fails
362 */
363 void removeParentlessJobs(int lifetime) throws ServiceRegistryException;
364
365 /**
366 * Gets the current running job
367 *
368 * @return the current job
369 */
370 Job getCurrentJob();
371
372 /**
373 * Sets the current running job
374 *
375 * @param job
376 * the current job
377 */
378 void setCurrentJob(Job job);
379
380 /**
381 * Gets the list of jobs that match the specified parameters.
382 *
383 * @param serviceType
384 * The jobs run by this type of service. If null, jobs from all hosts will be returned.
385 * @param status
386 * The status of the jobs. If null, jobs in all status will be returned.
387 * @return the jobs matching these criteria
388 * @throws ServiceRegistryException
389 * if there is a problem accessing the service registry
390 */
391 List<Job> getJobs(String serviceType, Status status) throws ServiceRegistryException;
392
393 /**
394 * Return the payload of all jobs for a specified operation type.
395 *
396 * @param operation
397 * Operation type to get payload for
398 * @return Serialized workflows
399 * @throws ServiceRegistryException
400 * if there is a problem accessing the service registry
401 */
402 List<String> getJobPayloads(String operation) throws ServiceRegistryException;
403
404 /**
405 * Return the payload of a specified number of jobs for a specified operation type.
406 *
407 * @param operation
408 * Operation type to get payload for
409 * @param limit
410 * How many results to return
411 * @param offset
412 * Offset for the set of returned results
413 * @return Serialized workflows
414 * @throws ServiceRegistryException
415 * if there is a problem accessing the service registry
416 */
417 List<String> getJobPayloads(String operation, int limit, int offset) throws ServiceRegistryException;
418
419 /**
420 * Return the number of jobs for a specified operation type.
421 *
422 * @param operation
423 * Operation type to check for
424 * @return Number of jobs for the specified operation type.
425 * @throws ServiceRegistryException
426 */
427 int getJobCount(String operation) throws ServiceRegistryException;
428
429 /**
430 * Get the list of active jobs.
431 *
432 * @return list of active jobs
433 * @throws ServiceRegistryException if there is a problem accessing the service registry
434 */
435 List<Job> getActiveJobs() throws ServiceRegistryException;
436
437 /**
438 * Get all child jobs from a job
439 *
440 * @param id
441 * the parent job id
442 * @return a list of the child jobs ordered by execution
443 * @throws ServiceRegistryException
444 * if there is a problem accessing the service registry
445 */
446 List<Job> getChildJobs(long id) throws ServiceRegistryException;
447
448 /**
449 * Return a facility to record job incidents.
450 *
451 * @see org.opencastproject.job.api.Incident
452 */
453 Incidents incident();
454
455 /**
456 * Finds the service registrations for this kind of job, ordered by load (lightest to heaviest).
457 *
458 * @param serviceType
459 * The type of service that must be handled by the hosts
460 * @return A list of hosts that handle this job type, in order of their running and queued job load
461 * @throws ServiceRegistryException
462 * if there is a problem accessing the service registry
463 */
464 List<ServiceRegistration> getServiceRegistrationsByLoad(String serviceType) throws ServiceRegistryException;
465
466 /**
467 * Finds the service registrations for this kind of job, including offline services and those in maintenance mode.
468 *
469 * @param serviceType
470 * The type of service that must be handled by the hosts
471 * @return A list of hosts that handle this job type
472 * @throws ServiceRegistryException
473 * if there is a problem accessing the service registry
474 */
475 List<ServiceRegistration> getServiceRegistrationsByType(String serviceType) throws ServiceRegistryException;
476
477 /**
478 * Finds the service registrations on the given host, including offline services and those in maintenance mode.
479 *
480 * @param host
481 * The host
482 * @return A list of service registrations on a single host
483 * @throws ServiceRegistryException
484 * if there is a problem accessing the service registry
485 */
486 List<ServiceRegistration> getServiceRegistrationsByHost(String host) throws ServiceRegistryException;
487
488 /**
489 * Finds a single service registration by host and type, even if the service is offline or in maintenance mode.
490 *
491 * @param serviceType
492 * The type of service
493 * @param host
494 * the base URL of the host
495 * @return The service registration, or null
496 * @throws ServiceRegistryException
497 * if there is a problem accessing the service registry
498 */
499 ServiceRegistration getServiceRegistration(String serviceType, String host) throws ServiceRegistryException;
500
501 /**
502 * Finds all service registrations, including offline services and those in maintenance mode.
503 *
504 * @return A list of service registrations
505 * @throws ServiceRegistryException
506 * if there is a problem accessing the service registry
507 */
508 List<ServiceRegistration> getServiceRegistrations() throws ServiceRegistryException;
509
510 /**
511 * Returns the service regstry's hostname. This can be used to fetch the list of services on the local host.
512 *
513 * @return The hostname that the service registry is running on.
514 */
515 String getRegistryHostname();
516
517 /**
518 * Finds all host registrations, including offline hosts and those in maintenance mode.
519 *
520 * @return A list of host registrations
521 * @throws ServiceRegistryException
522 * if there is a problem accessing the service registry
523 */
524 List<HostRegistration> getHostRegistrations() throws ServiceRegistryException;
525
526 /**
527 * Get statistics about jobs active on hosts.
528 *
529 * @return Host statistics
530 */
531 HostStatistics getHostStatistics();
532
533 /**
534 * Finds host registration for the given hostname.
535 *
536 * @param hostname to lookup
537 * @return host registrations
538 * @throws ServiceRegistryException
539 * if there is a problem accessing the service registry or the hostname is not found
540 */
541 HostRegistration getHostRegistration(String hostname) throws ServiceRegistryException;
542
543 /**
544 * Gets performance and runtime statistics for each known service registration.
545 *
546 * @return the service statistics
547 * @throws ServiceRegistryException
548 * if there is a problem accessing the service registry
549 */
550 List<ServiceStatistics> getServiceStatistics() throws ServiceRegistryException;
551
552 /**
553 * Count the number of jobs that match the specified parameters.
554 *
555 * @param serviceType
556 * The jobs run by this type of service. If null, the returned count will refer to all types of jobs.
557 * @param status
558 * The status of the receipts. If null, the returned count will refer to jobs in any status.
559 * @return the number of jobs
560 * @throws ServiceRegistryException
561 * if there is a problem accessing the service registry
562 */
563 long count(String serviceType, Status status) throws ServiceRegistryException;
564
565 /**
566 * Count the number of jobs running the given operation in this {@link Status}.
567 *
568 * @param serviceType
569 * The jobs run by this type of service
570 * @param operation
571 * the operation
572 * @param status
573 * The status of the jobs
574 * @return the number of jobs
575 * @throws ServiceRegistryException
576 * if there is a problem accessing the service registry
577 */
578 long countByOperation(String serviceType, String operation, Status status) throws ServiceRegistryException;
579
580 /**
581 * Count the number of jobs in this {@link Status} on this host
582 *
583 * @param serviceType
584 * The jobs run by this type of service
585 * @param host
586 * The server that created and will be handling the job
587 * @param status
588 * The status of the jobs
589 * @return the number of jobs
590 * @throws ServiceRegistryException
591 * if there is a problem accessing the service registry
592 */
593 long countByHost(String serviceType, String host, Status status) throws ServiceRegistryException;
594
595 /**
596 * Count the number of jobs executing the given operation in this {@link Status} on this host.
597 *
598 * @param serviceType
599 * The jobs run by this type of service
600 * @param host
601 * The server that created and will be handling the job
602 * @param operation
603 * the operation
604 * @param status
605 * The status of the jobs
606 * @return the number of jobs
607 * @throws ServiceRegistryException
608 * if there is a problem accessing the service registry
609 */
610 long count(String serviceType, String host, String operation, Status status) throws ServiceRegistryException;
611
612 /**
613 * Count active jobs and group them by organization and host.
614 *
615 * @return Map of organizations, hosts and the number of jobs.
616 */
617 Map<String, Map<String, Long>> countActiveByOrganizationAndHost();
618
619 /**
620 * Count active jobs of a given operation type and group them by organization.
621 *
622 * @return Map of organizations and the number of jobs.
623 */
624 Map<String, Long> countActiveTypeByOrganization(String operation);
625
626 /**
627 * Sets the given service to NORMAL state
628 *
629 * @param serviceType
630 * the service type
631 * @param host
632 * the host
633 * @throws NotFoundException
634 * if the service does not exist
635 */
636 void sanitize(String serviceType, String host) throws NotFoundException;
637
638 }