CODEWITHSUNDEEP
javaejbjavadoc
Sven Plath
Sven Plath

Reputation: 558

How to write Javadoc for EJBs and their interfaces?

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

Upvotes: 2

Views: 394

Answers (2)

koljaTM
koljaTM

Reputation: 10260

I would say it depends on which information is important to a client. If the recalculation is completely invisibloe to the user, there might not be a need to document it in the interface. If the recalculation details can be seen by the client in some other way, that would have to be indicated here, so that the user knows which interactions might happen. If the recalculation is completely internal and could be changed without the client noticing, it doesn't need to and shouldn't be in the interface description.

Upvotes: 0

Bohemian
Bohemian

Reputation: 425378

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.

Upvotes: 2

Related Questions