Package com.gigaspaces.internal.naming

Class LookupNamingService

java.lang.Object
com.gigaspaces.internal.naming.LookupNamingService
All Implemented Interfaces:
INamingService
public class LookupNamingService extends Object implements INamingService
The LookupNamingService class provides methods for obtaining references to remote services in a Jini LookupService. Each method of the LookupNamingService takes as one of its arguments a ServiceTemplate to lookup the desired service.
Since:
6.0
Version:
1.0
Author:
Igor Goldenberg

  • Constructor Details

  • Method Details

    • lookup

      public ServiceItem[] lookup(ServiceTemplate srvTemplate, int maxMatches, ServiceItemFilter filter)
      Description copied from interface: INamingService
      Queries the naming service in the managed set for service(s) that match the input criteria. Additionally, this method allows any entity to supply an object referred to as a filter. This filtering facility is particularly useful to entities that wish to extend the capabilities of standard template-matching.

      Entities typically employ this method when they need infrequent access to multiple instances of services, and when the cost of making remote queries is outweighed by the overhead of maintaining a local cache (for example, because of resource limitations).

      This version of lookup returns an array of instances of ServiceItem in which each element corresponds to a service reference that satisfies the matching criteria. The number of elements in the returned set will be no greater than the value of the maxMatches parameter, but may be less.

      Note that this version of lookup does not provide a blocking feature. That is, this version will return immediately with whatever number of service references it can find, up to the number indicated in the maxMatches parameter. If no services matching the input criteria can be found on the first attempt, an empty array is returned. It is important to understand this characteristic because there is a common usage scenario that can cause confusion when this version of lookup is used but fails to discover any instances of the expected service of interest. Suppose an entity creates a service discovery manager and then immediately calls this version of lookup, which simply queries the currently discovered lookup services for the service of interest. If the discovery manager employed by the service discovery manager has not yet disovered any lookup services (thus, there are no lookup services to query) the method will immediately return an empty array. This can be confusing when one verifies that instance(s) of such a service of interest have indeed been started and registered with the existing lookup service(s). To address this issue, one of the blocking versions of lookup could be used instead of this version, or the entity could simply wait until the discovery manager has been given enough time to complete its own (lookup) discovery processing.

      Specified by:
      lookup in interface INamingService
      maxMatches - this method will return no more than this number of service references
      filter - an instance of ServiceItemFilter containing matching criteria that should be applied in addition to the template-matching employed when searching for desired services. If null is input to this parameter, then only template-matching will be employed to find the desired services.
      Returns:
      an array of instances of ServiceItem where each element corresponds to a reference to a service that matches the criteria represented in the input parameters; or an empty array if no matching service can be found; null if no naming service can be found.
      See Also:

    • getLookupAttributes

      public Entry[] getLookupAttributes(Object service) throws RemoteException
      Description copied from interface: INamingService
      Get the current attribute sets for the service.
      Specified by:
      getLookupAttributes in interface INamingService
      Parameters:
      service - the service to get attributes from.
      Returns:
      the current attribute sets for the service
      Throws:
      RemoteException

    • modifyNamingAttributes

      public void modifyNamingAttributes(Object service, Entry[] attrSetTemplates, Entry[] attrSets) throws RemoteException
      Description copied from interface: INamingService
      Modify the current attribute sets for desired service. The resulting set will be used for all future joins. The same modifications are also made to all currently-joined naming services.
      Specified by:
      modifyNamingAttributes in interface INamingService
      Parameters:
      service - the service to modify the attrSet</> by matched attrSetTemplates.
      attrSetTemplates - the templates for matching attribute sets
      attrSets - the modifications to make to matching sets
      Throws:
      RemoteException

    • addNamingAttributes

      public void addNamingAttributes(Object service, Entry[] attrSets) throws RemoteException
      Description copied from interface: INamingService
      Add attribute sets for the service. The resulting set will be used for all future joins. The attribute sets are also added to all currently-joined lookup services.
      Specified by:
      addNamingAttributes in interface INamingService
      attrSets - the attribute sets to add
      Throws:
      RemoteException
      See Also:

    • getNumberOfRegistrars

      public int getNumberOfRegistrars()
      Specified by:
      getNumberOfRegistrars in interface INamingService
      Returns:
      The number of registrars available for querying by the naming service

    • getName

      public String getName()
      Specified by:
      getName in interface INamingService
      Returns:
      The Naming Service name.

    • terminate

      public void terminate()
      Description copied from interface: INamingService
      Terminate the naming service functionality.
      Specified by:
      terminate in interface INamingService
      See Also:

    • notify

      public LookupCache notify(ServiceTemplate tmpl, ServiceItemFilter filter, ServiceDiscoveryListener listener) throws RemoteException
      Description copied from interface: INamingService
      The notify method allows the client-like entity to request create a new managed set (or cache) and populate it with services, which match criteria defined by the entity, and whose references are registered with one or more of the lookup services the entity has targeted for discovery.

      This method returns an object of type LookupCache. Through this return value, the entity can query the cache for services of interest, manage the cache's event mechanism for service discoveries, or terminate the cache.

      An entity typically uses the object returned by this method to provide local storage of, and access to, references to services that it is interested in using. Entities needing frequent access to numerous services will find the object returned by this method quite useful because acquisition of those service references is provided through local method invocations. Additionally, because the object returned by this method provides an event mechanism, it is also useful to entities wishing to simply monitor, in an event-driven manner, the state changes that occur in the services of interest.

      Although not required, a common usage pattern for entities that wish to use the LookupCache class to store and manage "discovered" services is to create a separate cache for each service type of interest.

      Specified by:
      notify in interface INamingService
      Parameters:
      tmpl - template to match. It uses template-matching semantics to identify the service(s) to acquire from lookup services in the managed set. If this value is null, it is the equivalent of passing a ServiceTemplate constructed with all null arguments (all wildcards).
      filter - used to apply additional matching criteria to any ServiceItem found through template-matching. If this value is null, no additional filtering will be applied beyond the template-matching.
      listener - object that will receive notifications when services matching the input criteria are discovered for the first time, or have encountered a state change such as removal from all lookup services or attribute set changes. If this value is null, the cache resulting from that invocation will send no such notifications.
      Returns:
      LookupCache used to query the cache for services of interest, manage the cache's event mechanism for service discoveries, or terminate the cache.
      Throws:
      RemoteException - typically, this exception occurs when a RemoteException occurs as a result of an attempt to export the remote listener that receives service events from the lookup services in the managed set.
      See Also:

    • getServiceDiscoveryManager

      public ServiceDiscoveryManager getServiceDiscoveryManager()