chore: add @Blocking and @NonBlocking annotations for better documentation

Author: ttypic

lib/src/main/java/io/ably/lib/realtime/ChannelBase.java

@@ -211,6 +211,7 @@ private void setState(ChannelState newState, ErrorInfo reason, boolean resumed,
      * Spec: RTL4d
      * @throws AblyException
      */
+    @NonBlocking
     public void attach() throws AblyException {
         attach(null);
     }
@@ -229,6 +230,7 @@ public void attach() throws AblyException {
      * This listener is invoked on a background thread.
      * @throws AblyException
      */
+    @NonBlocking
     public void attach(CompletionListener listener) throws  AblyException {
         this.attach(false, listener);
     }
@@ -334,6 +336,7 @@ private void attachImpl(final boolean forceReattach, final CompletionListener li
      * Spec: RTL5e
      * @throws AblyException
      */
+    @NonBlocking
     public void detach() throws AblyException {
         detach(null);
     }
@@ -357,6 +360,7 @@ public void markAsReleased() {
      * This listener is invoked on a background thread.
      * @throws AblyException
      */
+    @NonBlocking
     public void detach(CompletionListener listener) throws AblyException {
         clearAttachTimers();
         detachWithTimeout(listener);
@@ -776,6 +780,7 @@ public interface MessageListener {
      * <p>
      * Spec: RTL8a, RTE5
      */
+    @NonBlocking
     public synchronized void unsubscribe() {
         Log.v(TAG, "unsubscribe(); channel = " + this.name);
         listeners.clear();
@@ -804,6 +809,7 @@ protected boolean attachOnSubscribeEnabled() {
      * This listener is invoked on a background thread.
      * @throws AblyException
      */
+    @NonBlocking
     public synchronized void subscribe(MessageListener listener) throws AblyException {
         Log.v(TAG, "subscribe(); channel = " + this.name);
         listeners.add(listener);
@@ -821,6 +827,7 @@ public synchronized void subscribe(MessageListener listener) throws AblyExceptio
      * <p>
      * This listener is invoked on a background thread.
      */
+    @NonBlocking
     public synchronized void unsubscribe(MessageListener listener) {
         Log.v(TAG, "unsubscribe(); channel = " + this.name);
         listeners.remove(listener);
@@ -841,6 +848,7 @@ public synchronized void unsubscribe(MessageListener listener) {
      * This listener is invoked on a background thread.
      * @throws AblyException
      */
+    @NonBlocking
     public synchronized void subscribe(String name, MessageListener listener) throws AblyException {
         Log.v(TAG, "subscribe(); channel = " + this.name + "; event = " + name);
         subscribeImpl(name, listener);
@@ -859,6 +867,7 @@ public synchronized void subscribe(String name, MessageListener listener) throws
      * <p>
      * This listener is invoked on a background thread.
      */
+    @NonBlocking
     public synchronized void unsubscribe(String name, MessageListener listener) {
         Log.v(TAG, "unsubscribe(); channel = " + this.name + "; event = " + name);
         unsubscribeImpl(name, listener);
@@ -876,6 +885,7 @@ public synchronized void unsubscribe(String name, MessageListener listener) {
      * This listener is invoked on a background thread.
      * @throws AblyException
      */
+    @NonBlocking
     public synchronized void subscribe(String[] names, MessageListener listener) throws AblyException {
         Log.v(TAG, "subscribe(); channel = " + this.name + "; (multiple events)");
         for(String name : names)
@@ -894,6 +904,7 @@ public synchronized void subscribe(String[] names, MessageListener listener) thr
      * <p>
      * This listener is invoked on a background thread.
      */
+    @NonBlocking
     public synchronized void unsubscribe(String[] names, MessageListener listener) {
         Log.v(TAG, "unsubscribe(); channel = " + this.name + "; (multiple events)");
         for(String name : names)
@@ -1546,6 +1557,7 @@ public void getMessageVersionsAsync(String serial, Param[] params, Callback<Asyn
      * @return A {@link PaginatedResult} object containing an array of {@link Message} objects.
      * @throws AblyException
      */
+    @Blocking
     public PaginatedResult<Message> history(Param[] params) throws AblyException {
         return historyImpl(ably.http, params).sync();
     }
@@ -1579,6 +1591,7 @@ PaginatedResult<Message> history(Http http, Param[] params) throws AblyException
      * @param callback Callback with {@link AsyncPaginatedResult} object containing an array of {@link Message} objects.
      * @throws AblyException
      */
+    @NonBlocking
     public void historyAsync(Param[] params, Callback<AsyncPaginatedResult<Message>> callback) {
         historyAsync(ably.http, params, callback);
     }
@@ -1609,6 +1622,7 @@ private BasePaginatedQuery.ResultRequest<Message> historyImpl(Http http, Param[]
      * @param options A {@link ChannelOptions} object.
      * @throws AblyException
      */
+    @NonBlocking
     public void setOptions(ChannelOptions options) throws AblyException {
         this.setOptions(options, null);
     }
@@ -1621,6 +1635,7 @@ public void setOptions(ChannelOptions options) throws AblyException {
      * @param listener An optional listener may be provided to notify of the success or failure of the operation.
      * @throws AblyException
      */
+    @NonBlocking
     public void setOptions(ChannelOptions options, CompletionListener listener) throws AblyException {
         this.options = options;
         this.messageEditsMixin = new MessageEditsMixin(basePath, ably.options, options, ably.auth);

lib/src/main/java/io/ably/lib/rest/Auth.java

@@ -29,6 +29,8 @@
 import io.ably.lib.util.Base64Coder;
 import io.ably.lib.util.Log;
 import io.ably.lib.util.Serialisation;
+import org.jetbrains.annotations.Blocking;
+import org.jetbrains.annotations.NonBlocking;
 
 /**
  * Token-generation and authentication operations for the Ably API.
@@ -663,6 +665,7 @@ public interface TokenCallback {
      * @return A {@link TokenDetails} object.
      * @throws AblyException
      */
+    @Blocking
     public TokenDetails authorize(TokenParams params, AuthOptions options) throws AblyException {
         /* Spec: RSA10g */
         if (options != null)
@@ -700,6 +703,7 @@ public TokenDetails authorize(TokenParams params, AuthOptions options) throws Ab
      * Alias of authorize() (0.9 RSA10l)
      */
     @Deprecated
+    @Blocking
     public TokenDetails authorise(TokenParams params, AuthOptions options) throws AblyException {
         Log.w(TAG, "authorise() is deprecated and will be removed in 1.0. Please use authorize() instead");
         return authorize(params, options);
@@ -722,6 +726,7 @@ public TokenDetails authorise(TokenParams params, AuthOptions options) throws Ab
      * @return A {@link TokenDetails} object.
      * @throws AblyException
      */
+    @Blocking
     public TokenDetails requestToken(TokenParams params, AuthOptions tokenOptions) throws AblyException {
         /* Spec: RSA8e */
         tokenOptions = (tokenOptions == null) ? this.authOptions : tokenOptions.copy();
@@ -885,6 +890,7 @@ public TokenDetails handleResponse(HttpCore.Response response, ErrorInfo error)
      * @return A {@link TokenRequest} object.
      * @throws AblyException
      */
+    @Blocking
     public TokenRequest createTokenRequest(TokenParams params, AuthOptions options) throws AblyException {
         /* Spec: RSA9h */
         options = (options == null) ? this.authOptions : options.copy();
@@ -1010,6 +1016,7 @@ public AuthOptions getAuthOptions() {
      * Please use {@link Auth#renewAuth} instead
      */
     @Deprecated
+    @NonBlocking
     public TokenDetails renew() throws AblyException {
         TokenDetails tokenDetails = assertValidToken(this.tokenParams, this.authOptions, true);
         ably.onAuthUpdated(tokenDetails.token, false);
@@ -1024,6 +1031,7 @@ public TokenDetails renew() throws AblyException {
      * Please note that completion callback  {@link RenewAuthResult#onCompletion(boolean, TokenDetails, ErrorInfo)}
      *              is called on a background thread.
      */
+    @NonBlocking
     public void renewAuth(RenewAuthResult result) throws AblyException {
         final TokenDetails tokenDetails = assertValidToken(this.tokenParams, this.authOptions, true);
 

lib/src/main/java/io/ably/lib/rest/ChannelBase.java

@@ -103,6 +103,7 @@ PublishResult publishWithResult(Http http, String name, Object data) throws Ably
      * @deprecated Use {@link #publishAsync(String, Object, Callback)} instead.
      */
     @Deprecated
+    @NonBlocking
     public void publishAsync(String name, Object data, CompletionListener listener) {
         publishAsync(ably.http, name, data, listener);
     }
@@ -247,6 +248,7 @@ public void execute(HttpScheduler http, final Callback<PublishResult> callback)
      * @return an array of Messages for this Channel.
      * @throws AblyException
      */
+    @Blocking
     public PaginatedResult<Message> history(Param[] params) throws AblyException {
         return history(ably.http, params);
     }
@@ -261,6 +263,7 @@ PaginatedResult<Message> history(Http http, Param[] params) throws AblyException
      * @param callback
      * @return
      */
+    @NonBlocking
     public void historyAsync(Param[] params, Callback<AsyncPaginatedResult<Message>> callback) {
         historyAsync(ably.http, params, callback);
     }
@@ -296,6 +299,7 @@ public class Presence {
          * @return A {@link PaginatedResult} object containing an array of {@link PresenceMessage} objects.
          * @throws AblyException
          */
+        @Blocking
         public PaginatedResult<PresenceMessage> get(Param[] params) throws AblyException {
             return get(ably.http, params);
         }
@@ -321,10 +325,12 @@ PaginatedResult<PresenceMessage> get(Http http, Param[] params) throws AblyExcep
          * <p>
          * This callback is invoked on a background thread.
          */
+        @NonBlocking
         public void getAsync(Param[] params, Callback<AsyncPaginatedResult<PresenceMessage>> callback) {
             getAsync(ably.http, params, callback);
         }
 
+        @NonBlocking
         void getAsync(Http http, Param[] params, Callback<AsyncPaginatedResult<PresenceMessage>> callback) {
             getImpl(http, params).async(callback);
         }
@@ -356,6 +362,7 @@ private BasePaginatedQuery.ResultRequest<PresenceMessage> getImpl(Http http, Par
          * @return A {@link PaginatedResult} object containing an array of {@link PresenceMessage} objects.
          * @throws AblyException
          */
+        @Blocking
         public PaginatedResult<PresenceMessage> history(Param[] params) throws AblyException {
             return history(ably.http, params);
         }
@@ -387,6 +394,7 @@ PaginatedResult<PresenceMessage> history(Http http, Param[] params) throws AblyE
          * This callback is invoked on a background thread.
          * @throws AblyException
          */
+        @NonBlocking
         public void historyAsync(Param[] params, Callback<AsyncPaginatedResult<PresenceMessage>> callback) {
             historyAsync(ably.http, params, callback);
         }