Coś się dzisiaj rozpisałem. W każdym bądź razie dzieje się dużo więc warto notować.
Generalnie piszę obecnie dokumentację dla jednego z projektów. Zwyczajne javadoc’i, swoją drogą wie ktoś jak dodać sekcję „Direct Know Subclasses” do javadoc’a, takie w których klient ma znaleźć opis co, kto i jak robi. Jednak i tu dorwała mnie refaktoryzacja kodu.
Problem:
Mamy sobie interfejs:

Listing 1. Omawiany interfejs – definicja

/**
 * Interfejs reprezentujący obiekty odbiorców dla modelu.
 *
 * @author Koziołek
 *
 */
public interface ModelRecipient {

	/**
	 * Metoda pozwala na przekazanie modelu.
	 * @param model model danych
	 */
	public void setModel(Model model);

	/**
	 * Metoda powinna być wywołana wtedy gdy chcemy, żeby odbiorca zaktualizował swój stan
	 */
	public void update();
}

Przeczytajcie dokładnie dokumentację. Prawidłowe użycie tego interfejsu powinno wyglądać mniej więcej tak:

Listing 2. Omawiany interfejs – użycie

modelRecipient.setModel(model);
modelRecipient.update();

Nie ma w tym nic złego, ale dziwnym wydaje się wymuszanie na kliencie wywołania metody update() jeżeli wywołał już setModel(). Rzecz w tym, że jako klient nie będę miał interesu w tym by tak naprawdę podwójnie informować odbiorcę, że zaszło jakieś zdarzenie. Pierwszy raz ustawiając model, a drugi wymuszając aktualizację stanu. Można zatem spokojnie wywalić metodę update():

Listing 3. Omawiany interfejs – po porawkach

/**
 * Interfejs reprezentujący obiekty odbiorców dla modelu.
 *
 * @author Koziołek
 *
 */
public interface ModelRecipient {

	/**
	 * Metoda pozwala na przekazanie modelu.
	 * @param model model danych
	 */
	public void setModel(Model model);
}

Co jednak w sytuacji gdy chcemy jawnie wywoływać aktualizację? Można zawsze rozszerzyć interfejs o odpowiednią metodę.

Listing 4. Omawiany interfejs – rozszerzony pod interfejs

/**
 * Interfejs reprezentujący obiekty odbiorców dla modelu z jawną aktualizacją.
 *
 * @author Koziołek
 *
 */
public interface ModelRecipientLazyUpdate extends ModelRecipient {

	/**
	 * Metoda powinna być wywołana wtedy gdy chcemy, żeby odbiorca zaktualizował swój stan
	 */
	public void update();
}

I to wszytko pisząc dokumentację…