Package org.opencastproject.serviceregistry.api

Interface ServiceRegistry

All Known Implementing Classes:
ServiceRegistryInMemoryImpl, ServiceRegistryJpaImpl
public interface ServiceRegistry
Manages clustered services and the Jobs they may create to enable asynchronous job handling.

  • Method Details

    • 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.

      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, 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.

      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.

      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, 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.

      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.

      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, 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:

    • 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

    • getHostStatistics

      HostStatistics getHostStatistics()
      Get statistics about jobs active on hosts.
      Returns:
      Host statistics

    • 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

    • 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

    • countActiveByOrganizationAndHost

      Map<String,Map<String,Long>> countActiveByOrganizationAndHost()
      Count active jobs and group them by organization and host.
      Returns:
      Map of organizations, hosts and the number of jobs.

    • countActiveTypeByOrganization

      Map<String,Long> countActiveTypeByOrganization(String operation)
      Count active jobs of a given operation type and group them by organization.
      Returns:
      Map of organizations and the number of jobs.

    • 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