Add Groups Service APIs

9 files changed, 657 insertions, 1 deletions

diff --git a/src/main/java/com/p4square/ccbapi/CCBAPI.java b/src/main/java/com/p4square/ccbapi/CCBAPI.java
index eb13cbf..6b9ba2e 100644
--- a/src/main/java/com/p4square/ccbapi/CCBAPI.java
+++ b/src/main/java/com/p4square/ccbapi/CCBAPI.java
@@ -59,4 +59,19 @@ public interface CCBAPI extends Closeable {
      * @throws IOException on failure.
      */
     UpdateIndividualProfileResponse updateIndividualProfile(UpdateIndividualProfileRequest request) throws IOException;
+
+    /**
+     * Retrieve one or more {@link GroupProfile}s.
+     *
+     * If {@link GetGroupProfilesRequest#withGroupId(int)} is set on the
+     * request, only the specified group will be returned.
+     * Otherwise, all groups are returned.
+     *
+     * The appropriate CCB API will be selected based on the options used.
+     *
+     * @param request A {@link GetGroupProfilesRequest}.
+     * @return A {@link GetGroupProfilesResponse} object on success, including when no groups are found.
+     * @throws IOException on failure.
+     */
+    GetGroupProfilesResponse getGroupProfiles(GetGroupProfilesRequest request) throws IOException;
 }
diff --git a/src/main/java/com/p4square/ccbapi/CCBAPIClient.java b/src/main/java/com/p4square/ccbapi/CCBAPIClient.java
index 96abf78..a0335ba 100644
--- a/src/main/java/com/p4square/ccbapi/CCBAPIClient.java
+++ b/src/main/java/com/p4square/ccbapi/CCBAPIClient.java
@@ -165,6 +165,43 @@ public class CCBAPIClient implements CCBAPI {
         return makeRequest("update_individual", params, form, UpdateIndividualProfileResponse.class);
     }
 
+    @Override
+    public GetGroupProfilesResponse getGroupProfiles(GetGroupProfilesRequest request) throws IOException {
+        // Prepare the request.
+        String serviceName;
+        final Map<String, String> params = new HashMap<>();
+
+        if (request.getId() != 0) {
+            // Use group_profile_from_id (id)
+            serviceName = "group_profile_from_id";
+            params.put("id", String.valueOf(request.getId()));
+
+        } else {
+            // Use group_profiles
+            serviceName = "group_profiles";
+            if (request.getModifiedSince() != null) {
+                params.put("modified_since", request.getModifiedSince().toString());
+            }
+            if (request.getPage() != 0) {
+                params.put("page", String.valueOf(request.getPage()));
+            }
+            if (request.getPerPage() != 0) {
+                params.put("per_page", String.valueOf(request.getPerPage()));
+            }
+            if (request.getIncludeParticipants() != null) {
+                params.put("include_participants", request.getIncludeParticipants() ? "true" : "false");
+            }
+        }
+
+        // This option applies to all request types.
+        if (request.getIncludeImageUrl() != null) {
+            params.put("include_image_link", request.getIncludeImageUrl() ? "true" : "false");
+        }
+
+        // Send the request and parse the response.
+        return makeRequest(serviceName, params, null, GetGroupProfilesResponse.class);
+    }
+
     /**
      * Build the URI for a particular service call.
      *
diff --git a/src/main/java/com/p4square/ccbapi/model/Address.java b/src/main/java/com/p4square/ccbapi/model/Address.java
index 9bbd6e3..01934d8 100644
--- a/src/main/java/com/p4square/ccbapi/model/Address.java
+++ b/src/main/java/com/p4square/ccbapi/model/Address.java
@@ -13,7 +13,8 @@ public class Address {
         @XmlEnumValue("mailing") MAILING,
         @XmlEnumValue("home") HOME,
         @XmlEnumValue("work") WORK,
-        @XmlEnumValue("other") OTHER;
+        @XmlEnumValue("other") OTHER,
+        @XmlEnumValue("meeting") MEETING;
     }
 
     @XmlAttribute(name="type")
diff --git a/src/main/java/com/p4square/ccbapi/model/GetGroupProfilesRequest.java b/src/main/java/com/p4square/ccbapi/model/GetGroupProfilesRequest.java
new file mode 100644
index 0000000..85bf752
--- /dev/null
+++ b/src/main/java/com/p4square/ccbapi/model/GetGroupProfilesRequest.java
@@ -0,0 +1,145 @@
+package com.p4square.ccbapi.model;
+
+import java.time.LocalDate;
+
+/**
+ * GetGroupProfilesRequest is the set of options for retrieving group profiles.
+ *
+ * If {@link #withGroupId(int)} is used, this request will return only the
+ * requested group.
+ *
+ * Otherwise, this request allows you to pass in a given date and have all
+ * groups created or modified since that date returned to you. If a date is
+ * not provided, all groups in the system will be returned.
+ *
+ * The image link in the image element will expire, and should be cached.
+ * Including it will significantly increase the runtime of the service and may
+ * cause a timeout. Please consider using {@link #withPerPage(int)} and
+ * {@link #withPage(int)} if you want to get the images from your groups.
+ */
+public class GetGroupProfilesRequest {
+
+    // Used with group_profile_from_id
+    private int id;
+
+    // Used with group_profiles
+    private LocalDate modifiedSince;
+    private int page;
+    private int perPage;
+    private Boolean includeParticipants;
+
+    // Used with any.
+    private Boolean includeImageLink;
+
+    public int getId() {
+        return id;
+    }
+
+    /**
+     * Request the {@link GroupProfile} for the given group id.
+     *
+     * @param id The id.
+     * @return this.
+     */
+    public GetGroupProfilesRequest withGroupId(final int id) {
+        this.id = id;
+        return this;
+    }
+
+    public Boolean getIncludeImageUrl() {
+        return includeImageLink;
+    }
+
+    /**
+     * Include the image URL in the result.
+     *
+     * Note: The image link in the image element will expire, and should be cached.
+     *
+     * @param value True if the image link should be included.
+     * @return this.
+     */
+    public GetGroupProfilesRequest withIncludeImageUrl(final boolean value) {
+        this.includeImageLink = value;
+        return this;
+    }
+
+    public LocalDate getModifiedSince() {
+        return modifiedSince;
+    }
+
+    /**
+     * Retrieve all groups modified since the given time.
+     *
+     * Note: This cannot be used with {@link #withGroupId(int)}.
+     *
+     * @param modifiedSince The given time.
+     * @return this.
+     */
+    public GetGroupProfilesRequest withModifiedSince(final LocalDate modifiedSince) {
+        this.modifiedSince = modifiedSince;
+        return this;
+    }
+
+    public int getPage() {
+        return page;
+    }
+
+
+    /**
+     * Select the page of results when paginating results.
+     *
+     * Note: This cannot be used with {@link #withGroupId(int)}.
+     *
+     * Defaults to 1 if {@link #withPerPage(int)} is specified on the request.
+     *
+     * @param page The starting page number.
+     * @return this.
+     */
+    public GetGroupProfilesRequest withPage(final int page) {
+        this.page = page;
+        return this;
+    }
+
+    public int getPerPage() {
+        return perPage;
+    }
+
+    /**
+     * Limit the number of groups returned.
+     *
+     * Note: This cannot be used with {@link #withGroupId(int)}.
+     *
+     * Defaults to 25 if {@link #withPage(int)} is specified on the request.
+     *
+     * @param perPage The maximum number to return.
+     * @return this.
+     */
+    public GetGroupProfilesRequest withPerPage(final int perPage) {
+        this.perPage = perPage;
+        return this;
+    }
+
+    public Boolean getIncludeParticipants() {
+        return includeParticipants;
+    }
+
+    /**
+     * Include all participants from the group in the response.
+     *
+     * {@link GroupProfile#getMainLeader()} and {@link GroupProfile#getLeaders()}
+     * are always populated, regardless of the value.
+     *
+     * Note: This cannot be used with {@link #withGroupId(int)}.
+     *
+     * Defaults to True.
+     *
+     * @see {@link GroupProfile#getParticipants()}
+     *
+     * @param includeParticipants
+     * @return this.
+     */
+    public GetGroupProfilesRequest withIncludeParticipants(final boolean includeParticipants) {
+        this.includeParticipants = includeParticipants;
+        return this;
+    }
+}
diff --git a/src/main/java/com/p4square/ccbapi/model/GetGroupProfilesResponse.java b/src/main/java/com/p4square/ccbapi/model/GetGroupProfilesResponse.java
new file mode 100644
index 0000000..270b338
--- /dev/null
+++ b/src/main/java/com/p4square/ccbapi/model/GetGroupProfilesResponse.java
@@ -0,0 +1,27 @@
+package com.p4square.ccbapi.model;
+
+import javax.xml.bind.annotation.*;
+import java.util.List;
+
+/**
+ * GetGroupProfilesResponse models the response of a variety of APIs which return one or more {@link GroupProfile}s.
+ */
+@XmlRootElement(name="response")
+@XmlAccessorType(XmlAccessType.NONE)
+public class GetGroupProfilesResponse extends CCBAPIResponse {
+
+    @XmlElementWrapper(name = "groups")
+    @XmlElement(name="group")
+    private List<GroupProfile> groups;
+
+    /**
+     * @return The list of groups retrieved from CCB.
+     */
+    public List<GroupProfile> getGroups() {
+        return groups;
+    }
+
+    public void setGroups(List<GroupProfile> groups) {
+        this.groups = groups;
+    }
+}
diff --git a/src/main/java/com/p4square/ccbapi/model/GroupProfile.java b/src/main/java/com/p4square/ccbapi/model/GroupProfile.java
new file mode 100644
index 0000000..6140200
--- /dev/null
+++ b/src/main/java/com/p4square/ccbapi/model/GroupProfile.java
@@ -0,0 +1,367 @@
+package com.p4square.ccbapi.model;
+
+import javax.xml.bind.annotation.*;
+import java.net.URL;
+import java.time.LocalDateTime;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Representation of a Group Profile.
+ */
+@XmlRootElement(name="individual")
+@XmlAccessorType(XmlAccessType.NONE)
+public class GroupProfile {
+
+    @XmlAttribute(name="id")
+    private int id;
+
+    @XmlElement(name="name")
+    private String name;
+
+    @XmlElement(name="description")
+    private String description;
+
+    @XmlElement(name="image")
+    private URL imageUrl;
+
+    @XmlElement(name="calendar_feed")
+    private URL calendarFeedUrl;
+
+    @XmlElement(name="main_leader")
+    private IndividualProfile mainLeader;
+
+    @XmlElement(name="coach")
+    private IndividualProfile coach;
+
+    @XmlElement(name="director")
+    private IndividualProfile director;
+
+    @XmlElementWrapper(name="leaders")
+    @XmlElement(name="leader")
+    private List<IndividualProfile> leaders;
+
+    @XmlElementWrapper(name="participants")
+    @XmlElement(name="participant")
+    private List<IndividualProfile> participants;
+
+    @XmlElement(name="current_members")
+    private int currentMembers;
+
+    @XmlElement(name="group_capacity")
+    private String groupCapacity;
+
+    @XmlElementWrapper(name="addresses")
+    @XmlElement(name="address")
+    private List<Address> addresses;
+
+    @XmlElement(name="childcare_provided")
+    private boolean childcareProvided;
+
+    @XmlElement(name="listed")
+    private boolean listed;
+
+    @XmlElement(name="public_search_listed")
+    private boolean publicSearchListed;
+
+    @XmlElement(name="inactive")
+    private boolean inactive;
+
+    @XmlElement(name="notification")
+    private boolean notification;
+
+    @XmlElement(name="interaction_type", defaultValue = "Announcement Only")
+    private InteractionType interactionType;
+
+    @XmlElement(name="membership_type", defaultValue = "Invitation")
+    private MembershipType membershipType;
+
+    @XmlElementWrapper(name="user_defined_fields")
+    @XmlElement(name="user_defined_field")
+    private CustomFieldCollection<CustomPulldownFieldValue> customPulldownFields;
+
+    @XmlElement(name="campus")
+    private Reference campus;
+
+    @XmlElement(name="group_type")
+    private Reference groupType;
+
+    @XmlElement(name="department")
+    private Reference department;
+
+    @XmlElement(name="area")
+    private Reference area;
+
+    @XmlElement(name="meeting_day")
+    private Reference meeting_day;
+
+    @XmlElement(name="meeting_time")
+    private Reference meeting_time;
+
+    @XmlElement(name="creator")
+    private IndividualReference createdBy;
+
+    @XmlElement(name="created")
+    private LocalDateTime createdTime;
+
+    @XmlElement(name="modifier")
+    private IndividualReference modifiedBy;
+
+    @XmlElement(name="modified")
+    private LocalDateTime modifiedTime;
+
+    public GroupProfile() {
+        leaders = new ArrayList<>();
+        participants = new ArrayList<>();
+        addresses = new ArrayList<>();
+        customPulldownFields = new CustomFieldCollection<>();
+    }
+
+    public int getId() {
+        return id;
+    }
+
+    public void setId(int id) {
+        this.id = id;
+    }
+
+    public String getName() {
+        return name;
+    }
+
+    public void setName(String name) {
+        this.name = name;
+    }
+
+    public String getDescription() {
+        return description;
+    }
+
+    public void setDescription(String description) {
+        this.description = description;
+    }
+
+    public URL getImageUrl() {
+        return imageUrl;
+    }
+
+    public void setImageUrl(URL imageUrl) {
+        this.imageUrl = imageUrl;
+    }
+
+    public URL getCalendarFeedUrl() {
+        return calendarFeedUrl;
+    }
+
+    public void setCalendarFeedUrl(URL calendarFeedUrl) {
+        this.calendarFeedUrl = calendarFeedUrl;
+    }
+
+    public IndividualProfile getMainLeader() {
+        return mainLeader;
+    }
+
+    public void setMainLeader(IndividualProfile mainLeader) {
+        this.mainLeader = mainLeader;
+    }
+
+    public IndividualProfile getCoach() {
+        return coach;
+    }
+
+    public void setCoach(IndividualProfile coach) {
+        this.coach = coach;
+    }
+
+    public IndividualProfile getDirector() {
+        return director;
+    }
+
+    public void setDirector(IndividualProfile director) {
+        this.director = director;
+    }
+
+    public List<IndividualProfile> getLeaders() {
+        return leaders;
+    }
+
+    public void setLeaders(List<IndividualProfile> leaders) {
+        this.leaders = leaders;
+    }
+
+    public List<IndividualProfile> getParticipants() {
+        return participants;
+    }
+
+    public void setParticipants(List<IndividualProfile> participants) {
+        this.participants = participants;
+    }
+
+    public int getCurrentMembers() {
+        return currentMembers;
+    }
+
+    public void setCurrentMembers(int currentMembers) {
+        this.currentMembers = currentMembers;
+    }
+
+    public String getGroupCapacity() {
+        return groupCapacity;
+    }
+
+    public void setGroupCapacity(String groupCapacity) {
+        this.groupCapacity = groupCapacity;
+    }
+
+    public List<Address> getAddresses() {
+        return addresses;
+    }
+
+    public void setAddresses(List<Address> addresses) {
+        this.addresses = addresses;
+    }
+
+    public boolean isChildcareProvided() {
+        return childcareProvided;
+    }
+
+    public void setChildcareProvided(boolean childcareProvided) {
+        this.childcareProvided = childcareProvided;
+    }
+
+    public boolean isListed() {
+        return listed;
+    }
+
+    public void setListed(boolean listed) {
+        this.listed = listed;
+    }
+
+    public boolean isPublicSearchListed() {
+        return publicSearchListed;
+    }
+
+    public void setPublicSearchListed(boolean publicSearchListed) {
+        this.publicSearchListed = publicSearchListed;
+    }
+
+    public boolean isInactive() {
+        return inactive;
+    }
+
+    public void setInactive(boolean inactive) {
+        this.inactive = inactive;
+    }
+
+    public boolean isNotification() {
+        return notification;
+    }
+
+    public void setNotification(boolean notification) {
+        this.notification = notification;
+    }
+
+    public InteractionType getInteractionType() {
+        return interactionType;
+    }
+
+    public void setInteractionType(InteractionType interactionType) {
+        this.interactionType = interactionType;
+    }
+
+    public MembershipType getMembershipType() {
+        return membershipType;
+    }
+
+    public void setMembershipType(MembershipType membershipType) {
+        this.membershipType = membershipType;
+    }
+
+    public CustomFieldCollection<CustomPulldownFieldValue> getCustomPulldownFields() {
+        return customPulldownFields;
+    }
+
+    public void setCustomPulldownFields(CustomFieldCollection<CustomPulldownFieldValue> customPulldownFields) {
+        this.customPulldownFields = customPulldownFields;
+    }
+
+    public Reference getCampus() {
+        return campus;
+    }
+
+    public void setCampus(Reference campus) {
+        this.campus = campus;
+    }
+
+    public Reference getGroupType() {
+        return groupType;
+    }
+
+    public void setGroupType(Reference groupType) {
+        this.groupType = groupType;
+    }
+
+    public Reference getDepartment() {
+        return department;
+    }
+
+    public void setDepartment(Reference department) {
+        this.department = department;
+    }
+
+    public Reference getArea() {
+        return area;
+    }
+
+    public void setArea(Reference area) {
+        this.area = area;
+    }
+
+    public Reference getMeeting_day() {
+        return meeting_day;
+    }
+
+    public void setMeeting_day(Reference meeting_day) {
+        this.meeting_day = meeting_day;
+    }
+
+    public Reference getMeeting_time() {
+        return meeting_time;
+    }
+
+    public void setMeeting_time(Reference meeting_time) {
+        this.meeting_time = meeting_time;
+    }
+
+    public IndividualReference getCreatedBy() {
+        return createdBy;
+    }
+
+    public void setCreatedBy(IndividualReference createdBy) {
+        this.createdBy = createdBy;
+    }
+
+    public LocalDateTime getCreatedTime() {
+        return createdTime;
+    }
+
+    public void setCreatedTime(LocalDateTime createdTime) {
+        this.createdTime = createdTime;
+    }
+
+    public IndividualReference getModifiedBy() {
+        return modifiedBy;
+    }
+
+    public void setModifiedBy(IndividualReference modifiedBy) {
+        this.modifiedBy = modifiedBy;
+    }
+
+    public LocalDateTime getModifiedTime() {
+        return modifiedTime;
+    }
+
+    public void setModifiedTime(LocalDateTime modifiedTime) {
+        this.modifiedTime = modifiedTime;
+    }
+}
diff --git a/src/main/java/com/p4square/ccbapi/model/InteractionType.java b/src/main/java/com/p4square/ccbapi/model/InteractionType.java
new file mode 100644
index 0000000..85475a3
--- /dev/null
+++ b/src/main/java/com/p4square/ccbapi/model/InteractionType.java
@@ -0,0 +1,12 @@
+package com.p4square.ccbapi.model;
+
+import javax.xml.bind.annotation.XmlEnumValue;
+
+/**
+ * Enumeration of the supported values for the interaction_type field of a GroupProfile.
+ */
+public enum InteractionType {
+    @XmlEnumValue("Announcement Only") ANNOUNCEMENT_ONLY,
+    @XmlEnumValue("Members Interact") MEMBERS_INTERACT,
+    @XmlEnumValue("Administrative") ADMINISTRATIVE;
+}
diff --git a/src/main/java/com/p4square/ccbapi/model/MembershipType.java b/src/main/java/com/p4square/ccbapi/model/MembershipType.java
new file mode 100644
index 0000000..7906aaa
--- /dev/null
+++ b/src/main/java/com/p4square/ccbapi/model/MembershipType.java
@@ -0,0 +1,18 @@
+package com.p4square.ccbapi.model;
+
+import javax.xml.bind.annotation.XmlEnumValue;
+
+/**
+ * Enumeration of the supported values for the membership_type field of a GroupProfile.
+ */
+public enum MembershipType {
+    /**
+     * Membership is open to anyone.
+     */
+    @XmlEnumValue("Open to All") OPEN,
+
+    /**
+     * Membership is moderated (Invitation or Request Required).
+     */
+    @XmlEnumValue("Invitation or Request Required") MODERATED;
+}
diff --git a/src/main/java/com/p4square/ccbapi/model/Reference.java b/src/main/java/com/p4square/ccbapi/model/Reference.java
new file mode 100644
index 0000000..5ac9800
--- /dev/null
+++ b/src/main/java/com/p4square/ccbapi/model/Reference.java
@@ -0,0 +1,34 @@
+package com.p4square.ccbapi.model;
+
+import javax.xml.bind.annotation.XmlAccessType;
+import javax.xml.bind.annotation.XmlAccessorType;
+import javax.xml.bind.annotation.XmlAttribute;
+import javax.xml.bind.annotation.XmlValue;
+
+/**
+ * Generic reference to a id and name.
+ */
+@XmlAccessorType(XmlAccessType.NONE)
+public class Reference {
+    @XmlAttribute(name="id")
+    private int id;
+
+    @XmlValue
+    private String name;
+
+    public int getId() {
+        return id;
+    }
+
+    public void setId(int id) {
+        this.id = id;
+    }
+
+    public String getName() {
+        return name;
+    }
+
+    public void setName(String name) {
+        this.name = name;
+    }
+}