001package com.box.sdk;
002
003import java.net.URL;
004import java.util.Iterator;
005
006import com.eclipsesource.json.JsonObject;
007
008/**
009 * Represents a set of Box users.
010 *
011 * <p>Unless otherwise noted, the methods in this class can throw an unchecked {@link BoxAPIException} (unchecked
012 * meaning that the compiler won't force you to handle it) if an error occurs. If you wish to implement custom error
013 * handling for errors related to the Box REST API, you should capture this exception explicitly.</p>
014 */
015public class BoxGroup extends BoxCollaborator {
016    private static final URLTemplate GROUPS_URL_TEMPLATE = new URLTemplate("groups");
017    private static final URLTemplate GROUP_URL_TEMPLATE = new URLTemplate("groups/%s");
018
019    /**
020     * Constructs a BoxGroup for a group with a given ID.
021     * @param  api the API connection to be used by the group.
022     * @param  id  the ID of the group.
023     */
024    public BoxGroup(BoxAPIConnection api, String id) {
025        super(api, id);
026    }
027
028    /**
029     * Creates a new group with a specified name.
030     * @param  api  the API connection to be used by the group.
031     * @param  name the name of the new group.
032     * @return      info about the created group.
033     */
034    public static BoxGroup.Info createGroup(BoxAPIConnection api, String name) {
035        JsonObject requestJSON = new JsonObject();
036        requestJSON.add("name", name);
037
038        URL url = GROUPS_URL_TEMPLATE.build(api.getBaseURL());
039        BoxJSONRequest request = new BoxJSONRequest(api, url, "POST");
040        request.setBody(requestJSON.toString());
041        BoxJSONResponse response = (BoxJSONResponse) request.send();
042        JsonObject responseJSON = JsonObject.readFrom(response.getJSON());
043
044        BoxGroup group = new BoxGroup(api, responseJSON.get("id").asString());
045        return group.new Info(responseJSON);
046    }
047
048    /**
049     * Gets an iterable of all the groups that the current user is a member of.
050     * @param  api the API connection to be used when retrieving the groups.
051     * @return     an iterable containing info about all the groups.
052     */
053    public static Iterable<BoxGroup.Info> getAllGroups(final BoxAPIConnection api) {
054        return new Iterable<BoxGroup.Info>() {
055            public Iterator<BoxGroup.Info> iterator() {
056                URL url = GROUPS_URL_TEMPLATE.build(api.getBaseURL());
057                return new BoxGroupIterator(api, url);
058            }
059        };
060    }
061
062    /**
063     * Gets information about this group.
064     * @return info about this group.
065     */
066    public Info getInfo() {
067        URL url = GROUP_URL_TEMPLATE.build(this.getAPI().getBaseURL(), this.getID());
068        BoxAPIRequest request = new BoxAPIRequest(this.getAPI(), url, "GET");
069        BoxJSONResponse response = (BoxJSONResponse) request.send();
070        JsonObject responseJSON = JsonObject.readFrom(response.getJSON());
071        return new Info(responseJSON);
072    }
073
074    /**
075     * Deletes this group.
076     */
077    public void delete() {
078        URL url = GROUP_URL_TEMPLATE.build(this.getAPI().getBaseURL(), this.getID());
079        BoxAPIRequest request = new BoxAPIRequest(this.getAPI(), url, "DELETE");
080        BoxAPIResponse response = request.send();
081        response.disconnect();
082    }
083
084    /**
085     * Contains information about a BoxGroup.
086     */
087    public class Info extends BoxCollaborator.Info {
088        /**
089         * Constructs an empty Info object.
090         */
091        public Info() {
092            super();
093        }
094
095        /**
096         * Constructs an Info object by parsing information from a JSON string.
097         * @param  json the JSON string to parse.
098         */
099        public Info(String json) {
100            super(json);
101        }
102
103        /**
104         * Constructs an Info object using an already parsed JSON object.
105         * @param  jsonObject the parsed JSON object.
106         */
107        Info(JsonObject jsonObject) {
108            super(jsonObject);
109        }
110
111        @Override
112        public BoxGroup getResource() {
113            return BoxGroup.this;
114        }
115    }
116}