Annotate methods that should be called with a wake lock.

bramble-api/src/main/java/org/briarproject/bramble/api/lifecycle/LifecycleManager.java

@@ -5,6 +5,7 @@ import org.briarproject.bramble.api.db.DatabaseComponent;
 import org.briarproject.bramble.api.db.DbException;
 import org.briarproject.bramble.api.db.Transaction;
 import org.briarproject.bramble.api.nullsafety.NotNullByDefault;
+import org.briarproject.bramble.api.system.Wakeful;
 
 import java.util.concurrent.ExecutorService;
 
@@ -65,6 +66,7 @@ public interface LifecycleManager {
 	 * Opens the {@link DatabaseComponent} using the given key and starts any
 	 * registered {@link Service Services}.
 	 */
+	@Wakeful
 	StartResult startServices(SecretKey dbKey);
 
 	/**
@@ -72,6 +74,7 @@ public interface LifecycleManager {
 	 * registered {@link ExecutorService ExecutorServices}, and closes the
 	 * {@link DatabaseComponent}.
 	 */
+	@Wakeful
 	void stopServices();
 
 	/**
@@ -104,6 +107,7 @@ public interface LifecycleManager {
 		 *
 		 * @param txn A read-write transaction
 		 */
+		@Wakeful
 		void onDatabaseOpened(Transaction txn) throws DbException;
 	}
 }

bramble-api/src/main/java/org/briarproject/bramble/api/lifecycle/Service.java

@@ -1,16 +1,20 @@
 package org.briarproject.bramble.api.lifecycle;
 
+import org.briarproject.bramble.api.system.Wakeful;
+
 public interface Service {
 
 	/**
-	 * Starts the service.This method must not be called concurrently with
+	 * Starts the service. This method must not be called concurrently with
 	 * {@link #stopService()}.
 	 */
+	@Wakeful
 	void startService() throws ServiceException;
 
 	/**
 	 * Stops the service. This method must not be called concurrently with
 	 * {@link #startService()}.
 	 */
+	@Wakeful
 	void stopService() throws ServiceException;
 }

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

@@ -4,6 +4,7 @@ import org.briarproject.bramble.api.Pair;
 import org.briarproject.bramble.api.nullsafety.NotNullByDefault;
 import org.briarproject.bramble.api.properties.TransportProperties;
 import org.briarproject.bramble.api.settings.SettingsManager;
+import org.briarproject.bramble.api.system.Wakeful;
 
 import java.util.Collection;
 
@@ -70,11 +71,13 @@ public interface Plugin {
 	/**
 	 * Starts the plugin.
 	 */
+	@Wakeful
 	void start() throws PluginException;
 
 	/**
 	 * Stops the plugin.
 	 */
+	@Wakeful
 	void stop() throws PluginException;
 
 	/**
@@ -106,6 +109,7 @@ public interface Plugin {
 	 * Attempts to create connections using the given transport properties,
 	 * passing any created connections to the corresponding handlers.
 	 */
+	@Wakeful
 	void poll(Collection<Pair<TransportProperties, ConnectionHandler>>
 			properties);
 }

bramble-api/src/main/java/org/briarproject/bramble/api/plugin/duplex/DuplexPlugin.java

@@ -8,6 +8,7 @@ import org.briarproject.bramble.api.plugin.Plugin;
 import org.briarproject.bramble.api.properties.TransportProperties;
 import org.briarproject.bramble.api.rendezvous.KeyMaterialSource;
 import org.briarproject.bramble.api.rendezvous.RendezvousEndpoint;
+import org.briarproject.bramble.api.system.Wakeful;
 
 import javax.annotation.Nullable;
 
@@ -21,6 +22,7 @@ public interface DuplexPlugin extends Plugin {
 	 * Attempts to create and return a connection using the given transport
 	 * properties. Returns null if a connection cannot be created.
 	 */
+	@Wakeful
 	@Nullable
 	DuplexTransportConnection createConnection(TransportProperties p);
 

bramble-api/src/main/java/org/briarproject/bramble/api/plugin/simplex/SimplexPlugin.java

@@ -5,6 +5,7 @@ import org.briarproject.bramble.api.plugin.Plugin;
 import org.briarproject.bramble.api.plugin.TransportConnectionReader;
 import org.briarproject.bramble.api.plugin.TransportConnectionWriter;
 import org.briarproject.bramble.api.properties.TransportProperties;
+import org.briarproject.bramble.api.system.Wakeful;
 
 import javax.annotation.Nullable;
 
@@ -18,6 +19,7 @@ public interface SimplexPlugin extends Plugin {
 	 * Attempts to create and return a reader for the given transport
 	 * properties. Returns null if a reader cannot be created.
 	 */
+	@Wakeful
 	@Nullable
 	TransportConnectionReader createReader(TransportProperties p);
 
@@ -25,6 +27,7 @@ public interface SimplexPlugin extends Plugin {
 	 * Attempts to create and return a writer for the given transport
 	 * properties. Returns null if a writer cannot be created.
 	 */
+	@Wakeful
 	@Nullable
 	TransportConnectionWriter createWriter(TransportProperties p);
 }

bramble-api/src/main/java/org/briarproject/bramble/api/system/TaskScheduler.java

@@ -14,6 +14,9 @@ public interface TaskScheduler {
 
 	/**
 	 * Submits the given task to the given executor after the given delay.
+	 * <p>
+	 * If the platform supports wake locks, a wake lock will be held while
+	 * submitting and running the task.
 	 */
 	Future<?> schedule(Runnable task, Executor executor, long delay,
 			TimeUnit unit);
@@ -22,6 +25,9 @@ public interface TaskScheduler {
 	 * Submits the given task to the given executor after the given delay,
 	 * and then repeatedly with the given interval between executions
 	 * (measured from the end of one execution to the beginning of the next).
+	 * <p>
+	 * If the platform supports wake locks, a wake lock will be held while
+	 * submitting and running the task.
 	 */
 	Future<?> scheduleWithFixedDelay(Runnable task, Executor executor,
 			long delay, long interval, TimeUnit unit);

bramble-api/src/main/java/org/briarproject/bramble/api/system/Wakeful.java

@@ -0,0 +1,19 @@
+package org.briarproject.bramble.api.system;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import javax.inject.Qualifier;
+
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+/**
+ * Annotation for methods that must be called while holding a wake lock, if
+ * the platform supports wake locks.
+ */
+@Qualifier
+@Target(METHOD)
+@Retention(RUNTIME)
+public @interface Wakeful {
+}