com.sun.jini.reggie
Class RegistrarProxy

java.lang.Object
  extended by com.sun.jini.reggie.RegistrarProxy
All Implemented Interfaces:
Serializable, Administrable, ServiceRegistrar, ReferentUuid
Direct Known Subclasses:
ConstrainableRegistrarProxy

 class RegistrarProxy
extends Object
implements ServiceRegistrar, Administrable, ReferentUuid, Serializable

A RegistrarProxy is a proxy for a registrar. Clients only see instances via the ServiceRegistrar, Administrable and ReferentUuid interfaces.

Author:
Sun Microsystems, Inc.

Field Summary
private static Logger logger
           
(package private)  ServiceID registrarID
          The registrar's service ID.
private static long serialVersionUID
           
(package private)  Registrar server
          The registrar.
 
Fields inherited from interface net.jini.core.lookup.ServiceRegistrar
TRANSITION_MATCH_MATCH, TRANSITION_MATCH_NOMATCH, TRANSITION_NOMATCH_MATCH
 
Constructor Summary
RegistrarProxy(Registrar server, ServiceID registrarID)
          Constructor for use by getInstance(), ConstrainableRegistrarProxy.
 
Method Summary
 boolean equals(Object obj)
          Proxies for servers with the same service ID are considered equal.
 Object getAdmin()
          Returns an object that implements whatever administration interfaces are appropriate for the particular service.
 Class[] getEntryClasses(ServiceTemplate tmpl)
          Looks at all service items that match the specified template, finds every entry (among those service items) that either doesn't match any entry templates or is a subclass of at least one matching entry template, and returns the set of the (most specific) classes of those entries.
 Object[] getFieldValues(ServiceTemplate tmpl, int setIndex, String field)
          Looks at all service items that match the specified template, finds every entry (among those service items) that matches tmpl.attributeSetTemplates[setIndex], and returns the set of values of the specified field of those entries.
 String[] getGroups()
          Returns the set of groups that this lookup service is currently a member of.
(package private) static RegistrarProxy getInstance(Registrar server, ServiceID registrarID)
          Returns RegistrarProxy or ConstrainableRegistrarProxy instance, depending on whether given server implements RemoteMethodControl.
 LookupLocator getLocator()
          Returns a LookupLocator that can be used if necessary for unicast discovery of the lookup service.
 Uuid getReferentUuid()
          Return the Uuid that has been assigned to the resource this proxy represents.
 ServiceID getServiceID()
          Returns the service ID of the lookup service.
 Class[] getServiceTypes(ServiceTemplate tmpl, String prefix)
          Looks at all service items that match the specified template, and for every service item finds the most specific type (class or interface) or types the service item is an instance of that are neither equal to, nor a superclass of, any of the service types in the template and that have names that start with the specified prefix, and returns the set of all such types.
(package private) static void handleException(Throwable e)
          Rethrow the exception if it is an Error, unless it is a LinkageError, OutOfMemoryError, or StackOverflowError.
 int hashCode()
           
 Object lookup(ServiceTemplate tmpl)
          Returns the service object (i.e., just ServiceItem.service) from an item matching the template, or null if there is no match.
 ServiceMatches lookup(ServiceTemplate tmpl, int maxMatches)
          Returns at most maxMatches items matching the template, plus the total number of items that match the template.
 EventRegistration notify(ServiceTemplate tmpl, int transitions, RemoteEventListener listener, MarshalledObject handback, long leaseDuration)
          Registers for event notification.
private  void readObject(ObjectInputStream in)
          Reads the default serializable field value for this instance, followed by the registrar's service ID encoded as specified by the ServiceID.writeBytes method.
private  void readObjectNoData()
          Throws InvalidObjectException, since data for this class is required.
 ServiceRegistration register(ServiceItem srvItem, long leaseDuration)
          Register a new service or re-register an existing service.
 String toString()
          Returns a string created from the proxy class name, the registrar's service ID, and the result of the underlying proxy's toString method.
private  void writeObject(ObjectOutputStream out)
          Writes the default serializable field value for this instance, followed by the registrar's service ID encoded as specified by the ServiceID.writeBytes method.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

serialVersionUID

private static final long serialVersionUID
See Also:
Constant Field Values

logger

private static final Logger logger

server

final Registrar server
The registrar.


registrarID

transient ServiceID registrarID
The registrar's service ID.

Constructor Detail

RegistrarProxy

RegistrarProxy(Registrar server,
               ServiceID registrarID)
Constructor for use by getInstance(), ConstrainableRegistrarProxy.

Method Detail

getInstance

static RegistrarProxy getInstance(Registrar server,
                                  ServiceID registrarID)
Returns RegistrarProxy or ConstrainableRegistrarProxy instance, depending on whether given server implements RemoteMethodControl.


getAdmin

public Object getAdmin()
                throws RemoteException
Description copied from interface: Administrable
Returns an object that implements whatever administration interfaces are appropriate for the particular service.

Specified by:
getAdmin in interface Administrable
Returns:
an object that implements whatever administration interfaces are appropriate for the particular service.
Throws:
RemoteException
See Also:
JoinAdmin

register

public ServiceRegistration register(ServiceItem srvItem,
                                    long leaseDuration)
                             throws RemoteException
Description copied from interface: ServiceRegistrar
Register a new service or re-register an existing service. The method is defined so that it can be used in an idempotent fashion. Specifically, if a call to register results in a RemoteException (in which case the item might or might not have been registered), the caller can simply repeat the call to register with the same parameters, until it succeeds.

To register a new service, item.serviceID should be null. In that case, if item.service does not equal (using MarshalledObject.equals) any existing item's service object, then a new service ID will be assigned and included in the returned ServiceRegistration. The service ID is unique over time and space with respect to all other service IDs generated by all lookup services. If item.service does equal an existing item's service object, the existing item is first deleted from the lookup service (even if it has different attributes) and its lease is cancelled, but that item's service ID is reused for the newly registered item.

To re-register an existing service, or to register the service in any other lookup service, item.serviceID should be set to the same service ID that was returned by the initial registration. If an item is already registered under the same service ID, the existing item is first deleted (even if it has different attributes or a different service instance) and its lease is cancelled. Note that service object equality is not checked in this case, to allow for reasonable evolution of the service (e.g., the serialized form of the stub changes, or the service implements a new interface).

Any duplicate attribute sets included in a service item are eliminated in the stored representation of the item. The lease duration request is not exact; the returned lease is allowed to have a shorter (but not longer) duration than what was requested. The registration is persistent across restarts (crashes) of the lookup service until the lease expires or is cancelled.

Specified by:
register in interface ServiceRegistrar
Parameters:
srvItem - service item to register
leaseDuration - requested lease duration, in milliseconds
Returns:
a ServiceRegistration in this lookup service for the specified service item
Throws:
RemoteException

lookup

public Object lookup(ServiceTemplate tmpl)
              throws RemoteException
Description copied from interface: ServiceRegistrar
Returns the service object (i.e., just ServiceItem.service) from an item matching the template, or null if there is no match. If multiple items match the template, it is arbitrary as to which service object is returned. If the returned object cannot be deserialized, an UnmarshalException is thrown with the standard RMI semantics.

Specified by:
lookup in interface ServiceRegistrar
Parameters:
tmpl - template to match
Returns:
an object that represents a service that matches the specified template
Throws:
RemoteException

lookup

public ServiceMatches lookup(ServiceTemplate tmpl,
                             int maxMatches)
                      throws RemoteException
Description copied from interface: ServiceRegistrar
Returns at most maxMatches items matching the template, plus the total number of items that match the template. The return value is never null, and the returned items array is only null if maxMatches is zero. For each returned item, if the service object cannot be deserialized, the service field of the item is set to null and no exception is thrown. Similarly, if an attribute set cannot be deserialized, that element of the attributeSets array is set to null and no exception is thrown.

Specified by:
lookup in interface ServiceRegistrar
Parameters:
tmpl - template to match
maxMatches - maximum number of matches to return
Returns:
a ServiceMatches instance that contains at most maxMatches items matching the template, plus the total number of items that match the template. The return value is never null, and the returned items array is only null if maxMatches is zero.
Throws:
RemoteException

notify

public EventRegistration notify(ServiceTemplate tmpl,
                                int transitions,
                                RemoteEventListener listener,
                                MarshalledObject handback,
                                long leaseDuration)
                         throws RemoteException
Description copied from interface: ServiceRegistrar
Registers for event notification. The registration is leased; the lease expiration request is not exact. The registration is persistent across restarts (crashes) of the lookup service until the lease expires or is cancelled. The event ID in the returned EventRegistration is unique at least with respect to all other active event registrations in this lookup service with different service templates or transitions.

While the event registration is in effect, a ServiceEvent is sent to the specified listener whenever a register, lease cancellation or expiration, or attribute change operation results in an item changing state in a way that satisfies the template and transition combination.

Specified by:
notify in interface ServiceRegistrar
Parameters:
tmpl - template to match
transitions - bitwise OR of any non-empty set of transition values
listener - listener to send events to
handback - object to include in every ServiceEvent generated
leaseDuration - requested lease duration
Returns:
an EventRegistration object to the entity that registered the specified remote listener
Throws:
RemoteException

getEntryClasses

public Class[] getEntryClasses(ServiceTemplate tmpl)
                        throws RemoteException
Description copied from interface: ServiceRegistrar
Looks at all service items that match the specified template, finds every entry (among those service items) that either doesn't match any entry templates or is a subclass of at least one matching entry template, and returns the set of the (most specific) classes of those entries. Duplicate classes are eliminated, and the order of classes within the returned array is arbitrary. Null (not an empty array) is returned if there are no such entries or no matching items. If a returned class cannot be deserialized, that element of the returned array is set to null and no exception is thrown.

Specified by:
getEntryClasses in interface ServiceRegistrar
Parameters:
tmpl - template to match
Returns:
an array of entry Classes (attribute sets) for every service that matches the specified template
Throws:
RemoteException

getFieldValues

public Object[] getFieldValues(ServiceTemplate tmpl,
                               int setIndex,
                               String field)
                        throws NoSuchFieldException,
                               RemoteException
Description copied from interface: ServiceRegistrar
Looks at all service items that match the specified template, finds every entry (among those service items) that matches tmpl.attributeSetTemplates[setIndex], and returns the set of values of the specified field of those entries. Duplicate values are eliminated, and the order of values within the returned array is arbitrary. Null (not an empty array) is returned if there are no matching items. If a returned value cannot be deserialized, that element of the returned array is set to null and no exception is thrown.

Specified by:
getFieldValues in interface ServiceRegistrar
Parameters:
tmpl - template to match
setIndex - index into tmpl.attributeSetTemplates
field - name of field of tmpl.attributeSetTemplates[setIndex]
Returns:
an array of objects that represents field values of entries associated with services that meet the specified matching criteria
Throws:
NoSuchFieldException - field does not name a field of the entry template
RemoteException

handleException

static void handleException(Throwable e)
Rethrow the exception if it is an Error, unless it is a LinkageError, OutOfMemoryError, or StackOverflowError. Otherwise print the exception stack trace if debugging is enabled.


getServiceTypes

public Class[] getServiceTypes(ServiceTemplate tmpl,
                               String prefix)
                        throws RemoteException
Description copied from interface: ServiceRegistrar
Looks at all service items that match the specified template, and for every service item finds the most specific type (class or interface) or types the service item is an instance of that are neither equal to, nor a superclass of, any of the service types in the template and that have names that start with the specified prefix, and returns the set of all such types. Duplicate types are eliminated, and the order of types within the returned array is arbitrary. Null (not an empty array) is returned if there are no such types. If a returned type cannot be deserialized, that element of the returned array is set to null and no exception is thrown.

Specified by:
getServiceTypes in interface ServiceRegistrar
Parameters:
tmpl - template to match
prefix - class name prefix
Returns:
an array of Classes of all services that either match the specified template or match the specified prefix
Throws:
RemoteException

getServiceID

public ServiceID getServiceID()
Description copied from interface: ServiceRegistrar
Returns the service ID of the lookup service. Note that this does not make a remote call. A lookup service is always registered with itself under this service ID, and if a lookup service is configured to register itself with other lookup services, it will register with all of them using this same service ID.

Specified by:
getServiceID in interface ServiceRegistrar
Returns:
the service ID of the lookup service.

getLocator

public LookupLocator getLocator()
                         throws RemoteException
Description copied from interface: ServiceRegistrar
Returns a LookupLocator that can be used if necessary for unicast discovery of the lookup service.

Specified by:
getLocator in interface ServiceRegistrar
Returns:
a LookupLocator that can be used for unicast discovery of the lookup service, if necessary.
Throws:
RemoteException

getGroups

public String[] getGroups()
                   throws RemoteException
Description copied from interface: ServiceRegistrar
Returns the set of groups that this lookup service is currently a member of.

Specified by:
getGroups in interface ServiceRegistrar
Returns:
a String array of groups that this lookup service is currently a member of.
Throws:
RemoteException

getReferentUuid

public Uuid getReferentUuid()
Description copied from interface: ReferentUuid
Return the Uuid that has been assigned to the resource this proxy represents.

Specified by:
getReferentUuid in interface ReferentUuid
Returns:
the Uuid associated with the resource this proxy represents. Will not return null.

hashCode

public int hashCode()
Overrides:
hashCode in class Object

equals

public boolean equals(Object obj)
Proxies for servers with the same service ID are considered equal.

Overrides:
equals in class Object

toString

public String toString()
Returns a string created from the proxy class name, the registrar's service ID, and the result of the underlying proxy's toString method.

Overrides:
toString in class Object
Returns:
String

writeObject

private void writeObject(ObjectOutputStream out)
                  throws IOException
Writes the default serializable field value for this instance, followed by the registrar's service ID encoded as specified by the ServiceID.writeBytes method.

Throws:
IOException

readObject

private void readObject(ObjectInputStream in)
                 throws IOException,
                        ClassNotFoundException
Reads the default serializable field value for this instance, followed by the registrar's service ID encoded as specified by the ServiceID.writeBytes method. Verifies that the deserialized registrar reference is non-null.

Throws:
IOException
ClassNotFoundException

readObjectNoData

private void readObjectNoData()
                       throws ObjectStreamException
Throws InvalidObjectException, since data for this class is required.

Throws:
ObjectStreamException


Copyright 2007-2010, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.