Java Enterprise Best Practices

Use the Unreferenced Interface to Clean Up Allocated Server State

The distributed garbage collector is a wonderful piece of code. It works in a very straightforward manner: a client gets a lease on a particular server object. The lease has a specific duration, and the client is responsible for renewing the lease before it expires. If the lease expires, and the client hasn’t renewed the lease, the server JVM is allowed to garbage-collect the server object (as long as no other clients have leases against that particular object).

If a server implements the Unreferenced interface—which contains a single method, unreferenced( )—the server will be notified via a call to unreferenced( ) that there are no valid leases against the server.

It’s important to note that any active instance of a stub, in any JVM, will automatically try to connect to the server and maintain a lease. This means that, for example, if the server is bound into the RMI registry, the registry will keep the server alive. (The RMI registry basically stores the stub in a hashtable. The stub keeps renewing its lease.)

In turn, this means that if you’re using a naming service to get instances of stubs, no other process can actually get a stub to a server if unreferenced has been called (unreferenced will be called only if the server is no longer bound into any naming services).

All of this makes the unreferenced method an ideal place to release server-side resources and shut down the server object gracefully.