Advertisement

The lookup() methods

The ServiceRegistrar's lookup() methods take two overloaded forms. The main difference between these two forms is the number of matches and service items each one returns. The two-parameter form can return multiple matches of the query expressed in the ServiceTemplate, while the one-parameter form returns only one match. In addition, the two-parameter form returns entire service items; the one-parameter form returns only the service object.

The two-parameter form of lookup()

Here's a javadoc excerpt that explains the two-parameter form of lookup():

public ServiceMatches lookup(ServiceTemplate tmpl,
    int maxMatches) throws java.rmi.RemoteException;

Returns at most maxMatches items matching the template, plus the total number of items that match the template. The return value is never null, and the returned items array is only null if maxMatches is zero. For each returned item, if the service object cannot be deserialized, the service field of the item is set to null and no exception is thrown. Similarly, if an attribute set cannot be deserialized, that element of the attributeSets array is set to null and no exception is thrown.

Here is the ServiceMatches class:

package net.jini.core.lookup;

public class ServiceMatches extends java.lang.Object
    implements java.io.Serializable {

    public ServiceItem[] items;
    public int totalMatches;
}

And here is the ServiceItem class:

package net.jini.core.lookup;

public class ServiceMatches extends java.lang.Object
    implements java.io.Serializable {

    public Entry[] attributeSets;
    public java.lang.Object service;
    public ServiceID serviceID;
}

As mentioned previously, each element of the items array returned by the two-parameter form is a complete service item, which includes the service object, service ID, and all the attribute sets. The maxMatches field helps clients manage the number of objects returned by this lookup().

The length of the items array in the returned ServiceMatches object will be less than or equal to the value passed to lookup() in maxMatches. The total number of matching service items, which is returned in totalMatches, will be greater than or equal to the length of the items array.

For example, if maxMatches is 50 and the service template matches 25 items, the length of the returned items array and the value of totalMatches will both be 25. Alternatively, if maxMatches is 50 but the service template matches 100 items, the length of the returned items array will be 50 and the value of totalMatches will be 100. When a service template matches more than maxMatches service items, the service items returned by the two-parameter lookup() are selected randomly from the full set of matching service items.

The one-parameter form of lookup()

The one-parameter lookup() method returns one matching service object chosen randomly from all the matches. Here's a javadoc excerpt explaining this form:

public ServiceMatches lookup(ServiceTemplate tmpl)
    throws java.rmi.RemoteException;

Returns the service object (i.e., just ServiceItem.service) from an item matching the template, or null if there is no match. If multiple items match the template, it is arbitrary as to which service object is returned. If the returned object cannot be deserialized, an UnmarshalException is thrown with the standard RMI semantics.

Because the one-parameter lookup() returns only one matching service object, clients can minimize the amount of object state and class files that are downloaded. But because the returned service object is selected arbitrarily, and is not identified by a service ID or described by associated attribute sets, the client must be confident that any matching service object will suffice.