Package com.gigaspaces.internal.naming

Interface INamingService

All Known Implementing Classes:
LookupNamingService
public interface INamingService
The INamingService interface provides methods:
  • For obtaining references to remote services in a remote naming service.
    Each method of the INamingService takes as one of its arguments a ServiceTemplate to lookup the desired service.
  • To control a service's participation in the join protocol.
    The object returned by the Administrable.getAdmin method should implement this interface, in addition to any other service-specific administration interfaces.
Since:
6.0
Version:
1.0
Author:
Igor Goldenberg
See Also:
  • Administrable

  • Method Details

    • lookup

      ServiceItem[] lookup(ServiceTemplate srvTemplate, int maxMatches, ServiceItemFilter filter)
      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.

      Parameters:
      tmpl - an instance of ServiceTemplate corresponding to the object to use for template-matching when searching for desired services. If null is input to this parameter, this method will use a wildcarded template (will match all services) when performing template-matching. Note that the effects of modifying contents of this parameter before this method returns are unpredictable and undefined.
      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:

    • notify

      LookupCache notify(ServiceTemplate tmpl, ServiceItemFilter filter, ServiceDiscoveryListener listener) throws RemoteException
      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.

      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:

    • getLookupAttributes

      Entry[] getLookupAttributes(Object service) throws RemoteException
      Get the current attribute sets for the service.
      Parameters:
      service - the service to get attributes from.
      Returns:
      the current attribute sets for the service
      Throws:
      RemoteException

    • modifyNamingAttributes

      void modifyNamingAttributes(Object service, Entry[] attrSetTemplates, Entry[] attrSets) throws RemoteException
      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.
      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

      void addNamingAttributes(Object service, Entry[] attrSets) throws RemoteException
      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.
      Parameters:
      attrSets - the attribute sets to add
      Throws:
      RemoteException

    • getNumberOfRegistrars

      int getNumberOfRegistrars()
      Returns:
      The number of registrars available for querying by the naming service

    • terminate

      void terminate()
      Terminate the naming service functionality.

    • getName

      String getName()
      Returns:
      The Naming Service name.