Support SearchItems endpoint

Author: OndraFiedler

README.md

@@ -13,7 +13,7 @@ The client is available in the [Maven Central Repository](https://mvnrepository.
     <dependency>
         <groupId>com.recombee</groupId>
         <artifactId>api-client</artifactId>
-        <version>2.4.2</version>
+        <version>3.0.0</version>
     </dependency>
 ```
 
@@ -81,6 +81,7 @@ import com.recombee.api_client.RecombeeClient;
 import com.recombee.api_client.api_requests.*;
 import com.recombee.api_client.bindings.RecommendationResponse;
 import com.recombee.api_client.bindings.Recommendation;
+import com.recombee.api_client.bindings.SearchResponse;
 import com.recombee.api_client.exceptions.ApiException;
 
 import java.util.ArrayList;
@@ -93,7 +94,7 @@ public class ItemPropertiesExample {
         RecombeeClient client = new RecombeeClient("--my-database-id--", "--db-private-token--");
 
         try {
-            client.send(new ResetDatabase()); //Clear everything from the database
+            client.send(new ResetDatabase()); // Clear everything from the database
 
             /*
             We will use computers as items in this example
@@ -146,13 +147,9 @@ public class ItemPropertiesExample {
 
 
             // Get 5 recommendations for user-42, who is currently viewing computer-6
-            RecommendationResponse recommendationResponse = client.send(new RecommendItemsToItem("computer-6", "user-42", 5));
-            System.out.println("Recommended items:");
-            for(Recommendation rec: recommendationResponse) System.out.println(rec.getId());
-
-
             // Recommend only computers that have at least 3 cores
-            recommendationResponse = client.send(new RecommendItemsToItem("computer-6", "user-42", 5)
+            RecommendationResponse recommendationResponse = client.send(
+                new RecommendItemsToItem("computer-6", "user-42", 5)
                     .setFilter(" 'num-cores'>=3 "));
             System.out.println("Recommended items with at least 3 processor cores:");
             for(Recommendation rec: recommendationResponse) System.out.println(rec.getId());
@@ -164,6 +161,20 @@ public class ItemPropertiesExample {
             System.out.println("Recommended up-sell items:");
             for(Recommendation rec: recommendationResponse) System.out.println(rec.getId());
 
+
+            // Filters, boosters and other settings can be set also in the Admin UI (admin.recombee.com)
+            // when scenario is specified
+            recommendationResponse = client.send(
+                new RecommendItemsToItem("computer-6", "user-42", 5).setScenario("product_detail")
+            );
+
+            // Perform personalized full-text search with a user's search query (e.g. "computers")
+            SearchResponse searchResponse = client.send(
+              new SearchItems("user-42", "computers", 5)
+              );
+            System.out.println("Search matches:");
+            for(Recommendation rec: searchResponse) System.out.println(rec.getId());
+
         } catch (ApiException e) {
             e.printStackTrace();
             //Use fallback

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>com.recombee</groupId>
     <artifactId>api-client</artifactId>
-    <version>2.4.2</version>
+    <version>3.0.0</version>
     <name>Recombee API Client</name>
     <description>A client library for easy use of the Recombee recommendation API</description>
     <url>http://recombee.com</url>

src/examples/java/com/recombee/api_client/examples/ItemPropertiesExample.java

@@ -1,9 +1,8 @@
-package com.recombee.api_client.examples;
-
 import com.recombee.api_client.RecombeeClient;
 import com.recombee.api_client.api_requests.*;
 import com.recombee.api_client.bindings.RecommendationResponse;
 import com.recombee.api_client.bindings.Recommendation;
+import com.recombee.api_client.bindings.SearchResponse;
 import com.recombee.api_client.exceptions.ApiException;
 
 import java.util.ArrayList;
@@ -13,22 +12,24 @@
 public class ItemPropertiesExample {
     public static void main(String[] args) {
 
-        RecombeeClient client = new RecombeeClient("--my-database-id--", "--my-secret-token--");
+        RecombeeClient client = new RecombeeClient("--my-database-id--", "--db-private-token--");
 
         try {
             client.send(new ResetDatabase()); //Clear everything from the database
 
             /*
             We will use computers as items in this example
-            Computers have three properties
+            Computers have four properties
               - price (floating point number)
               - number of processor cores (integer number)
               - description (string)
+              - image (url of computer's photo)
             */
 
             client.send(new AddItemProperty("price", "double"));
             client.send(new AddItemProperty("num-cores", "int"));
             client.send(new AddItemProperty("description", "string"));
+            client.send(new AddItemProperty("image", "image"));
 
             // Prepare requests for setting a catalog of computers
             final ArrayList<Request> requests = new ArrayList<Request>();
@@ -37,13 +38,15 @@ public static void main(String[] args) {
 
             for(int i=0; i<NUM; i++)
             {
+                final String itemId = String.format("computer-%s",i);
                 final SetItemValues req = new SetItemValues(
-                        String.format("computer-%s",i), //itemId
+                        itemId,
                         //values:
                         new HashMap<String, Object>() {{
                             put("price", 600.0 + 400*rand.nextDouble());
                             put("num-cores", 1 + rand.nextInt(7));
                             put("description", "Great computer");
+                            put("image", String.format("http://examplesite.com/products/%s.jpg", itemId));
                         }}
                 ).setCascadeCreate(true);  // Use cascadeCreate for creating item
                 // with given itemId, if it doesn't exist;
@@ -65,14 +68,10 @@ public static void main(String[] args) {
 
 
             // Get 5 recommendations for user-42, who is currently viewing computer-6
-            RecommendationResponse recommendationResponse = client.send(new RecommendItemsToItem("computer-6", "user-42", 5));
-            System.out.println("Recommended items:");
-            for(Recommendation rec: recommendationResponse) System.out.println(rec.getId());
-
-
             // Recommend only computers that have at least 3 cores
-            recommendationResponse = client.send(new RecommendItemsToItem("computer-6", "user-42", 5)
-                    .setFilter(" 'num-cores'>=3 "));
+            RecommendationResponse recommendationResponse = client.send(
+                    new RecommendItemsToItem("computer-6", "user-42", 5)
+                            .setFilter(" 'num-cores'>=3 "));
             System.out.println("Recommended items with at least 3 processor cores:");
             for(Recommendation rec: recommendationResponse) System.out.println(rec.getId());
 
@@ -83,9 +82,23 @@ public static void main(String[] args) {
             System.out.println("Recommended up-sell items:");
             for(Recommendation rec: recommendationResponse) System.out.println(rec.getId());
 
+
+            // Filters, boosters and other settings can be set also in the Admin UI (admin.recombee.com)
+            // when scenario is specified
+            recommendationResponse = client.send(
+                    new RecommendItemsToItem("computer-6", "user-42", 5).setScenario("product_detail")
+            );
+
+            // Perform personalized full-text search with a user's search query (e.g. "computers")
+            SearchResponse searchResponse = client.send(
+                    new SearchItems("user-42", "computers", 5)
+            );
+            System.out.println("Search matches:");
+            for(Recommendation rec: searchResponse) System.out.println(rec.getId());
+
         } catch (ApiException e) {
             e.printStackTrace();
             //Use fallback
         }
     }
-}
+}

src/main/java/com/recombee/api_client/RecombeeClient.java

@@ -67,6 +67,7 @@
 import com.recombee.api_client.api_requests.RecommendUsersToUser;
 import com.recombee.api_client.api_requests.RecommendItemsToItem;
 import com.recombee.api_client.api_requests.RecommendUsersToItem;
+import com.recombee.api_client.api_requests.SearchItems;
 import com.recombee.api_client.api_requests.UserBasedRecommendation;
 import com.recombee.api_client.api_requests.ItemBasedRecommendation;
 
@@ -85,7 +86,7 @@ public class RecombeeClient {
 
     final int BATCH_MAX_SIZE = 10000; //Maximal number of requests within one batch request
 
-    final String USER_AGENT = "recombee-java-api-client/2.4.2";
+    final String USER_AGENT = "recombee-java-api-client/3.0.0";
 
     private final OkHttpClient httpClient = new OkHttpClient();
 
@@ -104,8 +105,14 @@ public NetworkApplicationProtocol getDefaultProtocol() {
         return defaultProtocol;
     }
 
-    public void setDefaultProtocol(NetworkApplicationProtocol defaultProtocol) {
+    public RecombeeClient setDefaultProtocol(NetworkApplicationProtocol defaultProtocol) {
         this.defaultProtocol = defaultProtocol;
+        return this;
+    }
+    public RecombeeClient setBaseUri(String baseUri)
+    {
+        this.baseUri = baseUri;
+        return this;
     }
     /* Start of the generated code */
     public PropertyInfo send(GetItemPropertyInfo request) throws ApiException {
@@ -348,6 +355,16 @@ public RecommendationResponse send(RecommendUsersToItem request) throws ApiExcep
          return null;
     }
 
+    public SearchResponse send(SearchItems request) throws ApiException {
+        String responseStr = sendRequest(request);
+        try {
+            return this.mapper.readValue(responseStr, SearchResponse.class);
+        } catch (IOException e) {
+            e.printStackTrace();
+         }
+         return null;
+    }
+
     /* End of the generated code */
 
     public BatchResponse[] send(Batch batchRequest) throws ApiException {
@@ -439,6 +456,10 @@ else if ((request instanceof RecommendItemsToUser) ||
                     {
                         parsedResponse = mapper.convertValue(parsedResponse, RecommendationResponse.class);
                     }
+                    else if (request instanceof SearchItems)
+                    {
+                        parsedResponse = mapper.convertValue(parsedResponse, SearchResponse.class);
+                    }
                     /* Start of the generated code */
                     else if (request instanceof GetItemPropertyInfo)
                     {