From 1dda686049262d39d7b375504286f37f79c12532 Mon Sep 17 00:00:00 2001 From: Asterios Raptis Date: Wed, 14 Aug 2024 18:31:51 +0200 Subject: [PATCH] improve of javadoc --- .../pattern/eventbus/ApplicationEventBus.java | 14 ++- .../pattern/eventbus/GenericEventBusTest.java | 29 +++-- .../eventbus/ImportWizardPanelTest.java | 21 ++-- .../eventobject/ImportProgressPanel.java | 17 +-- .../eventobject/ImportProgressPanelTest.java | 15 +-- .../eventobject/ImportWizardModel.java | 6 +- .../eventobject/ImportWizardPanel.java | 13 +- .../pattern/observer/AbstractObserver.java | 22 ++-- .../pattern/observer/AbstractSubject.java | 21 ++-- .../pattern/observer/api/ActionCommand.java | 6 +- .../design/pattern/observer/api/Observer.java | 16 +-- .../design/pattern/observer/api/Subject.java | 42 +++---- .../pattern/observer/api/package-info.java | 24 ++++ .../design/pattern/observer/api/package.html | 11 -- .../pattern/observer/chat/ChatMessage.java | 12 +- .../pattern/observer/chat/ChatRoom.java | 50 +++++--- .../observer/chat/ChatRoomService.java | 18 +-- .../pattern/observer/chat/ChatRoomUser.java | 34 +++--- .../design/pattern/observer/chat/IUser.java | 18 +-- .../pattern/observer/chat/Invitation.java | 28 +++-- .../design/pattern/observer/chat/Message.java | 15 +-- .../observer/chat/MessageRoomModelBean.java | 53 ++++---- .../design/pattern/observer/chat/Room.java | 18 +-- .../pattern/observer/chat/StringMessage.java | 13 +- .../design/pattern/observer/chat/User.java | 33 +++-- .../chat/listener/MessageListener.java | 15 ++- .../observer/chat/listener/MessageObject.java | 22 ++-- .../observer/chat/listener/MessageSource.java | 39 +++--- .../chat/listener/MessageSubject.java | 23 ++-- .../observer/chat/listener/package-info.java | 23 ++++ .../pattern/observer/chat/package-info.java | 26 ++++ .../pattern/observer/event/EventListener.java | 10 +- .../pattern/observer/event/EventObject.java | 11 +- .../pattern/observer/event/EventSource.java | 23 ++-- .../pattern/observer/event/EventSubject.java | 23 ++-- .../pattern/observer/event/package-info.java | 24 ++++ .../observer/exception/ExceptionEvent.java | 5 +- .../observer/exception/ExceptionListener.java | 12 +- .../observer/exception/ExceptionMessage.java | 27 ++-- .../observer/exception/ExceptionMessages.java | 68 ++++++++++- .../exception/ExceptionObservers.java | 31 +++-- .../handlers/AbstractExceptionHandler.java | 31 +++-- .../handlers/DefaultExceptionHandler.java | 10 +- .../exception/handlers/package-info.java | 22 ++++ .../observer/exception/package-info.java | 25 ++++ .../pattern/observer/exception/package.html | 11 -- .../design/pattern/observer/package-info.java | 23 ++++ .../design/pattern/observer/package.html | 11 -- .../observer/chat/ApplicationUser.java | 21 +++- .../observer/chat/DataChatRoomUser.java | 23 +++- .../chat/DemonstrateChatObserver.java | 16 +-- .../observer/chat/SimpleChatRoomUser.java | 23 +++- .../observer/chat/example/ChatApp.java | 104 ++++++++++++++++ .../observer/chat/example/ChatRoom.java | 115 ++++++++++++++++++ .../observer/chat/example/ChatRoomUser.java | 51 ++++++++ .../observer/chat/example/StringMessage.java | 38 ++++++ .../pattern/observer/chat/example/User.java | 50 ++++++++ 57 files changed, 1080 insertions(+), 425 deletions(-) create mode 100644 observer/src/main/java/io/github/astrapi69/design/pattern/observer/api/package-info.java delete mode 100644 observer/src/main/java/io/github/astrapi69/design/pattern/observer/api/package.html create mode 100644 observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/listener/package-info.java create mode 100644 observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/package-info.java create mode 100644 observer/src/main/java/io/github/astrapi69/design/pattern/observer/event/package-info.java create mode 100644 observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/handlers/package-info.java create mode 100644 observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/package-info.java delete mode 100644 observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/package.html create mode 100644 observer/src/main/java/io/github/astrapi69/design/pattern/observer/package-info.java delete mode 100644 observer/src/main/java/io/github/astrapi69/design/pattern/observer/package.html create mode 100644 observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/example/ChatApp.java create mode 100644 observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/example/ChatRoom.java create mode 100644 observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/example/ChatRoomUser.java create mode 100644 observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/example/StringMessage.java create mode 100644 observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/example/User.java diff --git a/eventbus/src/test/java/io/github/astrapi69/design/pattern/eventbus/ApplicationEventBus.java b/eventbus/src/test/java/io/github/astrapi69/design/pattern/eventbus/ApplicationEventBus.java index ca84b37..99ea896 100644 --- a/eventbus/src/test/java/io/github/astrapi69/design/pattern/eventbus/ApplicationEventBus.java +++ b/eventbus/src/test/java/io/github/astrapi69/design/pattern/eventbus/ApplicationEventBus.java @@ -25,16 +25,18 @@ package io.github.astrapi69.design.pattern.eventbus; import lombok.Getter; + import com.google.common.eventbus.EventBus; + import io.github.astrapi69.design.pattern.eventbus.eventobject.ImportWizardModel; import io.github.astrapi69.design.pattern.observer.event.EventObject; import io.github.astrapi69.design.pattern.observer.event.EventSource; /** - * The class {@link ApplicationEventBus} serves as the central event bus for the application - * It provides access to various event sources, including those related to navigation and - * the import wizard model, and it uses an instance of {@link EventBus} from the Guava library - * to manage and dispatch events + * The class {@link ApplicationEventBus} serves as the central event bus for the application It + * provides access to various event sources, including those related to navigation and the import + * wizard model, and it uses an instance of {@link EventBus} from the Guava library to manage and + * dispatch events */ public class ApplicationEventBus { @@ -56,7 +58,8 @@ private ApplicationEventBus() /** * Retrieves an event source by its key * - * @param key the key associated with the event source + * @param key + * the key associated with the event source * @return the event source associated with the given key, or {@code null} if none is found */ public static EventSource get(final String key) @@ -94,4 +97,3 @@ public static ApplicationEventBus getInstance() return instance; } } - diff --git a/eventbus/src/test/java/io/github/astrapi69/design/pattern/eventbus/GenericEventBusTest.java b/eventbus/src/test/java/io/github/astrapi69/design/pattern/eventbus/GenericEventBusTest.java index 2619d0f..67cfcbd 100644 --- a/eventbus/src/test/java/io/github/astrapi69/design/pattern/eventbus/GenericEventBusTest.java +++ b/eventbus/src/test/java/io/github/astrapi69/design/pattern/eventbus/GenericEventBusTest.java @@ -32,10 +32,10 @@ import com.google.common.eventbus.Subscribe; /** - * The class {@link GenericEventBusTest} provides unit tests for the integration - * of the {@link GenericEventBus} with the {@link ApplicationEventBus} using the Guava {@link EventBus} - * The tests verify the registration, event posting, and unregistration of event listeners, - * ensuring correct behavior of the event bus system + * The class {@link GenericEventBusTest} provides unit tests for the integration of the + * {@link GenericEventBus} with the {@link ApplicationEventBus} using the Guava {@link EventBus} The + * tests verify the registration, event posting, and unregistration of event listeners, ensuring + * correct behavior of the event bus system */ public class GenericEventBusTest { @@ -46,9 +46,10 @@ public class GenericEventBusTest private static NavigationEventState navigationEventState; /** - * Test method for verifying the functionality of the {@link ApplicationEventBus} using the Guava {@link EventBus} - * It checks the correct registration and unregistration of listeners, - * the proper handling of different types of events, and the integrity of event-driven state changes + * Test method for verifying the functionality of the {@link ApplicationEventBus} using the + * Guava {@link EventBus} It checks the correct registration and unregistration of listeners, + * the proper handling of different types of events, and the integrity of event-driven state + * changes */ @Test public void testApplicationEventBus() @@ -92,10 +93,11 @@ public void testApplicationEventBus() } /** - * Event handler method for string-based events - * This method increments the counter each time it is called + * Event handler method for string-based events This method increments the counter each time it + * is called * - * @param event the event string, typically a command or action indicator + * @param event + * the event string, typically a command or action indicator */ @Subscribe public void onAddition(String event) @@ -104,10 +106,11 @@ public void onAddition(String event) } /** - * Event handler method for {@link NavigationEventState} events - * This method updates the {@code navigationEventState} field to reflect the state passed in the event + * Event handler method for {@link NavigationEventState} events This method updates the + * {@code navigationEventState} field to reflect the state passed in the event * - * @param navigationEventState the event containing the new navigation state + * @param navigationEventState + * the event containing the new navigation state */ @Subscribe public void onAdditionWithObject(NavigationEventState navigationEventState) diff --git a/eventbus/src/test/java/io/github/astrapi69/design/pattern/eventbus/ImportWizardPanelTest.java b/eventbus/src/test/java/io/github/astrapi69/design/pattern/eventbus/ImportWizardPanelTest.java index e3824dd..efbbaa4 100644 --- a/eventbus/src/test/java/io/github/astrapi69/design/pattern/eventbus/ImportWizardPanelTest.java +++ b/eventbus/src/test/java/io/github/astrapi69/design/pattern/eventbus/ImportWizardPanelTest.java @@ -33,9 +33,10 @@ import io.github.astrapi69.design.pattern.observer.event.EventSource; /** - * The class {@link ImportWizardPanelTest} provides unit tests for the {@link ImportWizardPanel} class - * It implements the {@link EventListener} interface to listen for {@link NavigationEventState} events - * and verify the correct behavior of the event handling and state update logic + * The class {@link ImportWizardPanelTest} provides unit tests for the {@link ImportWizardPanel} + * class It implements the {@link EventListener} interface to listen for + * {@link NavigationEventState} events and verify the correct behavior of the event handling and + * state update logic */ public class ImportWizardPanelTest implements EventListener> { @@ -46,7 +47,8 @@ public class ImportWizardPanelTest implements EventListener event) @@ -57,7 +59,8 @@ public void onEvent(EventObject event) /** * Updates the button state based on the given navigation state * - * @param navigationState the new navigation state to be applied + * @param navigationState + * the new navigation state to be applied */ protected void updateButtonState(NavigationEventState navigationState) { @@ -66,19 +69,19 @@ protected void updateButtonState(NavigationEventState navigationState) /** * Test method for verifying the event handling functionality of the {@link ImportWizardPanel} - * It registers the test class as a listener for {@link NavigationEventState} events, - * fires events, and verifies that the {@code navigationEventState} is updated correctly + * It registers the test class as a listener for {@link NavigationEventState} events, fires + * events, and verifies that the {@code navigationEventState} is updated correctly */ @Test public void testApplicationEventBus() { // Register as listener... final EventSource> eventSource = ApplicationEventBus - .getImportNavigationState(); + .getImportNavigationState(); eventSource.add(this); // Create an event source object final EventSource> navigationEventStateEventSource = ApplicationEventBus - .getImportNavigationState(); + .getImportNavigationState(); // Fire a new event navigationEventStateEventSource.fireEvent(new EventObject<>(NavigationEventState.UPDATE)); // Verify that the navigationEventState is set to NavigationEventState.UPDATE diff --git a/eventbus/src/test/java/io/github/astrapi69/design/pattern/eventbus/eventobject/ImportProgressPanel.java b/eventbus/src/test/java/io/github/astrapi69/design/pattern/eventbus/eventobject/ImportProgressPanel.java index 1ca093f..b382a1f 100644 --- a/eventbus/src/test/java/io/github/astrapi69/design/pattern/eventbus/eventobject/ImportProgressPanel.java +++ b/eventbus/src/test/java/io/github/astrapi69/design/pattern/eventbus/eventobject/ImportProgressPanel.java @@ -32,8 +32,8 @@ /** * The {@code ImportProgressPanel} class is responsible for handling events related to the - * {@code ImportWizardModel}. It listens for events on the {@code ApplicationEventBus} and - * updates its internal state when an event occurs. + * {@code ImportWizardModel}. It listens for events on the {@code ApplicationEventBus} and updates + * its internal state when an event occurs. */ public class ImportProgressPanel implements EventListener> { @@ -43,22 +43,23 @@ public class ImportProgressPanel implements EventListener> eventSource = ApplicationEventBus - .getImportWizardModel(); + .getImportWizardModel(); eventSource.add(this); } /** - * Handles the event when an {@code ImportWizardModel} event is fired. - * This method updates the internal {@code importWizardModel} with the event's source. + * Handles the event when an {@code ImportWizardModel} event is fired. This method updates the + * internal {@code importWizardModel} with the event's source. * - * @param event the event object containing the updated {@code ImportWizardModel} + * @param event + * the event object containing the updated {@code ImportWizardModel} */ @Override public void onEvent(EventObject event) diff --git a/eventbus/src/test/java/io/github/astrapi69/design/pattern/eventbus/eventobject/ImportProgressPanelTest.java b/eventbus/src/test/java/io/github/astrapi69/design/pattern/eventbus/eventobject/ImportProgressPanelTest.java index 9ea495d..9bfde3b 100644 --- a/eventbus/src/test/java/io/github/astrapi69/design/pattern/eventbus/eventobject/ImportProgressPanelTest.java +++ b/eventbus/src/test/java/io/github/astrapi69/design/pattern/eventbus/eventobject/ImportProgressPanelTest.java @@ -29,22 +29,23 @@ import static org.testng.Assert.assertNotNull; import static org.testng.Assert.assertNull; -import io.github.astrapi69.design.pattern.eventbus.ApplicationEventBus; import org.testng.annotations.Test; +import io.github.astrapi69.design.pattern.eventbus.ApplicationEventBus; + /** - * The class {@link ImportProgressPanelTest} provides unit tests for the {@link ImportProgressPanel} class - * It verifies the functionality of event handling and state synchronization between + * The class {@link ImportProgressPanelTest} provides unit tests for the {@link ImportProgressPanel} + * class It verifies the functionality of event handling and state synchronization between * {@link ImportProgressPanel} and {@link ImportWizardPanel} */ public class ImportProgressPanelTest { /** - * Test method for the interaction between {@link ImportProgressPanel} and {@link ImportWizardPanel} - * through the {@link ApplicationEventBus} - * It validates that events are correctly fired, received, and processed, ensuring that the model - * state is synchronized across the panels + * Test method for the interaction between {@link ImportProgressPanel} and + * {@link ImportWizardPanel} through the {@link ApplicationEventBus} It validates that events + * are correctly fired, received, and processed, ensuring that the model state is synchronized + * across the panels */ @Test public void testApplicationEventBus() diff --git a/eventbus/src/test/java/io/github/astrapi69/design/pattern/eventbus/eventobject/ImportWizardModel.java b/eventbus/src/test/java/io/github/astrapi69/design/pattern/eventbus/eventobject/ImportWizardModel.java index 3c34c7a..d0b885d 100644 --- a/eventbus/src/test/java/io/github/astrapi69/design/pattern/eventbus/eventobject/ImportWizardModel.java +++ b/eventbus/src/test/java/io/github/astrapi69/design/pattern/eventbus/eventobject/ImportWizardModel.java @@ -35,9 +35,9 @@ import lombok.ToString; /** - * The class {@link ImportWizardModel} acts as a model for the import wizard - * It contains data related to the import process, such as the application name, - * whether a database import is required, and the root directory for the import + * The class {@link ImportWizardModel} acts as a model for the import wizard It contains data + * related to the import process, such as the application name, whether a database import is + * required, and the root directory for the import */ @Getter @Setter diff --git a/eventbus/src/test/java/io/github/astrapi69/design/pattern/eventbus/eventobject/ImportWizardPanel.java b/eventbus/src/test/java/io/github/astrapi69/design/pattern/eventbus/eventobject/ImportWizardPanel.java index 7ad97fa..cdbf8ae 100644 --- a/eventbus/src/test/java/io/github/astrapi69/design/pattern/eventbus/eventobject/ImportWizardPanel.java +++ b/eventbus/src/test/java/io/github/astrapi69/design/pattern/eventbus/eventobject/ImportWizardPanel.java @@ -30,8 +30,8 @@ import io.github.astrapi69.design.pattern.observer.event.EventObject; /** - * The class {@link ImportWizardPanel} represents a panel in the import wizard - * It holds an instance of {@link ImportWizardModel} and can fire events related to the model + * The class {@link ImportWizardPanel} represents a panel in the import wizard It holds an instance + * of {@link ImportWizardModel} and can fire events related to the model */ public class ImportWizardPanel { @@ -41,8 +41,8 @@ public class ImportWizardPanel ImportWizardModel model; /** - * Constructs a new {@code ImportWizardPanel} with a default model - * The default model is initialized with a bundle application name "foobar" + * Constructs a new {@code ImportWizardPanel} with a default model The default model is + * initialized with a bundle application name "foobar" */ ImportWizardPanel() { @@ -50,12 +50,11 @@ public class ImportWizardPanel } /** - * Fires a new event to the {@link ApplicationEventBus} with the current model - * The event is created using the current state of the {@code ImportWizardModel} + * Fires a new event to the {@link ApplicationEventBus} with the current model The event is + * created using the current state of the {@code ImportWizardModel} */ public void fireNewEvent() { ApplicationEventBus.getImportWizardModel().fireEvent(EventObject.of(this.model)); } } - diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/AbstractObserver.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/AbstractObserver.java index 74b0e94..7de80c9 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/AbstractObserver.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/AbstractObserver.java @@ -28,27 +28,28 @@ import io.github.astrapi69.design.pattern.observer.api.Observer; import io.github.astrapi69.design.pattern.observer.api.Subject; - /** - * A generic implementation from the Observer-Pattern. - * + * A generic implementation of the Observer pattern This abstract class implements the + * {@link Observer} and {@link ActionCommand} interfaces, providing a basic framework for observers + * in the Observer design pattern + * * @param - * the generic type + * the generic type of the observable object */ public abstract class AbstractObserver implements Observer, ActionCommand { - /** The subject. */ + /** The subject being observed */ protected Subject> subject; - /** The observable. */ + /** The current observable object */ private T observable; /** - * Constructor for a new observer object. + * Constructor for a new observer object * * @param subject - * the subject + * the subject to observe */ public AbstractObserver(final Subject> subject) { @@ -58,9 +59,9 @@ public AbstractObserver(final Subject> subject) } /** - * Gets the observable object. + * Gets the current observable object * - * @return the observable + * @return the observable object */ public synchronized T getObservable() { @@ -76,5 +77,4 @@ public synchronized void update(final T observable) this.observable = observable; execute(); } - } diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/AbstractSubject.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/AbstractSubject.java index b87a8dd..e42b9d6 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/AbstractSubject.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/AbstractSubject.java @@ -33,44 +33,45 @@ import io.github.astrapi69.design.pattern.observer.api.Subject; /** - * The Class AbstractSubject is an implementation from the interface Subject. This class - * encapsulates the observable and fires an update if the observable changes. The update informs all - * registered observers about the change of the observable. + * The class {@link AbstractSubject} is an implementation of the {@link Subject} interface This + * class encapsulates the observable object and notifies all registered observers when the + * observable changes * * @param - * the generic type of the observable. + * the generic type of the observable object * @param * the generic type of the observer */ public abstract class AbstractSubject> implements Subject { - /** The observers. */ + /** The list of registered observers */ @Getter private final List observers; - /** The observable object. */ + + /** The current observable object */ @Getter private T observable; /** - * Initialize block. + * Initialization block to create the list of observers **/ { observers = new ArrayList<>(); } /** - * Default constructor for a new subject. + * Default constructor for a new subject with no initial observable */ public AbstractSubject() { } /** - * Constructor for a new subject with an observable. + * Constructor for a new subject with an initial observable * * @param observable - * the observable + * the initial observable object */ public AbstractSubject(final T observable) { diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/api/ActionCommand.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/api/ActionCommand.java index d986266..a80f652 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/api/ActionCommand.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/api/ActionCommand.java @@ -25,13 +25,15 @@ package io.github.astrapi69.design.pattern.observer.api; /** - * The interface {@link ActionCommand}. + * The interface {@link ActionCommand} represents a command that can be executed Implementations of + * this interface encapsulate a specific action that can be triggered */ public interface ActionCommand { /** - * Executes the command. + * Executes the command Implementing classes should define the specific action to be performed + * when this method is called */ void execute(); } diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/api/Observer.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/api/Observer.java index fb92964..0b82b04 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/api/Observer.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/api/Observer.java @@ -25,19 +25,21 @@ package io.github.astrapi69.design.pattern.observer.api; /** - * The Interface Observer. - * + * The Interface {@link Observer} represents an observer in the Observer design pattern It defines a + * contract for objects that should be notified of changes in an observable subject + * * @param - * the generic type of the observable. + * the generic type of the observable object that the observer is interested in */ public interface Observer { /** - * Update. + * This method is called to notify the observer of changes in the observable object Implementing + * classes should define the specific behavior that occurs when the observable object changes * - * @param t - * the t + * @param observable + * the observable object that has changed */ - void update(final T t); + void update(final T observable); } diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/api/Subject.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/api/Subject.java index bb7f700..2bc2a44 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/api/Subject.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/api/Subject.java @@ -28,23 +28,23 @@ import java.util.List; /** - * The interface {@link Subject} represents the "subject" (which is being "observed") being part of - * the object whose state change is being observed, to be communicated to the observers upon - * occurrence. + * The interface {@link Subject} represents the "subject" in the Observer design pattern The subject + * is the object whose state changes are being observed by one or more observers When the state of + * the subject changes, the observers are notified of the change * * @param - * the generic type of the observable. + * the generic type of the observable object whose state is being observed * @param - * the generic type of the observer + * the generic type of the observer that is observing the subject */ public interface Subject> { /** - * Adds the given observer. + * Adds the given observer to the list of observers * * @param observer - * the observer to be added. + * the observer to be added */ default void add(final O observer) { @@ -52,10 +52,10 @@ default void add(final O observer) } /** - * Adds the given observers. + * Adds the given observers to the list of observers * * @param observers - * the observers to be added. + * the observers to be added */ default void addAll(final Collection observers) { @@ -63,32 +63,32 @@ default void addAll(final Collection observers) } /** - * Gets the observable. + * Gets the observable object, which is the object being observed for state changes * - * @return the observable + * @return the observable object */ T getObservable(); /** - * Sets the observable. + * Sets the observable object, which is the object being observed for state changes * * @param observable - * the new observable + * the new observable object */ void setObservable(final T observable); /** - * Gets the observers that wants to be notified on changes. + * Gets the list of observers that wish to be notified of changes to the observable object * - * @return the observers + * @return the list of observers */ List getObservers(); /** - * Removes the given observer. + * Removes the given observer from the list of observers * * @param observer - * the observer to be remove. + * the observer to be removed */ default void remove(final O observer) { @@ -100,10 +100,10 @@ default void remove(final O observer) } /** - * Removes the given observers. + * Removes the given observers from the list of observers * * @param observers - * the observers to be remove. + * the observers to be removed */ default void removeAll(final Collection observers) { @@ -111,7 +111,8 @@ default void removeAll(final Collection observers) } /** - * Update observers. + * Notifies all observers of a change in the state of the observable object Each observer's + * {@code update} method is called with the current state of the observable */ default void updateObservers() { @@ -120,5 +121,4 @@ default void updateObservers() observer.update(getObservable()); } } - } diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/api/package-info.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/api/package-info.java new file mode 100644 index 0000000..6ce534e --- /dev/null +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/api/package-info.java @@ -0,0 +1,24 @@ +/** + * Provides interfaces that define the core components of the observer design pattern + * + *

+ * The observer pattern is a behavioral design pattern that allows an object, known as the subject, to maintain a list of its dependents, called observers, + * and notify them automatically of any state changes, usually by calling one of their methods + * This package contains the fundamental interfaces that are essential for implementing the observer pattern. + *

+ * + *

+ * The key interfaces in this package include: + *

+ *
    + *
  • {@link io.github.astrapi69.design.pattern.observer.api.Observer} - Represents the observer that watches the subject for changes
    • + *
  • {@link io.github.astrapi69.design.pattern.observer.api.Subject} - Represents the subject being observed
    • + *
  • {@link io.github.astrapi69.design.pattern.observer.api.ActionCommand} - Represents a command that can be executed, typically used by observers to respond to subject changes
    • + *
+ * + *

+ * These interfaces provide a flexible and extensible framework for implementing the observer pattern in various contexts + * By adhering to these interfaces, developers can create systems where objects can be notified of changes in other objects' states, promoting loose coupling and dynamic behavior. + *

+ */ +package io.github.astrapi69.design.pattern.observer.api; diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/api/package.html b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/api/package.html deleted file mode 100644 index 0e0a7a4..0000000 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/api/package.html +++ /dev/null @@ -1,11 +0,0 @@ - - - - - io.github.astrapi69.design.pattern.observer.api - - - - Provides interfaces for the generic implementation for the observer pattern. - - diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/ChatMessage.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/ChatMessage.java index d03ca55..444514c 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/ChatMessage.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/ChatMessage.java @@ -27,15 +27,20 @@ import java.io.Serializable; /** - * The class {@link ChatMessage}. + * The class {@link ChatMessage} represents a message in a chat application It implements the + * {@link Message} interface and is serializable + * + * @param + * the type of the value held by the message, which in this case is a + * {@link MessageRoomModelBean} */ public class ChatMessage implements Message, Serializable { - /** The Constant serialVersionUID. */ + /** The Constant serialVersionUID for serialization compatibility */ private static final long serialVersionUID = 1L; - /** The value. */ + /** The value of the message, typically containing the chat room details */ private MessageRoomModelBean value; /** @@ -56,5 +61,4 @@ public ChatMessage setValue(final MessageRoomModelBean value) this.value = value; return this; } - } diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/ChatRoom.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/ChatRoom.java index 194a5ea..9bb849a 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/ChatRoom.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/ChatRoom.java @@ -33,10 +33,12 @@ import io.github.astrapi69.design.pattern.observer.api.Subject; /** - * The Class ChatRoom. + * The class {@link ChatRoom} represents a chat room where users can send and receive messages It + * extends {@link AbstractSubject} and implements {@link Subject}, {@link Room}, and + * {@link Serializable} * * @param - * the generic type of the Message that will be send in this chat room. + * the generic type of the message that will be sent in this chat room */ public class ChatRoom> extends AbstractSubject> implements @@ -45,30 +47,35 @@ public class ChatRoom> extends AbstractSubject> observers; + + /** The message history of the chat room */ private final List messageHistory = new ArrayList<>(); - /** The name of the chat room. */ + + /** The name of the chat room */ private final String name; - /** The observable object. */ + + /** The observable message object */ private M observable; /** - * Initialize block. + * Initialization block to create the list of observers **/ { observers = new ArrayList<>(); } /** - * Constructor for a new subject with an observable. + * Constructor for a new chat room with an initial observable message and a name * * @param observable - * the observable + * the initial observable message * @param name - * the name + * the name of the chat room */ public ChatRoom(final M observable, final String name) { @@ -77,7 +84,7 @@ public ChatRoom(final M observable, final String name) } /** - * Constructor for a new chat room with the given name. + * Constructor for a new chat room with the given name * * @param name * the name of the chat room @@ -94,7 +101,6 @@ public ChatRoom(final String name) public synchronized void add(final ChatRoomUser observer) { observers.add(observer); - } /** @@ -110,9 +116,9 @@ public void addAll(final Collection> observers) } /** - * Gets the chat room users as User objects. + * Gets the chat room users as a list of {@link IUser} objects * - * @return the chat room users + * @return the list of chat room users */ @Override public List> getChatRoomUsers() @@ -125,6 +131,11 @@ public List> getChatRoomUsers() return chatRoomUsers; } + /** + * Gets the message history of the chat room + * + * @return the list of messages sent in the chat room + */ @Override public List getMessageHistory() { @@ -132,9 +143,9 @@ public List getMessageHistory() } /** - * Gets the name of the chat room. + * Gets the name of the chat room * - * @return the name of the chat room. + * @return the name of the chat room */ public String getName() { @@ -161,6 +172,9 @@ public synchronized void setObservable(final M observable) updateObservers(); } + /** + * {@inheritDoc} + */ @Override public boolean isSecure() { @@ -193,9 +207,9 @@ public void removeAll(final Collection> observers) } /** - * Returns the number of chat users in this chat room. + * Returns the number of users in this chat room * - * @return the number of chat users in this chat room. + * @return the number of users in this chat room */ public int size() { diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/ChatRoomService.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/ChatRoomService.java index c7208a2..d576cea 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/ChatRoomService.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/ChatRoomService.java @@ -29,28 +29,30 @@ import java.util.Map; /** - * The class {@link ChatRoomService}. + * The class {@link ChatRoomService} manages the creation and retrieval of chat rooms It provides a + * way to obtain a {@link ChatRoom} based on an observable message and a room name * * @param - * the generic type + * the generic type of the message that will be sent in the chat rooms */ public class ChatRoomService> implements Serializable { - /** The Constant serialVersionUID. */ + /** The Constant serialVersionUID for serialization compatibility */ private static final long serialVersionUID = 1L; - /** The chat rooms. */ + /** A map of chat room names to their corresponding {@link ChatRoom} instances */ private final Map> chatRooms = new HashMap<>(); /** - * Gets the chat room. + * Gets the chat room with the specified name If the chat room does not exist, a new one is + * created with the given observable message and name * * @param observable - * the observable + * the observable message for the chat room * @param name - * the name - * @return the chat room + * the name of the chat room + * @return the chat room associated with the given name */ public ChatRoom getChatRoom(final M observable, final String name) { diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/ChatRoomUser.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/ChatRoomUser.java index ae3e726..6b816e5 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/ChatRoomUser.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/ChatRoomUser.java @@ -30,10 +30,13 @@ import io.github.astrapi69.design.pattern.observer.api.Observer; /** - * The class {@link ChatRoomUser}. + * The class {@link ChatRoomUser} represents a user in a chat room who can send and receive messages + * This class implements {@link Observer} to observe messages in the chat room, + * {@link ActionCommand} to define actions when a message is received, and {@link Serializable} for + * serialization support * * @param - * the generic type + * the generic type of the message that will be sent and observed in the chat room */ public abstract class ChatRoomUser> implements @@ -42,22 +45,25 @@ public abstract class ChatRoomUser> Serializable { - /** The Constant serialVersionUID. */ + /** The Constant serialVersionUID for serialization compatibility */ private static final long serialVersionUID = 1L; - /** The user. */ + + /** The user associated with this chat room user */ private final IUser user; - /** The subject. */ + + /** The chat room (subject) that this user is part of */ protected ChatRoom subject; - /** The observable. */ + + /** The observable message currently observed by this user */ private M observable; /** - * Instantiates a new chat room user. + * Instantiates a new chat room user * * @param room - * the room + * the chat room (subject) that this user is part of * @param user - * the user + * the user associated with this chat room user */ public ChatRoomUser(final ChatRoom room, final IUser user) { @@ -68,9 +74,9 @@ public ChatRoomUser(final ChatRoom room, final IUser user) } /** - * Gets the observable object. + * Gets the observable message currently observed by this user * - * @return the observable + * @return the observable message */ public synchronized M getObservable() { @@ -78,7 +84,7 @@ public synchronized M getObservable() } /** - * Gets the user. + * Gets the user associated with this chat room user * * @return the user */ @@ -88,10 +94,10 @@ public IUser getUser() } /** - * Send the given message. + * Sends the given message to the chat room * * @param message - * the message + * the message to be sent */ public void send(final M message) { diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/IUser.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/IUser.java index ec00cfd..544948a 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/IUser.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/IUser.java @@ -27,23 +27,25 @@ import java.io.Serializable; /** - * The interface {@link IUser}. + * The interface {@link IUser} represents a user in a chat application It provides methods to manage + * the user's identity, including getting and setting the application user, retrieving the user's + * unique identifier, and obtaining the user's name * * @param - * the generic type + * the generic type representing the application user */ public interface IUser extends Serializable { /** - * Gets the application user. + * Gets the application user associated with this {@link IUser} * * @return the application user */ U getApplicationUser(); /** - * Sets the application user. + * Sets the application user associated with this {@link IUser} * * @param user * the new application user @@ -51,16 +53,16 @@ public interface IUser extends Serializable void setApplicationUser(final U user); /** - * Gets the id. + * Gets the unique identifier for this {@link IUser} * - * @return the id + * @return the unique identifier */ Serializable getId(); /** - * Gets the name. + * Gets the name of this {@link IUser} * - * @return the name + * @return the name of the user */ String getName(); } diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/Invitation.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/Invitation.java index 61efc62..5a9db27 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/Invitation.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/Invitation.java @@ -27,47 +27,49 @@ import java.io.Serializable; /** - * The Interface Invitation. + * The Interface {@link Invitation} represents an invitation to join a chat room It defines the + * methods to retrieve the sender, recipient, and the room associated with the invitation, as well + * as methods to check if the invitation has been accepted and if the denial is visible to the + * sender * * @param - * the generic type + * the generic type of the message associated with the chat room */ public interface Invitation> extends Serializable { /** - * Gets the recipient of this invitation. + * Gets the recipient of this invitation * - * @return the recipient of this invitation. + * @return the recipient of this invitation */ IUser getRecipient(); /** - * Gets the room for this invitation. + * Gets the room associated with this invitation * - * @return the room for this invitation. + * @return the room for this invitation */ Room getRoom(); /** - * Gets the sender of this invitation. + * Gets the sender of this invitation * - * @return the sender of this invitation. + * @return the sender of this invitation */ IUser getSender(); /** - * Checks if this invitation is accepted from the recipient. + * Checks if this invitation has been accepted by the recipient * - * @return true, if it is accepted otherwise false. + * @return true if the invitation is accepted, otherwise false */ boolean isAccepted(); /** - * Checks if the recipient wants that the sender sees that he denied his invitation. + * Checks if the recipient wants the sender to see that the invitation was denied * - * @return true, if the recipient wants that the sender sees that he denied his invitation - * otherwise false. + * @return true if the recipient wants the sender to see the denial, otherwise false */ boolean isDeniedVisible(); } diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/Message.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/Message.java index 3972fef..5fc0b81 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/Message.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/Message.java @@ -27,27 +27,28 @@ import java.io.Serializable; /** - * The interface {@link Message}. + * The interface {@link Message} represents a message that can be sent in a chat application It + * provides methods for getting and setting the value of the message * * @param - * the generic type + * the generic type of the value contained in the message */ public interface Message extends Serializable { /** - * Gets the value. + * Gets the value of the message * - * @return the value + * @return the value of the message */ T getValue(); /** - * Sets the value. + * Sets the value of the message * * @param value - * the value - * @return the message + * the value to set + * @return the updated message */ Message setValue(final T value); diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/MessageRoomModelBean.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/MessageRoomModelBean.java index 16cc8e1..76a4b91 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/MessageRoomModelBean.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/MessageRoomModelBean.java @@ -28,37 +28,42 @@ import java.util.Date; /** - * The class {@link MessageRoomModelBean}. - * + * The class {@link MessageRoomModelBean} represents a model for a message in a chat room It + * includes details such as the chat room name, the user who sent the message, the message content, + * and any associated data, as well as the date the message was created */ public class MessageRoomModelBean implements Serializable { - /** The Constant serialVersionUID. */ + /** The Constant serialVersionUID for serialization compatibility */ private static final long serialVersionUID = 1L; - /** The chat room name. */ + /** The name of the chat room */ private final String chatRoomName; - /** The date. */ + + /** The date the message was created */ private final Date date = new Date(); - /** The user. */ + + /** The user who sent the message */ private final IUser user; - /** The data. */ + + /** Any additional data associated with the message */ private Byte[] data; - /** The message. */ + + /** The content of the message */ private String message; /** - * Instantiates a new message room model. + * Instantiates a new {@code MessageRoomModelBean} with the specified details * * @param chatRoomName - * the chat room name + * the name of the chat room * @param user - * the user + * the user who sent the message * @param message - * the message + * the content of the message * @param data - * the data + * any additional data associated with the message */ public MessageRoomModelBean(final String chatRoomName, final IUser user, final String message, final Byte[] data) @@ -71,7 +76,7 @@ public MessageRoomModelBean(final String chatRoomName, final IUser user, } /** - * Gets the chat room name. + * Gets the name of the chat room * * @return the chat room name */ @@ -81,7 +86,7 @@ public String getChatRoomName() } /** - * Gets the data. + * Gets the additional data associated with the message * * @return the data */ @@ -91,7 +96,7 @@ public Byte[] getData() } /** - * Sets the data. + * Sets the additional data associated with the message * * @param data * the new data @@ -102,9 +107,9 @@ public void setData(final Byte[] data) } /** - * Gets the date. + * Gets the date the message was created * - * @return the date + * @return the creation date of the message */ public Date getDate() { @@ -112,9 +117,9 @@ public Date getDate() } /** - * Gets the message. + * Gets the content of the message * - * @return the message + * @return the message content */ public String getMessage() { @@ -122,10 +127,10 @@ public String getMessage() } /** - * Sets the message. + * Sets the content of the message * * @param message - * the new message + * the new message content */ public void setMessage(final String message) { @@ -133,9 +138,9 @@ public void setMessage(final String message) } /** - * Gets the user. + * Gets the user who sent the message * - * @return the user + * @return the user who sent the message */ public IUser getUser() { diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/Room.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/Room.java index 468daf3..67f8815 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/Room.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/Room.java @@ -28,32 +28,34 @@ import java.util.List; /** - * The interface {@link Room}. + * The interface {@link Room} represents a chat room in which users can participate It provides + * methods to retrieve the list of users in the chat room, the history of messages sent in the room, + * and to check whether the room is secure * * @param - * the generic type + * the generic type representing the messages that can be sent in the room */ public interface Room> extends Serializable { /** - * Gets the chat room users. + * Gets the list of users in the chat room * - * @return the chat room users + * @return the list of users in the chat room */ List> getChatRoomUsers(); /** - * Gets the message history. + * Gets the history of messages sent in the chat room * - * @return the message history + * @return the list of messages sent in the chat room */ List getMessageHistory(); /** - * Checks if is secure. + * Checks if the chat room is secure * - * @return true, if is secure + * @return true if the chat room is secure, otherwise false */ boolean isSecure(); } diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/StringMessage.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/StringMessage.java index 637ea8f..444fb0d 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/StringMessage.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/StringMessage.java @@ -25,29 +25,30 @@ package io.github.astrapi69.design.pattern.observer.chat; /** - * The class {@link StringMessage}. + * The class {@link StringMessage} represents a message that contains a string value It implements + * the {@link Message} interface and provides methods to get and set the string value */ public class StringMessage implements Message { - /** The Constant serialVersionUID. */ + /** The Constant serialVersionUID for serialization compatibility */ private static final long serialVersionUID = 1L; - /** The value. */ + /** The value of the string message */ private String value; /** - * Instantiates a new string message. + * Instantiates a new {@code StringMessage} with no initial value */ public StringMessage() { } /** - * Instantiates a new string message. + * Instantiates a new {@code StringMessage} with the given value * * @param value - * the value + * the value of the message */ public StringMessage(final String value) { diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/User.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/User.java index c3aa192..930d5a7 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/User.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/User.java @@ -25,29 +25,28 @@ package io.github.astrapi69.design.pattern.observer.chat; /** - * The class {@link User}. + * The class {@link User} represents a user in a chat application It implements the {@link IUser} + * interface and provides methods to manage the user's identity, including their name and ID */ public class User implements IUser { - /** The Constant serialVersionUID. */ + /** The Constant serialVersionUID for serialization compatibility */ private static final long serialVersionUID = 1L; - /** - * User Name. - */ + + /** The name of the user */ private String name; - /** - * User id number. - */ + + /** The ID number of the user */ private Integer id; /** - * Instantiates a new user. + * Instantiates a new user with the given name and ID * * @param name - * the name + * the name of the user * @param id - * the id + * the ID number of the user */ public User(final String name, final Integer id) { @@ -71,8 +70,8 @@ public User getApplicationUser() @Override public void setApplicationUser(final User user) { - - + // This method is intentionally left blank as this class represents the application user + // itself } /** @@ -85,10 +84,10 @@ public Integer getId() } /** - * Sets the id. + * Sets the ID number of the user * * @param id - * the new id + * the new ID number */ public void setId(final Integer id) { @@ -105,10 +104,10 @@ public String getName() } /** - * Sets the name. + * Sets the name of the user * * @param name - * the new name + * the new name of the user */ public void setName(final String name) { diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/listener/MessageListener.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/listener/MessageListener.java index 0d99909..9306044 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/listener/MessageListener.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/listener/MessageListener.java @@ -25,23 +25,22 @@ package io.github.astrapi69.design.pattern.observer.chat.listener; /** - * The listener interface for receiving message events. The class that is interested in processing a + * The listener interface for receiving message events The class that is interested in processing a * message implements this interface, and the object created with that class is registered with a - * component using the component's addMessageListener method. When the message event - * occurs, that object's appropriate method is invoked. - * + * component using the component's addMessageListener method When the message event + * occurs, the appropriate method of that object is invoked + * * @param - * the generic type from the message Event + * the generic type of the message event */ public interface MessageListener { /** - * Handles the given event. + * Handles the given message event * * @param event - * the event + * the event containing the message to be processed */ void onMessage(final T event); - } diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/listener/MessageObject.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/listener/MessageObject.java index e05aa41..af1fb8e 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/listener/MessageObject.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/listener/MessageObject.java @@ -25,24 +25,27 @@ package io.github.astrapi69.design.pattern.observer.chat.listener; /** - * The Class MessageObject. - * + * The Class {@link MessageObject} represents an object that contains a message event It + * encapsulates the source object on which the message event initially occurred + * * @param - * the generic type + * the generic type of the source object */ public class MessageObject { /** - * The object on which the message Event initially occurred. + * The object on which the message event initially occurred */ protected transient T source; /** - * Instantiates a new message object. - * + * Instantiates a new {@code MessageObject} with the given source + * * @param source - * the source + * the source object on which the message event occurred + * @throws IllegalArgumentException + * if the source is {@code null} */ public MessageObject(final T source) { @@ -55,13 +58,12 @@ public MessageObject(final T source) } /** - * Gets the source. + * Gets the source object on which the message event initially occurred * - * @return the source + * @return the source object */ public T getSource() { return source; } - } diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/listener/MessageSource.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/listener/MessageSource.java index 884b9c6..0f45579 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/listener/MessageSource.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/listener/MessageSource.java @@ -27,51 +27,54 @@ import java.util.Collection; /** - * The Interface MessageSource. - * + * The Interface {@link MessageSource} represents a source that can send messages to registered + * listeners It provides methods for adding, removing, and notifying {@link MessageListener} objects + * * @param - * the generic type + * the generic type of the message object */ public interface MessageSource { /** - * Adds the given messageListeners to the existing messageListeners list. - * + * Adds the given {@link MessageListener} to the list of listeners that will receive messages + * * @param messageListener - * the MessageListener object + * the {@link MessageListener} to be added */ void add(final MessageListener messageListener); /** - * Adds the all given messageListener to the existing messageListeners list. - * + * Adds all the given {@link MessageListener} objects to the list of listeners that will receive + * messages + * * @param messageListeners - * the MessageListener objects + * the collection of {@link MessageListener} objects to be added */ void addAll(final Collection> messageListeners); /** - * Fire the given message. - * + * Fires a message to all registered listeners with the given source object + * * @param source - * the message source + * the message source object to be sent to listeners */ void fireMessage(final T source); /** - * Removes the given MessageListener object from the existing messageListeners list. - * + * Removes the given {@link MessageListener} from the list of listeners that receive messages + * * @param messageListener - * the MessageListener object + * the {@link MessageListener} to be removed */ void remove(final MessageListener messageListener); /** - * Removes the all given MessageListener objects from the messageListeners list. - * + * Removes all the given {@link MessageListener} objects from the list of listeners that receive + * messages + * * @param messageListeners - * the MessageListener objects + * the collection of {@link MessageListener} objects to be removed */ void removeAll(final Collection> messageListeners); diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/listener/MessageSubject.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/listener/MessageSubject.java index 3842edd..27485be 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/listener/MessageSubject.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/listener/MessageSubject.java @@ -29,37 +29,40 @@ import java.util.List; /** - * The class {@link MessageSubject}. + * The class {@link MessageSubject} represents a subject in the Observer design pattern for handling + * messages It maintains a list of {@link MessageListener} objects that are notified when a message + * is fired * * @param - * the generic type + * the generic type of the message object */ public class MessageSubject implements MessageSource { - /** The event listeners. */ + /** The list of registered message listeners */ private final List> messageListeners; - /** The source. */ + + /** The current message source */ private T source; /** - * Initialize block. + * Initialization block to create the list of message listeners **/ { messageListeners = new ArrayList<>(); } /** - * Instantiates a new message subject. + * Instantiates a new {@code MessageSubject} with no initial source */ public MessageSubject() { } /** - * Instantiates a new message subject. + * Instantiates a new {@code MessageSubject} with the given initial source * * @param source - * the source + * the initial message source */ public MessageSubject(final T source) { @@ -73,7 +76,6 @@ public MessageSubject(final T source) public synchronized void add(final MessageListener messageListener) { messageListeners.add(messageListener); - } /** @@ -86,7 +88,7 @@ public synchronized void addAll(final Collection> messageList } /** - * Fire message. + * Fires a message to all registered listeners with the current source */ private synchronized void fireMessage() { @@ -123,5 +125,4 @@ public synchronized void removeAll(final Collection> messageL { this.messageListeners.removeAll(messageListeners); } - } diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/listener/package-info.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/listener/package-info.java new file mode 100644 index 0000000..d09394e --- /dev/null +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/listener/package-info.java @@ -0,0 +1,23 @@ +/** + * Provides interfaces and classes for implementing listeners in a chat application using the observer design pattern + * + *

+ * This package is focused on defining the components necessary for handling events in a chat system, specifically through the use of listeners + * Listeners are essential in the observer pattern as they allow objects to be notified of events, such as incoming messages or changes in chat state. + *

+ * + *

+ * The key interfaces and classes in this package include: + *

+ *
    + *
  • {@link io.github.astrapi69.design.pattern.observer.chat.listener.MessageListener} - Represents a listener that reacts to message events in the chat system
    • + *
  • {@link io.github.astrapi69.design.pattern.observer.chat.listener.MessageObject} - Encapsulates the message event that is passed to listeners when a message is received
    • + *
  • {@link io.github.astrapi69.design.pattern.observer.chat.listener.MessageSource} - Represents the source of messages, managing the registration of listeners and the firing of message events
    • + *
+ * + *

+ * This package plays a crucial role in enabling dynamic communication between components in the chat application by allowing objects to react to specific events + * It demonstrates how to use the observer pattern to create responsive and interactive chat systems. + *

+ */ +package io.github.astrapi69.design.pattern.observer.chat.listener; diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/package-info.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/package-info.java new file mode 100644 index 0000000..29c8722 --- /dev/null +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/chat/package-info.java @@ -0,0 +1,26 @@ +/** + * Provides classes and interfaces for implementing a chat application using the observer design pattern + * + *

+ * The chat package includes implementations of chat rooms, users, and messages, all of which interact through the observer pattern + * This package demonstrates how to structure a chat system where users can send and receive messages, and how those messages + * are propagated to all participants in the chat room. + *

+ * + *

+ * The key components of this package include: + *

+ *
    + *
  • {@link io.github.astrapi69.design.pattern.observer.chat.ChatRoom} - Represents a chat room where users can exchange messages
    • + *
  • {@link io.github.astrapi69.design.pattern.observer.chat.ChatRoomUser} - Represents a user participating in a chat room
    • + *
  • {@link io.github.astrapi69.design.pattern.observer.chat.Message} - An interface for messages sent within the chat room
    • + *
  • {@link io.github.astrapi69.design.pattern.observer.chat.StringMessage} - A concrete implementation of {@link io.github.astrapi69.design.pattern.observer.chat.Message} for text-based messages
    • + *
  • {@link io.github.astrapi69.design.pattern.observer.chat.User} - Represents a user entity in the chat system
    • + *
+ * + *

+ * The observer design pattern allows the chat application to notify all users in a chat room when a new message is received + * This package demonstrates a flexible and extensible way to implement such functionality using Java. + *

+ */ +package io.github.astrapi69.design.pattern.observer.chat; diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/event/EventListener.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/event/EventListener.java index 8104010..7813a80 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/event/EventListener.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/event/EventListener.java @@ -25,22 +25,22 @@ package io.github.astrapi69.design.pattern.observer.event; /** - * The {@link EventListener} interface is for receiving events. The class that is interested in + * The {@link EventListener} interface is for receiving events The class that is interested in * processing an event implements this interface, and the object created with that class is - * registered with a component using the component's addEventListener method. When the + * registered with a component using the component's addEventListener method When the * event occurs, that object's appropriate method is invoked * * @param - * the generic type from the event + * the generic type of the event to be processed */ public interface EventListener { /** - * Handles the given event. + * Handles the given event * * @param event - * the event + * the event to be handled */ void onEvent(final T event); diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/event/EventObject.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/event/EventObject.java index b901239..ee62314 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/event/EventObject.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/event/EventObject.java @@ -31,7 +31,8 @@ import lombok.experimental.SuperBuilder; /** - * The class {@link EventObject} serves as the name already tells as an event object + * The class {@link EventObject} serves, as its name suggests, as an event object It encapsulates + * the source object on which an event initially occurred * * @param * the generic type of the source object @@ -52,7 +53,7 @@ public class EventObject * Instantiates a new {@link EventObject} object * * @param source - * the source + * the source object on which the event occurred */ public EventObject(final @NonNull T source) { @@ -60,13 +61,13 @@ public EventObject(final @NonNull T source) } /** - * Factory method for create a new {@link EventObject} object + * Factory method to create a new {@link EventObject} object * * @param * the generic type of the source object * @param source - * the source - * @return the new created {@link EventObject} object + * the source object on which the event occurred + * @return the newly created {@link EventObject} object */ public static EventObject of(final @NonNull T source) { diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/event/EventSource.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/event/EventSource.java index 9947a86..e90334b 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/event/EventSource.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/event/EventSource.java @@ -27,7 +27,8 @@ import java.util.Collection; /** - * The interface {@link EventSource} + * The interface {@link EventSource} represents a source of events It provides methods to manage + * event listeners and to fire events to those listeners * * @param * the generic type of the source object @@ -36,42 +37,42 @@ public interface EventSource { /** - * Adds the given event listener to the eventListeners list. + * Adds the given event listener to the list of event listeners * * @param eventListener - * the event listener + * the event listener to be added */ void add(final EventListener eventListener); /** - * Adds the all given event listeners to the eventListeners list. + * Adds all the given event listeners to the list of event listeners * * @param eventListeners - * the event listeners + * the collection of event listeners to be added */ void addAll(final Collection> eventListeners); /** - * Fire the given event. + * Fires an event to all registered listeners with the given source object * * @param source - * the source + * the source object that the event relates to */ void fireEvent(final T source); /** - * Removes the given event listener from the eventListeners list. + * Removes the given event listener from the list of event listeners * * @param eventListener - * the event listener + * the event listener to be removed */ void remove(final EventListener eventListener); /** - * Removes the all given event listeners from the eventListeners list. + * Removes all the given event listeners from the list of event listeners * * @param eventListeners - * the event listeners + * the collection of event listeners to be removed */ void removeAll(final Collection> eventListeners); diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/event/EventSubject.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/event/EventSubject.java index 4e249ba..0414421 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/event/EventSubject.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/event/EventSubject.java @@ -33,7 +33,8 @@ import lombok.ToString; /** - * The class {@link EventSubject} + * The class {@link EventSubject} is an implementation of the {@link EventSource} interface It + * represents a subject that can have multiple event listeners and can fire events to them * * @param * the generic type of the source object @@ -44,29 +45,29 @@ public class EventSubject implements EventSource { - /** The event listeners */ + /** The collection of registered event listeners */ private final Collection> eventListeners; - /** The source object */ + /** The source object associated with the event */ private T source; - /* Initialization block */ + /* Initialization block to initialize the eventListeners collection */ { eventListeners = new ArrayList<>(); } /** - * Instantiates a new event subject. + * Instantiates a new {@code EventSubject} with no initial source */ public EventSubject() { } /** - * Instantiates a new event subject. + * Instantiates a new {@code EventSubject} with the specified source * * @param source - * the source + * the source object associated with the event */ public EventSubject(final T source) { @@ -74,13 +75,13 @@ public EventSubject(final T source) } /** - * Factory method for create a new {@link EventSubject} object + * Factory method to create a new {@link EventSubject} object * * @param * the generic type of the source object * @param source - * the source - * @return the new created {@link EventSubject} object + * the source object associated with the event + * @return the newly created {@link EventSubject} object */ public static EventSubject of(final @NonNull T source) { @@ -106,7 +107,7 @@ public synchronized void addAll(final Collection> eventListener } /** - * Fires the source event and inform all registered listeners. + * Fires the event to all registered listeners */ private synchronized void fireEvent() { diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/event/package-info.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/event/package-info.java new file mode 100644 index 0000000..6ea7374 --- /dev/null +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/event/package-info.java @@ -0,0 +1,24 @@ +/** + * Provides classes and interfaces for implementing event handling in the observer design pattern + * + *

+ * This package is designed to manage events and event sources within the observer pattern framework + * It includes the necessary components for creating, firing, and handling events, allowing objects to respond dynamically to changes in other objects' states. + *

+ * + *

+ * The key interfaces and classes in this package include: + *

+ *
    + *
  • {@link io.github.astrapi69.design.pattern.observer.event.EventListener} - Represents an interface for handling events that occur within the system
    • + *
  • {@link io.github.astrapi69.design.pattern.observer.event.EventObject} - Encapsulates the event data, acting as a carrier of the information related to the event
    • + *
  • {@link io.github.astrapi69.design.pattern.observer.event.EventSource} - Represents the source of events, managing event listeners and the firing of events
    • + *
  • {@link io.github.astrapi69.design.pattern.observer.event.EventSubject} - A concrete implementation of {@link io.github.astrapi69.design.pattern.observer.event.EventSource}, which manages a collection of event listeners and notifies them when an event occurs
    • + *
+ * + *

+ * This package is essential for building a robust event-driven architecture within an application, enabling objects to communicate changes efficiently and effectively + * It demonstrates how to use the observer pattern to manage and propagate events throughout a system. + *

+ */ +package io.github.astrapi69.design.pattern.observer.event; diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/ExceptionEvent.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/ExceptionEvent.java index c5a4236..8124607 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/ExceptionEvent.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/ExceptionEvent.java @@ -33,7 +33,8 @@ import lombok.ToString; /** - * The class {@link ExceptionEvent} acts like as an Observable. + * The class {@link ExceptionEvent} represents an event that encapsulates a {@link Throwable} object + * It acts as an observable event that can be passed to listeners interested in handling exceptions */ @Getter @Setter @@ -44,7 +45,7 @@ @Builder(toBuilder = true) public class ExceptionEvent { - /** The value. */ + /** The {@link Throwable} object associated with this event */ private Throwable value; } diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/ExceptionListener.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/ExceptionListener.java index 2ddef72..5b96740 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/ExceptionListener.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/ExceptionListener.java @@ -27,10 +27,10 @@ import java.util.EventListener; /** - * The listener interface for receiving exception events. The class that is interested in processing - * a exception event implements this interface, and the object created with that class is registered - * with a component using the component's addExceptionListener method. When the - * exception event occurs, that object's appropriate method is invoked. + * The listener interface for receiving exception events The class that is interested in processing + * an exception event implements this interface, and the object created with that class is + * registered with a component using the component's addExceptionListener method When + * the exception event occurs, that object's appropriate method is invoked * * @see ExceptionEvent */ @@ -38,10 +38,10 @@ public interface ExceptionListener extends EventListener { /** - * On exception. + * Invoked when an exception event occurs * * @param event - * the event + * the exception event to be processed */ void onException(final ExceptionEvent event); diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/ExceptionMessage.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/ExceptionMessage.java index 94557aa..3acc12c 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/ExceptionMessage.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/ExceptionMessage.java @@ -36,12 +36,13 @@ import lombok.ToString; /** - * Class for Messages in Exception classes. + * The class {@link ExceptionMessage} represents a message object used in exception handling It + * encapsulates information such as a properties key and value, an ID, and additional data that may + * be related to the exception * * @version 1.0 - * @author Asterios Raptis * @param - * the generic type + * the generic type of the additional data */ @Getter @Setter @@ -53,32 +54,30 @@ public class ExceptionMessage implements Serializable { - /** - * The serialVersionUID. - */ + /** The serialVersionUID for serialization compatibility */ private static final long serialVersionUID = 1L; - /** Reference for the key in the resources bundle. */ + /** The key reference for a property in the resource bundle */ private String propertiesKey; - /** Reference for the value in the resources bundle. */ + /** The value reference for a property in the resource bundle */ private String propertiesValue; - /** Reference for the id in the database. */ + /** The unique identifier in the database */ private String id; - /** The additions. */ + /** A list of additional data related to the exception */ private List additions; /** - * Default constructor. + * Constructor for creating an {@code ExceptionMessage} with specified key, value, and ID * * @param propertiesKey - * the properties key + * the key reference for a property in the resource bundle * @param propertiesValue - * the properties value + * the value reference for a property in the resource bundle * @param id - * the id + * the unique identifier in the database */ public ExceptionMessage(final String propertiesKey, final String propertiesValue, final String id) diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/ExceptionMessages.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/ExceptionMessages.java index a732af3..7cc6d4c 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/ExceptionMessages.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/ExceptionMessages.java @@ -31,26 +31,41 @@ import java.util.Set; /** - * The Class ExceptionMessages. - * + * The class {@link ExceptionMessages} manages a collection of exception messages organized by keys + * It allows adding, retrieving, and removing exception messages based on specific keys + * * @param - * the generic type + * the generic type of the additional data contained in the exception messages */ public class ExceptionMessages { - /** Contains all exceptionmessages. */ + /** A map that contains all exception messages, organized by keys */ private final Map>> exceptions = new HashMap<>(); + /** + * Adds a map of exception messages to the existing collection + * + * @param keyListMap + * the map of keys and corresponding sets of exception messages to be added + */ public void add(final Map>> keyListMap) { this.exceptions.putAll(keyListMap); } + /** + * Adds an exception message to the collection under the specified key + * + * @param key + * the key under which the exception message should be stored + * @param value + * the exception message to be added + */ public void add(final String key, final ExceptionMessage value) { Set> values = this.exceptions.get(key); - if (null == values) + if (values == null) { values = new HashSet<>(); this.exceptions.put(key, values); @@ -58,36 +73,79 @@ public void add(final String key, final ExceptionMessage value) values.add(value); } + /** + * Checks if the collection contains exception messages associated with the specified key + * + * @param key + * the key to be checked + * @return true if the key exists in the collection, otherwise false + */ public boolean containsKey(final String key) { return this.exceptions.containsKey(key); } + /** + * Retrieves the set of exception messages associated with the specified key + * + * @param key + * the key whose associated exception messages are to be returned + * @return the set of exception messages associated with the specified key, or null if no + * messages are found + */ public Set> get(final String key) { return this.exceptions.get(key); } + /** + * Retrieves the set of all keys used in the collection + * + * @return the set of all keys + */ public Set getKeys() { return this.exceptions.keySet(); } + /** + * Gets the number of unique keys in the collection + * + * @return the number of unique keys + */ public int getSize() { return this.exceptions.size(); } + /** + * Checks if the collection is empty + * + * @return true if the collection contains no entries, otherwise false + */ public boolean isEmpty() { return this.exceptions.isEmpty(); } + /** + * Removes all exception messages associated with the specified key + * + * @param key + * the key whose associated exception messages are to be removed + * @return the set of exception messages that were removed, or null if the key was not found + */ public Set> remove(final String key) { return this.exceptions.remove(key); } + /** + * Removes all exception messages associated with the specified collection of keys + * + * @param keys + * the collection of keys whose associated exception messages are to be removed + */ public void removeAll(final Collection keys) { for (final String key : keys) diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/ExceptionObservers.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/ExceptionObservers.java index 4b6bf99..d3d1298 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/ExceptionObservers.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/ExceptionObservers.java @@ -28,27 +28,31 @@ import java.util.List; /** - * The Class ExceptionObservers. + * The class {@link ExceptionObservers} is a singleton that manages a list of + * {@link ExceptionListener} objects It allows classes to register and unregister for exception + * events, and notifies registered listeners when an exception event occurs */ public class ExceptionObservers { - /** The instance. */ + /** The single instance of this class */ private static ExceptionObservers instance = null; - /** The exception listeners. */ + + /** The list of registered exception listeners */ protected List exceptionListeners = new ArrayList<>(); /** - * Instantiates a new exception observers. + * Instantiates a new {@code ExceptionObservers} object This constructor is private to enforce + * the singleton pattern */ private ExceptionObservers() { } /** - * Gets the single instance of ExceptionObservers. + * Gets the single instance of {@code ExceptionObservers} * - * @return single instance of ExceptionObservers + * @return the single instance of {@code ExceptionObservers} */ public static synchronized ExceptionObservers getInstance() { @@ -63,10 +67,11 @@ public static synchronized ExceptionObservers getInstance() } /** - * Adds the exception listener. This method allows classes to register for ExceptionEvents. + * Adds the specified exception listener to the list of listeners This method allows classes to + * register for exception events * * @param listener - * the listener + * the exception listener to be added */ public void addExceptionListener(final ExceptionListener listener) { @@ -74,10 +79,10 @@ public void addExceptionListener(final ExceptionListener listener) } /** - * Fire exception event. + * Fires an exception event to all registered listeners * * @param event - * the event + * the exception event to be fired */ void fireExceptionEvent(final ExceptionEvent event) { @@ -89,12 +94,12 @@ void fireExceptionEvent(final ExceptionEvent event) } } - /** - * Removes the exception listener. This method allows classes to unregister for ExceptionEvents. + * Removes the specified exception listener from the list of listeners This method allows + * classes to unregister for exception events * * @param listener - * the listener + * the exception listener to be removed */ public void removeExceptionListener(final ExceptionListener listener) { diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/handlers/AbstractExceptionHandler.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/handlers/AbstractExceptionHandler.java index 884d708..290e754 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/handlers/AbstractExceptionHandler.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/handlers/AbstractExceptionHandler.java @@ -32,7 +32,8 @@ import io.github.astrapi69.design.pattern.observer.exception.ExceptionListener; /** - * The abstract class that handles all exceptions. + * The abstract class {@link AbstractExceptionHandler} handles all exceptions by managing a list of + * {@link ExceptionListener} objects and updating them when an exception event occurs * * @version 1.0 * @author Asterios Raptis @@ -40,19 +41,17 @@ public abstract class AbstractExceptionHandler implements Serializable { - /** - * The serialVersionUID. - */ + /** The serialVersionUID for serialization compatibility */ private static final long serialVersionUID = 1L; - /** Lists of the ExceptionListeners. */ - private final List listeners = new ArrayList<>(); + /** The list of registered {@link ExceptionListener} objects */ + private final List listeners = new ArrayList<>(); /** - * Adds an ExceptionListener object. + * Adds an {@link ExceptionListener} object to the list of listeners * * @param listener - * the listener + * the listener to be added */ void addExceptionListener(final ExceptionListener listener) { @@ -60,10 +59,10 @@ void addExceptionListener(final ExceptionListener listener) } /** - * Removes an ExceptionListener object. + * Removes an {@link ExceptionListener} object from the list of listeners * * @param listener - * the listener + * the listener to be removed */ void removeExceptionListener(final ExceptionListener listener) { @@ -71,10 +70,10 @@ void removeExceptionListener(final ExceptionListener listener) } /** - * Update the given event. + * Updates all registered listeners with the given exception event * * @param event - * the event + * the exception event to be propagated to the listeners */ void update(final ExceptionEvent event) { @@ -85,14 +84,14 @@ void update(final ExceptionEvent event) } /** - * This method updates the listener for this event. + * Updates the specified listener with the given exception event This method must be implemented + * by subclasses to define how the event is propagated to the listener * * @param listener - * the listener + * the listener to be updated * @param event - * the event + * the exception event to be propagated to the listener */ public abstract void updateEvent(final ExceptionListener listener, final ExceptionEvent event); - } diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/handlers/DefaultExceptionHandler.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/handlers/DefaultExceptionHandler.java index f1956df..88c1518 100644 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/handlers/DefaultExceptionHandler.java +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/handlers/DefaultExceptionHandler.java @@ -28,12 +28,14 @@ import io.github.astrapi69.design.pattern.observer.exception.ExceptionListener; /** - * The Class DefaultExceptionHandler. + * The class {@link DefaultExceptionHandler} provides a default implementation for handling + * exception events It extends {@link AbstractExceptionHandler} and propagates exception events to + * the registered listeners */ public class DefaultExceptionHandler extends AbstractExceptionHandler { - /** The serialVersionUID. */ + /** The serialVersionUID for serialization compatibility */ private static final long serialVersionUID = -7194471234913656513L; /** @@ -46,10 +48,10 @@ public void updateEvent(final ExceptionListener listener, final ExceptionEvent e } /** - * Update on exception. + * Updates all registered listeners with the given exception event * * @param event - * the event + * the exception event to be propagated to the listeners */ public void updateOnException(final ExceptionEvent event) { diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/handlers/package-info.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/handlers/package-info.java new file mode 100644 index 0000000..f5cfa01 --- /dev/null +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/handlers/package-info.java @@ -0,0 +1,22 @@ +/** + * Provides classes for handling exceptions using the observer design pattern + * + *

+ * This package is focused on managing exception events and notifying registered listeners when exceptions occur + * By utilizing the observer pattern, it allows for a flexible and decoupled approach to exception handling, where multiple components can respond to exceptions in a coordinated manner. + *

+ * + *

+ * The key classes in this package include: + *

+ *
    + *
  • {@link io.github.astrapi69.design.pattern.observer.exception.handlers.AbstractExceptionHandler} - An abstract base class that provides common functionality for managing exception listeners and propagating exception events
    • + *
  • {@link io.github.astrapi69.design.pattern.observer.exception.handlers.DefaultExceptionHandler} - A concrete implementation of {@link io.github.astrapi69.design.pattern.observer.exception.handlers.AbstractExceptionHandler} that provides default behavior for handling exceptions and notifying listeners
    • + *
+ * + *

+ * This package is essential for building a robust exception handling mechanism within an application, allowing for centralized and consistent management of exception events + * It demonstrates how the observer pattern can be applied to exception handling to ensure that exceptions are effectively communicated and managed across the system. + *

+ */ +package io.github.astrapi69.design.pattern.observer.exception.handlers; diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/package-info.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/package-info.java new file mode 100644 index 0000000..6fff172 --- /dev/null +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/package-info.java @@ -0,0 +1,25 @@ +/** + * Provides classes and interfaces for handling exceptions using the observer design pattern + * + *

+ * This package is designed to facilitate the management and communication of exceptions within an application + * By using the observer pattern, it allows multiple components to listen for and respond to exception events, enabling a decoupled and flexible approach to exception handling. + *

+ * + *

+ * The key interfaces and classes in this package include: + *

+ *
    + *
  • {@link io.github.astrapi69.design.pattern.observer.exception.ExceptionEvent} - Encapsulates an exception event, carrying information about an exception that has occurred
    • + *
  • {@link io.github.astrapi69.design.pattern.observer.exception.ExceptionListener} - Represents a listener that reacts to exception events, allowing components to respond when exceptions occur
    • + *
  • {@link io.github.astrapi69.design.pattern.observer.exception.ExceptionMessage} - Represents a structured message related to an exception, containing details such as a properties key, value, and additional data
    • + *
  • {@link io.github.astrapi69.design.pattern.observer.exception.ExceptionObservers} - Manages a collection of exception listeners and notifies them when an exception event occurs, following the singleton pattern
    • + *
  • {@link io.github.astrapi69.design.pattern.observer.exception.ExceptionMessages} - Manages a collection of exception messages organized by keys, providing methods to add, retrieve, and remove messages
    • + *
+ * + *

+ * This package is crucial for implementing a centralized and consistent approach to exception handling in an application + * It demonstrates how the observer pattern can be applied to ensure that exceptions are effectively communicated and managed across different components in the system. + *

+ */ +package io.github.astrapi69.design.pattern.observer.exception; diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/package.html b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/package.html deleted file mode 100644 index ad6763b..0000000 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/exception/package.html +++ /dev/null @@ -1,11 +0,0 @@ - - - - - io.github.astrapi69.designpattern.observer.exception - - - - Provides helper classes for Exception Objects. - - diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/package-info.java b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/package-info.java new file mode 100644 index 0000000..cb8a5df --- /dev/null +++ b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/package-info.java @@ -0,0 +1,23 @@ +/** + * Provides core classes and interfaces for implementing the observer design pattern + * + *

+ * The observer design pattern is a behavioral design pattern where an object, known as the subject, maintains a list of its dependents, called observers, + * and notifies them automatically of any state changes, usually by calling one of their methods + * This package contains the foundational components necessary for building systems based on the observer pattern, enabling objects to be notified of changes in other objects' states. + *

+ * + *

+ * The key interfaces and classes in this package include: + *

+ *
    + *
  • {@link io.github.astrapi69.design.pattern.observer.AbstractObserver} - A base class that provides a concrete implementation of the observer interface, handling updates and executing commands
    • + *
  • {@link io.github.astrapi69.design.pattern.observer.AbstractSubject} - A base class that provides a concrete implementation of the subject interface, managing observers and updating them when changes occur
    • + *
+ * + *

+ * This package is essential for creating systems where objects need to be informed of state changes in other objects, promoting loose coupling and dynamic behavior + * It demonstrates the flexibility and power of the observer design pattern in a wide range of application scenarios. + *

+ */ +package io.github.astrapi69.design.pattern.observer; diff --git a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/package.html b/observer/src/main/java/io/github/astrapi69/design/pattern/observer/package.html deleted file mode 100644 index be5c075..0000000 --- a/observer/src/main/java/io/github/astrapi69/design/pattern/observer/package.html +++ /dev/null @@ -1,11 +0,0 @@ - - - - - io.github.astrapi69.design.pattern.observer - - - - Provides abstract classes for the generic implementation for the observer pattern. - - diff --git a/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/ApplicationUser.java b/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/ApplicationUser.java index cac18a7..e4bec50 100644 --- a/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/ApplicationUser.java +++ b/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/ApplicationUser.java @@ -28,33 +28,46 @@ import io.github.astrapi69.auth.SimpleUser; +/** + * The class {@link ApplicationUser} represents a user in the chat application It implements the + * {@link IUser} interface, providing methods to manage the application user's identity + */ public class ApplicationUser implements IUser { - /** - * - */ private static final long serialVersionUID = 1L; - SimpleUser applicationUser; + private SimpleUser applicationUser; + /** + * {@inheritDoc} + */ @Override public SimpleUser getApplicationUser() { return this.applicationUser; } + /** + * {@inheritDoc} + */ @Override public void setApplicationUser(final SimpleUser user) { this.applicationUser = user; } + /** + * {@inheritDoc} + */ @Override public Serializable getId() { return this.applicationUser.getId(); } + /** + * {@inheritDoc} + */ @Override public String getName() { diff --git a/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/DataChatRoomUser.java b/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/DataChatRoomUser.java index bcd5ef6..e5568ef 100644 --- a/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/DataChatRoomUser.java +++ b/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/DataChatRoomUser.java @@ -24,19 +24,32 @@ */ package io.github.astrapi69.design.pattern.observer.chat; +/** + * The class {@link DataChatRoomUser} represents a user in a chat room who can send and receive + * {@link ChatMessage} objects It extends {@link ChatRoomUser} and provides specific behavior for + * handling {@link ChatMessage} objects + */ public class DataChatRoomUser extends ChatRoomUser { - /** - * - */ private static final long serialVersionUID = 1L; + /** + * Instantiates a new {@code DataChatRoomUser} with the specified chat room and user + * + * @param room + * the chat room + * @param user + * the user associated with this chat room user + */ public DataChatRoomUser(final ChatRoom room, final IUser user) { super(room, user); } + /** + * {@inheritDoc} + */ @Override public void execute() { @@ -44,9 +57,11 @@ public void execute() + getUser().getName() + " sees the Message:\n" + getObservable().getValue().getMessage() + "\n----------------------------------------------"; System.out.println(display); - } + /** + * {@inheritDoc} + */ @Override public void send(final ChatMessage message) { diff --git a/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/DemonstrateChatObserver.java b/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/DemonstrateChatObserver.java index f9d8b55..071843b 100644 --- a/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/DemonstrateChatObserver.java +++ b/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/DemonstrateChatObserver.java @@ -27,18 +27,18 @@ import io.github.astrapi69.design.pattern.observer.api.Subject; /** - * An asynchronous update interface for receiving notifications about DemonstrateChat information as - * the DemonstrateChat is constructed. + * The class {@link DemonstrateChatObserver} demonstrates the usage of the chat observer pattern + * with various chat rooms and users This class contains a main method that simulates a chat session + * between multiple users in different chat rooms */ public class DemonstrateChatObserver { /** - * This method is called when information about an DemonstrateChat which was previously - * requested using an asynchronous interface becomes available. + * The main method that simulates a chat session between multiple users in different chat rooms * * @param args - * the args + * the command line arguments */ public static void main(final String[] args) { @@ -61,9 +61,6 @@ public static void main(final String[] args) (ChatRoom)firstRoom, alfredUser) { - /** - * - */ private static final long serialVersionUID = 1L; @Override @@ -73,7 +70,6 @@ public void execute() + alfredUser.getName() + " sees the Message:\n" + getObservable().getValue() + "\n----------------------------------------------"; System.out.println(display); - } @Override @@ -115,7 +111,7 @@ public void send(final StringMessage message) message = new StringMessage("im alone now :-(("); System.out.println("########## New message ##############"); alfredFirstRoom.send(message); - message = new StringMessage("Im leafing this room too..."); + message = new StringMessage("Im leaving this room too..."); System.out.println("########## New message ##############"); alfredFirstRoom.send(message); firstRoom.remove(alfredFirstRoom); diff --git a/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/SimpleChatRoomUser.java b/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/SimpleChatRoomUser.java index c6e5d81..7889b4f 100644 --- a/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/SimpleChatRoomUser.java +++ b/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/SimpleChatRoomUser.java @@ -24,19 +24,32 @@ */ package io.github.astrapi69.design.pattern.observer.chat; +/** + * The class {@link SimpleChatRoomUser} represents a user in a chat room who can send and receive + * string messages It extends {@link ChatRoomUser} and provides specific behavior for handling + * {@link StringMessage} objects + */ public class SimpleChatRoomUser extends ChatRoomUser { - /** - * - */ private static final long serialVersionUID = 1L; + /** + * Instantiates a new {@code SimpleChatRoomUser} with the specified chat room and user + * + * @param room + * the chat room + * @param user + * the user associated with this chat room user + */ public SimpleChatRoomUser(final ChatRoom room, final IUser user) { super(room, user); } + /** + * {@inheritDoc} + */ @Override public void execute() { @@ -44,9 +57,11 @@ public void execute() + getUser().getName() + " sees the Message:\n" + getObservable().getValue() + "\n----------------------------------------------"; System.out.println(display); - } + /** + * {@inheritDoc} + */ @Override public void send(final StringMessage message) { diff --git a/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/example/ChatApp.java b/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/example/ChatApp.java new file mode 100644 index 0000000..fea8473 --- /dev/null +++ b/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/example/ChatApp.java @@ -0,0 +1,104 @@ +package io.github.astrapi69.design.pattern.observer.chat.example; + +import java.awt.*; +import java.awt.event.ActionEvent; +import java.awt.event.ActionListener; + +import javax.swing.*; + +import io.github.astrapi69.design.pattern.observer.chat.IUser; + +public class ChatApp +{ + + private JFrame frame; + private JTextArea chatArea; + private JTextField inputField; + private ChatRoom chatRoom; + + public static void main(String[] args) + { + SwingUtilities.invokeLater(ChatApp::new); + } + + public ChatApp() + { + initialize(); + } + + private void initialize() + { + // Create the chat room + chatRoom = new ChatRoom<>("General"); + + // Create some users + User user1 = new User("Alice", 1); + User user2 = new User("Bob", 2); + + // Register the users in the chat room + ChatRoomUser chatUser1 = new ChatRoomUserImpl(chatRoom, user1); + ChatRoomUser chatUser2 = new ChatRoomUserImpl(chatRoom, user2); + + // Set up the frame + frame = new JFrame("Chat Room"); + frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE); + frame.setSize(400, 300); + frame.setLayout(new BorderLayout()); + + // Create chat area + chatArea = new JTextArea(); + chatArea.setEditable(false); + frame.add(new JScrollPane(chatArea), BorderLayout.CENTER); + + // Create input field + inputField = new JTextField(); + inputField.addActionListener(new ActionListener() + { + @Override + public void actionPerformed(ActionEvent e) + { + String text = inputField.getText(); + if (!text.isEmpty()) + { + StringMessage message = new StringMessage(text); + chatUser1.send(message); + inputField.setText(""); + } + } + }); + frame.add(inputField, BorderLayout.SOUTH); + + // Show the frame + frame.setVisible(true); + + // Simulate a message from another user + Timer timer = new Timer(5000, new ActionListener() + { + @Override + public void actionPerformed(ActionEvent e) + { + StringMessage message = new StringMessage("Hello from " + user2.getName() + "!"); + chatUser2.send(message); + } + }); + timer.setRepeats(false); + timer.start(); + } + + // Implementation of a simple ChatRoomUser that updates the chat area when a message is received + private class ChatRoomUserImpl extends ChatRoomUser + { + + public ChatRoomUserImpl(ChatRoom room, IUser user) + { + super(room, user); + } + + @Override + public void execute() + { + SwingUtilities.invokeLater(() -> chatArea + .append(getUser().getName() + ": " + getObservable().getValue() + "\n")); + } + } +} diff --git a/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/example/ChatRoom.java b/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/example/ChatRoom.java new file mode 100644 index 0000000..32b273d --- /dev/null +++ b/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/example/ChatRoom.java @@ -0,0 +1,115 @@ +package io.github.astrapi69.design.pattern.observer.chat.example; + +import java.io.Serializable; +import java.util.ArrayList; +import java.util.Collection; +import java.util.List; + +import io.github.astrapi69.design.pattern.observer.AbstractSubject; +import io.github.astrapi69.design.pattern.observer.chat.IUser; +import io.github.astrapi69.design.pattern.observer.chat.Message; +import io.github.astrapi69.design.pattern.observer.chat.Room; + +public class ChatRoom> extends AbstractSubject> + implements + Room, + Serializable +{ + + private static final long serialVersionUID = 1L; + private final List> observers = new ArrayList<>(); + private final List messageHistory = new ArrayList<>(); + private final String name; + private M observable; + + public ChatRoom(String name) + { + this.name = name; + } + + public ChatRoom(M observable, String name) + { + this.observable = observable; + this.name = name; + } + + @Override + public synchronized void add(ChatRoomUser observer) + { + observers.add(observer); + } + + @Override + public void addAll(Collection> observers) + { + this.observers.addAll(observers); + } + + @Override + public List> getChatRoomUsers() + { + List> chatRoomUsers = new ArrayList<>(); + for (ChatRoomUser chatUser : observers) + { + chatRoomUsers.add(chatUser.getUser()); + } + return chatRoomUsers; + } + + @Override + public List getMessageHistory() + { + return messageHistory; + } + + @Override + public synchronized M getObservable() + { + return observable; + } + + @Override + public synchronized void setObservable(M observable) + { + this.observable = observable; + messageHistory.add(observable); + updateObservers(); + } + + @Override + public boolean isSecure() + { + return false; + } + + @Override + public synchronized void remove(ChatRoomUser observer) + { + observers.remove(observer); + } + + @Override + public void removeAll(Collection> observers) + { + this.observers.removeAll(observers); + } + + public int size() + { + return observers.size(); + } + + @Override + public synchronized void updateObservers() + { + for (ChatRoomUser observer : observers) + { + observer.update(observable); + } + } + + public String getName() + { + return name; + } +} diff --git a/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/example/ChatRoomUser.java b/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/example/ChatRoomUser.java new file mode 100644 index 0000000..6a512c1 --- /dev/null +++ b/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/example/ChatRoomUser.java @@ -0,0 +1,51 @@ +package io.github.astrapi69.design.pattern.observer.chat.example; + +import java.io.Serializable; + +import io.github.astrapi69.design.pattern.observer.api.ActionCommand; +import io.github.astrapi69.design.pattern.observer.api.Observer; +import io.github.astrapi69.design.pattern.observer.chat.IUser; +import io.github.astrapi69.design.pattern.observer.chat.Message; + +public abstract class ChatRoomUser> + implements + Observer, + ActionCommand, + Serializable +{ + + private static final long serialVersionUID = 1L; + private final IUser user; + protected ChatRoom subject; + private M observable; + + public ChatRoomUser(ChatRoom room, IUser user) + { + this.subject = room; + this.observable = this.subject.getObservable(); + this.user = user; + this.subject.add(this); + } + + @Override + public synchronized void update(M observable) + { + this.observable = observable; + execute(); + } + + public synchronized M getObservable() + { + return observable; + } + + public IUser getUser() + { + return user; + } + + public void send(M message) + { + subject.setObservable(message); + } +} diff --git a/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/example/StringMessage.java b/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/example/StringMessage.java new file mode 100644 index 0000000..eae6310 --- /dev/null +++ b/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/example/StringMessage.java @@ -0,0 +1,38 @@ +package io.github.astrapi69.design.pattern.observer.chat.example; + +import io.github.astrapi69.design.pattern.observer.chat.Message; + +public class StringMessage implements Message +{ + + private static final long serialVersionUID = 1L; + private String value; + + public StringMessage() + { + } + + public StringMessage(String value) + { + this.value = value; + } + + @Override + public String getValue() + { + return value; + } + + @Override + public StringMessage setValue(String value) + { + this.value = value; + return this; + } + + @Override + public String toString() + { + return "StringMessage [value=" + value + "]"; + } +} diff --git a/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/example/User.java b/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/example/User.java new file mode 100644 index 0000000..242940c --- /dev/null +++ b/observer/src/test/java/io/github/astrapi69/design/pattern/observer/chat/example/User.java @@ -0,0 +1,50 @@ +package io.github.astrapi69.design.pattern.observer.chat.example; + +import io.github.astrapi69.design.pattern.observer.chat.IUser; + +public class User implements IUser +{ + + private static final long serialVersionUID = 1L; + private String name; + private Integer id; + + public User(String name, Integer id) + { + this.name = name; + this.id = id; + } + + @Override + public User getApplicationUser() + { + return this; + } + + @Override + public void setApplicationUser(User user) + { + } + + @Override + public Integer getId() + { + return id; + } + + public void setId(Integer id) + { + this.id = id; + } + + @Override + public String getName() + { + return name; + } + + public void setName(String name) + { + this.name = name; + } +}