Support image and imageList item property types

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.0.1</version>
+        <version>2.1.0</version>
     </dependency>
 ```
 
@@ -90,22 +90,24 @@ import java.util.Random;
 public class ItemPropertiesExample {
     public static void main(String[] args) {
 
-        RecombeeClient client = new RecombeeClient("client-test", "jGGQ6ZKa8rQ1zTAyxTc0EMn55YPF7FJLUtaMLhbsGxmvwxgTwXYqmUk5xVZFw98L");
+        RecombeeClient client = new RecombeeClient("--my-database-id--", "--my-secret-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>();
@@ -114,13 +116,15 @@ public class ItemPropertiesExample {
 
             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;

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>com.recombee</groupId>
     <artifactId>api-client</artifactId>
-    <version>2.0.1</version>
+    <version>2.1.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/main/java/com/recombee/api_client/RecombeeClient.java

@@ -85,7 +85,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.0.1";
+    final String USER_AGENT = "recombee-java-api-client/2.1.0";
 
     private final OkHttpClient httpClient = new OkHttpClient();
 

src/main/java/com/recombee/api_client/api_requests/AddItemProperty.java

@@ -20,14 +20,14 @@ public class AddItemProperty extends Request {
      */
     protected String propertyName;
     /**
-     * Value type of the item property to be created. One of: `int`, `double`, `string`, `boolean`, `timestamp`, `set`
+     * Value type of the item property to be created. One of: `int`, `double`, `string`, `boolean`, `timestamp`, `set`, `image` or `imageList`.
      */
     protected String type;
 
     /**
      * Construct the request
      * @param propertyName Name of the item property to be created. Currently, the following names are reserved:`id`, `itemid`, case insensitively. Also, the length of the property name must not exceed 63 characters.
-     * @param type Value type of the item property to be created. One of: `int`, `double`, `string`, `boolean`, `timestamp`, `set`
+     * @param type Value type of the item property to be created. One of: `int`, `double`, `string`, `boolean`, `timestamp`, `set`, `image` or `imageList`.
      */
     public AddItemProperty (String propertyName,String type) {
         this.propertyName = propertyName;

src/main/java/com/recombee/api_client/api_requests/DeleteViewPortion.java

@@ -11,7 +11,6 @@
 import com.recombee.api_client.util.HTTPMethod;
 
 /**
- * The view portions feature is currently experimental.
  * Deletes an existing view portion specified by (`userId`, `itemId`, `sessionId`) from the database.
  */
 public class DeleteViewPortion extends Request {

src/main/java/com/recombee/api_client/api_requests/ItemBasedRecommendation.java

@@ -110,11 +110,11 @@ public class ItemBasedRecommendation extends Request {
      */
     protected String minRelevance;
     /**
-     * **Expert option** If the *targetUserId* is provided: If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Recombee API allows you to control this per-request in backward fashion. You may penalize an item for being recommended in the near past. For the specific user, `rotationRate=1` means maximal rotation, `rotationRate=0` means absolutely no rotation. You may also use, for example `rotationRate=0.2` for only slight rotation of recommended items.
+     * **Expert option** If the *targetUserId* is provided: If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Recombee API allows you to control this per-request in backward fashion. You may penalize an item for being recommended in the near past. For the specific user, `rotationRate=1` means maximal rotation, `rotationRate=0` means absolutely no rotation. You may also use, for example `rotationRate=0.2` for only slight rotation of recommended items. Default: `0.01`.
      */
     protected Double rotationRate;
     /**
-     * **Expert option** If the *targetUserId* is provided: Taking *rotationRate* into account, specifies how long time it takes to an item to recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized.
+     * **Expert option** If the *targetUserId* is provided: Taking *rotationRate* into account, specifies how long time it takes to an item to recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized. Default: `7200.0`.
      */
     protected Double rotationTime;
     /**
@@ -261,15 +261,15 @@ public ItemBasedRecommendation setMinRelevance(String minRelevance) {
     }
 
     /**
-     * @param rotationRate **Expert option** If the *targetUserId* is provided: If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Recombee API allows you to control this per-request in backward fashion. You may penalize an item for being recommended in the near past. For the specific user, `rotationRate=1` means maximal rotation, `rotationRate=0` means absolutely no rotation. You may also use, for example `rotationRate=0.2` for only slight rotation of recommended items.
+     * @param rotationRate **Expert option** If the *targetUserId* is provided: If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Recombee API allows you to control this per-request in backward fashion. You may penalize an item for being recommended in the near past. For the specific user, `rotationRate=1` means maximal rotation, `rotationRate=0` means absolutely no rotation. You may also use, for example `rotationRate=0.2` for only slight rotation of recommended items. Default: `0.01`.
      */
     public ItemBasedRecommendation setRotationRate(double rotationRate) {
          this.rotationRate = rotationRate;
          return this;
     }
 
     /**
-     * @param rotationTime **Expert option** If the *targetUserId* is provided: Taking *rotationRate* into account, specifies how long time it takes to an item to recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized.
+     * @param rotationTime **Expert option** If the *targetUserId* is provided: Taking *rotationRate* into account, specifies how long time it takes to an item to recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized. Default: `7200.0`.
      */
     public ItemBasedRecommendation setRotationTime(double rotationTime) {
          this.rotationTime = rotationTime;

src/main/java/com/recombee/api_client/api_requests/ListItemViewPortions.java

@@ -11,7 +11,6 @@
 import com.recombee.api_client.util.HTTPMethod;
 
 /**
- * The view portions feature is currently experimental.
  * List all the view portions of an item ever submitted by different users.
  */
 public class ListItemViewPortions extends Request {

src/main/java/com/recombee/api_client/api_requests/ListUserViewPortions.java

@@ -11,7 +11,6 @@
 import com.recombee.api_client.util.HTTPMethod;
 
 /**
- * The view portions feature is currently experimental.
  * List all the view portions ever submitted by a given user.
  */
 public class ListUserViewPortions extends Request {

src/main/java/com/recombee/api_client/api_requests/MergeUsers.java

@@ -17,11 +17,11 @@
 public class MergeUsers extends Request {
 
     /**
-     * ID of the source user.
+     * ID of the targer user.
      */
     protected String targetUserId;
     /**
-     * ID of the target user.
+     * ID of the source user.
      */
     protected String sourceUserId;
     /**
@@ -31,8 +31,8 @@ public class MergeUsers extends Request {
 
     /**
      * Construct the request
-     * @param targetUserId ID of the source user.
-     * @param sourceUserId ID of the target user.
+     * @param targetUserId ID of the targer user.
+     * @param sourceUserId ID of the source user.
      */
     public MergeUsers (String targetUserId,String sourceUserId) {
         this.targetUserId = targetUserId;

src/main/java/com/recombee/api_client/api_requests/RecommendItemsToUser.java

@@ -107,11 +107,11 @@ public class RecommendItemsToUser extends Request {
      */
     protected String minRelevance;
     /**
-     * **Expert option** If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Recombee API allows you to control this per-request in backward fashion. You may penalize an item for being recommended in the near past. For the specific user, `rotationRate=1` means maximal rotation, `rotationRate=0` means absolutely no rotation. You may also use, for example `rotationRate=0.2` for only slight rotation of recommended items.
+     * **Expert option** If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Recombee API allows you to control this per-request in backward fashion. You may penalize an item for being recommended in the near past. For the specific user, `rotationRate=1` means maximal rotation, `rotationRate=0` means absolutely no rotation. You may also use, for example `rotationRate=0.2` for only slight rotation of recommended items. Default: `0.1`.
      */
     protected Double rotationRate;
     /**
-     * **Expert option** Taking *rotationRate* into account, specifies how long time it takes to an item to recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized.
+     * **Expert option** Taking *rotationRate* into account, specifies how long time it takes to an item to recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized. Default: `7200.0`.
      */
     protected Double rotationTime;
     /**
@@ -245,15 +245,15 @@ public RecommendItemsToUser setMinRelevance(String minRelevance) {
     }
 
     /**
-     * @param rotationRate **Expert option** If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Recombee API allows you to control this per-request in backward fashion. You may penalize an item for being recommended in the near past. For the specific user, `rotationRate=1` means maximal rotation, `rotationRate=0` means absolutely no rotation. You may also use, for example `rotationRate=0.2` for only slight rotation of recommended items.
+     * @param rotationRate **Expert option** If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Recombee API allows you to control this per-request in backward fashion. You may penalize an item for being recommended in the near past. For the specific user, `rotationRate=1` means maximal rotation, `rotationRate=0` means absolutely no rotation. You may also use, for example `rotationRate=0.2` for only slight rotation of recommended items. Default: `0.1`.
      */
     public RecommendItemsToUser setRotationRate(double rotationRate) {
          this.rotationRate = rotationRate;
          return this;
     }
 
     /**
-     * @param rotationTime **Expert option** Taking *rotationRate* into account, specifies how long time it takes to an item to recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized.
+     * @param rotationTime **Expert option** Taking *rotationRate* into account, specifies how long time it takes to an item to recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized. Default: `7200.0`.
      */
     public RecommendItemsToUser setRotationTime(double rotationTime) {
          this.rotationTime = rotationTime;

src/main/java/com/recombee/api_client/api_requests/SetViewPortion.java

@@ -11,7 +11,6 @@
 import com.recombee.api_client.util.HTTPMethod;
 
 /**
- * The view portions feature is currently experimental.
  * Sets viewed portion of an item (for example a video or article) by a user (at a session).
  * If you send new request with the same (`userId`, `itemId`, `sessionId`), the portion gets updated.
  */
@@ -26,11 +25,11 @@ public class SetViewPortion extends Request {
      */
     protected String itemId;
     /**
-     * Viewed portion of the item (number between 0.0 (viewed nothing) and 1.0 (viewed full item) ).
+     * Viewed portion of the item (number between 0.0 (viewed nothing) and 1.0 (viewed full item) ). It should be the really viewed part of the item, no matter seeking, so for example if the user seeked immediately to half of the item and then viewed 10% of the item, the `portion` should still be `0.1`.
      */
     protected Double portion;
     /**
-     * Id of session in which the user viewed the item
+     * ID of session in which the user viewed the item. Default is `null` (`None`, `nil`, `NULL` etc. depending on language).
      */
     protected String sessionId;
     /**
@@ -46,7 +45,7 @@ public class SetViewPortion extends Request {
      * Construct the request
      * @param userId User who viewed a portion of the item
      * @param itemId Viewed item
-     * @param portion Viewed portion of the item (number between 0.0 (viewed nothing) and 1.0 (viewed full item) ).
+     * @param portion Viewed portion of the item (number between 0.0 (viewed nothing) and 1.0 (viewed full item) ). It should be the really viewed part of the item, no matter seeking, so for example if the user seeked immediately to half of the item and then viewed 10% of the item, the `portion` should still be `0.1`.
      */
     public SetViewPortion (String userId,String itemId,double portion) {
         this.userId = userId;
@@ -56,7 +55,7 @@ public SetViewPortion (String userId,String itemId,double portion) {
     }
 
     /**
-     * @param sessionId Id of session in which the user viewed the item
+     * @param sessionId ID of session in which the user viewed the item. Default is `null` (`None`, `nil`, `NULL` etc. depending on language).
      */
     public SetViewPortion setSessionId(String sessionId) {
          this.sessionId = sessionId;