com.sun.jini.fiddler

Class FiddlerRegistration

java.lang.Object

com.sun.jini.fiddler.FiddlerRegistration

All Implemented Interfaces:

Serializable, LookupDiscoveryRegistration, ReferentUuid

Direct Known Subclasses:

FiddlerRegistration.ConstrainableFiddlerRegistration

 class FiddlerRegistration
extends Object
implements LookupDiscoveryRegistration, ReferentUuid, Serializable

This class is an implementation of the LookupDiscoveryRegistration interface.

When a client requests a registration with a lookup discovery service, an instance of this class is returned. This class is used by the client as a proxy to the registration object created by the lookup discovery service for the client. The remote methods of this class each have a counterpart on the back-end server of the Fiddler implementation of the lookup discovery service. The client can use the methods implemented in this class to manage the parameters of its registration with the lookup discovery service.

Author:

Sun Microsystems, Inc.

See Also:

LookupDiscoveryRegistration

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
(package private) static class	FiddlerRegistration.ConstrainableFiddlerRegistration The constrainable version of FiddlerRegistration.

Field Summary

Fields

Modifier and Type	Field and Description
(package private) EventRegistration	eventReg The object which encapsulates the information used by the client to identify a notification sent by the lookup discovery service to the listener registered with the lookup discovery service by the client's registration, for which the instance of this class serves as proxy.
(package private) Uuid	registrationID The unique identifier assigned to the current instance of this registration proxy class by the lookup discovery service.
private static long	serialVersionUID
(package private) Fiddler	server The reference through which communication occurs between the client-side and the server-side of the lookup discovery service

Constructor Summary

Constructors

Modifier	Constructor and Description
private	FiddlerRegistration(Fiddler server, Uuid registrationID, EventRegistration eventReg) Constructs a new instance of FiddlerRegistration.

Method Summary

Methods

Modifier and Type	Method and Description
void	addGroups(String[] groups) Adds a set of group names to the managed set of groups associated with the registration corresponding to the current instance of this class.
void	addLocators(LookupLocator[] locators) Adds a set of LookupLocator objects to the managed set of locators associated with the registration corresponding to the current instance of this class.
static FiddlerRegistration	createRegistration(Fiddler server, Uuid registrationID, EventRegistration eventReg) Public static factory method that creates and returns an instance of FiddlerRegistration.
void	discard(ServiceRegistrar registrar) Informs the lookup discovery service of the existence of an unavailable lookup service and requests that the lookup discovery service discard the unavailable lookup service.
boolean	equals(Object obj) For any instance of this class, indicates whether the object input to this method is equal to the current instance of this class; where equality of proxies to a registration with a lookup discovery service is defined by reference equality.
EventRegistration	getEventRegistration() Returns an EventRegistration object that encapsulates the information needed by the client to identify a notification sent by the lookup discovery service to the registration's listener.
String[]	getGroups() Returns an array consisting of the names of the groups whose members are lookup services the lookup discovery service will attempt to discover for the registration corresponding to the current instance of this class.
Lease	getLease() Returns the Lease object that controls a client's registration with the lookup discovery service.
LookupLocator[]	getLocators() Returns an array consisting of the the LookupLocator objects corresponding to specific lookup services the lookup discovery service will attempt to discover for for the registration corresponding to the current instance of this class.
Uuid	getReferentUuid() Returns the universally unique identifier that has been assigned to the resource this proxy represents.
ServiceRegistrar[]	getRegistrars() Returns an array consisting of instances of the ServiceRegistrar interface.
int	hashCode() For any instance of this class, returns the hashcode value generated by the hashCode method of the registration ID associated with the current instance of this proxy.
private static int	indexFirstNull(Object[] arr) Finds the index of the first element in the input array that contains null.
private static void	insertRegistrars(ServiceRegistrar[] regsArray, ArrayList regsList) Places the the lookup service reference(s), contained in the input ArrayList, into the 'empty' slots occurring at the end (indicated by the first null element) of the input array.
private void	readObject(ObjectInputStream s) When an instance of this class is deserialized, this method is automatically invoked.
private void	readObjectNoData() During deserialization of an instance of this class, if it is found that the stream contains no data, this method is automatically invoked.
void	removeGroups(String[] groups) Deletes a set of group names from the managed set of groups associated with the registration corresponding to the current instance of this class.
void	removeLocators(LookupLocator[] locators) Deletes a set of LookupLocator objects from the managed set of locators associated with the registration corresponding to the current instance of this class.
void	setGroups(String[] groups) Replaces all of the group names in the managed set of groups associated with the registration corresponding to the current instance of this class.
void	setLocators(LookupLocator[] locators) Replaces with a new set of LookupLocator objects, all of the elements in the managed set of locators associated with the registration corresponding to the current instance of this class.
private static ArrayList	unmarshalRegistrars(ArrayList marshalledRegs, ArrayList unmarshalledRegs) Attempts to unmarshal each element of the first input argument.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

serialVersionUID

private static final long serialVersionUID

See Also:

Constant Field Values

server

final Fiddler server

The reference through which communication occurs between the client-side and the server-side of the lookup discovery service

registrationID

final Uuid registrationID

The unique identifier assigned to the current instance of this registration proxy class by the lookup discovery service. This ID is used to determine equality between registrations (proxies), as well as to index into the various managed sets maintained by the back-end server.

eventReg

final EventRegistration eventReg

The object which encapsulates the information used by the client to identify a notification sent by the lookup discovery service to the listener registered with the lookup discovery service by the client's registration, for which the instance of this class serves as proxy.

Note that it is this object that contains the lease object through which the client requests the renewal or cancellation of its registration with this service.

Constructor Detail

FiddlerRegistration

private FiddlerRegistration(Fiddler server,
                   Uuid registrationID,
                   EventRegistration eventReg)

Constructs a new instance of FiddlerRegistration.

Parameters:

server - reference to the server object through which communication occurs between the client-side and server-side of the lookup discovery service.

registrationID - the unique identifier assigned by the lookup discovery service to the current instance of this proxy

eventReg - object which encapsulates the information used by the client to identify a notification sent by the lookup discovery service to the listener registered with the lookup discovery service by the client's registration, for which the instance of this class serves as proxy.

It is through this object that the client requests the renewal or cancellation of the registration being constructed.

Method Detail

createRegistration

public static FiddlerRegistration createRegistration(Fiddler server,
                                     Uuid registrationID,
                                     EventRegistration eventReg)

Public static factory method that creates and returns an instance of FiddlerRegistration. If the server associated with this registration implements RemoteMethodControl, then the object returned by this method will also implement RemoteMethodControl.

Parameters:

server - reference to the server object through which communication occurs between the client-side and server-side of the lookup discovery service.

registrationID - the unique identifier assigned by the lookup discovery service to the current instance of this proxy

eventReg - object which encapsulates the information used by the client to identify a notification sent by the lookup discovery service to the listener registered with the lookup discovery service by the client's registration, for which the instance of this class serves as proxy.

It is through this object that the client requests the renewal or cancellation of the registration being constructed.

Returns:

an instance of FiddlerRegistration that implements RemoteMethodControl if the given server does.

getEventRegistration

public EventRegistration getEventRegistration()

Returns an EventRegistration object that encapsulates the information needed by the client to identify a notification sent by the lookup discovery service to the registration's listener. This method is not remote and takes no arguments.

Specified by:

getEventRegistration in interface LookupDiscoveryRegistration

Returns:

the EventRegistration for this registration.

See Also:

LookupDiscoveryRegistration.getEventRegistration()

getLease

public Lease getLease()

Returns the Lease object that controls a client's registration with the lookup discovery service. It is through the object returned by this method that the client can request the renewal or cancellation of the registration with the lookup discovery service. This method is not remote and takes no arguments.

Specified by:

getLease in interface LookupDiscoveryRegistration

Returns:

the Lease on this registration.

See Also:

LookupDiscoveryRegistration.getLease()

getRegistrars

public ServiceRegistrar[] getRegistrars()
                                 throws LookupUnmarshalException,
                                        RemoteException

Returns an array consisting of instances of the ServiceRegistrar interface. Each element in the returned set is a proxy to one of lookup service(s) that have already been discovered for this registration. The contents of the returned set make up the 'remote state' of this registration's currently discovered lookup service(s). This method returns a new array on each invocation.

To obtain the desired lookup service proxies, this method sends a request to the the lookup discovery service. Upon receiving the request, the lookup discovery service sends the requested set of proxies as a set of marshalled instances of the ServiceRegistrar interface. Thus, in order to construct the return set, this method attempts to unmarshal each element of the set received from the lookup discovery service. Should a failure occur while attempting to unmarshal any of the elements of the received set of marshalled proxy objects, this method will throw an exception of type LookupUnmarshalException.

When a LookupUnmarshalException is thrown by this method, the contents of the exception provides the client with the following useful information: (1) the knowledge that a problem has occurred while unmarshalling at least one of the elements making up the remote state of this registration's discovered lookup service(s), (2) the set consisting of the proxy objects that were successfully unmarshalled by this method, (3) the set consisting of the marshalled proxy objects that could not be unmarshalled by this method, and (4) the set of exceptions corresponding to each failed attempt at unmarshalling.

Typically, the type of exception that occurs when attempting to unmarshal an element of the set of marshalled proxies is either an IOException or a ClassNotFoundException. A ClassNotFoundException occurs whenever a remote field of the marshalled proxy cannot be retrieved (usually because the codebase of one of the field's classes or interfaces is currently 'down'). To address this situation, the client may wish to proceed with its processing using the successfully unmarshalled proxies; and attempt to unmarshal the unavailable proxies (or re-invoke this method) at some later time.

Note that if this method returns successfully without throwing a LookupUnmarshalException, the client is guaranteed that all marshalled proxies returned to this method by the lookup discovery service have been successfully unmarshalled; and the client then has a snapshot - relative to the point in time when this method is invoked - of the remote state of the lookup service(s) discovered for this registration.

Specified by:

getRegistrars in interface LookupDiscoveryRegistration

Returns:

an array of ServiceRegistrar objects.

Throws:

LookupUnmarshalException - this exception is thrown when failure occurs while attempting to unmarshal one or more of the marshalled instances of ServiceRegistrar received from the lookup discovery service.

RemoteException - typically, this exception occurs when there is a communication failure between the client and the lookup discovery service.

NoSuchObjectException - whenever the referenced registration is invalid or non-existent.

See Also:

LookupDiscoveryRegistration.getRegistrars()

getGroups

public String[] getGroups()
                   throws RemoteException

Returns an array consisting of the names of the groups whose members are lookup services the lookup discovery service will attempt to discover for the registration corresponding to the current instance of this class. This set of group names is referred to as the registration's 'managed set of groups'.

If the registration's managed set of groups is currently empty, then the empty array is returned. If the lookup discovery service currently has no managed set of groups for the registration through which the request is being made, then null will be returned.

Specified by:

getGroups in interface LookupDiscoveryRegistration

Returns:

a String array containing the elements of the managed set of groups for the registration.

Throws:

RemoteException - typically, this exception occurs when there is a communication failure between the client and the lookup discovery service.

NoSuchObjectException - whenever the registrationID parameter references an invalid or non-existent registration.

See Also:

LookupDiscoveryRegistration.getGroups()

getLocators

public LookupLocator[] getLocators()
                            throws RemoteException

Returns an array consisting of the the LookupLocator objects corresponding to specific lookup services the lookup discovery service will attempt to discover for for the registration corresponding to the current instance of this class. This set of locators is referred to as the registration's 'managed set of locators'.

If the registration's managed set of locators is currently empty, then the empty array is returned. If the lookup discovery service currently has no managed set of locators for the registration through which the request is being made, then null will be returned.

Specified by:

getLocators in interface LookupDiscoveryRegistration

Returns:

array consisting of net.jini.core.discovery.LookupLocator objects corresponding to the elements of the managed set of locators for the registration.

Throws:

RemoteException - typically, this exception occurs when there is a communication failure between the client and the lookup discovery service.

NoSuchObjectException - whenever the registrationID parameter references an invalid or non-existent registration.

See Also:

LookupDiscoveryRegistration.getLocators()

addGroups

public void addGroups(String[] groups)
               throws RemoteException

Adds a set of group names to the managed set of groups associated with the registration corresponding to the current instance of this class.

Specified by:

addGroups in interface LookupDiscoveryRegistration

Parameters:

groups - a String array, none of whose elements may be null, consisting of the group names with which to augment the registration's managed set of groups.

If any element of this parameter duplicates any other element of this parameter, the duplicate will be ignored. If any element of this parameter duplicates any element of the registration's current managed set of groups, the duplicate will be ignored.

If the empty set is input, then the registration's managed set of groups will not change. If null is input, this method will throw a NullPointerException.

Throws:

UnsupportedOperationException - this exception occurs when the lookup discovery service has no managed set of groups associated with the registration.

NullPointerException - this exception occurs when either null is input to the groups parameter, or one or more of the elements of the groups parameter is null.

RemoteException - typically, this exception occurs when there is a communication failure between the client and the lookup discovery service. When this exception does occur, the registration's managed set of groups may or may not have been successfully augmented.

NoSuchObjectException - whenever the registrationID parameter references an invalid or non-existent registration.

See Also:

LookupDiscoveryRegistration.addGroups(java.lang.String[])

setGroups

public void setGroups(String[] groups)
               throws RemoteException

Replaces all of the group names in the managed set of groups associated with the registration corresponding to the current instance of this class.

Specified by:

setGroups in interface LookupDiscoveryRegistration

Parameters:

groups - a String array, none of whose elements may be null, consisting of the group names with which to replace the names in this registration's managed set of groups.

If any element of this parameter duplicates any other element of this parameter, the duplicate will be ignored.

If the empty set is input, then group discovery for the registration will cease. If null is input, the lookup discovery service will attempt to discover all as yet undiscovered lookup services located within its multicast radius and, upon discovery of any such lookup service, will send to the registration's listener an event signaling that discovery.

Throws:

NullPointerException - this exception occurs when one or more of the elements of the groups parameter is null.

RemoteException - typically, this exception occurs when there is a communication failure between the client and the lookup discovery service. When this exception does occur, the registration's managed set of groups may or may not have been successfully replaced.

NoSuchObjectException - whenever the registrationID parameter references an invalid or non-existent registration.

See Also:

LookupDiscoveryRegistration.setGroups(java.lang.String[])

removeGroups

public void removeGroups(String[] groups)
                  throws RemoteException

Deletes a set of group names from the managed set of groups associated with the registration corresponding to the current instance of this class.

Specified by:

removeGroups in interface LookupDiscoveryRegistration

Parameters:

groups - a String array, none of whose elements may be null, consisting of the group names to delete from the registration's managed set of groups.

If any element of this parameter duplicates any other element of this parameter, the duplicate will be ignored.

If the empty set is input, the registration's managed set of groups will not change. If null is input, this method will throw a NullPointerException.

Throws:

UnsupportedOperationException - this exception occurs when the lookup discovery service has no managed set of groups associated with the registration.

NullPointerException - this exception occurs when either null is input to the groups parameter, or one or more of the elements of the groups parameter is null.

RemoteException - typically, this exception occurs when there is a communication failure between the client and the lookup discovery service. When this exception does occur, the registration's managed set of groups may or may not have been successfully modified.

NoSuchObjectException - whenever the registrationID parameter references an invalid or non-existent registration.

See Also:

LookupDiscoveryRegistration.removeGroups(java.lang.String[])

addLocators

public void addLocators(LookupLocator[] locators)
                 throws RemoteException

Adds a set of LookupLocator objects to the managed set of locators associated with the registration corresponding to the current instance of this class.

Specified by:

addLocators in interface LookupDiscoveryRegistration

Parameters:

locators - an array, none of whose elements may be null, consisting of the LookupLocator objects with which to augment the registration's managed set of locators.

If any element of this parameter duplicates any other element of this parameter, the duplicate will be ignored. If any element of this parameter duplicates any element of the registration's managed set of locators, the duplicate will be ignored.

If the empty array is input, then the registration's managed set of locators will not change. If null is input, this method will throw a NullPointerException.

Throws:

UnsupportedOperationException - this exception occurs when the lookup discovery service has no managed set of locators associated with the registration.

NullPointerException - this exception occurs when either null is input to the locators parameter, or one or more of the elements of the locators parameter is null.

RemoteException - typically, this exception occurs when there is a communication failure between the client and the lookup discovery service. When this exception does occur, the registration's managed set of locators may or may not have been successfully augmented.

NoSuchObjectException - whenever the registrationID parameter references an invalid or non-existent registration.

See Also:

LookupDiscoveryRegistration.addLocators(net.jini.core.discovery.LookupLocator[])

setLocators

public void setLocators(LookupLocator[] locators)
                 throws RemoteException

Replaces with a new set of LookupLocator objects, all of the elements in the managed set of locators associated with the registration corresponding to the current instance of this class.

Specified by:

setLocators in interface LookupDiscoveryRegistration

Parameters:

locators - an array, none of whose elements may be null, consisting of the LookupLocator objects with which to replace the locators in the registration's managed set of locators.

If any element of this parameter duplicates any other element of this parameter, the duplicate will be ignored.

If the empty array is input, then locator discovery for the registration will cease. If null is input, this method will throw a NullPointerException.

Throws:

NullPointerException - this exception occurs when either null is input to the locators parameter, or one or more of the elements of the locators parameter is null.

RemoteException - typically, this exception occurs when there is a communication failure between the client and the lookup discovery service. When this exception does occur, the registration's managed set of locators may or may not have been successfully replaced.

NoSuchObjectException - whenever the registrationID parameter references an invalid or non-existent registration.

See Also:

LookupDiscoveryRegistration.setLocators(net.jini.core.discovery.LookupLocator[])

removeLocators

public void removeLocators(LookupLocator[] locators)
                    throws RemoteException

Deletes a set of LookupLocator objects from the managed set of locators associated with the registration corresponding to the current instance of this class.

Specified by:

removeLocators in interface LookupDiscoveryRegistration

Parameters:

locators - an array, none of whose elements may be null, consisting of the LookupLocator objects to remove from the registration's managed set of locators.

If any element of this parameter duplicates any other element of this parameter, the duplicate will be ignored.

If the empty set is input, the managed set of locators will not change. If null is input, this method will throw a NullPointerException.

Throws:

UnsupportedOperationException - this exception occurs when the lookup discovery service has no managed set of locators associated with the registration.

NullPointerException - this exception occurs when either null is input to the locators parameter, or one or more of the elements of the locators parameter is null.

RemoteException - typically, this exception occurs when there is a communication failure between the client and the lookup discovery service. When this exception does occur, the registration's managed set of locators may or may not have been successfully modified.

NoSuchObjectException - whenever the registrationID parameter references an invalid or non-existent registration.

See Also:

LookupDiscoveryRegistration.removeLocators(net.jini.core.discovery.LookupLocator[])

discard

public void discard(ServiceRegistrar registrar)
             throws RemoteException

Informs the lookup discovery service of the existence of an unavailable lookup service and requests that the lookup discovery service discard the unavailable lookup service.

Specified by:

discard in interface LookupDiscoveryRegistration

Parameters:

registrar - a reference to the lookup service that the lookup discovery service is being asked to discard.

If this parameter equals none of the lookup services contained in the managed set of lookup services for this registration, no action will be taken.

Throws:

NullPointerException - this exception occurs when null is input to the registrar parameter.

RemoteException - typically, this exception occurs when there is a communication failure between the client and the lookup discovery service. When this exception does occur, the lookup service may or may not have been successfully discarded.

NoSuchObjectException - whenever the registrationID parameter references an invalid or non-existent registration.

See Also:

LookupDiscoveryRegistration.discard(net.jini.core.lookup.ServiceRegistrar)

getReferentUuid

public Uuid getReferentUuid()

Returns the universally unique identifier that has been assigned to the resource this proxy represents.

Specified by:

getReferentUuid in interface ReferentUuid

Returns:

the instance of Uuid that is associated with the resource this proxy represents. This method will not return null.

See Also:

ReferentUuid

hashCode

public int hashCode()

For any instance of this class, returns the hashcode value generated by the hashCode method of the registration ID associated with the current instance of this proxy.

Overrides:

hashCode in class Object

Returns:

int value representing the hashcode for an instance of this class.

equals

public boolean equals(Object obj)

For any instance of this class, indicates whether the object input to this method is equal to the current instance of this class; where equality of proxies to a registration with a lookup discovery service is defined by reference equality. That is, two proxies are equal if they reference (are proxies to) the same backend server.

Overrides:

equals in class Object

Parameters:

obj - reference to the object that is to be compared to the object on which this method is invoked.

Returns:

true if the object input is referentially equal to the object on which this method is invoked; false otherwise.

unmarshalRegistrars

private static ArrayList unmarshalRegistrars(ArrayList marshalledRegs,
                            ArrayList unmarshalledRegs)

Attempts to unmarshal each element of the first input argument. When an element of that argument is successfully unmarshalled, that element is removed from the first set and the resulting unmarshalled proxy is placed in the set referenced by the second input argument. Whenever failure occurs as a result of an attempt to unmarshal one of the elements of the first set, the exception that is thrown as as a result of that failure is placed in the returned set of exceptions.

Note that there is a one-to-one correspondence between the exceptions contained in the return set and the remaining elements in the first set after all unmarshalling attempts have completed.

Parameters:

marshalledRegs - an ArrayList object consisting of marshalled instances of ServiceRegistrar, each corresponding to a proxy to a lookup service.

unmarshalledRegs - an ArrayList object consisting of all successfully unmarshalled proxies from the first argument.

Returns:

an ArrayList consisting of the exceptions that occur as a result of attempts to unmarshal each element of the first argument to this method.

insertRegistrars

private static void insertRegistrars(ServiceRegistrar[] regsArray,
                    ArrayList regsList)

Places the the lookup service reference(s), contained in the input ArrayList, into the 'empty' slots occurring at the end (indicated by the first null element) of the input array.

Parameters:

regsArray - array that will receive the new references.

regsList - ArrayList containing the ServiceRegistrar references to place in regsArray input argument.

indexFirstNull

private static int indexFirstNull(Object[] arr)

Finds the index of the first element in the input array that contains null.

If the array is null (or has zero length), -1 will be returned. If every element of the array is non-null, this method will return the length of the array. Thus, after invoking this method, it is important to test for these conditions to avoid the occurrence of an IndexOutOfBoundsException when using the value returned by this method.

Parameters:

arr - Object array to examine for the first occurrence of null

Returns:

the index of the first element in the input array that contains null. A value of -1 is returned if the input array is null; the length of the array is returned if no element in the array is null.

readObject

private void readObject(ObjectInputStream s)
                 throws IOException,
                        ClassNotFoundException

When an instance of this class is deserialized, this method is automatically invoked. This implementation of this method validates the state of the deserialized instance.

Throws:

InvalidObjectException - if the state of the deserialized instance of this class is found to be invalid.

IOException

ClassNotFoundException

readObjectNoData

private void readObjectNoData()
                       throws InvalidObjectException

During deserialization of an instance of this class, if it is found that the stream contains no data, this method is automatically invoked. Because it is expected that the stream should always contain data, this implementation of this method simply declares that something must be wrong.

Throws:

InvalidObjectException - to indicate that there was no data in the stream during deserialization of an instance of this class; declaring that something is wrong.

InvalidObjectException