From f4f40c68c238328b1a1b8b6ec0a4550c0de8694a Mon Sep 17 00:00:00 2001
From: Oliver Kopp <kopp.dev@gmail.com>
Date: Thu, 3 Oct 2024 23:22:49 +0200
Subject: [PATCH] Improve doc and code comments

Co-authored-by: Christoph <siedlerkiller@gmail.com>
---
 docs/code-howtos/remote-storage-sql.md            | 15 +++++++++++++--
 .../jabref/logic/shared/PostgreSQLProcessor.java  |  1 -
 .../listener/PostgresSQLNotificationListener.java |  6 +++---
 3 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/docs/code-howtos/remote-storage-sql.md b/docs/code-howtos/remote-storage-sql.md
index 267d05129fe..cf0772ad9d9 100644
--- a/docs/code-howtos/remote-storage-sql.md
+++ b/docs/code-howtos/remote-storage-sql.md
@@ -9,14 +9,25 @@ For user documentation, see <https://docs.jabref.org/collaborative-work/sqldatab
 
 ## Handling large shared databases
 
-Synchronization times may get long when working with a large database containing several thousand entries. Therefore, synchronization only happens if several conditions are fulfilled:
+Synchronization times may get long when working with a large database containing several thousand entries.
+Therefore, we use PostgreSQL's `LISTEN` and `NOTIFY` commands to inform the client about changes in the database on an entry level.
+
+Background reading: <https://www.baeldung.com/spring-postgresql-message-broker>.
+
+## Handling synchronization of "micro-edits"
+
+It causes too much load both on the server and at all subscribed clients to synchronize every single letter change.
+Therefore, synchronization only happens if several conditions are fulfilled:
 
 * Edit to another field.
 * Major changes have been made (pasting or deleting more than one character).
 
 Class `org.jabref.logic.util.CoarseChangeFilter.java` checks both conditions.
 
-Remaining changes that have not been synchronized yet are saved at closing the database rendering additional closing time. Saving is realized in `org.jabref.logic.shared.DBMSSynchronizer.java`. Following methods account for synchronization modes:
+Remaining changes that have not been synchronized yet are saved at closing the database rendering additional closing time.
+Saving is realized in `org.jabref.logic.shared.DBMSSynchronizer.java`.
+
+Following methods account for synchronization modes:
 
 * `pullChanges` synchronizes the database unconditionally.
 * `pullLastEntryChanges` synchronizes only if there are remaining entry changes. It is invoked when closing the shared database (`closeSharedDatabase`).
diff --git a/src/main/java/org/jabref/logic/shared/PostgreSQLProcessor.java b/src/main/java/org/jabref/logic/shared/PostgreSQLProcessor.java
index 21b04d09c6a..5143dbc882a 100644
--- a/src/main/java/org/jabref/logic/shared/PostgreSQLProcessor.java
+++ b/src/main/java/org/jabref/logic/shared/PostgreSQLProcessor.java
@@ -35,7 +35,6 @@ public PostgreSQLProcessor(DatabaseConnection connection) {
      */
     @Override
     public void setUp() throws SQLException {
-
         if (CURRENT_VERSION_DB_STRUCT == 1 && checkTableAvailability("ENTRY", "FIELD", "METADATA")) {
             // checkTableAvailability does not distinguish if same table name exists in different schemas
             // VERSION_DB_STRUCT_DEFAULT must be forced
diff --git a/src/main/java/org/jabref/logic/shared/listener/PostgresSQLNotificationListener.java b/src/main/java/org/jabref/logic/shared/listener/PostgresSQLNotificationListener.java
index 96b8b7ccaf6..59ef9258874 100644
--- a/src/main/java/org/jabref/logic/shared/listener/PostgresSQLNotificationListener.java
+++ b/src/main/java/org/jabref/logic/shared/listener/PostgresSQLNotificationListener.java
@@ -30,13 +30,13 @@ public PostgresSQLNotificationListener(DBMSSynchronizer dbmsSynchronizer, PGConn
     public void run() {
         stop = false;
         try {
-            // noinspection InfiniteLoopStatement
-            while (!stop) {
-                PGNotification notifications[] = pgConnection.getNotifications();
+            while (!stop && !Thread.currentThread().isInterrupted()) {
+                PGNotification[] notifications = pgConnection.getNotifications();
 
                 if (notifications != null) {
                     for (PGNotification notification : notifications) {
                         if (!notification.getName().equals(DBMSProcessor.PROCESSOR_ID)) {
+                            // Only process notifications that are not sent by this processor
                             dbmsSynchronizer.pullChanges();
                         }
                     }