Representations api

src/main/java/com/box/sdk/BoxFile.java

@@ -7,11 +7,14 @@
 import java.net.MalformedURLException;
 import java.net.URL;
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.Collection;
 import java.util.Date;
 import java.util.EnumSet;
+import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 import java.util.concurrent.TimeUnit;
 
 import com.box.sdk.internal.utils.Parsers;
@@ -439,6 +442,33 @@ public BoxFile.Info getInfo(String... fields) {
         return new Info(response.getJSON());
     }
 
+    /**
+     * Gets information about this item including a specified set of representations.
+     * @see <a href=https://developer.box.com/reference#section-x-rep-hints-header>X-Rep-Hints Header</a>
+     *
+     * @param representationHints hints for representations to be retrieved
+     * @param fields the fields to retrieve.
+     * @return info about this item containing only the specified fields, including representations.
+     */
+    public BoxFile.Info getInfoWithRepresentations(String representationHints, String... fields) {
+        if (representationHints.matches(Representation.X_REP_HINTS_PATTERN)) {
+            //Since the user intends to get representations, add it to fields, even if user has missed it
+            Set<String> fieldsSet = new HashSet<String>(Arrays.asList(fields));
+            fieldsSet.add("representations");
+            String queryString = new QueryStringBuilder().appendParam("fields",
+                fieldsSet.toArray(new String[fieldsSet.size()])).toString();
+            URL url = FILE_URL_TEMPLATE.buildWithQuery(this.getAPI().getBaseURL(), queryString, this.getID());
+
+            BoxAPIRequest request = new BoxAPIRequest(this.getAPI(), url, "GET");
+            request.addHeader("X-Rep-Hints", representationHints);
+            BoxJSONResponse response = (BoxJSONResponse) request.send();
+            return new Info(response.getJSON());
+        } else {
+            throw new BoxAPIException("Represention hints is not valid."
+                + " Refer documention on how to construct X-Rep-Hints Header");
+        }
+    }
+
     /**
      * Updates the information about this file with any info fields that have been modified locally.
      *

src/main/java/com/box/sdk/Representation.java

@@ -4,17 +4,22 @@
 import java.net.URL;
 
 import com.eclipsesource.json.JsonObject;
-import com.eclipsesource.json.JsonValue;
 
 /**
  * The class represents one instance of a file representation.
  */
 public class Representation {
 
+    /**
+     * Used to validate if the hints header has (near) valid value.
+     */
+    protected static final String X_REP_HINTS_PATTERN = "^(?:\\[[a-z0-9_]+(?:\\?[a-z0-9_]+\\=[a-z0-9_]+(?:"
+        + "\\|[a-z0-9_]+)*(?:&[a-z0-9_]+\\=[a-z0-9_]+(?:\\|[a-z0-9_]+)*)*)?(?:,[a-z0-9_]+(?:\\?[a-z0-9_]+\\=[a-z0-9_]+"
+        + "(?:\\|[a-z0-9_]+)*(?:&[a-z0-9_]+\\=[a-z0-9_]+(?:\\|[a-z0-9_]+)*)*)?)*\\])+$";
+
     private String representation;
-    private Properties properties;
-    private Metadata metadata;
-    private String assetPath;
+    private JsonObject properties;
+    private JsonObject metadata;
     private Info info;
     private Content content;
     private Status status;
@@ -28,11 +33,9 @@ public Representation(JsonObject representationJson) {
             if (member.getName().equals("representation")) {
                 this.representation = member.getValue().asString();
             } else if (member.getName().equals("properties")) {
-                this.properties = new Properties(member.getValue().asObject());
+                this.properties = member.getValue().asObject();
             } else if (member.getName().equals("metadata")) {
-                this.metadata = new Metadata(member.getValue().asObject());
-            } else if (member.getName().equals("assetPath")) {
-                this.assetPath = member.getValue().asString();
+                this.metadata = member.getValue().asObject();
             } else if (member.getName().equals("info")) {
                 this.info = new Info(member.getValue().asObject());
             } else if (member.getName().equals("content")) {
@@ -56,30 +59,21 @@ public String getRepresentation() {
     /**
      * Get representation's set of static properties to distinguish between subtypes of a given representation,
      * for example, different sizes of jpg's. Each representation has its own set of properties.
-     * @return properties of representation
+     * @return properties of representation as JsonObject
      */
-    public Properties getProperties() {
+    public JsonObject getProperties() {
         return this.properties;
     }
 
     /**
      * Get representation's metadata.
      *
-     * @return metadata
+     * @return metadataas JsonObject
      */
-    public Metadata getMetadata() {
+    public JsonObject getMetadata() {
         return this.metadata;
     }
 
-    /**
-     * Get representation's asset path.
-     *
-     * @return The values used to substitute for asset_path in the content.url_template.
-     */
-    public String getAssetPath() {
-        return this.assetPath;
-    }
-
     /**
      * Get Info which has an opaque URL which will return status information about the file.
      * It may change over time and should not be hard-coded or cached.
@@ -105,97 +99,6 @@ public Status getStatus() {
         return this.status;
     }
 
-    /**
-     * A set of static properties to distinguish between subtypes of a given representation,
-     * for example, different sizes of jpg's. Each representation has its own set of properties.
-     */
-    public class Properties {
-
-        private String dimensions;
-        private String paged;
-        private String thumb;
-
-        /**
-         * Construct a representation's properties.
-         * @param members json object
-         */
-        public Properties(JsonObject members) {
-            for (JsonObject.Member member : members) {
-                if (member.getName().equals("dimensions")) {
-                    this.dimensions = member.getValue().asString();
-                } else if (member.getName().equals("paged")) {
-                    this.paged = member.getValue().asString();
-                } else if (member.getName().equals("thumb")) {
-                    this.thumb = member.getValue().asString();
-                }
-            }
-        }
-
-        /**
-         * Get dimensions of representation.
-         * @return dimensions
-         */
-        public String getDimensions() {
-            return this.dimensions;
-        }
-
-        /**
-         * Get whether or not multiple pages are supported or not.
-         * @return paged value
-         */
-        public String getPaged() {
-            return this.paged;
-        }
-
-        /**
-         * When true, down-sampling options are used to produce a better image.
-         * @return thumb value
-         */
-        public String getThumb() {
-            return this.thumb;
-        }
-    }
-
-    /**
-     * Representation's metadata which is a set of dynamic properties about this specific representation of this
-     * specific file. Metadata is different for each representation subtype.
-     */
-    public class Metadata {
-
-        private int pages;
-        private JsonObject jsonObject;
-
-        /**
-         * Construct a representation's metadata.
-         * @param members json object
-         */
-        public Metadata(JsonObject members) {
-            for (JsonObject.Member member : members) {
-                if (member.getName().equals("pages")) {
-                    this.pages = member.getValue().asInt();
-                }
-            }
-            this.jsonObject = members;
-        }
-
-        /**
-         * No. of pages in a multi-page representation.
-         * @return no. of pages
-         */
-        public int getPages() {
-            return this.pages;
-        }
-
-        /**
-         * Returns a json value for any field in a repreentation's metadata.
-         * @param field the field that designates the key
-         * @return the metadata property value.
-         */
-        public JsonValue get(String field) {
-            return this.jsonObject.get(field);
-        }
-    }
-
     /**
      * Representation's info URL.
      */

src/test/java/com/box/sdk/BoxFileTest.java

@@ -431,30 +431,53 @@ public void getRepresentationsUnitTest() throws MalformedURLException {
         BoxFile file = new BoxFile(api, "0");
         List<Representation> representations = file.getInfo("representations").getRepresentations();
         Assert.assertEquals("There should be only one representation", 1, representations.size());
-        Assert.assertEquals("There should content.url_template exists with valid value",
+        Assert.assertEquals("content.url_template should exist with valid value",
             ".../{+asset_path}", representations.get(0).getContent().getUrlTemplate());
-        Assert.assertEquals("There should info.url exists with valid value",
+        Assert.assertEquals("info.url should exist with valid value",
             new URL("http://dummy.com"), representations.get(0).getInfo().getUrl());
-        Assert.assertEquals("There should metadata.pages has exact value",
-            10, representations.get(0).getMetadata().getPages());
-        Assert.assertEquals("There should properties.dimensions exists with valid value",
-            "2048x2048", representations.get(0).getProperties().getDimensions());
-        Assert.assertEquals("There should properties.paged exists with valid value",
-            "true", representations.get(0).getProperties().getPaged());
-        Assert.assertEquals("There should properties.thumb exists with valid value",
-            "false", representations.get(0).getProperties().getThumb());
-        Assert.assertEquals("There should representation exists with valid value",
+        Assert.assertEquals("metadata.pages should have exact value",
+            10, representations.get(0).getMetadata().get("pages").asInt());
+        Assert.assertEquals("properties.dimensions should exist with valid value",
+            "2048x2048", representations.get(0).getProperties().get("dimensions").asString());
+        Assert.assertEquals("properties.paged should exist with valid value",
+            "true", representations.get(0).getProperties().get("paged").asString());
+        Assert.assertEquals("properties.thumb should exist with valid value",
+            "false", representations.get(0).getProperties().get("thumb").asString());
+        Assert.assertEquals("representation should exist with valid value",
             "png", representations.get(0).getRepresentation());
-        Assert.assertEquals("There should status.state exists with valid value",
+        Assert.assertEquals("status.state should exist with valid value",
             "success", representations.get(0).getStatus().getState());
     }
 
+    @Test
+    @Category(UnitTest.class)
+    public void getRepresentationsShouldThrowExceptionWhenHintsIsInvalid() throws MalformedURLException {
+        BoxAPIConnection api = new BoxAPIConnection("");
+        BoxFile file = new BoxFile(api, "0");
+        try {
+            List<Representation> representations = file.getInfoWithRepresentations("png",
+                "representations").getRepresentations();
+        } catch (Exception e) {
+            Assert.assertTrue("BoxAPIException should be thrown", e instanceof BoxAPIException);
+        }
+    }
+
     @Test
     @Category(IntegrationTest.class)
-    public void getRepresentationsIntegrationTest() throws MalformedURLException {
+    public void getInfoWithRepresentationsIntegrationTestWithSimpleHint() throws MalformedURLException {
         BoxAPIConnection api = new BoxAPIConnection(TestConfig.getAccessToken());
         BoxFile file = new BoxFile(api, "135907614435");
-        List<Representation> representations = file.getInfo("representations").getRepresentations();
+        List<Representation> representations = file.getInfoWithRepresentations("[png]").getRepresentations();
+        Assert.assertTrue("There should be at least one representation", representations.size() > 0);
+    }
+
+    @Test
+    @Category(IntegrationTest.class)
+    public void getInfoWithRepresentationsIntegrationTestWithComplexHint() throws MalformedURLException {
+        BoxAPIConnection api = new BoxAPIConnection(TestConfig.getAccessToken());
+        BoxFile file = new BoxFile(api, "135907614435");
+        List<Representation> representations = file.getInfoWithRepresentations(
+            "[jpg,png?dimensions=1024x1024][pdf]").getRepresentations();
         Assert.assertTrue("There should be at least one representation", representations.size() > 0);
     }