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