001package com.box.sdk; 002 003import com.eclipsesource.json.Json; 004import com.eclipsesource.json.JsonObject; 005import com.eclipsesource.json.JsonValue; 006import java.net.URL; 007import java.text.ParseException; 008import java.util.Date; 009 010/** 011 * Represents a device pin. 012 * 013 * <p>Unless otherwise noted, the methods in this class can throw an unchecked {@link 014 * BoxAPIException} (unchecked meaning that the compiler won't force you to handle it) if an error 015 * occurs. If you wish to implement custom error handling for errors related to the Box REST API, 016 * you should capture this exception explicitly. 017 */ 018@BoxResourceType("device_pin") 019public class BoxDevicePin extends BoxResource { 020 021 /** The URL template used for operation with the device pin. */ 022 public static final URLTemplate DEVICE_PIN_URL_TEMPLATE = new URLTemplate("device_pinners/%s"); 023 024 /** The URL template used to get all the device pins within a given enterprise. */ 025 public static final URLTemplate ENTERPRISE_DEVICE_PINS_TEMPLATE = 026 new URLTemplate("enterprises/%s/device_pinners"); 027 028 /** Default limit of the device info entries per one response page. */ 029 private static final int DEVICES_DEFAULT_LIMIT = 100; 030 031 /** 032 * Constructs a device pin for a resource with a given ID. 033 * 034 * @param api the API connection to be used by the resource. 035 * @param id the ID of the resource. 036 */ 037 public BoxDevicePin(BoxAPIConnection api, String id) { 038 super(api, id); 039 } 040 041 /** 042 * Returns iterable with all the device pins within a given enterprise. Must be an enterprise 043 * admin with the manage enterprise scope to make this call. 044 * 045 * @param api API used to connect the Box. 046 * @param enterpriseID ID of the enterprise to get all the device pins within. 047 * @param fields the optional fields to retrieve. 048 * @return iterable with all the device pins within a given enterprise. 049 */ 050 public static Iterable<BoxDevicePin.Info> getEnterpriceDevicePins( 051 final BoxAPIConnection api, String enterpriseID, String... fields) { 052 return getEnterpriceDevicePins(api, enterpriseID, DEVICES_DEFAULT_LIMIT, fields); 053 } 054 055 /** 056 * Returns iterable with all the device pins within a given enterprise. Must be an enterprise 057 * admin with the manage enterprise scope to make this call. 058 * 059 * @param api API used to connect the Box. 060 * @param enterpriseID ID of the enterprise to get all the device pins within. 061 * @param limit the maximum number of items per single response. 062 * @param fields the optional fields to retrieve. 063 * @return iterable with all the device pins within a given enterprise. 064 */ 065 public static Iterable<BoxDevicePin.Info> getEnterpriceDevicePins( 066 final BoxAPIConnection api, String enterpriseID, int limit, String... fields) { 067 QueryStringBuilder builder = new QueryStringBuilder(); 068 if (fields.length > 0) { 069 builder.appendParam("fields", fields); 070 } 071 return new BoxResourceIterable<BoxDevicePin.Info>( 072 api, 073 ENTERPRISE_DEVICE_PINS_TEMPLATE.buildWithQuery( 074 api.getBaseURL(), builder.toString(), enterpriseID), 075 limit) { 076 077 @Override 078 protected BoxDevicePin.Info factory(JsonObject jsonObject) { 079 BoxDevicePin pin = new BoxDevicePin(api, jsonObject.get("id").asString()); 080 return pin.new Info(jsonObject); 081 } 082 }; 083 } 084 085 /** 086 * Gets information about the device pin. 087 * 088 * @param fields the fields to retrieve. 089 * @return info about the device pin. 090 */ 091 public Info getInfo(String... fields) { 092 QueryStringBuilder builder = new QueryStringBuilder(); 093 if (fields.length > 0) { 094 builder.appendParam("fields", fields); 095 } 096 URL url = 097 DEVICE_PIN_URL_TEMPLATE.buildWithQuery( 098 this.getAPI().getBaseURL(), builder.toString(), this.getID()); 099 BoxJSONRequest request = new BoxJSONRequest(this.getAPI(), url, "GET"); 100 try (BoxJSONResponse response = request.send()) { 101 JsonObject responseJSON = Json.parse(response.getJSON()).asObject(); 102 return new Info(responseJSON); 103 } 104 } 105 106 /** Deletes the device pin. */ 107 public void delete() { 108 URL url = DEVICE_PIN_URL_TEMPLATE.build(this.getAPI().getBaseURL(), this.getID()); 109 BoxAPIRequest request = new BoxAPIRequest(this.getAPI(), url, "DELETE"); 110 request.send().close(); 111 } 112 113 /** Contains information about a task assignment. */ 114 public class Info extends BoxResource.Info { 115 116 /** @see #getOwnedBy() */ 117 private BoxUser.Info ownedBy; 118 119 /** @see #getProductName() */ 120 private String productName; 121 122 /** @see #getCreatedAt() */ 123 private Date createdAt; 124 125 /** @see #getModifiedAt() */ 126 private Date modifiedAt; 127 128 /** Constructs an empty Info object. */ 129 public Info() { 130 super(); 131 } 132 133 /** 134 * Constructs an Info object by parsing information from a JSON string. 135 * 136 * @param json the JSON string to parse. 137 */ 138 public Info(String json) { 139 super(json); 140 } 141 142 /** 143 * Constructs an Info object using an already parsed JSON object. 144 * 145 * @param jsonObject the parsed JSON object. 146 */ 147 Info(JsonObject jsonObject) { 148 super(jsonObject); 149 } 150 151 /** {@inheritDoc} */ 152 @Override 153 public BoxResource getResource() { 154 return BoxDevicePin.this; 155 } 156 157 /** 158 * Gets ID of the user that the pin belongs to. 159 * 160 * @return ID of the user that the pin belongs to. 161 */ 162 public BoxUser.Info getOwnedBy() { 163 return this.ownedBy; 164 } 165 166 /** 167 * Gets the type of device being pinned. 168 * 169 * @return the type of device being pinned. 170 */ 171 public String getProductName() { 172 return this.productName; 173 } 174 175 /** 176 * Gets the time this pin was created. 177 * 178 * @return the time this pin was created. 179 */ 180 public Date getCreatedAt() { 181 return this.createdAt; 182 } 183 184 /** 185 * Gets the time this pin was modified. 186 * 187 * @return the time this pin was modified. 188 */ 189 public Date getModifiedAt() { 190 return this.modifiedAt; 191 } 192 193 /** {@inheritDoc} */ 194 @Override 195 void parseJSONMember(JsonObject.Member member) { 196 super.parseJSONMember(member); 197 198 String memberName = member.getName(); 199 JsonValue value = member.getValue(); 200 try { 201 if (memberName.equals("owned_by")) { 202 JsonObject userJSON = value.asObject(); 203 if (this.ownedBy == null) { 204 String userID = userJSON.get("id").asString(); 205 BoxUser user = new BoxUser(getAPI(), userID); 206 this.ownedBy = user.new Info(userJSON); 207 } else { 208 this.ownedBy.update(userJSON); 209 } 210 } else if (memberName.equals("product_name")) { 211 this.productName = value.asString(); 212 } else if (memberName.equals("created_at")) { 213 this.createdAt = BoxDateFormat.parse(value.asString()); 214 } else if (memberName.equals("modified_at")) { 215 this.modifiedAt = BoxDateFormat.parse(value.asString()); 216 } 217 } catch (ParseException e) { 218 assert false : "A ParseException indicates a bug in the SDK."; 219 } 220 } 221 } 222}