finish prospect query, add tests

Author: stephen powis

src/main/java/com/darksci/pardot/api/PardotClient.java

@@ -8,6 +8,7 @@
 import com.darksci.pardot.api.parser.email.EmailReadResponseParser;
 import com.darksci.pardot.api.parser.email.EmailStatsResponseParser;
 import com.darksci.pardot.api.parser.login.LoginResponseParser;
+import com.darksci.pardot.api.parser.prospect.ProspectQueryResponseParser;
 import com.darksci.pardot.api.parser.prospect.ProspectReadResponseParser;
 import com.darksci.pardot.api.parser.user.UserAbilitiesParser;
 import com.darksci.pardot.api.parser.user.UserQueryResponseParser;
@@ -23,6 +24,7 @@
 import com.darksci.pardot.api.request.email.EmailSendOneToOneRequest;
 import com.darksci.pardot.api.request.email.EmailStatsRequest;
 import com.darksci.pardot.api.request.login.LoginRequest;
+import com.darksci.pardot.api.request.prospect.ProspectQueryRequest;
 import com.darksci.pardot.api.request.prospect.ProspectReadRequest;
 import com.darksci.pardot.api.request.user.UserAbilitiesRequest;
 import com.darksci.pardot.api.request.user.UserQueryRequest;
@@ -35,6 +37,7 @@
 import com.darksci.pardot.api.response.email.EmailStatsResponse;
 import com.darksci.pardot.api.response.login.LoginResponse;
 import com.darksci.pardot.api.response.prospect.Prospect;
+import com.darksci.pardot.api.response.prospect.ProspectQueryResponse;
 import com.darksci.pardot.api.response.user.User;
 import com.darksci.pardot.api.response.user.UserAbilitiesResponse;
 import com.darksci.pardot.api.response.user.UserQueryResponse;
@@ -174,6 +177,7 @@ private void checkLogin() {
 
     /**
      * Make login request
+     * @param request Login request definition.
      * @return LoginResponse returned from server.
      */
     public LoginResponse login(LoginRequest request) {
@@ -297,6 +301,15 @@ public Prospect prospectRead(final ProspectReadRequest request) {
         return submitRequest(request, new ProspectReadResponseParser());
     }
 
+    /**
+     * Make API request to query prospects.
+     * @param request Request definition.
+     * @return Parsed api response.
+     */
+    public ProspectQueryResponse.Result prospectQuery(final ProspectQueryRequest request) {
+        return submitRequest(request, new ProspectQueryResponseParser());
+    }
+
     /**
      * Clean up instance, releasing any resources held internally.
      */

src/main/java/com/darksci/pardot/api/parser/prospect/ProspectQueryResponseParser.java

@@ -0,0 +1,19 @@
+package com.darksci.pardot.api.parser.prospect;
+
+import com.darksci.pardot.api.parser.JacksonFactory;
+import com.darksci.pardot.api.parser.ResponseParser;
+import com.darksci.pardot.api.response.campaign.CampaignQueryResponse;
+import com.darksci.pardot.api.response.prospect.ProspectQueryResponse;
+
+import java.io.IOException;
+
+/**
+ * Handles parsing ProspectQuery API responses into POJOs.
+ */
+public class ProspectQueryResponseParser implements ResponseParser<ProspectQueryResponse.Result> {
+
+    @Override
+    public ProspectQueryResponse.Result parseResponse(final String responseStr) throws IOException {
+        return JacksonFactory.newInstance().readValue(responseStr, ProspectQueryResponse.class).getResult();
+    }
+}

src/main/java/com/darksci/pardot/api/request/BaseRequest.java

@@ -1,7 +1,10 @@
 package com.darksci.pardot.api.request;
 
+import com.darksci.pardot.api.request.email.EmailSendOneToOneRequest;
+
 import java.util.Collection;
 import java.util.HashMap;
+import java.util.HashSet;
 import java.util.Map;
 
 /**
@@ -39,6 +42,23 @@ protected T setBooleanParam(final String parameterName, final boolean booleanVal
         return setParam(parameterName, booleanValue);
     }
 
+    protected T withCollectionParam(final String name, final Object value) {
+        Collection<Object> values = getParam(name);
+        if (values == null) {
+            values = new HashSet<>();
+        }
+        values.add(value);
+
+        return setParam(name, values);
+    }
+
+    protected T withCollectionParams(final String name, Collection<?> values) {
+        for (final Object value: values) {
+            withCollectionParam(name, value);
+        }
+        return (T) this;
+    }
+
     /**
      * Returns all set RequestParameters for the Request.
      * @return All set Request Parameters generated from Request builder.

src/main/java/com/darksci/pardot/api/request/email/EmailSendOneToOneRequest.java

@@ -112,13 +112,7 @@ public EmailSendOneToOneRequest withReplyToEmail(final String replyToEmail) {
      * @return RequestBuilder
      */
     public EmailSendOneToOneRequest withTag(final String tag) {
-        Collection<String> tags = getParam("tags");
-        if (tags == null) {
-            tags = new HashSet<>();
-        }
-        tags.add(tag);
-
-        return setParam("tags", tags);
+        return withCollectionParam("tags", tag);
     }
 
     /**
@@ -127,10 +121,7 @@ public EmailSendOneToOneRequest withTag(final String tag) {
      * @return RequestBuilder
      */
     public EmailSendOneToOneRequest withTags(Collection<String> tags) {
-        for (final String tag: tags) {
-            withTag(tag);
-        }
-        return this;
+        return withCollectionParams("tags", tags);
     }
 
     /**

src/main/java/com/darksci/pardot/api/request/prospect/ProspectQueryRequest.java

@@ -0,0 +1,268 @@
+package com.darksci.pardot.api.request.prospect;
+
+import com.darksci.pardot.api.request.BaseQueryRequest;
+import com.darksci.pardot.api.request.DateParameter;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.Collection;
+import java.util.stream.Collectors;
+
+/**
+ * Defines a Prospect Query Request.
+ */
+public class ProspectQueryRequest extends BaseQueryRequest<ProspectQueryRequest> {
+
+    @Override
+    public String getApiEndpoint() {
+        return "prospect/do/query";
+    }
+
+    /**
+     * Specifies the fields to be returned. Note: If this parameter isn't present, all default fields and custom fields
+     * for which the prospect has a value will be returned;
+     * id field will always be returned.
+     *
+     * Each call will append the field argument to the list of previously passed fields.
+     *
+     * @param fields Collection of fields to be selected by the request.
+     * @return RequestBuilder
+     */
+    public ProspectQueryRequest withFields(Collection<String> fields) {
+        final String fieldsStr = fields.stream().collect(Collectors.joining( "," ));
+        final String currentValue = getParam("fields");
+        if (currentValue == null) {
+            // set
+            return setParam("fields", fieldsStr);
+        } else {
+            // Append
+            return setParam("fields", currentValue + "," + fieldsStr);
+        }
+    }
+
+    /**
+     * Specifies the fields to be returned. Note: If this parameter isn't present, all default fields and custom fields
+     * for which the prospect has a value will be returned;
+     * id field will always be returned.
+     *
+     * Each call will append the field argument to the list of previously passed fields.
+     *
+     * @param field Field to be selected by request.
+     * @return RequestBuilder
+     */
+    public ProspectQueryRequest withField(final String field) {
+        final String currentValue = getParam("fields");
+        if (currentValue == null) {
+            // set
+            return setParam("fields", field);
+        } else {
+            // Append
+            return setParam("fields", currentValue + "," + field);
+        }
+    }
+
+    /**
+     * Only select prospects who are assigned.
+     * @return RequestBuilder
+     */
+    public ProspectQueryRequest withAssignedOnly() {
+        return setBooleanParam("assigned", true);
+    }
+
+    /**
+     * Only select prospects who are NOT assigned.
+     * @return RequestBuilder
+     */
+    public ProspectQueryRequest withUnassignedOnly() {
+        return setBooleanParam("assigned", false);
+    }
+
+    /**
+     * Only select prospects who are assigned to the specified user, by Id.
+     * @param userId The userId to filter by.
+     * @return RequestBuilder
+     */
+    public ProspectQueryRequest withAssignedUser(final Long userId) {
+        return setParam("assigned_to_user", userId);
+    }
+
+    /**
+     * Only select prospects who are assigned to the specified user, by email address.
+     * @param userEmail The user to filter by, as defined by their Email address.
+     * @return RequestBuilder
+     */
+    public ProspectQueryRequest withAssignUser(final String userEmail) {
+        return setParam("assigned_to_user", userEmail);
+    }
+
+    /**
+     * Only select prospects who are archived.
+     * @return RequestBuilder
+     */
+    public ProspectQueryRequest withArchivedOnly() {
+        return super.withArchivedOnly(true);
+    }
+
+    /**
+     * Only select prospects who are NOT archived. (Default value)
+     * @return RequestBuilder
+     */
+    public ProspectQueryRequest withNotArchivedOnly() {
+        return super.withArchivedOnly(false);
+    }
+
+    /**
+     * Only select prospects who have a grade equal to the specified grade.
+     * @param grade Grade in format of "A", "A+", "B", "C-"
+     * @return RequestBuilder
+     */
+    public ProspectQueryRequest withGradeEqualTo(final String grade) {
+        return setParam("grade_equal_to", grade);
+    }
+
+    /**
+     * Only select prospects who have a grade greater than to the specified grade.
+     * @param grade Grade in format of "A", "A+", "B", "C-"
+     * @return RequestBuilder
+     */
+    public ProspectQueryRequest withGradeGreaterThan(final String grade) {
+        return setParam("grade_greater_than", grade);
+    }
+
+    /**
+     * Only select prospects who have a grade less than the specified grade.
+     * @param grade Grade in format of "A", "A+", "B", "C-"
+     * @return RequestBuilder
+     */
+    public ProspectQueryRequest withGradeLessThan(final String grade) {
+        return setParam("grade_less_than", grade);
+    }
+
+    /**
+     * Only select prospects who have been starred.
+     * @return RequestBuilder
+     */
+    public ProspectQueryRequest withStarredOnly() {
+        return setBooleanParam("is_starred", true);
+    }
+
+    /**
+     * Only select prospects who have NOT been starred.
+     * @return RequestBuilder
+     */
+    public ProspectQueryRequest withNotStarredOnly() {
+        return setBooleanParam("is_starred", false);
+    }
+
+    /**
+     * Only select prospects who have a last activity date after a specified value.
+     * @param lastActivityAfter The date to filter.
+     * @return RequestBuilder
+     */
+    public ProspectQueryRequest withLastActivityAfter(DateParameter lastActivityAfter) {
+        return setParam("last_activity_after", lastActivityAfter);
+    }
+
+    /**
+     * Only select prospects who have no activity.
+     * @return RequestBuilder
+     */
+    public ProspectQueryRequest withNonActiveOnly() {
+        return setBooleanParam("last_activity_never", true);
+    }
+
+    /**
+     * Only select prospects who are member's of the specified list Id.
+     * @param listId Id of List to filter prospects by.
+     * @return RequestBuilder
+     */
+    public ProspectQueryRequest withListId(final Long listId) {
+        return setParam("list_id", listId);
+    }
+
+    /**
+     * Only select prospects who are considered 'new'.
+     * @return RequestBuilder
+     */
+    public ProspectQueryRequest withNewOnly() {
+        return setBooleanParam("new", true);
+    }
+
+    /**
+     * Only select prospects who are NOT considered 'new'.
+     * @return RequestBuilder
+     */
+    public ProspectQueryRequest withNotNewOnly() {
+        return setBooleanParam("new", false);
+    }
+
+    /**
+     * Only select prospects who have have a score equal to the specified value.
+     * @param score Score value to filter by.
+     * @return RequestBuilder
+     */
+    public ProspectQueryRequest withScoreEqualTo(final Integer score) {
+        return setParam("score_equal_to", score);
+    }
+
+    /**
+     * Only select prospects who have have a score greater than the specified value.
+     * @param score Score value to filter by.
+     * @return RequestBuilder
+     */
+    public ProspectQueryRequest withScoreGreaterThan(final Integer score) {
+        return setParam("score_greater_than", score);
+    }
+
+    /**
+     * Only select prospects who have have a score less than the specified value.
+     * @param score Score value to filter by.
+     * @return RequestBuilder
+     */
+    public ProspectQueryRequest withScoreLessThan(final Integer score) {
+        return setParam("score_less_than", score);
+    }
+
+    /**
+     * Sort by CreatedAt.
+     * @return BaseQueryRequest
+     */
+    public ProspectQueryRequest withSortByCreatedAt() {
+        return super.withSortByCreatedAt();
+    }
+
+    /**
+     * Sort results by UpdatedAt.
+     * @return BaseQueryRequest
+     */
+    public ProspectQueryRequest withSortByUpdatedAt() {
+        return super.withSortByUpdatedAt();
+    }
+
+    /**
+     * Sort results by Probability.
+     * @return BaseQueryRequest
+     */
+    public ProspectQueryRequest withSortByProbability() {
+        return withSortBy("probability");
+    }
+
+
+    /**
+     * Sort results by Probability.
+     * @return BaseQueryRequest
+     */
+    public ProspectQueryRequest withSortByLastActivityAt() {
+        return withSortBy("last_activity_at");
+    }
+
+
+    /**
+     * Sort results by Id.
+     * @return BaseQueryRequest
+     */
+    public ProspectQueryRequest withSortById() {
+        return super.withSortById();
+    }
+
+}