LD.4. Supporting Interfaces and Classes

The lookup discovery service depends on the LookupDiscoveryRegistration interface, as well as on the concrete classes RemoteDiscoveryEvent and LookupUnmarshalException.

LD.4.1. The LookupDiscoveryRegistration Interface

When a client requests a registration with the lookup discovery service, an object that implements the LookupDiscoveryRegistration interface is returned. It is through this interface that the client manages the state of its registration with the lookup discovery service.

package net.jini.discovery; 

public interface LookupDiscoveryRegistration {
    public EventRegistration getEventRegistration(); 
    public Lease getLease(); 
    public ServiceRegistrar[] getRegistrars() 
                             throws LookupUnmarshalException, 
                                    RemoteException; 
    public String[] getGroups() throws RemoteException; 
    public LookupLocator[] getLocators() 
                                      throws RemoteException; 
    public void addGroups(String[] groups) 
                                      throws RemoteException; 
    public void setGroups(String[] groups) 
                                      throws RemoteException; 
    public void removeGroups(String[] groups) 
                                      throws RemoteException; 
    public void addLocators(LookupLocator[] locators) 
                                      throws RemoteException; 
    public void setLocators(LookupLocator[] locators) 
                                      throws RemoteException; 
    public void removeLocators(LookupLocator[] locators) 
                                      throws RemoteException; 
    public void discard(ServiceRegistrar registrar) 
                                      throws RemoteException; 
} 

As with the LookupDiscoveryService interface, the LookupDiscoveryRegistration interface is not a remote interface. Each implementation of the lookup discovery service exports proxy objects that implement this interface local to the client, using an implementation-specific protocol to communicate with the actual remote server. All of the proxy methods must obey normal Java RMI remote interface semantics except where explicitly noted. Two proxy objects are equal (using the equals method) if they are proxies for the same registration created by the same lookup discovery service.

The discovery facility of the lookup discovery service, together with its event mechanism, make up the set of resources clients register to use. Because the resources of the lookup discovery service are leased, access is granted for only a limited period of time unless there is an active expression of continuing interest on the part of the client.

When a client uses the registration process to request that a lookup discovery service perform discovery of a set of desired lookup services, the client is also registered with the service’s event mechanism. Because of this implicit registration with the event mechanism, the lookup discovery service “bundles” both resources under a single lease. When that lease expires, both discovery processing and event notifications will cease with respect to the registration that resulted from the client’s request.

To facilitate lease management and event handling, the LookupDiscoveryRegistration interface defines methods that allow the client to retrieve its event registration information. Additional methods defined by this interface allow the client to retrieve references to the registration’s currently discovered lookup services, as well as to modify the managed sets of groups and locators.

If the client’s registration with the lookup discovery service has expired or been cancelled, then any invocation of a remote method defined in this interface will result in a NoSuchObjectException. That is, any method that communicates with the back end server of the lookup discovery service will throw a NoSuchObjectException if the registration on which the method is invoked no longer exists. Note that if a client receives a NoSuchObjectException as a result of an invocation of such a method, although the client can assume that the regis tration no longer exists, the client cannot assume that the lookup discovery service itself no longer exists.

Each remote method of this interface may throw a RemoteException. Typically, this exception occurs when there is a communication failure between the client and the lookup discovery service. Whenever this exception occurs as a result of the invocation of one of these methods, the method may or may not have completed its processing successfully.

LD.4.1.1. The Semantics

The methods defined by this interface are organized into a set of accessor methods, a set of group mutator methods, a set of locator mutator methods, and the discard method. Through the accessor methods, various elements of a registration’s state can be retrieved. The mutator methods provide a mechanism for changing the set of groups and locators to be discovered for the registration. Through the discard method, a particular lookup service may be made eligible for rediscovery.

The Accessor Methods

The getEventRegistration method returns an EventRegistration object that encapsulates the information the client needs to identify a notification sent by the lookup discovery service to the registration’s listener. This method is not remote and takes no arguments.

The getLease method returns the Lease object that controls a client’s registration with the lookup discovery service. It is through the Lease object returned by this method that the client requests the renewal or cancellation of the registration with the lookup discovery service. This method is not remote and takes no arguments.

Note that the object returned by the getEventRegistration method also provides a getLease method. That method and the getLease method defined by the LookupDiscoveryRegistration interface both return the same Lease object. The getLease method defined here is provided as a convenience to avoid the indirection associated with the getLease method on the EventRegistration object, as well as to avoid the overhead of making two method calls.

The getRegistrars method returns a set of instances of the ServiceRegistrar interface. Each element in the set is a proxy to one of the lookup services that have already been discovered for the registration. Additionally, each element in the set will be unique with respect to all other elements in the set, as determined by the equals method provided by each element. The contents of the set make up the current remote state of the set of lookup services discovered for the registration. This method returns a new array on each invocation.

This method can be used to maintain synchronization between the set of discovered lookup services making up a registration’s local state on the client and the registration’s corresponding remote state maintained by the lookup discovery service. The local state can become unsynchronized with the remote state when a gap occurs in the events received by the registration’s listener.

According to the event semantics of the lookup discovery service, if there is no gap between two sequence numbers, no events have been missed and the states remain synchronized with each other; if there is a gap, events may or may not have been missed. Therefore, upon finding gaps in the sequence of events, the client can invoke this method and use the returned information to synchronize the local state with the remote state.

To construct its return set, the getRegistrars method retrieves from the lookup discovery service the set of lookup service proxies making up the registration’s current remote state. When the lookup discovery service sends the requested set of proxies, the set is sent as a set of marshalled instances of the ServiceRegistrar interface. The lookup discovery service individually marshals each proxy in the set that it sends because if it were not to do so, any deserialization failure on the set would result in an IOException, and failure would be declared for the whole deserialization process, not just an individual element. This would mean that all elements of the set sent by the lookup discovery service— even those that were successfully deserialized—would be unavailable to the client. Individually marshalling each element in the set minimizes the “all or nothing” aspect of the deserialization process, allowing the client to recover those proxies that can be successfully unmarshalled and to proceed with processing that might not be possible otherwise.

When constructing the return set, this method attempts to unmarshal each element of the set of marshalled proxy objects sent by the lookup discovery service. When failure occurs while attempting to unmarshal any of those elements, this method throws an exception of type LookupUnmarshalException (described later). It is through the contents of that exception that the client can recover any available proxies and perform error handling related to the unavailable proxies. The contents of the LookupUnmarshalException provide the client with the following useful information:

• The knowledge that a problem has occurred while unmarshalling at least one of the elements making up the remote state of the registration’s discovered lookup services

• The set of proxy objects that were successfully unmarshalled by the getRegistrars method

• The set of marshalled proxy objects that could not be unmarshalled by the getRegistrars method

• The set of exceptions corresponding to each failed attempt at unmarshalling

The type of exception that occurs when attempting to unmarshal an element of the set sent by the lookup discovery service is typically an IOException or a ClassNotFoundException (usually the more common of the two). A ClassNotFoundException occurs whenever a remote object on which the marshalled proxy depends cannot be retrieved and loaded, usually because the codebase of one of the object’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.

If the getRegistrars method returns successfully without throwing a LookupUnmarshalException, the client is guaranteed that all marshalled proxies belonging to the set sent by the lookup discovery service have each been successfully unmarshalled; the client then has a snapshot—relative to the point in time when this method is invoked—of the remote state of the lookup services discovered for the associated registration.

The getGroups method returns an array consisting of the group names from the registration’s managed set; that is, the names of the groups the lookup discovery service is currently configured to discover for the associated registration. If the managed set of groups is empty, this method returns the empty array. If there is no managed set of groups associated with the registration (that is, the lookup discovery service is configured to discover DiscoveryGroupManagement.ALL_GROUPS for the registration), then null is returned.

The getLocators method returns an array consisting of the LookupLocator objects from the registration’s managed set; that is, the locators of the specific lookup services the lookup discovery service is currently configured to discover for the associated registration. If the managed set of locators is empty, this method returns the empty array.

The Group Mutator Methods

With respect to a particular registration, the groups to be discovered may be modified using the methods described in this section. In each case, a set of groups is represented as a String array, none of whose elements may be null. If any set of groups input to one of these methods contains one or more null elements, a NullPointerException is thrown. The empty set is denoted by the empty array (DiscoveryGroupManagement.NO_GROUPS), and “no set” is indicated by null (DiscoveryGroupManagement.ALL_GROUPS). No set indicates that all lookup services within the multicast radius should be discovered, regardless of group membership. Invoking any of these methods with an input set of groups that contains duplicate names is equivalent to performing the invocation with the duplicate group names removed from the input set.

The addGroups method adds a set of group names to the registration’s managed set. This method takes one argument: a String array consisting of the set of group names with which to augment the registration’s managed set.

If the registration has no current managed set of groups to augment, this method throws an UnsupportedOperationException. If the parameter value is null, this method throws a NullPointerException. If the parameter value is the empty array, then the registration’s managed set of groups will not change.

The setGroups method replaces all of the group names in the registration’s managed set with names from a new set. This method takes one argument: a String array consisting of the set of group names with which to replace the current names in the registration’s managed set.

If null is passed to setGroups, the lookup discovery service will attempt to discover any undiscovered lookup services located within range of the lookup discovery service, regardless of group membership.

If the empty set is passed to setGroups, then group discovery will be halted until the registration’s managed set of groups is changed—through a subsequent call to this method or to addGroups—to a set that is either a non-empty set of group names or null.

The removeGroups method deletes a set of group names from the registration’s managed set. This method takes one argument: a String array containing the set of group names to remove from the registration’s managed set.

If the registration has no current managed set of groups from which to remove elements, this method throws an UnsupportedOperationException. If null is input, this method throws a NullPointerException. If the registration does have a managed set of groups from which to remove elements, but either the input set is empty or none of the elements in the input set match any element in the managed set, then the registration’s managed set of groups will not change.

Once a new group name has been placed in the registration’s managed set as a result of an invocation of either addGroups or setGroups, if there are lookup services belonging to that group that have already been discovered for that registration, no event will be sent to the registration’s listener for those particular lookup services. However, attempts to discover any undiscovered lookup services belonging to that group will continue to be made on behalf of the registration.

Any already discovered lookup service that is a member of one or more of the groups removed from the registration’s managed set as a result of an invocation of either setGroups or removeGroups will be discarded and will no longer be eligible for discovery (for that registration), but only if that lookup service satisfies both of the following conditions:

• The lookup service is not a member of any group in the registration’s new managed set resulting from the invocation of setGroups or removeGroups

• With respect to the registration, the lookup service is not currently eligible for discovery through locator discovery; that is, the lookup service does not correspond to any element in the registration’s managed set of locators.

The Locator Mutator Methods

With respect to a particular registration, the set of locators to discover may be modified using the methods described in this section. In each case, a set of locators is represented as an array of LookupLocator objects, none of whose elements may be null. If any set of locators input to one of these methods contains one of more null elements, a NullPointerException is thrown. Invoking any of these methods with a set of locators that contains duplicate locators (as determined by LookupLocator.equals) is equivalent to performing the invocation with the duplicates removed from the input set.

The addLocators method adds a set of LookupLocator objects to the registration’s managed set. This method takes one argument: an array consisting of the set of locators with which to augment the registration’s managed set.

If null is passed to addLocators, a NullPointerException will be thrown. If the parameter value is the empty array, the registration’s managed set of locators will not change.

The setLocators method replaces all of the locators in the registration’s managed set with LookupLocator objects from a new set. This method takes one argument: an array consisting of the set of locators with which to replace the current locators in the registration’s managed set.

If null is passed to setLocators, a NullPointerException will be thrown.

If the empty set is passed to setLocators, then locator discovery will be halted until the registration’s managed set of locators is changed—through a subsequent call to this method or to addLocators—to a set that is nonnull and non-empty.

The removeLocators method deletes a set of LookupLocator objects from the registration’s managed set. This method takes one argument: an array contain ing the set of LookupLocator objects to remove from the registration’s managed set.

If null is passed to removeLocators, a NullPointerException will be thrown. If any element of the set of locators to remove is not contained in the registration’s managed set, removeLocators takes no action with respect to that element. If the parameter value is the empty array, the managed set of locators will not change.

Whenever a new locator is placed in the managed set as a result of an invocation of one of the locator mutator methods and that new locator equals none of the previously discovered locators (across all registrations), the lookup discovery service will attempt unicast discovery of the lookup service associated with the new locator.

If locator discovery is attempted for a registration, such discovery attempts will be repeated until one of the following events occurs:

• The lookup service is discovered

• The client’s lease on the registration expires

• The client explicitly removes the locator from the registration’s managed set

Upon discovery of the lookup service corresponding to the new locator, or upon finding a match between the new locator and a previously discovered lookup service, a discovered event will be sent to the registration’s listener, unless that lookup service was previously discovered for that registration through group discovery.

Any already discovered lookup service corresponding to a locator that is removed from the registration’s managed set as a result of an invocation of either setLocators or removeLocators will be discarded and will no longer be eligible for discovery, but only if it is not currently eligible for discovery through group discovery—that is, only if the lookup service is not also a member of one or more of the groups in the registration’s managed set of groups.

Discarding Lookup Services

When the lookup discovery service removes an already discovered lookup service from a registration’s managed set of lookup services, the lookup service is said to be discarded.

There are a number of situations in which the lookup discovery service will discard a lookup service:

• In response to a discard request resulting from an invocation of a registration’s discard method

• In response to a declaration—via an invocation of one of the mutator methods on a registration—that there is no longer any interest in one or more of the registration’s already discovered lookup services

• In response to the determination that the multicast announcements from an already discovered lookup service indicate that the lookup service has changed its group membership in such a way that the lookup service is no longer of interest to one or more of the registrations that previously registered interest in the groups of that lookup service

• In response to the determination that the multicast announcements from an already discovered lookup service are no longer being received

For each of these cases, whenever the lookup discovery service discards a lookup service, it will send an event to the registration’s listener to notify it that the lookup service has been discarded.

The discard method provides a mechanism for registered clients to inform the lookup discovery service of the existence of an unavailable—or unreachable—lookup service, and to request that the lookup discovery service discard that lookup service and make it eligible for rediscovery.

The discard method takes a single argument: the proxy to the lookup service to discard. This method takes no action if the parameter to this method equals none of the proxies reflected in the managed set (using proxy equality as defined in The Jini Technology Core Platform Specification, “Lookup Service”. If null is passed to discard, a NullPointerException is thrown.

Although the lookup discovery service monitors the multicast announcements from all discovered lookup services for indications of unavailability, it should be noted that there are conditions under which the lookup discovery service will not discard such a lookup service, even when the lookup service is found to be unreachable. Whether or not the lookup discovery service discards such an unreachable lookup service is dependent on how each registration is configured for discovery with respect to that lookup service. If every registration that is configured to discover the unreachable lookup service is configured to discover it through locator discovery only, the lookup discovery service will not discard the lookup service. In other words, in order for the lookup discovery service to discard a lookup service it has determined is unreachable, at least one registration must be configured for discovery of at least one group in which that lookup service is a member.

Thus, whenever a client determines that a previously discovered lookup service has become unreachable, it should not rely on the lookup discovery service to discard the lookup service. Instead, the client should inform the lookup discovery service—through the invocation of the registration’s discard method—that the previously discovered lookup service is no longer available and that attempts should be made to rediscover that lookup service for the registration. Typically, a client determines that a lookup service is unavailable when the client attempts to use the lookup service but receives an indefinite exception, a bad object exception, or a bad invocation exception as a result of the attempt.

Note that the lookup discovery service may be acting on behalf of numerous clients that have access to the same lookup service. If that lookup service becomes unavailable, many of those clients may invoke discard between the time the lookup service becomes unavailable and the time it is rediscovered. Upon the first invocation of discard, the lookup discovery service will re-initiate discovery of the relevant lookup service for the registration of the client that made the invocation. For all other invocations made prior to rediscovery, the registrations through which the invocation is made are sent a discarded event, and added to the list of registrations that will be notified when rediscovery of the lookup service does occur. That is, upon rediscovery of the lookup service, only those registrations through which the discard method was invoked will be notified.

Upon successful completion of the discard method, the proxy requested to be discarded is guaranteed to have been removed from the managed set of the registration through which the invocation was made. No such guarantee is made with respect to when the discarded event is sent to each such registration’s listener. That is, the event notifying the listeners that the lookup service has been discarded may or may not be sent asynchronously.

LD.4.2. The RemoteDiscoveryEvent Class

When the lookup discovery service discovers or discards a lookup service matching the criteria established through one of its registrations, the lookup discovery service sends an instance of the RemoteDiscoveryEvent class to the RemoteEventListener implemented by the client and registered with the lookup discovery service.

package net.jini.discovery; 

public class RemoteDiscoveryEvent extends RemoteEvent {
    public RemoteDiscoveryEvent(Object source, 
                                long eventID, 
                                long seqNum, 
                                MarshalledObject handback, 
                                boolean discarded, 
                                Map groups) 
                                       throws IOException {...} 

    public boolean isDiscarded() {...} 
    public ServiceRegistrar[] getRegistrars() 
                          throws LookupUnmarshalException {...} 
    public Map getGroups() {...} 
} 

The RemoteDiscoveryEvent class provides an encapsulation of event information that the lookup discovery service uses to notify a registration of the occurrence of an event involving one or more ServiceRegistrar objects (lookup services) in which the registration has registered interest. The lookup discovery service passes an instance of this class to the registration’s discovery listener when one of the following events occurs:

• Each lookup service referenced in the event has been discovered for the first time or rediscovered after having been discarded.

• Each lookup service referenced in the event has been either actively or passively discarded.

RemoteDiscoveryEvent is a subclass of RemoteEvent, adding the following additional items of abstract state:

• A boolean indicating whether the lookup services referenced by the event have been discovered or discarded

• A set of marshalled instances of the ServiceRegistrar interface having the characteristic that when each element is unmarshalled, the result is a proxy to one of the discovered or discarded lookup services referenced by the event

• A Map instance in which the elements of the map’s key set are the instances of ServiceID that correspond to each lookup service reference returned in the event, and the map’s value set contains the corresponding member groups of each lookup service reference

Methods are defined through which this additional state may be retrieved upon receipt of an instance of this class.

Clients need to know not only when a targeted lookup service has been discovered, but also when it has been discarded. The lookup discovery service uses an instance of RemoteDiscoveryEvent to notify a registration when either of these events occurs, as indicated by the value of the boolean state variable. When the value of that variable is true, the event is referred to as a discarded event; when false, it is referred to as a discovered event.

LD.4.2.1. The Semantics

The constructor of the RemoteDiscoveryEvent class takes the following parameters as input:

• A reference to the lookup discovery service that generated the event

• The event identifier that maps a particular registration to both its listener and its targeted groups and locators

• The sequence number of the event being constructed

• The client-defined handback (which may be null)

• A flag indicating whether the event being constructed is a discovered event or a discarded event

• A Map whose key set contains the proxies to newly discovered or discarded lookup service(s) the event is to reference, and whose value set contains the corresponding member groups of each lookup service

If the groups parameter is empty, the constructor will throw an IllegalArgumentException. If null is input to the groups parameter, the constructor will throw a NullPointerException. If none of the proxies referenced in the groups parameter can be successfully serialized, the constructor will throw an IOException.

The isDiscarded method returns a boolean that indicates whether the event is a discovered event or a discarded event. If the event is a discovered event, then this method returns false. If the event is a discarded event, true is retuned.

The getRegistrars method returns an array consisting of instances of the ServiceRegistrar interface. Each element in the returned set is a proxy to one of the newly discovered or discarded lookup services that caused a RemoteDiscoveryEvent to be sent. Additionally, each element in the returned set will be unique with respect to all other elements in the set, as determined by the equals method provided by each element. This method does not make a remote call. With respect to multiple invocations of this method, each invocation will return a new array.

When the lookup discovery service sends an instance of RemoteDiscoveryEvent to the listener of a client’s registration, the set of lookup service proxies contained in the event consists of marshalled instances of the ServiceRegistrar interface. The lookup discovery service individually marshals each proxy associated with the event because if it were not to do so, any deserialization failure on the set would result in an IOException, and failure would be declared for the whole deserialization process, not just an individual element. This would mean that all elements of the set sent in the event—even those that can be successfully deserialized—would be unavailable to the client through this method. Just as with the getRegistrars method defined by the LookupDiscoveryRegistration interface, individually marshalling each element in the set minimizes the “all or nothing” aspect of the deserialization process, allowing the client to recover those proxies that can be successfully unmarshalled and to proceed with processing that might not be possible otherwise.

When constructing the return set, this method attempts to unmarshal each element of the set of marshalled proxy objects contained in the event. When failure occurs while attempting to unmarshal any of the elements of that set, this method throws an exception of type LookupUnmarshalException. It is through the contents of this exception that the client can recover any available proxies and perform error handling with respect to the unavailable proxies.

If the getRegistrars method returns successfully without throwing a LookupUnmarshalException, the client is guaranteed that all marshalled proxies sent in the event have each been successfully unmarshalled during that particular invocation. Furthermore, after the first such successful invocation, no more unmarshalling attempts will be made (because such attempts are no longer necessary), and all future invocations of this method are guaranteed to return an array with contents identical to the contents of the array returned by the first successful invocation.

Note that an array, rather than a single proxy, is returned by the getRegistrars method so that implementations of the lookup discovery service can choose to “batch” the information sent to a registration. With respect to discoveries, batching the information may be particularly useful when a client first registers with the lookup discovery service.

Upon initial registration, multiple lookup services are typically found over a short period of time, providing the lookup discovery service with the opportunity to send all of the initially discovered lookup services in only one event. Afterward, as so-called “late joiner” lookup services are found sporadically, the lookup discovery service may send events referencing only one lookup service.

Note that the event sequence numbers, as defined earlier in Section LD.3.2, “Event Semantics”, are strictly increasing, even when the information is batched.

The getGroups method returns a Map in which the elements of the map’s key set are the instances of ServiceID that correspond to each lookup service for which the event was constructed and sent. Each element of the returned map’s value set is a String array containing the names of the member groups of the associated lookup service whose ServiceID equals to the corresponding key. This method does not make a remote call. On each invocation of this method, the same Map object is returned; that is, a copy is not made.

The Map returned by the getGroups method is keyed by the ServiceID of each lookup service in the event, rather than by the proxy of each lookup service to avoid the deserialization issues addressed by the getRegistrars method. Thus, client’s wishing to retrieve the set of member groups corresponding to any element of the array returned by the getRegistrars method, must use the ServiceID of the desired element from that array as the key to the get method of the Map returned by this method and then cast to String[].

LD.4.2.2. Serialized Forms

LD.4.3. The LookupUnmarshalException Class

Recall that when unmarshalling an instance of MarshalledObject, one of the following checked exceptions is possible:

• An IOException, which can occur while deserializing the object from its internal representation

• A ClassNotFoundException, which can occur if, while deserializing the object from its internal representation, either the class file of the object cannot be found, or the class file of an interface or class referenced by the object being deserialized cannot be found. Typically, a ClassNotFoundException occurs when the codebase from which to retrieve the needed class file is not currently available

The LookupUnmarshalException class provides a mechanism that clients of the lookup discovery service may use for efficient handling of the exceptions that may occur when unmarshalling elements of a set of marshalled instances of the ServiceRegistrar interface. When elements in such a set are unmarshalled, the LookupUnmarshalException class may be used to collect and report pertinent information generated when failure occurs during the unmarshalling process.

package net.jini.discovery; 

public class LookupUnmarshalException extends Exception {
    public LookupUnmarshalException 
                    (ServiceRegistrar[] registrars, 
                     MarshalledObject[] marshalledRegistrars, 
                     Throwable[] exceptions) {...} 
    public LookupUnmarshalException 
                    (ServiceRegistrar[] registrars, 
                     MarshalledObject[] marshalledRegistrars, 
                     Throwable[] exceptions, 
                     String message) {...} 
    public ServiceRegistrar[] getRegistrars() {...} 
    public MarshalledObject[] getMarshalledRegistrars() {...} 
    public Throwable[] getExceptions() {...} 
} 

The LookupUnmarshalException class is a subclass of Exception, adding the following additional items of abstract state:

• A set of ServiceRegistrar instances in which each element is the result of a successful unmarshalling attempt

• A set of marshalled instances of ServiceRegistrar in which each element is the result of an unsuccessful unmarshalling attempt

• A set of exceptions (IOException, ClassNotFoundException, or some unchecked exception) in which each element corresponds to one of the unsuccessful unmarshalling attempts

When exceptional conditions occur while unmarshalling a set of marshalled instances of ServiceRegistrar, the LookupUnmarshalException class can be used not only to indicate that an exceptional condition has occurred, but also to provide information that can be used to perform error handling activities such as:

• Determining if it is feasible to continue with processing

• Reporting errors

• Attempting recovery

• Performing debug activities

LD.4.3.1. The Semantics

The constructor of the LookupUnmarshalException class has two forms. The first form of the constructor takes the following parameters as input:

• An array containing the set of instances of ServiceRegistrar that were successfully unmarshalled

• An array containing the set of marshalled ServiceRegistrar instances that could not be unmarshalled

• An array containing the set of exceptions that occurred during the unmarshalling process

The second form of the constructor takes the same arguments as the first and one additional argument: a String describing the nature of the exception.

Each element in the exceptions parameter should be an instance of IOException, ClassNotFoundException, or some unchecked exception. Furthermore, there is a one-to-one correspondence between each element in the exceptions parameter and each element in the marshalledRegistrars parameter. That is, the element of the exceptions parameter corresponding to index i should be an instance of the exception that occurred while attempting to unmarshal the element at index i of the marshalledRegistrars parameter.

If the number of elements in the exceptions parameter does not equal the number of elements in the marshalledRegistrars parameter, the constructor will throw an IllegalArgumentException.

The getRegistrars method is an accessor method that returns an array consisting of instances of ServiceRegistrar, where each element of the array corresponds to a successfully unmarshalled object. Note that the same array is returned on each invocation of this method; that is, a copy is not made.

The getMarshalledRegistrars method is an accessor method that returns an array consisting of instances of MarshalledObject, where each element of the array is a marshalled instance of the ServiceRegistrar interface and corresponds to an object that could not be successfully unmarshalled. Note that the same array is returned on each invocation of this method; that is, a copy is not made.

The getExceptions method is an accessor method that returns an array consisting of instances of Throwable, where each element of the array corresponds to one of the exceptions that occurred during the unmarshalling process. Each element in the return set is an instance of IOException, ClassNotFoundException, or some unchecked exception. Additionally, there should be a one-to-one correspondence between each element in the array returned by this method and the array returned by the getMarshalledRegistrars method. Note that the same array is returned on each invocation of this method; that is, a copy is not made.

LD.4.3.2. Serialized Forms