Coverage Report

Coverage Report - org.kuali.rice.ksb.api.bus.ServiceBus

Classes in this File

 package org.kuali.rice.ksb.api.bus;
 
 import java.util.List;
 import java.util.Map;
 
 import javax.xml.namespace.QName;
 
 /**
  * The {@code 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.
  * 
  * <p>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 {@link #synchronize()}
  * method or on a periodic basis (the details of which are up to the implementation).
  * 
  * <p>Note that the {@code ServiceBus} manages two primary collections of
  * {@link 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).
  * 
  * @see Endpoint
  * @see ServiceConfiguration
  * @see ServiceDefinition
  * 
  * @author Kuali Rice Team (rice.collab@kuali.org)
  *
  */
 public interface ServiceBus {
 
         /**
          * 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.
          * 
          * @return the instance ID for the application in which this service bus client is resident
          */
         public String getInstanceId();
         
         /**
          * 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.
          * 
          * @return 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
          */
         public List<Endpoint> getEndpoints(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.
          * 
          * <p>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.
          * 
          * <p>In most cases, it is preferable to use {@link #getEndpoints(QName)} instead of this
          * method.  Because it will preferably return a local endpoint reference for a given
          * service endpoint if one is available.
          * 
          * @return 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
          */
         public List<Endpoint> getRemoteEndpoints(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.
          *  
          * @param serviceName the name of the service represented by the local endpoint
          * @return 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
          */
         public Endpoint getLocalEndpoint(QName serviceName);
           
         /**
          * Returns an unmodifiable list of all services that have been published by this service bus client.
          * 
          * @return 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.
          */
         public Map<QName, Endpoint> getLocalEndpoints();
 
         /**
          * Returns an unmodifiable list of all available and online endpoints of which the service bus is aware, including
          * both local and remote endpoints.
          * 
          * @return all available endpoints, this list may be empty if no endpoints exist but
          * will never be null
          */
         public List<Endpoint> getAllEndpoints();
           
         /**
          * 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.
          * 
          * <p>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 {@link Endpoint} instances each time.
          * 
          * @param serviceName the name of the service for which to locate an available endpoint
          * @return an available endpoint for the service with the given name, or null if none is available
          * @throws IllegalArgumentException if serviceName is null
          */
         public Endpoint getEndpoint(QName serviceName);
           
         /**
          * 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.
          * 
          * @param serviceConfiguration the service configuration by which to lookup up the endpoint
          * @return 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
          */
         public Endpoint getConfiguredEndpoint(ServiceConfiguration serviceConfiguration);
         
         /**
          * 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.
          * 
          * <p>This proxy should additionally be thread-safe.
          * 
          * <p>This method is equivalent to invoking {@link #getEndpoint(QName).getService()}.
          * 
          * @param serviceName the name of the service for which to locate an available proxy
          * @return an available proxy for the service with the given name, or null if none is available
          * @throws IllegalArgumentException if serviceName is null
          */
         public Object getService(QName serviceName);
 
         /**
          * 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.
          *
          * <p>The method also provides the ability for the service bus to immediately synchronize
          * with the service registry after registering the service if {@code synchronize} is set
          * to {@code true}.
          * 
          * @see #synchronize()
          * 
          * @param serviceDefinition the definition of the service to publish, must not be null
          * @param synchronize indicates whether or not this service bus client should immediately synchronize
          * it's changes with the registry after registering the service.
          * @return the service configuration for the published service
          * @throws IllegalArgumentException if serviceDefinition is null
          */
         public ServiceConfiguration publishService(ServiceDefinition serviceDefinition, boolean synchronize);
 
         /**
          * Functions as per {@link #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).
          * 
          * @see #publishService(ServiceDefinition, boolean)
          * @see #synchronize()
          * 
          * @param serviceDefinitions the list of definition for the services to publish, must not be null
          * @param synchronize indicates whether or not this service bus client should immediately synchronize
          * it's changes with the registry after registering the services.
          * @return 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
          */
         public List<ServiceConfiguration> publishServices(List<ServiceDefinition> definition, 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.
          * 
          * <p>This method also provides the ability for the service bus to immediately synchronize
          * with the service registry after removing the service if {@code synchronize} is set
          * to {@code true}.  If the service is not located and successfully removed, however, the
          * sychronization will not run.
          * 
          * @see #synchronize()
          * 
          * @param serviceName the name of the service to remove
          * @param synchronize indicates whether or not this service bus client should immediately synchronize
          * after removing the service
          * @return true if the service was removed, false otherwise
          * @throws IllegalArgumentException if the given serviceName is null
          */
         public boolean removeService(QName serviceName, boolean synchronize);
 
         /**
          * Functions as per {@link #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).
          * 
          * <p>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.
          * 
          * @see #removeService(QName, boolean)
          * @see #synchronize()
          * 
          * @param serviceNames the list of names for the services to remove, must not be null
          * @param synchronize indicates whether or not this service bus client should immediately synchronize
          * it's changes with the registry after removing the services.
          * @return 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
          */
         public List<Boolean> removeServices(List<QName> serviceConfigurations, boolean synchronize);
 
         /**
          * Synchronizes the current client's service bus with the central service registry.  This is done automatically
          * on a periodic basic, 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.
          */
         public void synchronize();
         
 }

1		package org.kuali.rice.ksb.api.bus;
2
3		import java.util.List;
4		import java.util.Map;
5
6		import javax.xml.namespace.QName;
7
8		/**
9		* The {@code ServiceBus} is the primary api that client applications use to
10		* interact with the Kuali Service Bus. It provides capabilities to retrieve
11		* services endpoints for use when needing to invoke a service. It
12		* also provides a mechanism by which a client application can publish it's own
13		* services to the bus.
14		*
15		* <p>The service bus may be backed by a service registry which can be used to
16		* locate services which other applications have published to the service
17		* registry. The service bus will synchronize it's known state with the of the
18		* registry, either through explicit invocations of the {@link #synchronize()}
19		* method or on a periodic basis (the details of which are up to the implementation).
20		*
21		* <p>Note that the {@code ServiceBus} manages two primary collections of
22		* {@link Endpoint} classes. Those that have been published by this application
23		* (referred to as "local" endpoints) and those which have been published by other
24		* applications (referred to as "remote" endpoints).
25		*
26		* @see Endpoint
27		* @see ServiceConfiguration
28		* @see ServiceDefinition
29		*
30		* @author Kuali Rice Team (rice.collab@kuali.org)
31		*
32		*/
33		public interface ServiceBus {
34
35		/**
36		* Returns the instance ID which identifies this client application to the service bus.
37		* The instance ID should be unique for each client of the service bus and will never be
38		* blank or null.
39		*
40		* @return the instance ID for the application in which this service bus client is resident
41		*/
42		public String getInstanceId();
43
44		/**
45		* Returns an unmodifiable list of accessible endpoints that are available to the service bus
46		* with the given service name. This method will only return endpoints that the service
47		* bus believes are online, endpoints which are offline will not be included. In certain
48		* cases a specific service endpoint will be available both as a local and remote service.
49		* In these cases, the list returned from this method will preferentially include the
50		* local service. It will not include both the local and remote endpoint to the same
51		* service. This is important as this method may be used to get endpoints for broadcasting
52		* service calls to all endpoints with a given name. In these cases, it is not desirable
53		* to invoke the same endpoint twice.
54		*
55		* @return a list of the remote endpoints that are available for the given service name,
56		* this list will never be null but may be empty if there are no remote endpoints for
57		* the given service name
58		* @throws IllegalArgumentException if serviceName is null
59		*/
60		public List<Endpoint> getEndpoints(QName serviceName);
61
62		/**
63		* Returns an unmodifiable list of remotely accessible endpoints that are available in the service registry
64		* with the given service name. This method will only return endpoints that the service
65		* bus believes are online, endpoints which are offline will not be included.
66		*
67		* <p>If the service bus client has also deployed a service with this name, a remoted
68		* endpoint to this service will likely also be included in this list assuming that
69		* endpoint has already been synchronized with the registry.
70		*
71		* <p>In most cases, it is preferable to use {@link #getEndpoints(QName)} instead of this
72		* method. Because it will preferably return a local endpoint reference for a given
73		* service endpoint if one is available.
74		*
75		* @return a list of all endpoints that are available for the given service name,
76		* this list will never be null but may be empty if there are no endpoints for
77		* the given service name
78		* @throws IllegalArgumentException if serviceName is null
79		*/
80		public List<Endpoint> getRemoteEndpoints(QName serviceName);
81
82		/**
83		* Returns the endpoint for the service with the given name that was published by this
84		* service bus client. If this client has not published any such service, then this
85		* method will return null.
86		*
87		* @param serviceName the name of the service represented by the local endpoint
88		* @return the local endpoint for the given service name which was deployed
89		* by this client, or null if no such service has been published
90		* @throws IllegalArgumentException if serviceName is null
91		*/
92		public Endpoint getLocalEndpoint(QName serviceName);
93
94		/**
95		* Returns an unmodifiable list of all services that have been published by this service bus client.
96		*
97		* @return a map with the local service name as the key and the local endpoint as the
98		* value which contains all local services published by this service bus client. This
99		* map may be empty if this client has published no services, but it should never be
100		* null.
101		*/
102		public Map<QName, Endpoint> getLocalEndpoints();
103
104		/**
105		* Returns an unmodifiable list of all available and online endpoints of which the service bus is aware, including
106		* both local and remote endpoints.
107		*
108		* @return all available endpoints, this list may be empty if no endpoints exist but
109		* will never be null
110		*/
111		public List<Endpoint> getAllEndpoints();
112
113		/**
114		* Returns an available endpoint for the service with the given name. If the service with
115		* the given name is published locally, preference will be given to the locally deployed
116		* version of the service.
117		*
118		* <p>Based on the nature of this method, if there is more than one endpoint available for
119		* the given name, multiple invocations of this method with the same service name may
120		* return different {@link Endpoint} instances each time.
121		*
122		* @param serviceName the name of the service for which to locate an available endpoint
123		* @return an available endpoint for the service with the given name, or null if none is available
124		* @throws IllegalArgumentException if serviceName is null
125		*/
126		public Endpoint getEndpoint(QName serviceName);
127
128		/**
129		* Returns the endpoint matching the given service configuration, if one exists. In the
130		* case of services published by this service bus client, this method will preferably
131		* return the local endpoints in place of a remote endpoint to the same service.
132		*
133		* @param serviceConfiguration the service configuration by which to lookup up the endpoint
134		* @return the endpoint who's service configuration matches the given configuration, or null if
135		* no such match could be determined
136		* @throws IllegalArgumentException if the given serviceConfiguration is null
137		*/
138		public Endpoint getConfiguredEndpoint(ServiceConfiguration serviceConfiguration);
139
140		/**
141		* Returns a proxy to the service with the given name. This proxy should have built-in support
142		* for fail-over and load balancing capabilities. This means it is safe for client applications
143		* to cache a reference to this service proxy.
144		*
145		* <p>This proxy should additionally be thread-safe.
146		*
147		* <p>This method is equivalent to invoking {@link #getEndpoint(QName).getService()}.
148		*
149		* @param serviceName the name of the service for which to locate an available proxy
150		* @return an available proxy for the service with the given name, or null if none is available
151		* @throws IllegalArgumentException if serviceName is null
152		*/
153		public Object getService(QName serviceName);
154
155		/**
156		* Publish a service with the given ServiceDefinition to the service bus. This
157		* effectively updates the service registry and provides an endpoint for other
158		* applications to invoke. If this application has already published a service
159		* under this name, it will be updated instead to reflect the new ServiceDefinition.
160		*
161		* <p>The method also provides the ability for the service bus to immediately synchronize
162		* with the service registry after registering the service if {@code synchronize} is set
163		* to {@code true}.
164		*
165		* @see #synchronize()
166		*
167		* @param serviceDefinition the definition of the service to publish, must not be null
168		* @param synchronize indicates whether or not this service bus client should immediately synchronize
169		* it's changes with the registry after registering the service.
170		* @return the service configuration for the published service
171		* @throws IllegalArgumentException if serviceDefinition is null
172		*/
173		public ServiceConfiguration publishService(ServiceDefinition serviceDefinition, boolean synchronize);
174
175		/**
176		* Functions as per {@link #publishService(ServiceDefinition, boolean)} but allows for multiple
177		* services to be published to the bus in a single operation. If the given list of service
178		* definitions is empty then this method will do nothing (including skipping synchronization with
179		* the registry if that was requested).
180		*
181		* @see #publishService(ServiceDefinition, boolean)
182		* @see #synchronize()
183		*
184		* @param serviceDefinitions the list of definition for the services to publish, must not be null
185		* @param synchronize indicates whether or not this service bus client should immediately synchronize
186		* it's changes with the registry after registering the services.
187		* @return the list of service configurations for the published services in the same order as the list
188		* of service definitions
189		* @throws IllegalArgumentException if serviceDefinitions is null
190		*/
191		public List<ServiceConfiguration> publishServices(List<ServiceDefinition> definition, boolean synchronize);
192
193		/**
194		* Removes the service from the service bus and the service registry with the given service name. Client
195		* applications should only be able to remove services that they themselves have published.
196		*
197		* <p>This method also provides the ability for the service bus to immediately synchronize
198		* with the service registry after removing the service if {@code synchronize} is set
199		* to {@code true}. If the service is not located and successfully removed, however, the
200		* sychronization will not run.
201		*
202		* @see #synchronize()
203		*
204		* @param serviceName the name of the service to remove
205		* @param synchronize indicates whether or not this service bus client should immediately synchronize
206		* after removing the service
207		* @return true if the service was removed, false otherwise
208		* @throws IllegalArgumentException if the given serviceName is null
209		*/
210		public boolean removeService(QName serviceName, boolean synchronize);
211
212		/**
213		* Functions as per {@link #removeService(QName, boolean)} but allows for multiple
214		* services to be removed from the bus in a single operation. If the given list of service
215		* names is empty then this method will do nothing (including skipping synchronization with
216		* the registry if that was requested).
217		*
218		* <p>If the list returned from the method contains only false responses (meaning that no services
219		* were removed) this method will skip synchronization even if it is requested.
220		*
221		* @see #removeService(QName, boolean)
222		* @see #synchronize()
223		*
224		* @param serviceNames the list of names for the services to remove, must not be null
225		* @param synchronize indicates whether or not this service bus client should immediately synchronize
226		* it's changes with the registry after removing the services.
227		* @return a list of Booleans indicating which of the service removals were successful. This list will be
228		* in the same order as the list of service configurations that were passed in.
229		* @throws IllegalArgumentException if serviceNames is null
230		*/
231		public List<Boolean> removeServices(List<QName> serviceConfigurations, boolean synchronize);
232
233		/**
234		* Synchronizes the current client's service bus with the central service registry. This is done automatically
235		* on a periodic basic, but can be invoked manually through this method. This method should both register any
236		* outstanding service publications to the registry, as well as detect any changes in remote services that
237		* have been published/removed by other applications in the registry and update local service bus state
238		* accordingly.
239		*/
240		public void synchronize();
241
242		}