Register a new service or re-register an existing service. The method is defined so that it
can be used in an idempotent fashion. Specifically, if a call to register results in a
RemoteException (in which case the item might or might not have been registered), the caller
can simply repeat the call to register with the same parameters, until it succeeds.
To
register a new service, item.serviceID should be null. In that case, if item.service does
not equal (using MarshalledObject.equals) any existing item's service object, then a new
service ID will be assigned and included in the returned ServiceRegistration. The service ID
is unique over time and space with respect to all other service IDs generated by all lookup
services. If item.service does equal an existing item's service object, the existing item is
first deleted from the lookup service (even if it has different attributes) and its lease is
cancelled, but that item's service ID is reused for the newly registered item.
To
re-register an existing service, or to register the service in any other lookup service,
item.serviceID should be set to the same service ID that was returned by the initial
registration. If an item is already registered under the same service ID, the existing item
is first deleted (even if it has different attributes or a different service instance) and
its lease is cancelled. Note that service object equality is not checked in this case, to
allow for reasonable evolution of the service (e.g., the serialized form of the stub changes,
or the service implements a new interface).
Any duplicate attribute sets included in a
service item are eliminated in the stored representation of the item. The lease duration
request is not exact; the returned lease is allowed to have a shorter (but not longer)
duration than what was requested. The registration is persistent across restarts (crashes)
of the lookup service until the lease expires or is cancelled.