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