From e6ac6913a7dc0deb523821d66bb4df217b9e7af7 Mon Sep 17 00:00:00 2001
From: akwizgran <michael@briarproject.org>
Date: Mon, 20 Jan 2020 14:48:33 +0000
Subject: [PATCH] Update javadocs for lock-safe methods.

---
 .../briarproject/bramble/api/event/EventBus.java  |  2 ++
 .../bramble/api/plugin/PluginCallback.java        | 15 ++++++++++++++-
 2 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/bramble-api/src/main/java/org/briarproject/bramble/api/event/EventBus.java b/bramble-api/src/main/java/org/briarproject/bramble/api/event/EventBus.java
index d27449833..cf57b67ed 100644
--- a/bramble-api/src/main/java/org/briarproject/bramble/api/event/EventBus.java
+++ b/bramble-api/src/main/java/org/briarproject/bramble/api/event/EventBus.java
@@ -18,6 +18,8 @@ public interface EventBus {
 	/**
 	 * Asynchronously notifies all listeners of an event. Listeners are
 	 * notified on the {@link EventExecutor}.
+	 * <p>
+	 * This method can safely be called while holding a lock.
 	 */
 	void broadcast(Event e);
 }
diff --git a/bramble-api/src/main/java/org/briarproject/bramble/api/plugin/PluginCallback.java b/bramble-api/src/main/java/org/briarproject/bramble/api/plugin/PluginCallback.java
index ed057a958..1b149cde1 100644
--- a/bramble-api/src/main/java/org/briarproject/bramble/api/plugin/PluginCallback.java
+++ b/bramble-api/src/main/java/org/briarproject/bramble/api/plugin/PluginCallback.java
@@ -2,6 +2,9 @@ package org.briarproject.bramble.api.plugin;
 
 import org.briarproject.bramble.api.nullsafety.NotNullByDefault;
 import org.briarproject.bramble.api.plugin.Plugin.State;
+import org.briarproject.bramble.api.plugin.event.TransportActiveEvent;
+import org.briarproject.bramble.api.plugin.event.TransportInactiveEvent;
+import org.briarproject.bramble.api.plugin.event.TransportStateEvent;
 import org.briarproject.bramble.api.properties.TransportProperties;
 import org.briarproject.bramble.api.settings.Settings;
 
@@ -33,7 +36,17 @@ public interface PluginCallback extends ConnectionHandler {
 	void mergeLocalProperties(TransportProperties p);
 
 	/**
-	 * Signals that the transport's state may have changed.
+	 * Informs the callback of the plugin's current state.
+	 * <p>
+	 * If the current state is different from the previous state, the callback
+	 * will broadcast a {@link TransportStateEvent}. If the current state is
+	 * {@link State#ACTIVE} and the previous state was not
+	 * {@link State#ACTIVE}, the callback will broadcast a
+	 * {@link TransportActiveEvent}. If the current state is not
+	 * {@link State#ACTIVE} and the previous state was {@link State#ACTIVE},
+	 * the callback will broadcast a {@link TransportInactiveEvent}.
+	 * <p>
+	 * This method can safely be called while holding a lock.
 	 */
 	void pluginStateChanged(State state);
 }