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}