Package org.kuali.rice.ksb.api.registry

Interface ServiceRegistry

public interface ServiceRegistry
Defines the interface for a remotely accessible service registry. Applications can query for information about available services through the apis provided as well as publishing their own services.

The ServiceRegistry deals primarily with the concept of a ServiceEndpoint which holds a ServiceInfo and a ServiceDescriptor. These pieces include information about the service and it's configuration which might be needed by applications wishing to invoke those services.

Many of the operations on the ServiceRegistry only return the ServiceInfo. This is because retrieving the full ServiceDescriptor is a more expensive operation (since it consists of a serialized XML representation of the service's configuration which needs to be unmarshaled and processed) and typically the descriptor is only needed when the client application actually wants to connect to the service.

The ServiceInfo provides two important pieces of information which help the registry (and the applications which interact with it) understand who the owner of a service is. The first of these is the "application id" which identifies the application which owns the service. In terms of Kuali Rice, an "application" is an abstract concept and consist of multiple instances of an application which are essentially mirrors of each other and publish the same set of services. Each of these individuals instances of an application is identified by the "instance id" which is also available from the ServiceInfo.

Author:
Kuali Rice Team (rice.collab@kuali.org)
See Also:

  • Method Details

    • getOnlineServicesByName

      List<ServiceInfo> getOnlineServicesByName(QName serviceName) throws RiceIllegalArgumentException
      Returns an unmodifiable list of ServiceInfo for all services that have a status of ServiceEndpointStatus.ONLINE with the given name. If there are no services with the given name, this method should return an empty list.

      It is typical in clustered environments and other situations that more than one online service might be available for a given service name. It is intended that a client of the registry will use an available endpoint of their choosing to connect to and invoke the service.

      Parameters:
      serviceName - the name of the service to locate
      Returns:
      an unmodifiable list of ServiceInfo for online services with the given name. If no services were found, an empty list will be returned, but this method should never return null.
      Throws:
      RiceIllegalArgumentException - if serviceName is null

    • getAllOnlineServices

      List<ServiceInfo> getAllOnlineServices()
      Returns an unmodifiable list of ServiceInfo for all services in the registry that have a status of ServiceEndpointStatus.ONLINE. If there are no online services in the registry, this method will return an empty list.
      Returns:
      an unmodifiable list of ServiceInfo for all online services in the registry. If no services were found, an empty list will be returned, but this method should never return null.

    • getAllServices

      List<ServiceInfo> getAllServices()
      Returns an unmodifiable list of ServiceInfo for all services in the registry. If there are no services in the registry, this method will return an empty list.
      Returns:
      an unmodifiable list of ServiceInfo for all services in the registry. If no services were found, an empty list will be returned, but this method should never return null.

    • getAllServicesForInstance

      List<ServiceInfo> getAllServicesForInstance(String instanceId) throws RiceIllegalArgumentException
      Returns an unmodifiable list of ServiceInfo for all services that have an instance id which matches the given instance id, regardless of their status. If there are no services published for the given instance, this method should return an empty list.
      Parameters:
      instanceId - the instance id of the services to locate
      Returns:
      an unmodifiable listof ServiceInfo for all services in the registry for the given instance id
      Throws:
      RiceIllegalArgumentException - if instanceId is a null or blank value

    • getAllServicesForApplication

      List<ServiceInfo> getAllServicesForApplication(String applicationId) throws RiceIllegalArgumentException
      Returns an unmodifiable list of ServiceInfo for all services that have an application id which matches the given application id, regardless of their status. If there are no services published for the given application, this method should return an empty list.
      Parameters:
      applicationId - the application id of the services to locate
      Returns:
      an unmodifiable listof ServiceInfo for all services in the registry for the given application id
      Throws:
      RiceIllegalArgumentException - if applicationId is a null or blank value

    • getServiceDescriptor

      ServiceDescriptor getServiceDescriptor(String serviceDescriptorId) throws RiceIllegalArgumentException
      Returns the ServiceDescriptor which has the given id. If there is no descriptor for the id, this method will return null.
      Parameters:
      serviceDescriptorId -
      Returns:
      Throws:
      RiceIllegalArgumentException

    • getServiceDescriptors

      List<ServiceDescriptor> getServiceDescriptors(List<String> serviceDescriptorIds) throws RiceIllegalArgumentException
      Returns an unmodifiable list of ServiceDescriptor which match the given list of service descriptor ids. The list that is returned from this method may be smaller than the list of ids that were supplied. This happens in cases where a service descriptor for a given id in the list could not be found.
      Parameters:
      serviceDescriptorIds - the list of service descriptor ids for which to locate the corresponding service descriptor
      Returns:
      an unmodifiable list of the service descriptors that could be located for the given list of ids. This list may be smaller than the original list of ids that was supplied if the corresponding descriptor could not be located for a given id in the registry. If no service descriptors could be located, this method will return an empty list. It should never return null.
      Throws:
      RiceIllegalArgumentException - if serviceDescriptorIds is null

    • publishService

      ServiceEndpoint publishService(ServiceEndpoint serviceEndpoint) throws RiceIllegalArgumentException
      Publishes the given ServiceEndpoint to the registry. If there is no service id on the ServiceInfo then this constitutes a new registry endpoint, so it will be added to the registry. If the given endpoint already has a ServiceInfo with a service id, then the corresponding entry in the registry will be updated instead.
      Parameters:
      serviceEndpoint - the service endpoint to publish
      Returns:
      the result of publishing the endpoint, if this is a new registry entry, then the service endpoint that is returned will contain access to both the service id and service descriptor id that were generated for this entry in the registry. This method will never return null.
      Throws:
      RiceIllegalArgumentException - if serviceEndpoint is null

    • publishServices

      List<ServiceEndpoint> publishServices(List<ServiceEndpoint> serviceEndpoints) throws RiceIllegalArgumentException
      Publishes the list of ServiceEndpoints to the registry. This functions the same way as executing publishService(ServiceEndpoint) on each individual ServiceEndpoint. However, it performs this as an atomic operation, so if there is an error when publishing one service endpoint in the list, then none of the endpoints will be published.
      Parameters:
      serviceEndpoints - the list of service endpoints to publish
      Returns:
      the result of publishing the endpoints (see publishService(ServiceEndpoint) for details). This list will always be the same size and in the same order as the list of service endpoints that were supplied for publshing.
      Throws:
      RiceIllegalArgumentException - if serviceEndpoints is null or if any ServiceEndpoint within the list is null

    • removeServiceEndpoint

      ServiceEndpoint removeServiceEndpoint(String serviceId) throws RiceIllegalArgumentException
      Removes the service from the registry with the given service id if it exists. If the service with the given id exists and was successfully removed, a copy of the removed ServiceEndpoint entry will be returned. Otherwise, this method will return null.
      Parameters:
      serviceId - the id of the service to remove
      Returns:
      the removed ServiceEndpoint if a service with the given id exists in the registry, if no such service exists, this method will return null
      Throws:
      RiceIllegalArgumentException - if serviceId is null or a blank value

    • removeServiceEndpoints

      List<ServiceEndpoint> removeServiceEndpoints(List<String> serviceIds) throws RiceIllegalArgumentException
      As removeServiceEndpoint(String) but removes all services that match the given list of service ids. It could be the case that some of the given ids do not match a service in the registry, in this case that ServiceEndpoint would not be included in the resulting list of services that were removed. Because of this, the list that is returned from this method may be smaller then the list of ids that were supplied.
      Parameters:
      serviceIds - the list of service ids to remove from the registry
      Returns:
      a list of all service endpoints that were successfully removed, if no such endpoints were removed, this list will be empty, but it will never be null
      Throws:
      RiceIllegalArgumentException - if serviceIds is null or if one of the ids in the list is null or blank

    • removeAndPublish

      RemoveAndPublishResult removeAndPublish(List<String> removeServiceIds, List<ServiceEndpoint> publishServiceEndpoints) throws RiceIllegalArgumentException
      Performs a single atomic operation of removing and publishing a set of services in the registry. This operation is useful in situations where a client application contains apis to manage the services they are publishing on the bus and they want to ensure the registry is kept in a consistent state in terms of what they have published.

      Behaviorally, this operation is equivalent to performing a removeServiceEndpoints(List) followed by a publishServices(List), except that a null list is valid for either removeServiceIds or publishServiceEndpoints. In the case that a null or empty list is passed for either of these, that particular portion of the operation will not be performed.

      This method returns a RemoveAndPublishResult which contains a list of the services that were successfully removed as well as those that were published.

      Parameters:
      removeServiceIds - the list of ids of the services to remove, if this parameter is null or an empty list, then no remove operation will be executed
      publishServiceEndpoints - the list of service endpoints to publish, if this parameter is null or an empty list, then no publish operation will be executed
      Returns:
      the result of the operation which contains information on which services were successfully removed as well as published, this method will never return null
      Throws:
      RiceIllegalArgumentException

    • updateStatus

      boolean updateStatus(String serviceId, ServiceEndpointStatus status) throws RiceIllegalArgumentException
      Updates the status for the service with the given id to the given ServiceEndpointStatus.
      Parameters:
      serviceId - the id of the service for which to update the status
      status - the status to update this service to
      Returns:
      true if the service with the given id exists in the registry and was updated, false otherwise
      Throws:
      RiceIllegalArgumentException - if serviceId is null or a blank value
      RiceIllegalArgumentException - if status is null

    • updateStatuses

      List<String> updateStatuses(List<String> serviceIds, ServiceEndpointStatus status) throws RiceIllegalArgumentException
      As per updateStatus(String, ServiceEndpointStatus) but updates mutliple statuses as part of a single operation.

      This method returns a List of ids of the services that were updated. If a given service id does not exist in the registry, that id won't be included in the result. So the resuling list of updated ids may be smaller than the given list of service ids (though it will never be null).

      Parameters:
      serviceIds - the list of ids of the services for which to update the status
      status - the status to update the services to
      Returns:
      an unmodifiable list containing the ids of the services that were successfully updated, since it's possible some of the supplied ids might not exist in the registry this list could be smaller than the given serviceIds list
      Throws:
      RiceIllegalArgumentException - if serviceIds is null or if any of the entries in the list is null or has a blank value
      RiceIllegalArgumentException - if status is null

    • takeInstanceOffline

      void takeInstanceOffline(String instanceId) throws RiceIllegalArgumentException
      Flips the status of all services that match the given instance id to the status of {@link ServiceEndpointStatus#OFFLINE. It is intended that this operation will be used by a registry client who is going offline for maintenance or other reasons and wants to ensure that the state of the registry is consistent with the application's state.
      Parameters:
      instanceId - the id of the instance for which to set all services to the offline status
      Throws:
      RiceIllegalArgumentException - if instanceId is null or a blank value