org.kuali.rice.ksb.api.bus
Interface ServiceBus

All Known Implementing Classes:

ServiceBusImpl

public interface ServiceBus

The ServiceBus is the primary api that client applications use to interact with the Kuali Service Bus. It provides capabilities to retrieve services endpoints for use when needing to invoke a service. It also provides a mechanism by which a client application can publish it's own services to the bus.

The service bus may be backed by a service registry which can be used to locate services which other applications have published to the service registry. The service bus will synchronize it's known state with the of the registry, either through explicit invocations of the synchronize() method or on a periodic basis (the details of which are up to the implementation).

Note that the ServiceBus manages two primary collections of Endpoint classes. Those that have been published by this application (referred to as "local" endpoints) and those which have been published by other applications (referred to as "remote" endpoints).

Author:

Kuali Rice Team (rice.collab@kuali.org)

See Also:

Endpoint, ServiceConfiguration, ServiceDefinition

Method Summary

List<Endpoint>	getAllEndpoints() Returns an unmodifiable list of all available and online endpoints of which the service bus is aware, including both local and remote endpoints.
Endpoint	getConfiguredEndpoint(ServiceConfiguration serviceConfiguration) Returns the endpoint matching the given service configuration, if one exists.
Endpoint	getEndpoint(QName serviceName) Returns an available endpoint for the service with the given name.
Endpoint	getEndpoint(QName serviceName, String applicationId) Returns an available endpoint for the service with the given name which is hosted by the application with the given application id.
List<Endpoint>	getEndpoints(QName serviceName) Returns an unmodifiable list of accessible endpoints that are available to the service bus with the given service name.
List<Endpoint>	getEndpoints(QName serviceName, String applicationId) Returns an unmodifiable list of accessible endpoints that are available to the service bus with the given service name for the given application id.
String	getInstanceId() Returns the instance ID which identifies this client application to the service bus.
Endpoint	getLocalEndpoint(QName serviceName) Returns the endpoint for the service with the given name that was published by this service bus client.
Map<QName,Endpoint>	getLocalEndpoints() Returns an unmodifiable list of all services that have been published by this service bus client.
List<Endpoint>	getRemoteEndpoints(QName serviceName) Returns an unmodifiable list of remotely accessible endpoints that are available in the service registry with the given service name.
Object	getService(QName serviceName) Returns a proxy to the service with the given name.
Object	getService(QName serviceName, String applicationId) Returns a proxy to the service with the given name which is hosted by the application with the given application id.
ServiceConfiguration	publishService(ServiceDefinition serviceDefinition, boolean synchronize) Publish a service with the given ServiceDefinition to the service bus.
List<ServiceConfiguration>	publishServices(List<ServiceDefinition> serviceDefinitions, boolean synchronize) Functions as per publishService(ServiceDefinition, boolean) but allows for multiple services to be published to the bus in a single operation.
boolean	removeService(QName serviceName, boolean synchronize) Removes the service from the service bus and the service registry with the given service name.
List<Boolean>	removeServices(List<QName> serviceNames, boolean synchronize) Functions as per removeService(QName, boolean) but allows for multiple services to be removed from the bus in a single operation.
void	synchronize() Synchronizes the current client's service bus with the central service registry.
void	synchronizeLocalServices() Synchronizes information about the services this client is publishing with the central service registry.
void	synchronizeRemoteServices() Fetches information about the current state of the remote services available in the registry and the synchronizes the current client's service bus state.

Method Detail

getInstanceId

String getInstanceId()

Returns the instance ID which identifies this client application to the service bus. The instance ID should be unique for each client of the service bus and will never be blank or null.

Returns:

the instance ID for the application in which this service bus client is resident

getEndpoints

List<Endpoint> getEndpoints(QName serviceName)

Returns an unmodifiable list of accessible endpoints that are available to the service bus with the given service name. This method will only return endpoints that the service bus believes are online, endpoints which are offline will not be included. In certain cases a specific service endpoint will be available both as a local and remote service. In these cases, the list returned from this method will preferentially include the local service. It will *not* include both the local and remote endpoint to the same service. This is important as this method may be used to get endpoints for broadcasting service calls to all endpoints with a given name. In these cases, it is not desirable to invoke the same endpoint twice.

Returns:

a list of the remote endpoints that are available for the given service name, this list will never be null but may be empty if there are no remote endpoints for the given service name

Throws:

IllegalArgumentException - if serviceName is null

getEndpoints

List<Endpoint> getEndpoints(QName serviceName,
                            String applicationId)

Returns an unmodifiable list of accessible endpoints that are available to the service bus with the given service name for the given application id. This method will only return endpoints that the service bus believes are online, endpoints which are offline will not be included. In certain cases a specific service endpoint will be available both as a local and remote service. In these cases, the list returned from this method will preferentially include the local service. It will *not* include both the local and remote endpoint to the same service. This is important as this method may be used to get endpoints for broadcasting service calls to all endpoints with a given name. In these cases, it is not desirable to invoke the same endpoint twice.

Parameters:

serviceName - the name of the service for which to locate an available endpoint

applicationId - the id of the application for which to locate an available endpoint for the given service name

Returns:

a list of the remote endpoints that are available for the given service name, this list will never be null but may be empty if there are no remote endpoints for the given service name

Throws:

IllegalArgumentException - if serviceName is null

Since:

2.1.1

getRemoteEndpoints

List<Endpoint> getRemoteEndpoints(QName serviceName)

Returns an unmodifiable list of remotely accessible endpoints that are available in the service registry with the given service name. This method will only return endpoints that the service bus believes are online, endpoints which are offline will not be included.

If the service bus client has also deployed a service with this name, a remoted endpoint to this service will likely also be included in this list assuming that endpoint has already been synchronized with the registry.

In most cases, it is preferable to use getEndpoints(QName) instead of this method. Because it will preferably return a local endpoint reference for a given service endpoint if one is available.

Returns:

a list of all endpoints that are available for the given service name, this list will never be null but may be empty if there are no endpoints for the given service name

Throws:

IllegalArgumentException - if serviceName is null

getLocalEndpoint

Endpoint getLocalEndpoint(QName serviceName)

Returns the endpoint for the service with the given name that was published by this service bus client. If this client has not published any such service, then this method will return null.

Parameters:

serviceName - the name of the service represented by the local endpoint

Returns:

the local endpoint for the given service name which was deployed by this client, or null if no such service has been published

Throws:

IllegalArgumentException - if serviceName is null

getLocalEndpoints

Map<QName,Endpoint> getLocalEndpoints()

Returns an unmodifiable list of all services that have been published by this service bus client.

Returns:

a map with the local service name as the key and the local endpoint as the value which contains all local services published by this service bus client. This map may be empty if this client has published no services, but it should never be null.

getAllEndpoints

List<Endpoint> getAllEndpoints()

Returns an unmodifiable list of all available and online endpoints of which the service bus is aware, including both local and remote endpoints.

Returns:

all available endpoints, this list may be empty if no endpoints exist but will never be null

getEndpoint

Endpoint getEndpoint(QName serviceName)

Returns an available endpoint for the service with the given name. If the service with the given name is published locally, preference will be given to the locally deployed version of the service.

Based on the nature of this method, if there is more than one endpoint available for the given name, multiple invocations of this method with the same service name may return different Endpoint instances each time.

Parameters:

serviceName - the name of the service for which to locate an available endpoint

Returns:

an available endpoint for the service with the given name, or null if none is available

Throws:

IllegalArgumentException - if serviceName is null

getEndpoint

Endpoint getEndpoint(QName serviceName,
                     String applicationId)

Returns an available endpoint for the service with the given name which is hosted by the application with the given application id. This operation functions the same as getEndpoint(QName) with the exception that it will only consider endpoints with the given application id.

Invoking this method with a null or blank value for applicationId is equivalent to invoking getEndpoint(QName).

Parameters:

serviceName - the name of the service for which to locate an available endpoint

applicationId - the id of the application for which to locate an available endpoint for the given service name

Returns:

an available endpoint for the service with the given name and application id, or null if none is available

Throws:

IllegalArgumentException - if serviceName is null

getConfiguredEndpoint

Endpoint getConfiguredEndpoint(ServiceConfiguration serviceConfiguration)

Returns the endpoint matching the given service configuration, if one exists. In the case of services published by this service bus client, this method will preferably return the local endpoints in place of a remote endpoint to the same service.

Parameters:

serviceConfiguration - the service configuration by which to lookup up the endpoint

Returns:

the endpoint who's service configuration matches the given configuration, or null if no such match could be determined

Throws:

IllegalArgumentException - if the given serviceConfiguration is null

getService

Object getService(QName serviceName)

Returns a proxy to the service with the given name. This proxy should have built-in support for fail-over and load balancing capabilities. This means it is safe for client applications to cache a reference to this service proxy.

This proxy should additionally be thread-safe.

This method is equivalent to invoking #getEndpoint(QName).getService().

Parameters:

serviceName - the name of the service for which to locate an available proxy

Returns:

an available proxy for the service with the given name, or null if none is available

Throws:

IllegalArgumentException - if serviceName is null

getService

Object getService(QName serviceName,
                  String applicationId)

Returns a proxy to the service with the given name which is hosted by the application with the given application id. This operation functions the same as getService(QName) with the exception that it will only consider endpoints with the given application id.

Invoking this method with a null or blank value for applicationId is equivalent to invoking getService(QName). This method is also equivalent to invoking #getEndpoint(QName, String).getService().

Parameters:

serviceName - the name of the service for which to locate an available proxy

applicationId - the id of the application for which to locate an available proxy for the given service name

Returns:

an available proxy for the service with the given name, or null if none is available

Throws:

IllegalArgumentException - if serviceName is null

publishService

ServiceConfiguration publishService(ServiceDefinition serviceDefinition,
                                    boolean synchronize)

Publish a service with the given ServiceDefinition to the service bus. This effectively updates the service registry and provides an endpoint for other applications to invoke. If this application has already published a service under this name, it will be updated instead to reflect the new ServiceDefinition.

The method also provides the ability for the service bus to immediately synchronize with the service registry after registering the service if synchronize is set to true.

Parameters:

serviceDefinition - the definition of the service to publish, must not be null

synchronize - indicates whether or not this service bus client should immediately synchronize it's changes with the registry after registering the service.

Returns:

the service configuration for the published service

Throws:

IllegalArgumentException - if serviceDefinition is null

See Also:

synchronize()

publishServices

List<ServiceConfiguration> publishServices(List<ServiceDefinition> serviceDefinitions,
                                           boolean synchronize)

Functions as per publishService(ServiceDefinition, boolean) but allows for multiple services to be published to the bus in a single operation. If the given list of service definitions is empty then this method will do nothing (including skipping synchronization with the registry if that was requested).

Parameters:

serviceDefinitions - the list of definition for the services to publish, must not be null

synchronize - indicates whether or not this service bus client should immediately synchronize it's changes with the registry after registering the services.

Returns:

the list of service configurations for the published services in the same order as the list of service definitions

Throws:

IllegalArgumentException - if serviceDefinitions is null

See Also:

publishService(ServiceDefinition, boolean), synchronize()

removeService

boolean removeService(QName serviceName,
                      boolean synchronize)

Removes the service from the service bus and the service registry with the given service name. Client applications should only be able to remove services that they themselves have published.

This method also provides the ability for the service bus to immediately synchronize with the service registry after removing the service if synchronize is set to true. If the service is not located and successfully removed, however, the sychronization will not run.

Parameters:

serviceName - the name of the service to remove

synchronize - indicates whether or not this service bus client should immediately synchronize after removing the service

Returns:

true if the service was removed, false otherwise

Throws:

IllegalArgumentException - if the given serviceName is null

See Also:

synchronize()

removeServices

List<Boolean> removeServices(List<QName> serviceNames,
                             boolean synchronize)

Functions as per removeService(QName, boolean) but allows for multiple services to be removed from the bus in a single operation. If the given list of service names is empty then this method will do nothing (including skipping synchronization with the registry if that was requested).

If the list returned from the method contains only false responses (meaning that no services were removed) this method will skip synchronization even if it is requested.

Parameters:

serviceNames - the list of names for the services to remove, must not be null

synchronize - indicates whether or not this service bus client should immediately synchronize it's changes with the registry after removing the services.

Returns:

a list of Booleans indicating which of the service removals were successful. This list will be in the same order as the list of service configurations that were passed in.

Throws:

IllegalArgumentException - if serviceNames is null

See Also:

removeService(QName, boolean), synchronize()

synchronize

void synchronize()

Synchronizes the current client's service bus with the central service registry. This may be done automatically on a periodic basic depending on the implementation of this service, but can be invoked manually through this method. This method should both register any outstanding service publications to the registry, as well as detect any changes in remote services that have been published/removed by other applications in the registry and update local service bus state accordingly.

Invoking this method is equivalent to invoking synchronizeLocalServices() and synchronizeRemoteServices() in either order. However, the semantics vary slightly as this method should attempt to invoke them as an atomic operation.

synchronizeRemoteServices

void synchronizeRemoteServices()

Fetches information about the current state of the remote services available in the registry and the synchronizes the current client's service bus state.

synchronizeLocalServices

void synchronizeLocalServices()

Synchronizes information about the services this client is publishing with the central service registry.