How to write Javadoc for EJBs and their interfaces?

Question

Consider the following example

@Remote
public interface RegistrationService {
    public String register();
    public void unregister(String id);
    public void heartbeat(String id);
}

@Stateless
@Remote(RegistrationService.class)
public class RegistrationServiceBean implements RegistrationService {
    /* ... */
}

I have an interface, lets say RegistrationService. With this, a remote client is able to register itself onto the application. By calling heartbeat() periodically, it signals that it is still alive.

What would be the correct way to document EJBs and their interfaces?

For example:

Interface

1. The user of this interface can register itself onto the application. The application then recalculates something to distribute evenly across all registered clients. (This would involve knowledge about other classes, the recalculation class for example)
2. The user of the interface is able to register itself and notify the server if it is still connected. The implementation uses this information to issue tasks to underlying systems based on the amount of registered clients (This does not involve knowledge about other classes, however is not so precice from an application point of view)

Class

1. This implementation of the RegistrationService issues recalculations in the RecalculationClass when a client registers, unregisters or a heartbeat expires. This is necessary, because the data has to be evenly distributed between clients.

Any thoughts appreciated. Thanks.

Sven

Answer 1

Interface javadoc should have no information about the implementation. Interfaces are about the what, not the how.

For example, it would be valid for the implementation to completely ignore calls made to the interface's methods - ie have an empty method.

Your javadoc should say something like: Notifies that the specified application is still alive. What the implementation chooses to do with that information is up to it.