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}