com.sun.jini.fiddler

Interface Fiddler

All Superinterfaces:

Administrable, DestroyAdmin, FiddlerAdmin, JoinAdmin, Remote, ServiceProxyAccessor

All Known Implementing Classes:

ActivatableFiddlerImpl, FiddlerImpl, NonActivatableFiddlerImpl, TransientFiddlerImpl

interface Fiddler
extends Remote, Administrable, FiddlerAdmin, ServiceProxyAccessor

This interface defines the private protocol between the client-side proxy and the server of a lookup discovery service.

The declared methods mirror the methods of the LookupDiscoveryService interface. Classes that act as a "smart proxy" to the lookup discovery service typically contain a field which implements this interface. When the lookup discovery service registers with a lookup service, the proxy - containing a "server field" that is an instance of this interface - is registered. It is through the server field that the proxy interacts with the back-end server of the lookup discovery service, on behalf of a client, using the private protocol defined by a class that implements this interface.

Author:

Sun Microsystems, Inc.

Method Summary

Methods

Modifier and Type	Method and Description
void	addGroups(Uuid registrationID, 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(Uuid registrationID, 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.
void	cancelLease(Uuid registrationID, Uuid leaseID) This method cancels the lease corresponding to the given registrationID and leaseID parameters.
Exception[]	cancelLeases(Uuid[] registrationIDs, Uuid[] leaseIDs) Cancels all leases from a LeaseMap.
void	discard(Uuid registrationID, 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.
String[]	getGroups(Uuid registrationID) 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.
LookupLocator[]	getLocators(Uuid registrationID) 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	getProxyID() Returns the unique identifier generated (or recovered) by the back-end implementation of the lookup discovery service when an instance of that service is constructed.
MarshalledObject[]	getRegistrars(Uuid registrationID) Returns an array consisting of instances of the ServiceRegistrar interface.
LookupDiscoveryRegistration	register(String[] groups, LookupLocator[] locators, RemoteEventListener listener, MarshalledObject handback, long leaseDuration) On behalf of a requesting client, creates a registration with the lookup discovery service, which then performs discovery processing on behalf of the client.
void	removeGroups(Uuid registrationID, 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(Uuid registrationID, 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.
long	renewLease(Uuid registrationID, Uuid leaseID, long duration) This method renews the lease corresponding to the given registrationID and leaseID parameters, granting a new duration that is less than or equal to the requested duration value contained in the duration parameter.
FiddlerRenewResults	renewLeases(Uuid[] registrationIDs, Uuid[] leaseIDs, long[] durations) Renews all leases from a LeaseMap.
void	setGroups(Uuid registrationID, 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(Uuid registrationID, 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.

Methods inherited from interface net.jini.admin.Administrable

getAdmin

Methods inherited from interface com.sun.jini.fiddler.FiddlerAdmin

getLeaseBound, getPersistenceSnapshotThreshold, getPersistenceSnapshotWeight, setLeaseBound, setPersistenceSnapshotThreshold, setPersistenceSnapshotWeight

Methods inherited from interface net.jini.admin.JoinAdmin

addLookupAttributes, addLookupGroups, addLookupLocators, getLookupAttributes, getLookupGroups, getLookupLocators, modifyLookupAttributes, removeLookupGroups, removeLookupLocators, setLookupGroups, setLookupLocators

Methods inherited from interface com.sun.jini.admin.DestroyAdmin

destroy

Methods inherited from interface com.sun.jini.start.ServiceProxyAccessor

getServiceProxy

Method Detail

getProxyID

Uuid getProxyID()
                throws RemoteException

Returns the unique identifier generated (or recovered) by the back-end implementation of the lookup discovery service when an instance of that service is constructed. This ID is typically used to determine equality between the proxies of any two instances of the lookup discovery service.

Returns:

the unique ID that was generated (or recovered) by the back-end implementation of the lookup discovery service at creation time

Throws:

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

register

LookupDiscoveryRegistration register(String[] groups,
                                   LookupLocator[] locators,
                                   RemoteEventListener listener,
                                   MarshalledObject handback,
                                   long leaseDuration)
                                     throws RemoteException

On behalf of a requesting client, creates a registration with the lookup discovery service, which then performs discovery processing on behalf of the client.

Parameters:

groups - String array, none of whose elements may be null, consisting of zero or more names of groups to which lookup services to discover belong.

locators - array of zero or more non-null LookupLocator objects, each corresponding to a specific lookup service to discover.

listener - a non-null instance of RemoteEventListener. This argument specifies the entity that will receive events notifying the registration that a lookup service of interest has been discovered.

handback - null or an instance of MarshalledObject. This argument specifies an object that will be included in the notification event that the lookup discovery service sends to the registered listener.

leaseDuration - long value representing the amount of time (in milliseconds) for which the resources of the lookup discovery service are being requested.

Returns:

an instance of the LookupDiscoveryRegistration interface.

Throws:

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 may or may not have completed successfully.

See Also:

LookupDiscoveryService.register(java.lang.String[], net.jini.core.discovery.LookupLocator[], net.jini.core.event.RemoteEventListener, java.rmi.MarshalledObject, long)

getRegistrars

MarshalledObject[] getRegistrars(Uuid registrationID)
                                 throws RemoteException,
                                        ThrowThis

Returns an array consisting of instances of the ServiceRegistrar interface. Each element in the returned set is a proxy to one of the lookup service(s) that have already been discovered for the registration corresponding to the registrationID parameter. Each element of the return set is a marshalled instance of the ServiceRegistrar interface. The contents of the returned set make up the 'remote state' of the registration's currently discovered lookup service(s).

Parameters:

registrationID - unique identifier assigned to the registration from which the set of registrars is being retrieved

Returns:

an array of MarshalledObject objects where each element is is a marshalled instance of ServiceRegistrar.

Throws:

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

ThrowThis - which is a non-remote "wrapper" class used to wrap various remote exceptions (for example, NoSuchObjectException) that this method wishes to throw. When a service is implemented as a smart proxy with a backend server, and a method on the backend which was invoked through the proxy wishes to explicitly throw a particular remote exception, it cannot simply throw that exception if it wishes that exception to be visible to the proxy running on the "client side". This is because when the backend throws any remote exception, the RMI sub-system automatically wraps that exception in a java.rmi.ServerException. Thus, the proxy will only be able to "see" the ServerException (the actual exception that the backend tried to throw is "buried" in the detail field of the ServerException). Thus, in order to allow the proxy access to the actual remote exception this method throws, that exception wraps the desired remote exception in the non-remote exception ThrowThis; which will not be wrapped in a ServerException. This method throws a NoSuchObjectException wrapped in a ThrowThis exception whenever the registrationID parameter references an invalid or non-existent registration.

See Also:

LookupDiscoveryRegistration.getRegistrars()

getGroups

String[] getGroups(Uuid registrationID)
                   throws RemoteException,
                          ThrowThis

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.

Parameters:

registrationID - unique identifier assigned to the registration from which the set of groups is being retrieved

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 - wrapped in an instance of com.sun.jini.proxy.ThrowThis exception whenever the registrationID parameter references an invalid or non-existent registration. Refer to the description of the getRegistrars method for more information on this exception.

ThrowThis

See Also:

LookupDiscoveryRegistration.getGroups()

getLocators

LookupLocator[] getLocators(Uuid registrationID)
                            throws RemoteException,
                                   ThrowThis

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.

Parameters:

registrationID - unique identifier assigned to the registration from which the set of locators is being retrieved

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 - wrapped in an instance of com.sun.jini.proxy.ThrowThis exception whenever the registrationID parameter references an invalid or non-existent registration. Refer to the description of the getRegistrars method for more information on this exception.

ThrowThis

See Also:

LookupDiscoveryRegistration.getLocators()

addGroups

void addGroups(Uuid registrationID,
             String[] groups)
               throws RemoteException,
                      ThrowThis

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

Parameters:

registrationID - unique identifier assigned to the registration to which the set of groups being augmented corresponds

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:

IllegalStateException - this exception occurs when the addGroups method of the discovery manager is invoked after the terminate method of that manager is called.

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 - wrapped in an instance of com.sun.jini.proxy.ThrowThis exception whenever the registrationID parameter references an invalid or non-existent registration. Refer to the description of the getRegistrars method for more information on this exception.

ThrowThis

See Also:

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

setGroups

void setGroups(Uuid registrationID,
             String[] groups)
               throws RemoteException,
                      ThrowThis

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

Parameters:

registrationID - unique identifier assigned to the registration to which the set of groups being replaced corresponds

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:

IllegalStateException - this exception occurs when the addGroups method of the discovery manager is invoked after the terminate method of that manager is called.

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 - wrapped in an instance of com.sun.jini.proxy.ThrowThis exception whenever the registrationID parameter references an invalid or non-existent registration. Refer to the description of the getRegistrars method for more information on this exception.

ThrowThis

See Also:

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

removeGroups

void removeGroups(Uuid registrationID,
                String[] groups)
                  throws RemoteException,
                         ThrowThis

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

Parameters:

registrationID - unique identifier assigned to the registration to which the set of groups being removed corresponds

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:

IllegalStateException - this exception occurs when the addGroups method of the discovery manager is invoked after the terminate method of that manager is called.

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 - wrapped in an instance of com.sun.jini.proxy.ThrowThis exception whenever the registrationID parameter references an invalid or non-existent registration. Refer to the description of the getRegistrars method for more information on this exception.

ThrowThis

See Also:

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

addLocators

void addLocators(Uuid registrationID,
               LookupLocator[] locators)
                 throws RemoteException,
                        ThrowThis

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

Parameters:

registrationID - unique identifier assigned to the registration to which the set of locators being augmented corresponds

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 - wrapped in an instance of com.sun.jini.proxy.ThrowThis exception whenever the registrationID parameter references an invalid or non-existent registration. Refer to the description of the getRegistrars method for more information on this exception.

ThrowThis

See Also:

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

setLocators

void setLocators(Uuid registrationID,
               LookupLocator[] locators)
                 throws RemoteException,
                        ThrowThis

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.

Parameters:

registrationID - unique identifier assigned to the registration to which the set of locators being replaced corresponds

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 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 - wrapped in an instance of com.sun.jini.proxy.ThrowThis exception whenever the registrationID parameter references an invalid or non-existent registration. Refer to the description of the getRegistrars method for more information on this exception.

ThrowThis

See Also:

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

removeLocators

void removeLocators(Uuid registrationID,
                  LookupLocator[] locators)
                    throws RemoteException,
                           ThrowThis

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

Parameters:

registrationID - unique identifier assigned to the registration to which the set of locators being removed corresponds

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 - wrapped in an instance of com.sun.jini.proxy.ThrowThis exception whenever the registrationID parameter references an invalid or non-existent registration. Refer to the description of the getRegistrars method for more information on this exception.

ThrowThis

See Also:

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

discard

void discard(Uuid registrationID,
           ServiceRegistrar registrar)
             throws RemoteException,
                    ThrowThis

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.

Parameters:

registrationID - unique identifier assigned to the registration making the current discard request

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 - wrapped in an instance of com.sun.jini.proxy.ThrowThis exception whenever the registrationID parameter references an invalid or non-existent registration. Refer to the description of the getRegistrars method for more information on this exception.

ThrowThis

See Also:

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

renewLease

long renewLease(Uuid registrationID,
              Uuid leaseID,
              long duration)
                throws UnknownLeaseException,
                       RemoteException

This method renews the lease corresponding to the given registrationID and leaseID parameters, granting a new duration that is less than or equal to the requested duration value contained in the duration parameter.

Parameters:

registrationID - unique identifier assigned to the registration to which the lease being renewed corresponds

leaseID - identifier assigned by the lease grantor to the lease being renewed

duration - the requested duration for the lease being renewed

Returns:

long value representing the actual duration that was granted for the renewed lease. Note that the actual duration granted and returned by this method may be less than the duration requested.

Throws:

UnknownLeaseException - this exception occurs when the lease being renewed does not exist, or is unknown to the lease grantor; typically because the lease has expired.

RemoteException - typically, this exception occurs when there is a communication failure between the client and the server. When this exception does occur, the lease may or may not have been renewed successfully.

See Also:

Lease.renew(long)

renewLeases

FiddlerRenewResults renewLeases(Uuid[] registrationIDs,
                              Uuid[] leaseIDs,
                              long[] durations)
                                throws RemoteException

Renews all leases from a LeaseMap.

For each element in the registrationIDs parameter, this method will renew the corresponding element in the leaseIDs parameter with the corresponding element in the registrationID parameter.

Parameters:

registrationIDs - array containing the unique identifiers assigned to the each registration to which each lease to be renewed corresponds

leaseIDs - array containing the identifiers assigned by the lease grantor to each lease being renewed

durations - array containing the requested durations for each lease being renewed

Returns:

an instance of FiddlerRenewResults containing data corresponding to the results (granted durations or exceptions) of each renewal attempt

Throws:

RemoteException - typically, this exception occurs when there is a communication failure between the client and the server. When this exception does occur, this method may or may not have complete its processing successfully.

See Also:

LeaseMap.renewAll()

cancelLease

void cancelLease(Uuid registrationID,
               Uuid leaseID)
                 throws UnknownLeaseException,
                        RemoteException

This method cancels the lease corresponding to the given registrationID and leaseID parameters.

Parameters:

registrationID - unique identifier assigned to the registration to which the lease being cancelled corresponds

leaseID - identifier assigned by the lease grantor to the lease being cancelled

Throws:

UnknownLeaseException - this exception occurs when the lease being cancelled is unknown to the lease grantor.

RemoteException - typically, this exception occurs when there is a communication failure between the client and the server. When this exception does occur, the lease may or may not have been cancelled successfully.

See Also:

Lease.cancel()

cancelLeases

Exception[] cancelLeases(Uuid[] registrationIDs,
                       Uuid[] leaseIDs)
                         throws RemoteException

Cancels all leases from a LeaseMap.

For each element in the registrationIDs parameter, this method will cancel the corresponding element in the leaseIDs parameter.

Parameters:

registrationIDs - array containing the unique identifiers assigned to the each registration to which each lease to be cancelled corresponds

leaseIDs - array containing the identifiers assigned by the lease grantor to each lease being cancelled

Returns:

array consisting of any exceptions that may have occurred while attempting to cancel one of the leases in the map.

Throws:

RemoteException - typically, this exception occurs when there is a communication failure between the client and the server. When this exception does occur, this method may or may not have complete its processing successfully.

See Also:

LeaseMap.cancelAll()