org.kuali.rice.ksb.api.registry
Interface ServiceRegistry

All Known Implementing Classes:

LazyRemoteServiceRegistryConnector, ServiceRegistryImpl

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:

ServiceEndpoint, ServiceInfo, ServiceDescriptor

Method Summary

List<ServiceInfo>	getAllOnlineServices() Returns an unmodifiable list of ServiceInfo for all services in the registry that have a status of ServiceEndpointStatus.ONLINE.
List<ServiceInfo>	getAllServices() Returns an unmodifiable list of ServiceInfo for all services in the registry.
List<ServiceInfo>	getAllServicesForInstance(String instanceId) Returns an unmodifiable list of ServiceInfo for all services that have an instance id which matches the given instance id, regardless of their status.
List<ServiceInfo>	getOnlineServicesByName(QName serviceName) Returns an unmodifiable list of ServiceInfo for all services that have a status of ServiceEndpointStatus.ONLINE with the given name.
ServiceDescriptor	getServiceDescriptor(String serviceDescriptorId) Returns the ServiceDescriptor which has the given id.
List<ServiceDescriptor>	getServiceDescriptors(List<String> serviceDescriptorIds) Returns an unmodifiable list of ServiceDescriptor which match the given list of service descriptor ids.
ServiceEndpoint	publishService(ServiceEndpoint serviceEndpoint) Publishes the given ServiceEndpoint to the registry.
List<ServiceEndpoint>	publishServices(List<ServiceEndpoint> serviceEndpoints) Publishes the list of ServiceEndpoints to the registry.
RemoveAndPublishResult	removeAndPublish(List<String> removeServiceIds, List<ServiceEndpoint> publishServiceEndpoints) Performs a single atomic operation of removing and publishing a set of services in the registry.
ServiceEndpoint	removeServiceEndpoint(String serviceId) Removes the service from the registry with the given service id if it exists.
List<ServiceEndpoint>	removeServiceEndpoints(List<String> serviceIds) As removeServiceEndpoint(String) but removes all services that match the given list of service ids.
void	takeInstanceOffline(String instanceId) Flips the status of all services that match the given instance id to the status of {@link ServiceEndpointStatus#OFFLINE.
boolean	updateStatus(String serviceId, ServiceEndpointStatus status) Updates the status for the service with the given id to the given ServiceEndpointStatus.
List<String>	updateStatuses(List<String> serviceIds, ServiceEndpointStatus status) As per updateStatus(String, ServiceEndpointStatus) but updates mutliple statuses as part of a single operation.

Method Detail

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

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)

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

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