Merge pull request #148 from kuzzleio/3.0.1-proposal

Release 3.0.1

Author: stafyniaksacha

README.md

@@ -11,7 +11,6 @@ A backend software, self-hostable and ready to use to power modern apps.
 
 You can access the Kuzzle repository on [Github](https://github.com/kuzzleio/kuzzle)
 
-
 ## SDK Documentation
 
 The complete SDK documentation is available [here](http://docs.kuzzle.io/sdk-reference)
@@ -24,7 +23,7 @@ https://github.com/kuzzleio/kuzzle-sdk/issues
 
 ## Installation
 
-You can configure your android project to get the Kuzzle's android SDK from jcenter in your build.gradle:
+You can configure your Android project to get Kuzzle's Android SDK from jcenter in your build.gradle:
 
     buildscript {
         repositories {
@@ -40,6 +39,94 @@ You can configure your android project to get the Kuzzle's android SDK from jcen
         compile 'io.kuzzle:sdk-android:2.2.0'
     }
 
+## Basic usage
+
+```java
+Kuzzle kuzzle = new Kuzzle("host", new ResponseListener<Void>() {
+@Override
+public void onSuccess(Void object) {
+    // Handle success
+    KuzzleDocument doc = new KuzzleDocument(dataCollection);
+    doc.setContent("foo", "bar").save();
+}
+
+@Override
+public void onError(JSONObject error) {
+    // Handle error
+}
+});
+```
+
+## KuzzleDocument
+
+KuzzleDocument is an encapsulation of a JSONObject.
+
+```java
+KuzzleDataCollection myCollection = new KuzzleDataCollection(kuzzle, "myNewCollection");
+KuzzleDocument myDocument = new KuzzleDocument(myCollection);
+// Add properties to the body
+myDocument.setContent("foo", "bar");
+// Persist the document
+myDocument.save();
+// Send it on real time (not persistent)
+myDocument.publish();
+```
+
+## Adding metadata
+
+As stated [here](http://kuzzle.io/api-reference/#sending-metadata) you can add metadata to a subscription.
+
+```java
+KuzzleOptions options = new KuzzleOptions();
+JSONObject metadata = new JSONObject();
+metadata.put("foo", "bar");
+options.setMetadata(metadata);
+myCollection.subscribe(options);
+```
+
+# Login
+
+## Prerequisite
+
+To login using kuzzle you need at least one authentication plugin. You can refer [here](https://github.com/kuzzleio/kuzzle-plugin-auth-passport-local) for a local authentication plugin
+or [here](https://github.com/kuzzleio/kuzzle-plugin-auth-passport-oauth) to refer to our OAuth2 plugin.
+
+To know more about how to log in with a Kuzzle SDK, please refer to our [documentation](http://docs.kuzzle.io/sdk-reference/kuzzle/login/)
+
+If you have the kuzzle-plugin-auth-passport-local installed you can login using either the Kuzzle's constructor or the login method.
+
+### Login with an OAuth strategy
+
+If you have an OAUTH plugin like kuzzle-plugin-auth-passport-oauth, you may use the KuzzleWebViewClient class to handle the second authentication phase:
+
+```java
+Handler handler = new Handler();
+WebView webView = (WebView) findViewById(R.id.webView);
+webView.setWebViewClient(kuzzle.getKuzzleWebViewClient());
+kuzzle.login("github", new KuzzleResponseListener<JSONObject>() {
+      @Override
+      public void onSuccess(final JSONObject object) {
+        handler.post(new Runnable() {
+          @Override
+          public void run() {
+            try {
+              if (object.has("headers")) {
+                webView.loadUrl(object.getJSONObject("headers").getString("Location"));
+              }
+            } catch (JSONException e) {
+              e.printStackTrace();
+            }
+          }
+        });
+      }
+
+      @Override
+      public void onError(JSONObject error) {
+        Log.e("error", error.toString());
+      }
+    });
+```
+
 ## License
 
-[Apache 2](LICENSE.md)
+[Apache 2](LICENSE)

build.gradle

@@ -2,7 +2,7 @@ apply plugin: 'com.android.library'
 apply plugin: 'jacoco-android'
 apply plugin: 'com.jfrog.bintray'
 apply plugin: 'com.github.dcendents.android-maven'
-version = "3.0.0"
+version = "3.0.1"
 buildscript {
     repositories {
         jcenter()

src/main/java/io/kuzzle/sdk/core/Collection.java

@@ -176,7 +176,7 @@ public void scroll(String scrollId, final Options options, final JSONObject filt
     options.setScrollId(scrollId);
 
     try {
-      this.kuzzle.query(makeQueryArgs("document", "scroll"), request, options, new OnQueryDoneListener() {
+      this.kuzzle.query(this.kuzzle.buildQueryArgs("document", "scroll"), request, options, new OnQueryDoneListener() {
         @Override
         public void onSuccess(JSONObject object) {
           try {

src/main/java/io/kuzzle/sdk/core/Document.java

@@ -170,7 +170,7 @@ public void onError(JSONObject error) {
   /**
    * {@link #exists(Options, ResponseListener)}
    */
-  public void exists(@NonNull final ResponseListener<JSONObject> listener) {
+  public void exists(@NonNull final ResponseListener<Boolean> listener) {
     this.exists(null, listener);
   }
 
@@ -180,7 +180,7 @@ public void exists(@NonNull final ResponseListener<JSONObject> listener) {
    * @param options - Request options
    * @param listener - Response callback listener
    */
-  public void exists(final Options options, @NonNull final ResponseListener<JSONObject> listener) {
+  public void exists(final Options options, @NonNull final ResponseListener<Boolean> listener) {
     if (this.id == null) {
       throw new IllegalStateException("Document.exists: cannot check if the document exists if no id has been provided");
     }
@@ -193,8 +193,11 @@ public void exists(final Options options, @NonNull final ResponseListener<JSONOb
       this.kuzzle.query(this.dataCollection.makeQueryArgs("document", "exists"), this.serialize(), options, new OnQueryDoneListener() {
         @Override
         public void onSuccess(JSONObject object) {
-          listener.onSuccess(object);
-          ;
+          try {
+            listener.onSuccess(object.getBoolean("result"));
+          } catch (JSONException e) {
+            throw new RuntimeException(e);
+          }
         }
 
         @Override

src/main/java/io/kuzzle/sdk/core/Kuzzle.java

@@ -912,7 +912,7 @@ public void login(@NonNull final String strategy, final JSONObject credentials,
       }
 
       if (expiresIn >= 0) {
-        body.put("expiresIn", expiresIn);
+        query.put("expiresIn", expiresIn);
       }
 
       query.put("strategy", strategy);
@@ -1303,7 +1303,7 @@ public Kuzzle removeListener(Event event, EventListener listener) {
 
   /**
    * Renew all registered subscriptions. Usually called after:
-   * - a connection, if subscriptions occured before
+   * - a connection, if subscriptions occurred before
    * - a reconnection
    * - after a successful login attempt, to subscribe with the new credentials
    */
@@ -1430,7 +1430,7 @@ private void reconnect() {
    */
   protected Socket createSocket() throws URISyntaxException {
     IO.Options opt = new IO.Options();
-    opt.forceNew = true;
+    opt.forceNew = false;
     opt.reconnection = this.autoReconnect;
     opt.reconnectionDelay = this.reconnectionDelay;
     return IO.socket("http://" + host + ":" + this.port, opt);
@@ -2152,7 +2152,7 @@ public void whoAmI(@NonNull final ResponseListener<User> listener) {
         public void onSuccess(JSONObject response) {
           try {
             JSONObject result = response.getJSONObject("result");
-            listener.onSuccess(new User(Kuzzle.this, result.getString("_id"), result.getJSONObject("_source")));
+            listener.onSuccess(new User(Kuzzle.this, result.getString("_id"), result.getJSONObject("_source"), result.getJSONObject("_meta")));
           } catch (JSONException e) {
             throw new RuntimeException(e);
           }

src/main/java/io/kuzzle/sdk/enums/Scope.java

@@ -4,5 +4,6 @@ public enum Scope {
   IN,
   OUT,
   ALL,
-  NONE
+  NONE,
+  UNKNOWN
 }

src/main/java/io/kuzzle/sdk/enums/Users.java

@@ -1,8 +1,5 @@
 package io.kuzzle.sdk.enums;
 
-/**
- * Created by kblondel on 11/12/15.
- */
 public enum Users {
   IN,
   OUT,

src/main/java/io/kuzzle/sdk/responses/NotificationResponse.java

@@ -44,8 +44,12 @@ public NotificationResponse(final Kuzzle kuzzle, final JSONObject object) {
       this.scope = (object.isNull("scope") ? null : Scope.valueOf(object.getString("scope").toUpperCase()));
       this.users = (object.isNull("user") ? null : Users.valueOf(object.getString("user").toUpperCase()));
       if (!object.getJSONObject("result").isNull("_source")) {
-        this.document = new Document(new Collection(kuzzle, this.collection, this.index), object.getJSONObject("result"));
-        this.document.setId(this.result.getString("_id"));
+        JSONObject content = object.getJSONObject("result");
+        String id = content.getString("_id");
+        JSONObject meta = content.isNull("_meta") ? new JSONObject() : content.getJSONObject("_meta");
+        content.remove("_id");
+        content.remove("_meta");
+        this.document = new Document(new Collection(kuzzle, this.collection, this.index), id, content, meta);
       }
     } catch (JSONException e) {
       throw new RuntimeException(e);

src/main/java/io/kuzzle/sdk/responses/SearchResult.java

@@ -2,6 +2,7 @@
 
 import android.support.annotation.NonNull;
 
+import org.json.JSONArray;
 import org.json.JSONException;
 import org.json.JSONObject;
 
@@ -99,16 +100,19 @@ public JSONObject getFilters() {
   public void fetchNext(ResponseListener<SearchResult> listener) {
     JSONObject filters;
     Options options;
+
     try {
       options = new Options(this.options);
     } catch (JSONException e) {
       throw new RuntimeException(e);
     }
     options.setPrevious(this);
 
+    // retrieve next results with scroll if original search use it
     if (options.getScrollId() != null) {
-      if(this.fetchedDocument >= this.getTotal()) {
+      if (this.fetchedDocument >= this.getTotal()) {
         listener.onSuccess(null);
+
         return;
       }
 
@@ -125,6 +129,37 @@ public void fetchNext(ResponseListener<SearchResult> listener) {
       return;
     }
 
+    // retrieve next results using ES's search_after
+    if (options.getSize() != null && this.filters.has("sort")) {
+      if (this.fetchedDocument >= this.getTotal()) {
+        listener.onSuccess(null);
+
+        return;
+      }
+
+      if (options.getFrom() != null) {
+        options.setFrom(null);
+      }
+
+      try {
+        JSONArray searchAfter = new JSONArray();
+
+        for (int i = 0; i < this.filters.getJSONArray("sort").length(); i++) {
+          Document doc = this.getDocuments().get(this.getDocuments().size() - 1);
+          searchAfter.put(doc.getContent().get(this.filters.getJSONArray("sort").getJSONObject(i).keys().next()));
+        }
+
+        this.filters.put("search_after", searchAfter);
+      } catch (JSONException e) {
+        throw new RuntimeException(e);
+      }
+
+      this.collection.search(this.filters, options, listener);
+
+      return;
+    }
+
+    // retrieve next results with  from/size if original search use it
     if (options.getFrom() != null && options.getSize() != null) {
       try {
         filters = new JSONObject(this.filters.toString());

src/main/java/io/kuzzle/sdk/security/AbstractSecurityDocument.java

@@ -20,6 +20,7 @@ public class AbstractSecurityDocument {
   protected String  updateActionName;
   public final String id;
   public JSONObject content;
+  public JSONObject meta;
 
   /**
    * Instantiates a new Abstract kuzzle security document.
@@ -29,7 +30,7 @@ public class AbstractSecurityDocument {
    * @param content Security document content
    * @throws JSONException 
    */
-  public AbstractSecurityDocument(final Kuzzle kuzzle, @NonNull final String id, final JSONObject content) throws JSONException {
+  public AbstractSecurityDocument(final Kuzzle kuzzle, @NonNull final String id, final JSONObject content, final JSONObject meta) throws JSONException {
     if (id == null) {
       throw new IllegalArgumentException("Cannot initialize with a null ID");
     }
@@ -43,6 +44,12 @@ public AbstractSecurityDocument(final Kuzzle kuzzle, @NonNull final String id, f
     } else {
       this.content = new JSONObject();
     }
+
+    if (meta != null) {
+      setMeta(meta);
+    } else {
+      this.meta = new JSONObject();
+    }
   }
 
   /**
@@ -62,6 +69,23 @@ public AbstractSecurityDocument setContent(@NonNull final JSONObject content) th
     return this;
   }
 
+  /**
+   * Sets the metadata of this object
+   *
+   * @param meta New metadata
+   * @return this
+   * @throws JSONException
+   */
+  public AbstractSecurityDocument setMeta(@NonNull final JSONObject meta) throws JSONException {
+    if (meta == null) {
+      throw new IllegalArgumentException("AbstractSecurityDocument.setMeta: cannot set null metadata");
+    }
+
+    this.meta = new JSONObject(meta.toString());
+
+    return this;
+  }
+
   /**
    * Serializes this object to a plain-old JSON object
    *
@@ -149,6 +173,15 @@ public JSONObject getContent() {
     return this.content;
   }
 
+  /**
+   * Getter for the "meta" property
+   *
+   * @return the document metadata
+   */
+  public JSONObject getMeta() {
+    return this.meta;
+  }
+
   /**
    * {@link #update(JSONObject, Options, ResponseListener)}
    */