Merge branch '581-plugin-states' into 'plugin-toggles'

Better methods for querying plugin states

See merge request briar/briar!1209

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);
 }

bramble-api/src/main/java/org/briarproject/bramble/api/plugin/Plugin.java

@@ -9,6 +9,38 @@ import java.util.Collection;
 @NotNullByDefault
 public interface Plugin {
 
+	enum State {
+
+		/**
+		 * The plugin has not been started, has been stopped, or is disabled by
+		 * settings.
+		 */
+		DISABLED,
+
+		/**
+		 * The plugin is being enabled and can't yet make or receive
+		 * connections.
+		 */
+		ENABLING,
+
+		/**
+		 * The plugin is enabled and can make or receive connections.
+		 */
+		ACTIVE,
+
+		/**
+		 * The plugin is enabled but can't make or receive connections
+		 */
+		INACTIVE
+	}
+
+	/**
+	 * Reason code returned by {@link #getReasonDisabled()} ()} to indicate
+	 * that the plugin is disabled because it has not been started or has been
+	 * stopped.
+	 */
+	int REASON_STARTING_STOPPING = 0;
+
 	/**
 	 * Returns the plugin's transport identifier.
 	 */
@@ -35,9 +67,19 @@ public interface Plugin {
 	void stop() throws PluginException;
 
 	/**
-	 * Returns true if the plugin is running.
+	 * Returns the current state of the plugin.
 	 */
-	boolean isRunning();
+	State getState();
+
+	/**
+	 * Returns an integer code indicating why the plugin is
+	 * {@link State#DISABLED disabled}, or -1 if the plugin is not disabled.
+	 * <p>
+	 * The codes used are plugin-specific, except the generic code
+	 * {@link #REASON_STARTING_STOPPING}, which may be used by
+	 * any plugin.
+	 */
+	int getReasonDisabled();
 
 	/**
 	 * Returns true if the plugin should be polled periodically to attempt to

bramble-api/src/main/java/org/briarproject/bramble/api/plugin/PluginCallback.java

@@ -1,6 +1,10 @@
 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;
 
@@ -32,12 +36,17 @@ public interface PluginCallback extends ConnectionHandler {
 	void mergeLocalProperties(TransportProperties p);
 
 	/**
-	 * Signals that the transport is enabled.
+	 * 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 transportEnabled();
-
-	/**
-	 * Signals that the transport is disabled.
-	 */
-	void transportDisabled();
+	void pluginStateChanged(State state);
 }

bramble-api/src/main/java/org/briarproject/bramble/api/plugin/TorConstants.java

@@ -23,4 +23,8 @@ public interface TorConstants {
 	int PREF_TOR_NETWORK_WITH_BRIDGES = 2;
 	int PREF_TOR_NETWORK_NEVER = 3;
 
+	int REASON_USER = 1;
+	int REASON_BATTERY = 2;
+	int REASON_MOBILE_DATA = 3;
+	int REASON_COUNTRY_BLOCKED = 4;
 }

bramble-api/src/main/java/org/briarproject/bramble/api/plugin/event/TransportActiveEvent.java

@@ -2,20 +2,22 @@ package org.briarproject.bramble.api.plugin.event;
 
 import org.briarproject.bramble.api.event.Event;
 import org.briarproject.bramble.api.nullsafety.NotNullByDefault;
+import org.briarproject.bramble.api.plugin.Plugin.State;
 import org.briarproject.bramble.api.plugin.TransportId;
 
 import javax.annotation.concurrent.Immutable;
 
 /**
- * An event that is broadcast when a transport is disabled.
+ * An event that is broadcast when a plugin enters the {@link State#ACTIVE}
+ * state.
  */
 @Immutable
 @NotNullByDefault
-public class TransportDisabledEvent extends Event {
+public class TransportActiveEvent extends Event {
 
 	private final TransportId transportId;
 
-	public TransportDisabledEvent(TransportId transportId) {
+	public TransportActiveEvent(TransportId transportId) {
 		this.transportId = transportId;
 	}
 

bramble-api/src/main/java/org/briarproject/bramble/api/plugin/event/TransportInactiveEvent.java

@@ -2,20 +2,22 @@ package org.briarproject.bramble.api.plugin.event;
 
 import org.briarproject.bramble.api.event.Event;
 import org.briarproject.bramble.api.nullsafety.NotNullByDefault;
+import org.briarproject.bramble.api.plugin.Plugin.State;
 import org.briarproject.bramble.api.plugin.TransportId;
 
 import javax.annotation.concurrent.Immutable;
 
 /**
- * An event that is broadcast when a transport is enabled.
+ * An event that is broadcast when a plugin leaves the {@link State#ACTIVE}
+ * state.
  */
 @Immutable
 @NotNullByDefault
-public class TransportEnabledEvent extends Event {
+public class TransportInactiveEvent extends Event {
 
 	private final TransportId transportId;
 
-	public TransportEnabledEvent(TransportId transportId) {
+	public TransportInactiveEvent(TransportId transportId) {
 		this.transportId = transportId;
 	}
 

bramble-api/src/main/java/org/briarproject/bramble/api/plugin/event/TransportStateEvent.java

@@ -0,0 +1,32 @@
+package org.briarproject.bramble.api.plugin.event;
+
+import org.briarproject.bramble.api.event.Event;
+import org.briarproject.bramble.api.nullsafety.NotNullByDefault;
+import org.briarproject.bramble.api.plugin.Plugin.State;
+import org.briarproject.bramble.api.plugin.TransportId;
+
+import javax.annotation.concurrent.Immutable;
+
+/**
+ * An event that is broadcast when the {@link State state} of a plugin changes.
+ */
+@Immutable
+@NotNullByDefault
+public class TransportStateEvent extends Event {
+
+	private final TransportId transportId;
+	private final State state;
+
+	public TransportStateEvent(TransportId transportId, State state) {
+		this.transportId = transportId;
+		this.state = state;
+	}
+
+	public TransportId getTransportId() {
+		return transportId;
+	}
+
+	public State getState() {
+		return state;
+	}
+}