Nullity inference and documentation update

Also, it seems that "Transport" isn't a legal name for an inner enum

Author: forresthopkinsa

README.md

@@ -77,7 +77,7 @@ class SocketController {
 }
 ```
 
-Check out the [full example server](https://github.com/NaikSoftware/stomp-protocol-example-server)
+Check out the [upstream example server](https://github.com/NaikSoftware/stomp-protocol-example-server)
 
 ## Example library usage
 
@@ -91,7 +91,7 @@ Check out the [full example server](https://github.com/NaikSoftware/stomp-protoc
 
  // ...
 
- StompClient client = Stomp.over(WebSocket.class, "http://localhost/example-endpoint");
+ StompClient client = Stomp.over(Stomp.ConnectionProvider.OKHTTP, "http://localhost/example-endpoint");
  client.connect();
 
  client.topic("/topic/greetings").subscribe(message -> {
@@ -110,13 +110,13 @@ Check out the [full example server](https://github.com/NaikSoftware/stomp-protoc
 
 ```
 
-See the [full example](https://github.com/NaikSoftware/StompProtocolAndroid/tree/master/example-client)
+See the [upstream example](https://github.com/NaikSoftware/StompProtocolAndroid/tree/master/example-client)
 
-Method `Stomp.over` consume class for create connection as first parameter.
-You must provide dependency for lib and pass class.
-At now supported connection providers:
-- `org.java_websocket.WebSocket.class` ('org.java-websocket:Java-WebSocket:1.3.2')
-- `okhttp3.WebSocket.class` ('com.squareup.okhttp3:okhttp:3.8.1')
+Method `Stomp.over` uses an enum to know what connection provider to use.
+
+Currently supported connection providers:
+- `Stomp.ConnectionProvider.JWS` ('org.java-websocket:Java-WebSocket:1.3.2')
+- `Stomp.ConnectionProvider.OKHTTP` ('com.squareup.okhttp3:okhttp:3.8.1')
 
 You can add own connection provider. Just implement interface `ConnectionProvider`.
 If you implement new provider, please create pull request :)
@@ -143,7 +143,7 @@ client.lifecycle().subscribe(lifecycleEvent -> {
 You can use a custom OkHttpClient (for example, [if you want to allow untrusted HTTPS](https://gist.github.com/grow2014/b6969d8f0cfc0f0a1b2bf12f84973dec)) using the four-argument overload of Stomp.over, like so:
 
 ``` java
-client = Stomp.over(WebSocket.class, address, null, getUnsafeOkHttpClient());
+client = Stomp.over(Stomp.ConnectionProvider.OKHTTP, address, null, getUnsafeOkHttpClient());
 ```
 
 Yes, it's safe to pass `null` for either (or both) of the last two arguments. That's exactly what the shorter overloads do.
@@ -222,6 +222,9 @@ These are the possible changes you need to make to your code for this branch, if
 - Passing null as the topic path now throws an exception
   - Previously, it was supposed to silently fail, although it would probably hit a NPE first (untested)
   - Now it throws an IllegalArgumentException
+- Connection Provider is selected by an enum
+  - It used to be done by passing it a WebSocket class from either JWS or OkHttp
+  - New way of using it can be seen in the examples above
 
 ## Additional Reading
 

lib/src/main/java/ua/naiksoftware/stomp/AbstractConnectionProvider.java

@@ -1,5 +1,7 @@
 package ua.naiksoftware.stomp;
 
+import android.support.annotation.NonNull;
+import android.support.annotation.Nullable;
 import android.util.Log;
 
 import rx.Completable;
@@ -16,14 +18,17 @@ abstract class AbstractConnectionProvider implements ConnectionProvider {
 
     private static final String TAG = AbstractConnectionProvider.class.getSimpleName();
 
+    @NonNull
     private final PublishSubject<LifecycleEvent> mLifecycleStream;
+    @NonNull
     private final PublishSubject<String> mMessagesStream;
 
     AbstractConnectionProvider() {
         mLifecycleStream = PublishSubject.create();
         mMessagesStream = PublishSubject.create();
     }
 
+    @NonNull
     @Override
     public Observable<String> messages() {
         createWebSocketConnection();
@@ -48,6 +53,7 @@ public Observable<String> messages() {
      */
     abstract void createWebSocketConnection();
 
+    @NonNull
     @Override
     public Completable send(String stompMessage) {
         return Completable.fromCallable(() -> {
@@ -82,9 +88,10 @@ public Completable send(String stompMessage) {
      * return webSocket;
      * </pre>
      */
+    @Nullable
     abstract Object getSocket();
 
-    void emitLifecycleEvent(LifecycleEvent lifecycleEvent) {
+    void emitLifecycleEvent(@NonNull LifecycleEvent lifecycleEvent) {
         Log.d(TAG, "Emit lifecycle event: " + lifecycleEvent.getType().name());
         mLifecycleStream.onNext(lifecycleEvent);
     }
@@ -94,6 +101,7 @@ void emitMessage(String stompMessage) {
         mMessagesStream.onNext(stompMessage);
     }
 
+    @NonNull
     @Override
     public Observable<LifecycleEvent> getLifecycleReceiver() {
         return mLifecycleStream;

lib/src/main/java/ua/naiksoftware/stomp/OkHttpConnectionProvider.java

@@ -1,5 +1,8 @@
 package ua.naiksoftware.stomp;
 
+import android.support.annotation.NonNull;
+import android.support.annotation.Nullable;
+
 import java.util.HashMap;
 import java.util.Map;
 import java.util.TreeMap;
@@ -16,18 +19,21 @@
 class OkHttpConnectionProvider extends AbstractConnectionProvider {
 
     private final String mUri;
+    @NonNull
     private final Map<String, String> mConnectHttpHeaders;
     private final OkHttpClient mOkHttpClient;
 
+    @Nullable
     private WebSocket openedSocked;
 
-    OkHttpConnectionProvider(String uri, Map<String, String> connectHttpHeaders, OkHttpClient okHttpClient) {
+    OkHttpConnectionProvider(String uri, @Nullable Map<String, String> connectHttpHeaders, OkHttpClient okHttpClient) {
         super();
         mUri = uri;
         mConnectHttpHeaders = connectHttpHeaders != null ? connectHttpHeaders : new HashMap<>();
         mOkHttpClient = okHttpClient;
     }
 
+    @NonNull
     @Override
     public Completable disconnect() {
         return Completable.fromAction(() -> openedSocked.close(1000, ""));
@@ -48,7 +54,7 @@ void createWebSocketConnection() {
         openedSocked = mOkHttpClient.newWebSocket(requestBuilder.build(),
                 new WebSocketListener() {
                     @Override
-                    public void onOpen(WebSocket webSocket, Response response) {
+                    public void onOpen(WebSocket webSocket, @NonNull Response response) {
                         LifecycleEvent openEvent = new LifecycleEvent(LifecycleEvent.Type.OPENED);
 
                         TreeMap<String, String> headersAsMap = headersAsMap(response);
@@ -63,7 +69,7 @@ public void onMessage(WebSocket webSocket, String text) {
                     }
 
                     @Override
-                    public void onMessage(WebSocket webSocket, ByteString bytes) {
+                    public void onMessage(WebSocket webSocket, @NonNull ByteString bytes) {
                         emitMessage(bytes.utf8());
                     }
 
@@ -87,12 +93,14 @@ void bareSend(String stompMessage) {
         openedSocked.send(stompMessage);
     }
 
+    @Nullable
     @Override
     Object getSocket() {
         return openedSocked;
     }
 
-    private TreeMap<String, String> headersAsMap(Response response) {
+    @NonNull
+    private TreeMap<String, String> headersAsMap(@NonNull Response response) {
         TreeMap<String, String> headersAsMap = new TreeMap<>();
         Headers headers = response.headers();
         for (String key : headers.names()) {
@@ -101,7 +109,7 @@ private TreeMap<String, String> headersAsMap(Response response) {
         return headersAsMap;
     }
 
-    private void addConnectionHeadersToBuilder(Request.Builder requestBuilder, Map<String, String> mConnectHttpHeaders) {
+    private void addConnectionHeadersToBuilder(@NonNull Request.Builder requestBuilder, @NonNull Map<String, String> mConnectHttpHeaders) {
         for (Map.Entry<String, String> headerEntry : mConnectHttpHeaders.entrySet()) {
             requestBuilder.addHeader(headerEntry.getKey(), headerEntry.getValue());
         }

lib/src/main/java/ua/naiksoftware/stomp/Stomp.java

@@ -1,5 +1,6 @@
 package ua.naiksoftware.stomp;
 
+import android.support.annotation.NonNull;
 import android.support.annotation.Nullable;
 
 import java.util.Map;
@@ -19,19 +20,19 @@
  */
 public class Stomp {
 
-    public static StompClient over(Transport transport, String uri) {
-        return over(transport, uri, null, null);
+    public static StompClient over(@NonNull ConnectionProvider connectionProvider, String uri) {
+        return over(connectionProvider, uri, null, null);
     }
 
     /**
      *
-     * @param transport transport method
+     * @param connectionProvider connectionProvider method
      * @param uri URI to connect
      * @param connectHttpHeaders HTTP headers, will be passed with handshake query, may be null
      * @return StompClient for receiving and sending messages. Call #StompClient.connect
      */
-    public static StompClient over(Transport transport, String uri, Map<String, String> connectHttpHeaders) {
-        return over(transport, uri, connectHttpHeaders, null);
+    public static StompClient over(@NonNull ConnectionProvider connectionProvider, String uri, Map<String, String> connectHttpHeaders) {
+        return over(connectionProvider, uri, connectHttpHeaders, null);
     }
 
     /**
@@ -40,32 +41,32 @@ public static StompClient over(Transport transport, String uri, Map<String, Stri
      *     <li>{@code org.java_websocket.WebSocket}: cannot accept an existing client</li>
      *     <li>{@code okhttp3.WebSocket}: can accept a non-null instance of {@code okhttp3.OkHttpClient}</li>
      * </ul>
-     * @param transport transport method
+     * @param connectionProvider connectionProvider method
      * @param uri URI to connect
      * @param connectHttpHeaders HTTP headers, will be passed with handshake query, may be null
      * @param okHttpClient Existing client that will be used to open the WebSocket connection, may be null to use default client
      * @return StompClient for receiving and sending messages. Call #StompClient.connect
      */
-    public static StompClient over(Transport transport, String uri, @Nullable Map<String, String> connectHttpHeaders, @Nullable OkHttpClient okHttpClient) {
-        if (transport == Transport.JWS) {
+    public static StompClient over(@NonNull ConnectionProvider connectionProvider, String uri, @Nullable Map<String, String> connectHttpHeaders, @Nullable OkHttpClient okHttpClient) {
+        if (connectionProvider == ConnectionProvider.JWS) {
             if (okHttpClient != null) {
                 throw new IllegalArgumentException("You cannot pass a webSocketClient with 'org.java_websocket.WebSocket'. use null instead.");
             }
             return createStompClient(new WebSocketsConnectionProvider(uri, connectHttpHeaders));
         }
 
-        if (transport == Transport.OKHTTP) {
+        if (connectionProvider == ConnectionProvider.OKHTTP) {
             return createStompClient(new OkHttpConnectionProvider(uri, connectHttpHeaders, (okHttpClient == null) ? new OkHttpClient() : okHttpClient));
         }
 
-        throw new IllegalArgumentException("Transport type not supported: " + transport.toString());
+        throw new IllegalArgumentException("ConnectionProvider type not supported: " + connectionProvider.toString());
     }
 
-    private static StompClient createStompClient(ConnectionProvider connectionProvider) {
+    private static StompClient createStompClient(ua.naiksoftware.stomp.ConnectionProvider connectionProvider) {
         return new StompClient(connectionProvider);
     }
 
-    public enum Transport {
+    public enum ConnectionProvider {
         OKHTTP, JWS
     }
 }

lib/src/main/java/ua/naiksoftware/stomp/WebSocketsConnectionProvider.java

@@ -1,5 +1,7 @@
 package ua.naiksoftware.stomp;
 
+import android.support.annotation.NonNull;
+import android.support.annotation.Nullable;
 import android.util.Log;
 
 import org.java_websocket.WebSocket;
@@ -29,6 +31,7 @@ class WebSocketsConnectionProvider extends AbstractConnectionProvider {
     private static final String TAG = WebSocketsConnectionProvider.class.getSimpleName();
 
     private final String mUri;
+    @NonNull
     private final Map<String, String> mConnectHttpHeaders;
 
     private WebSocketClient mWebSocketClient;
@@ -39,11 +42,12 @@ class WebSocketsConnectionProvider extends AbstractConnectionProvider {
      * Support UIR scheme ws://host:port/path
      * @param connectHttpHeaders may be null
      */
-    WebSocketsConnectionProvider(String uri, Map<String, String> connectHttpHeaders) {
+    WebSocketsConnectionProvider(String uri, @Nullable Map<String, String> connectHttpHeaders) {
         mUri = uri;
         mConnectHttpHeaders = connectHttpHeaders != null ? connectHttpHeaders : new HashMap<>();
     }
 
+    @NonNull
     @Override
     public Completable disconnect() {
         return Completable.fromAction(() -> mWebSocketClient.close());
@@ -57,7 +61,7 @@ void createWebSocketConnection() {
         mWebSocketClient = new WebSocketClient(URI.create(mUri), new Draft_17(), mConnectHttpHeaders, 0) {
 
             @Override
-            public void onWebsocketHandshakeReceivedAsClient(WebSocket conn, ClientHandshake request, ServerHandshake response) throws InvalidDataException {
+            public void onWebsocketHandshakeReceivedAsClient(WebSocket conn, ClientHandshake request, @NonNull ServerHandshake response) throws InvalidDataException {
                 Log.d(TAG, "onWebsocketHandshakeReceivedAsClient with response: " + response.getHttpStatus() + " " + response.getHttpStatusMessage());
                 mServerHandshakeHeaders = new TreeMap<>();
                 Iterator<String> keys = response.iterateHttpFields();
@@ -68,7 +72,7 @@ public void onWebsocketHandshakeReceivedAsClient(WebSocket conn, ClientHandshake
             }
 
             @Override
-            public void onOpen(ServerHandshake handshakeData) {
+            public void onOpen(@NonNull ServerHandshake handshakeData) {
                 Log.d(TAG, "onOpen with handshakeData: " + handshakeData.getHttpStatus() + " " + handshakeData.getHttpStatusMessage());
                 LifecycleEvent openEvent = new LifecycleEvent(LifecycleEvent.Type.OPENED);
                 openEvent.setHandshakeResponseHeaders(mServerHandshakeHeaders);

lib/src/main/java/ua/naiksoftware/stomp/client/StompClient.java

@@ -1,5 +1,7 @@
 package ua.naiksoftware.stomp.client;
 
+import android.support.annotation.NonNull;
+import android.support.annotation.Nullable;
 import android.util.Log;
 
 import java.util.ArrayList;
@@ -70,7 +72,7 @@ public void connect(List<StompHeader> _headers) {
      *
      * @param _headers might be null
      */
-    public void connect(List<StompHeader> _headers, boolean reconnect) {
+    public void connect(@Nullable List<StompHeader> _headers, boolean reconnect) {
         if (reconnect) disconnect();
         if (mConnected) return;
         lifecycle()
@@ -119,7 +121,7 @@ public Completable send(String destination, String data) {
                 data));
     }
 
-    public Completable send(StompMessage stompMessage) {
+    public Completable send(@NonNull StompMessage stompMessage) {
         Completable completable = mConnectionProvider.send(stompMessage.compile());
         mConnectionComplete.subscribe();
         return completable.startWith(mConnectionComplete);
@@ -141,7 +143,7 @@ public Observable<StompMessage> topic(String destinationPath) {
         return topic(destinationPath, null);
     }
 
-    public Observable<StompMessage> topic(String destPath, List<StompHeader> headerList) {
+    public Observable<StompMessage> topic(@Nullable String destPath, List<StompHeader> headerList) {
         if (destPath == null)
             return Observable.error(new IllegalArgumentException("Topic path cannot be null"));
         else if (!mStreamMap.containsKey(destPath))
@@ -155,7 +157,7 @@ else if (!mStreamMap.containsKey(destPath))
         return mStreamMap.get(destPath);
     }
 
-    private Completable subscribePath(String destinationPath, List<StompHeader> headerList) {
+    private Completable subscribePath(String destinationPath, @Nullable List<StompHeader> headerList) {
         String topicId = UUID.randomUUID().toString();
 
         if (mTopics == null) mTopics = new HashMap<>();

lib/src/main/java/ua/naiksoftware/stomp/client/StompMessage.java

@@ -1,5 +1,8 @@
 package ua.naiksoftware.stomp.client;
 
+import android.support.annotation.NonNull;
+import android.support.annotation.Nullable;
+
 import java.io.StringReader;
 import java.util.ArrayList;
 import java.util.List;
@@ -40,6 +43,7 @@ public String getStompCommand() {
         return mStompCommand;
     }
 
+    @Nullable
     public String findHeader(String key) {
         if (mStompHeaders == null) return null;
         for (StompHeader header : mStompHeaders) {
@@ -48,6 +52,7 @@ public String findHeader(String key) {
         return null;
     }
 
+    @NonNull
     public String compile() {
         StringBuilder builder = new StringBuilder();
         builder.append(mStompCommand).append('\n');
@@ -62,7 +67,7 @@ public String compile() {
         return builder.toString();
     }
 
-    public static StompMessage from(String data) {
+    public static StompMessage from(@Nullable String data) {
         if (data == null || data.trim().isEmpty()) {
             return new StompMessage(StompCommand.UNKNOWN, null, data);
         }