org.opencastproject.serviceregistry.api

Interface ServiceRegistry

All Known Implementing Classes:

ServiceRegistryInMemoryImpl

public interface ServiceRegistry

Manages clustered services and the Jobs they may create to enable asynchronous job handling.

Method Summary

Modifier and Type	Method and Description
long	count(String serviceType, Job.Status status) Count the number of jobs that match the specified parameters.
long	count(String serviceType, String host, String operation, Job.Status status) Count the number of jobs executing the given operation in this Job.Status on this host.
long	countByHost(String serviceType, String host, Job.Status status) Count the number of jobs in this Job.Status on this host
long	countByOperation(String serviceType, String operation, Job.Status status) Count the number of jobs running the given operation in this Job.Status.
long	countOfAbnormalServices() Gets the count of the number of abnormal services across the whole system.
Job	createJob(String type, String operation) Create and store a new job that will be dispatched as soon as possible.
Job	createJob(String type, String operation, Float jobLoad) Create and store a new job that will be dispatched as soon as possible.
Job	createJob(String type, String operation, List<String> arguments) Create and store a new job that will be dispatched as soon as possible.
Job	createJob(String type, String operation, List<String> arguments, Float jobLoad) Create and store a new job that will be dispatched as soon as possible.
Job	createJob(String type, String operation, List<String> arguments, String payload) Create and store a new job that will be dispatched as soon as possible.
Job	createJob(String type, String operation, List<String> arguments, String payload, boolean queueable) Create and store a new job.
Job	createJob(String type, String operation, List<String> arguments, String payload, boolean queueable, Float jobLoad) Create and store a new job.
Job	createJob(String type, String operation, List<String> arguments, String payload, boolean queueable, Job parentJob) Create and store a new job.
Job	createJob(String type, String operation, List<String> arguments, String payload, boolean queueable, Job parentJob, Float jobLoad) Create and store a new job.
Job	createJob(String type, String operation, List<String> arguments, String payload, Float jobLoad) Create and store a new job that will be dispatched as soon as possible.
void	disableHost(String host) Disables a Opencast server from service.
void	enableHost(String host) Enable an inactive host as a provider of Opencast services.
List<Job>	getActiveJobs() Get the list of active jobs.
List<Job>	getChildJobs(long id) Get all child jobs from a job
SystemLoad	getCurrentHostLoads() Gets a map of hosts to the number of jobs currently loading that host
Job	getCurrentJob() Gets the current running job
HostRegistration	getHostRegistration(String hostname) Finds host registration for the given hostname.
List<HostRegistration>	getHostRegistrations() Finds all host registrations, including offline hosts and those in maintenance mode.
Job	getJob(long id) Gets a receipt by its ID, or null if not found
int	getJobCount(String operation) Return the number of jobs for a specified operation type.
List<String>	getJobPayloads(String operation) Return the payload of all jobs for a specified operation type.
List<String>	getJobPayloads(String operation, int limit, int offset) Return the payload of a specified number of jobs for a specified operation type.
List<Job>	getJobs(String serviceType, Job.Status status) Gets the list of jobs that match the specified parameters.
SystemLoad.NodeLoad	getMaxLoadOnNode(String host) Returns the maximum load that can be handled by a given node.
SystemLoad	getMaxLoads() Returns the maximum load that can be handled by the currently registered hosts.
float	getOwnLoad() Gets the load value for the current host (ie, the host this service registry lives on
String	getRegistryHostname() Returns the service regstry's hostname.
ServiceRegistration	getServiceRegistration(String serviceType, String host) Finds a single service registration by host and type, even if the service is offline or in maintenance mode.
List<ServiceRegistration>	getServiceRegistrations() Finds all service registrations, including offline services and those in maintenance mode.
List<ServiceRegistration>	getServiceRegistrationsByHost(String host) Finds the service registrations on the given host, including offline services and those in maintenance mode.
List<ServiceRegistration>	getServiceRegistrationsByLoad(String serviceType) Finds the service registrations for this kind of job, ordered by load (lightest to heaviest).
List<ServiceRegistration>	getServiceRegistrationsByType(String serviceType) Finds the service registrations for this kind of job, including offline services and those in maintenance mode.
List<ServiceStatistics>	getServiceStatistics() Gets performance and runtime statistics for each known service registration.
Incidents	incident() Return a facility to record job incidents.
void	registerHost(String host, String address, String nodeName, long memory, int cores, float maxLoad) Registers a host as a provider of Opencast services.
ServiceRegistration	registerService(String serviceType, String host, String path) Registers a host to handle a specific type of job
ServiceRegistration	registerService(String serviceType, String host, String path, boolean jobProducer) Registers a host to handle a specific type of job
void	removeJobs(List<Long> ids) Deletes the given jobs from the service registry
void	removeParentlessJobs(int lifetime) Removes all jobs which do not have a parent job (except workflow instance jobs) and which have passed their lifetime.
void	sanitize(String serviceType, String host) Sets the given service to NORMAL state
void	setCurrentJob(Job job) Sets the current running job
void	setMaintenanceStatus(String host, boolean maintenance) Sets a registered host's maintenance status
void	unregisterHost(String host) Removes an Opencast server from service.
void	unRegisterService(String serviceType, String host) Unregisters a host from handling a specific type of job
Job	updateJob(Job job) Update the job in the database

Method Detail

registerHost

void registerHost(String host,
                  String address,
                  String nodeName,
                  long memory,
                  int cores,
                  float maxLoad)
           throws ServiceRegistryException

Registers a host as a provider of Opencast services.

Parameters:

host - The base URL for this server

address - The IP address of this host

nodeName - Human readable description of this node

memory - The allocated memory of this host

cores - The available cores of this host

maxLoad - the maximum load this host can support

Throws:

ServiceRegistryException - if communication with the service registry fails

unregisterHost

void unregisterHost(String host)
             throws ServiceRegistryException

Removes an Opencast server from service.

Parameters:

host - The base URL for this server

Throws:

ServiceRegistryException - if communication with the service registry fails

enableHost

void enableHost(String host)
         throws ServiceRegistryException,
                NotFoundException

Enable an inactive host as a provider of Opencast services.

Parameters:

host - The base URL for this server

Throws:

NotFoundException - if the host does not exist

ServiceRegistryException - if communication with the service registry fails

disableHost

void disableHost(String host)
          throws ServiceRegistryException,
                 NotFoundException

Disables a Opencast server from service.

Parameters:

host - The base URL for this server

Throws:

NotFoundException - if the host does not exist

ServiceRegistryException - if communication with the service registry fails

getMaxLoads

SystemLoad getMaxLoads()
                throws ServiceRegistryException

Returns the maximum load that can be handled by the currently registered hosts. Note that this load is *not* 1-to-1 equivalent with number of jobs. A job may take up more than one load.

Returns:

the total load that can be processed concurrently

Throws:

ServiceRegistryException - if communication with the service registry fails

getMaxLoadOnNode

SystemLoad.NodeLoad getMaxLoadOnNode(String host)
                              throws ServiceRegistryException,
                                     NotFoundException

Returns the maximum load that can be handled by a given node. Note that this load is *not* 1-to-1 equivalent with number of jobs. A job may take up more than one load.

Parameters:

host - The base URL for this server

Returns:

the total load that can be processed concurrently on that node

Throws:

ServiceRegistryException - if communication with the service registry fails

NotFoundException

getCurrentHostLoads

SystemLoad getCurrentHostLoads()
                        throws ServiceRegistryException

Gets a map of hosts to the number of jobs currently loading that host

Returns:

the map of hosts to job counts

Throws:

ServiceRegistryException

getOwnLoad

float getOwnLoad()
          throws ServiceRegistryException

Gets the load value for the current host (ie, the host this service registry lives on

Returns:

the load value for this host

Throws:

ServiceRegistryException

registerService

ServiceRegistration registerService(String serviceType,
                                    String host,
                                    String path)
                             throws ServiceRegistryException

Registers a host to handle a specific type of job

Parameters:

serviceType - The job type

host - The base URL where the service that can handle this service type can be found

path - The path to the service endpoint

Returns:

the service registration

Throws:

ServiceRegistryException - if communication with the service registry fails

registerService

ServiceRegistration registerService(String serviceType,
                                    String host,
                                    String path,
                                    boolean jobProducer)
                             throws ServiceRegistryException

Registers a host to handle a specific type of job

Parameters:

serviceType - The service type

host - The base URL where the service that can handle this job type can be found

path - The path to the service endpoint

jobProducer - Whether this service registration produces Jobs to track long running operations

Returns:

the service registration

Throws:

ServiceRegistryException - if communication with the service registry fails

unRegisterService

void unRegisterService(String serviceType,
                       String host)
                throws ServiceRegistryException

Unregisters a host from handling a specific type of job

Parameters:

serviceType - The service type

host - The base URL where the service that can handle this job type can be found

Throws:

ServiceRegistryException - if communication with the service registry fails

setMaintenanceStatus

void setMaintenanceStatus(String host,
                          boolean maintenance)
                   throws ServiceRegistryException,
                          NotFoundException

Sets a registered host's maintenance status

Parameters:

host - The base URL where the service that can handle this service type can be found

maintenance - the new maintenance status for this service

Throws:

ServiceRegistryException - if communication with the service registry fails

NotFoundException - if the host does not exist

createJob

Job createJob(String type,
              String operation)
       throws ServiceRegistryException

Create and store a new job that will be dispatched as soon as possible. This is equivalent to calling createJob(String, String, List, String, boolean) with an empty argument list.

Note that this job will be linked to the current job as its parent. Use createJob(String, String, List, String, boolean, Job) and pass null as the job if you don't need the link.

Parameters:

type - the type of service responsible for this job

operation - the operation for this service to run

Returns:

the job

Throws:

ServiceRegistryException - if there is a problem creating the job

createJob

Job createJob(String type,
              String operation,
              Float jobLoad)
       throws ServiceRegistryException

Create and store a new job that will be dispatched as soon as possible. This is equivalent to calling createJob(String, String, List, String, boolean) with an empty argument list.

Note that this job will be linked to the current job as its parent. Use createJob(String, String, List, String, boolean, Job) and pass null as the job if you don't need the link.

Parameters:

type - the type of service responsible for this job

operation - the operation for this service to run

jobLoad - the load caused by this job, roughly equivalent to the number of cores used this job

Returns:

the job

Throws:

ServiceRegistryException - if there is a problem creating the job

createJob

Job createJob(String type,
              String operation,
              List<String> arguments)
       throws ServiceRegistryException

Create and store a new job that will be dispatched as soon as possible. This is equivalent to calling createJob(String, String, List, String, boolean).

Note that this job will be linked to the current job as its parent. Use createJob(String, String, List, String, boolean, Job) and pass null as the job if you don't need the link.

Parameters:

type - the type of service responsible for this job

operation - the operation for this service to run

arguments - the arguments to the operation

Returns:

the job

Throws:

ServiceRegistryException - if there is a problem creating the job

createJob

Job createJob(String type,
              String operation,
              List<String> arguments,
              Float jobLoad)
       throws ServiceRegistryException

Create and store a new job that will be dispatched as soon as possible. This is equivalent to calling createJob(String, String, List, String, boolean).

Note that this job will be linked to the current job as its parent. Use createJob(String, String, List, String, boolean, Job) and pass null as the job if you don't need the link.

Parameters:

type - the type of service responsible for this job

operation - the operation for this service to run

arguments - the arguments to the operation

jobLoad - the load caused by this job, roughly equivalent to the number of cores used this job

Returns:

the job

Throws:

ServiceRegistryException - if there is a problem creating the job

createJob

Job createJob(String type,
              String operation,
              List<String> arguments,
              String payload)
       throws ServiceRegistryException

Create and store a new job that will be dispatched as soon as possible. This is equivalent to calling createJob(String, String, List, String, boolean). The job will carry the given payload from the beginning.

Note that this job will be linked to the current job as its parent. Use createJob(String, String, List, String, boolean, Job) and pass null as the job if you don't need the link.

Parameters:

type - the type of service responsible for this job

operation - the operation for this service to run

arguments - the arguments to the operation

payload - an optional initial payload

Returns:

the job

Throws:

ServiceRegistryException - if there is a problem creating the job

createJob

Job createJob(String type,
              String operation,
              List<String> arguments,
              String payload,
              Float jobLoad)
       throws ServiceRegistryException

Create and store a new job that will be dispatched as soon as possible. This is equivalent to calling createJob(String, String, List, String, boolean). The job will carry the given payload from the beginning.

Note that this job will be linked to the current job as its parent. Use createJob(String, String, List, String, boolean, Job) and pass null as the job if you don't need the link.

Parameters:

type - the type of service responsible for this job

operation - the operation for this service to run

arguments - the arguments to the operation

payload - an optional initial payload

jobLoad - the load caused by this job, roughly equivalent to the number of cores used this job

Returns:

the job

Throws:

ServiceRegistryException - if there is a problem creating the job

createJob

Job createJob(String type,
              String operation,
              List<String> arguments,
              String payload,
              boolean queueable)
       throws ServiceRegistryException

Create and store a new job. If enqueueImmediately is true, the job will be in the Job.Status.QUEUED state and will be dispatched as soon as possible. Otherwise, it will be Job.Status.INSTANTIATED.

Note that this job will be linked to the current job as its parent. Use createJob(String, String, List, String, boolean, Job) and pass null as the job if you don't need the link.

Parameters:

type - the type of service responsible for this job

operation - the operation for this service to run

arguments - the arguments to the operation

payload - an optional initial payload

queueable - whether the job can be enqueued for dispatch. If false, the job's initial state will be Job.Status.INSTANTIATED and will not be dispatched.

Returns:

the job

Throws:

ServiceRegistryException - if there is a problem creating the job

createJob

Job createJob(String type,
              String operation,
              List<String> arguments,
              String payload,
              boolean queueable,
              Float jobLoad)
       throws ServiceRegistryException

Create and store a new job. If enqueueImmediately is true, the job will be in the Job.Status.QUEUED state and will be dispatched as soon as possible. Otherwise, it will be Job.Status.INSTANTIATED.

Note that this job will be linked to the current job as its parent. Use createJob(String, String, List, String, boolean, Job) and pass null as the job if you don't need the link.

Parameters:

type - the type of service responsible for this job

operation - the operation for this service to run

arguments - the arguments to the operation

payload - an optional initial payload

queueable - whether the job can be enqueued for dispatch. If false, the job's initial state will be Job.Status.INSTANTIATED and will not be dispatched.

jobLoad - the load caused by this job, roughly equivalent to the number of cores used this job

Returns:

the job

Throws:

ServiceRegistryException - if there is a problem creating the job

createJob

Job createJob(String type,
              String operation,
              List<String> arguments,
              String payload,
              boolean queueable,
              Job parentJob)
       throws ServiceRegistryException

Create and store a new job. If enqueueImmediately is true, the job will be in the Job.Status.QUEUED state and will be dispatched as soon as possible. Otherwise, it will be Job.Status.INSTANTIATED.

Parameters:

type - the type of service responsible for this job

operation - the operation for this service to run

arguments - the arguments to the operation

payload - an optional initial payload

queueable - whether the job can be enqueued for dispatch. If false, the job's initial state will be Job.Status.INSTANTIATED and will not be dispatched.

parentJob - the parent job

Returns:

the job

Throws:

ServiceRegistryException - if there is a problem creating the job

createJob

Job createJob(String type,
              String operation,
              List<String> arguments,
              String payload,
              boolean queueable,
              Job parentJob,
              Float jobLoad)
       throws ServiceRegistryException

Create and store a new job. If enqueueImmediately is true, the job will be in the Job.Status.QUEUED state and will be dispatched as soon as possible. Otherwise, it will be Job.Status.INSTANTIATED.

Parameters:

type - the type of service responsible for this job

operation - the operation for this service to run

arguments - the arguments to the operation

payload - an optional initial payload

queueable - whether the job can be enqueued for dispatch. If false, the job's initial state will be Job.Status.INSTANTIATED and will not be dispatched.

parentJob - the parent job

jobLoad - the load caused by this job, roughly equivalent to the number of cores used this job

Returns:

the job

Throws:

ServiceRegistryException - if there is a problem creating the job

updateJob

Job updateJob(Job job)
       throws NotFoundException,
              ServiceRegistryException

Update the job in the database

Parameters:

job -

Returns:

the updated job

Throws:

NotFoundException - if the job does not exist

ServiceRegistryException - if there is a problem updating the job

getJob

Job getJob(long id)
    throws NotFoundException,
           ServiceRegistryException

Gets a receipt by its ID, or null if not found

Parameters:

id - the job id

Returns:

the job or null

Throws:

NotFoundException

ServiceRegistryException

removeJobs

void removeJobs(List<Long> ids)
         throws NotFoundException,
                ServiceRegistryException

Deletes the given jobs from the service registry

Parameters:

ids - the job ids

Throws:

NotFoundException

ServiceRegistryException

removeParentlessJobs

void removeParentlessJobs(int lifetime)
                   throws ServiceRegistryException

Removes all jobs which do not have a parent job (except workflow instance jobs) and which have passed their lifetime.

Parameters:

lifetime - lifetime in days

Throws:

ServiceRegistryException - if removing the jobs fails

getCurrentJob

Job getCurrentJob()

Gets the current running job

Returns:

the current job

setCurrentJob

void setCurrentJob(Job job)

Sets the current running job

Parameters:

job - the current job

getJobs

List<Job> getJobs(String serviceType,
                  Job.Status status)
           throws ServiceRegistryException

Gets the list of jobs that match the specified parameters.

Parameters:

serviceType - The jobs run by this type of service. If null, jobs from all hosts will be returned.

status - The status of the jobs. If null, jobs in all status will be returned.

Returns:

the jobs matching these criteria

Throws:

ServiceRegistryException - if there is a problem accessing the service registry

getJobPayloads

List<String> getJobPayloads(String operation)
                     throws ServiceRegistryException

Return the payload of all jobs for a specified operation type.

Parameters:

operation - Operation type to get payload for

Returns:

Serialized workflows

Throws:

ServiceRegistryException - if there is a problem accessing the service registry

getJobPayloads

List<String> getJobPayloads(String operation,
                            int limit,
                            int offset)
                     throws ServiceRegistryException

Return the payload of a specified number of jobs for a specified operation type.

Parameters:

operation - Operation type to get payload for

limit - How many results to return

offset - Offset for the set of returned results

Returns:

Serialized workflows

Throws:

ServiceRegistryException - if there is a problem accessing the service registry

getJobCount

int getJobCount(String operation)
         throws ServiceRegistryException

Return the number of jobs for a specified operation type.

Parameters:

operation - Operation type to check for

Returns:

Number of jobs for the specified operation type.

Throws:

ServiceRegistryException

getActiveJobs

List<Job> getActiveJobs()
                 throws ServiceRegistryException

Get the list of active jobs.

Returns:

list of active jobs

Throws:

ServiceRegistryException - if there is a problem accessing the service registry

getChildJobs

List<Job> getChildJobs(long id)
                throws ServiceRegistryException

Get all child jobs from a job

Parameters:

id - the parent job id

Returns:

a list of the child jobs ordered by execution

Throws:

ServiceRegistryException - if there is a problem accessing the service registry

incident

Incidents incident()

Return a facility to record job incidents.

See Also:

Incident

getServiceRegistrationsByLoad

List<ServiceRegistration> getServiceRegistrationsByLoad(String serviceType)
                                                 throws ServiceRegistryException

Finds the service registrations for this kind of job, ordered by load (lightest to heaviest).

Parameters:

serviceType - The type of service that must be handled by the hosts

Returns:

A list of hosts that handle this job type, in order of their running and queued job load

Throws:

ServiceRegistryException - if there is a problem accessing the service registry

getServiceRegistrationsByType

List<ServiceRegistration> getServiceRegistrationsByType(String serviceType)
                                                 throws ServiceRegistryException

Finds the service registrations for this kind of job, including offline services and those in maintenance mode.

Parameters:

serviceType - The type of service that must be handled by the hosts

Returns:

A list of hosts that handle this job type

Throws:

ServiceRegistryException - if there is a problem accessing the service registry

getServiceRegistrationsByHost

List<ServiceRegistration> getServiceRegistrationsByHost(String host)
                                                 throws ServiceRegistryException

Finds the service registrations on the given host, including offline services and those in maintenance mode.

Parameters:

host - The host

Returns:

A list of service registrations on a single host

Throws:

ServiceRegistryException - if there is a problem accessing the service registry

getServiceRegistration

ServiceRegistration getServiceRegistration(String serviceType,
                                           String host)
                                    throws ServiceRegistryException

Finds a single service registration by host and type, even if the service is offline or in maintenance mode.

Parameters:

serviceType - The type of service

host - the base URL of the host

Returns:

The service registration, or null

Throws:

ServiceRegistryException - if there is a problem accessing the service registry

getServiceRegistrations

List<ServiceRegistration> getServiceRegistrations()
                                           throws ServiceRegistryException

Finds all service registrations, including offline services and those in maintenance mode.

Returns:

A list of service registrations

Throws:

ServiceRegistryException - if there is a problem accessing the service registry

getRegistryHostname

String getRegistryHostname()

Returns the service regstry's hostname. This can be used to fetch the list of services on the local host.

Returns:

The hostname that the service registry is running on.

getHostRegistrations

List<HostRegistration> getHostRegistrations()
                                     throws ServiceRegistryException

Finds all host registrations, including offline hosts and those in maintenance mode.

Returns:

A list of host registrations

Throws:

ServiceRegistryException - if there is a problem accessing the service registry

getHostRegistration

HostRegistration getHostRegistration(String hostname)
                              throws ServiceRegistryException

Finds host registration for the given hostname.

Parameters:

hostname - to lookup

Returns:

host registrations

Throws:

ServiceRegistryException - if there is a problem accessing the service registry or the hostname is not found

getServiceStatistics

List<ServiceStatistics> getServiceStatistics()
                                      throws ServiceRegistryException

Gets performance and runtime statistics for each known service registration.

Returns:

the service statistics

Throws:

ServiceRegistryException - if there is a problem accessing the service registry

countOfAbnormalServices

long countOfAbnormalServices()
                      throws ServiceRegistryException

Gets the count of the number of abnormal services across the whole system.

Returns:

the count of abnormal services

Throws:

ServiceRegistryException

count

long count(String serviceType,
           Job.Status status)
    throws ServiceRegistryException

Count the number of jobs that match the specified parameters.

Parameters:

serviceType - The jobs run by this type of service. If null, the returned count will refer to all types of jobs.

status - The status of the receipts. If null, the returned count will refer to jobs in any status.

Returns:

the number of jobs

Throws:

ServiceRegistryException - if there is a problem accessing the service registry

countByOperation

long countByOperation(String serviceType,
                      String operation,
                      Job.Status status)
               throws ServiceRegistryException

Count the number of jobs running the given operation in this Job.Status.

Parameters:

serviceType - The jobs run by this type of service

operation - the operation

status - The status of the jobs

Returns:

the number of jobs

Throws:

ServiceRegistryException - if there is a problem accessing the service registry

countByHost

long countByHost(String serviceType,
                 String host,
                 Job.Status status)
          throws ServiceRegistryException

Count the number of jobs in this Job.Status on this host

Parameters:

serviceType - The jobs run by this type of service

host - The server that created and will be handling the job

status - The status of the jobs

Returns:

the number of jobs

Throws:

ServiceRegistryException - if there is a problem accessing the service registry

count

long count(String serviceType,
           String host,
           String operation,
           Job.Status status)
    throws ServiceRegistryException

Count the number of jobs executing the given operation in this Job.Status on this host.

Parameters:

serviceType - The jobs run by this type of service

host - The server that created and will be handling the job

operation - the operation

status - The status of the jobs

Returns:

the number of jobs

Throws:

ServiceRegistryException - if there is a problem accessing the service registry

sanitize

void sanitize(String serviceType,
              String host)
       throws NotFoundException

Sets the given service to NORMAL state

Parameters:

serviceType - the service type

host - the host

Throws:

NotFoundException - if the service does not exist