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}