Added support for push API.

README.md

@@ -214,16 +214,13 @@ If you are not using Maven, you will need these libraries, and their dependencie
 
   * places
   * prefs
+  * push
   * reflection
   * stats
   * tags
   * test
   * urls
 
-## Not Yet Implemented
-
-  * push
-
 
 # BUILDING FROM SOURCE
 To build the project, use Maven. The jar file will end up in the "target" directory:

src/main/java/net/jeremybrooks/jinx/JinxConstants.java

@@ -301,6 +301,15 @@ public enum Period {
     week
   }
 
+  /**
+   * Represents the verification mode.
+   * Used by {@link net.jeremybrooks.jinx.api.PushApi}
+   */
+  public enum VerificationMode {
+    sync,
+    async
+  }
+
   public enum PictureStyle {
     blackandwhite("Black and White"),
     depthoffield("Depth of Field"),

src/main/java/net/jeremybrooks/jinx/api/PushApi.java

@@ -0,0 +1,194 @@
+package net.jeremybrooks.jinx.api;
+
+import net.jeremybrooks.jinx.Jinx;
+import net.jeremybrooks.jinx.JinxConstants;
+import net.jeremybrooks.jinx.JinxException;
+import net.jeremybrooks.jinx.JinxUtils;
+import net.jeremybrooks.jinx.response.Response;
+import net.jeremybrooks.jinx.response.push.Subscriptions;
+import net.jeremybrooks.jinx.response.push.Topics;
+
+import java.util.List;
+import java.util.Map;
+import java.util.TreeMap;
+
+/**
+ * Provides access to the Flickr push API.
+ *
+ * <p>This API is experimental. Check the Flickr documentation before using.</p>
+ *
+ * @author Jeremy Brooks
+ */
+public class PushApi {
+  private Jinx jinx;
+
+  private PushApi() {
+
+  }
+
+  public PushApi(Jinx jinx) {
+    this.jinx = jinx;
+  }
+
+  /**
+   * Returns a list of the subscriptions for the logged-in user.
+   *
+   * (this method is experimental and may change)
+   *
+   * This method requires authentication with 'read' permission.
+   *
+   * @return subscriptions for the logged in user.
+   * @throws JinxException if there are any errors.
+   * @see <a href="https://www.flickr.com/services/api/flickr.push.getSubscriptions.html">flickr.push.getSubscriptions</a>
+   */
+  public Subscriptions getSubscriptions() throws JinxException {
+    Map<String, String> params = new TreeMap<>();
+    params.put("method", "flickr.push.getSubscriptions");
+    return jinx.flickrGet(params, Subscriptions.class);
+  }
+
+  /**
+   * Get all available push topics.
+   *
+   * (this method is experimental and may change)
+   *
+   * This method does not require authentication.
+   *
+   * @return all the different flavors of topics.
+   * @throws JinxException if there are any errors.
+   * @see <a href="https://www.flickr.com/services/api/flickr.push.getTopics.html">flickr.push.getTopics</a>
+   */
+  public Topics getTopics() throws JinxException {
+    Map<String, String> params = new TreeMap<>();
+    params.put("method", "flickr.push.getTopics");
+    return jinx.flickrGet(params, Topics.class);
+  }
+
+
+  /**
+   * Subscribe to a push feed.
+   *
+   * (this method is experimental and may change)
+   *
+   * This method requires authentication with 'read' permission.
+   *
+   * @param topic             the type of subscription. See {@link #getTopics()}. Required.
+   * @param callbackUrl       the url for the subscription endpoint. Limited to 255 bytes, and must be
+   *                          unique for this user, i.e. no two subscriptions for a given user may
+   *                          use the same callback url. Required.
+   * @param mode              verification mode. Required.
+   * @param verificationToken the verification token to be echoed back to the subscriber during the
+   *                          verification callback, as per the Google PubSubHubbub spec.
+   *                          Limited to 200 bytes. Optional.
+   * @param leaseSeconds      number of seconds for which the subscription will be valid. Legal values
+   *                          are 60 to 86400 (1 minute to 1 day). If not present, the subscription will
+   *                          be auto-renewing. Optional.
+   * @param woeIds            a 32-bit integer for a Where on Earth ID. Only valid if topic is geo. The order of
+   *                          precedence for geo subscriptions is : woe ids, place ids,
+   *                          radial i.e. the latitude, longitude parameters will be ignored if placeIds is present,
+   *                          which will be ignored if woeIds is present. Optional.
+   * @param placeIds          a list of Flickr place IDs. Only valid if topic is geo. The order of precedence for
+   *                          geo subscriptions is : woe ids, place ids, radial i.e. the latitude, longitude parameters will be
+   *                          ignored if placeIds is present, which will be ignored if woeIds is present. Optional.
+   * @param latitude          a latitude value, in decimal format. Only valid if topic is geo. Defines the latitude for a
+   *                          radial query centered around (latitude, longitude). The order of precedence for geo
+   *                          subscriptions is : woe ids, place ids, radial i.e. the latitude, longitude parameters will
+   *                          be ignored if placeIds is present, which will be ignored if woeIds is present. Optional.
+   * @param longitude         a longitude value, in decimal format. Only valid if topic is geo. Defines the longitude
+   *                          for a radial query centered around (latitude, longitude). The order of precedence for geo
+   *                          subscriptions is : woe ids, place ids, radial i.e. the latitude, longitude parameters will
+   *                          be ignored if placeIds is present, which will be ignored if woeIds is present. Optional.
+   * @param radius            a radius value, in the units defined by radiusUnits. Only valid if topic is geo. Defines the radius
+   *                          of a circle for a radial query centered around (latitude, longitude). Default is 5 km. The order
+   *                          of precedence for geo subscriptions is : woe ids, place ids, radial i.e. the latitude, longitude
+   *                          parameters will be ignored if placeIds is present, which will be ignored if woeIds is present. Optional.
+   * @param radiusUnits       defines the units for the radius parameter. Only valid if topic is geo.
+   *                          Options are mi and km. Default is km. Optional.
+   * @param accuracy          defines the minimum accuracy required for photos to be included in a subscription. Only valid
+   *                          if topic is geo Legal values are 1-16, default is 1 (i.e. any accuracy level). World level is 1,
+   *                          Country is ~3, Region is ~6, City is ~11, Street is ~16. Optional.
+   * @param commonsNSIDs      a list of nsids representing Flickr Commons institutions. See {@link CommonsApi#getInstitutions()}.
+   *                          Only valid if topic is commons. If not present this argument defaults to all Flickr Commons
+   *                          institutions. Optional.
+   * @param tags              a list of strings to be used for tag subscriptions. Photos with one or more of the tags listed
+   *                          will be included in the subscription. Only valid if the topic is tags. Optional.
+   * @return if successful, response.stat will be "ok".
+   * @throws JinxException if required parameters are missing, or if there are any errors.
+   * @see <a href="https://www.flickr.com/services/api/flickr.push.subscribe.html">flickr.push.subscribe</a>
+   */
+  public Response subscribe(String topic, String callbackUrl, JinxConstants.VerificationMode mode,
+                            String verificationToken, Integer leaseSeconds, Integer woeIds,
+                            List<String> placeIds, Float latitude, Float longitude, Integer radius,
+                            JinxConstants.RadiusUnits radiusUnits, Integer accuracy, List<String> commonsNSIDs,
+                            List<String> tags) throws JinxException {
+    JinxUtils.validateParams(topic, callbackUrl, mode);
+    Map<String, String> params = new TreeMap<>();
+    params.put("method", "flickr.push.subscribe");
+    params.put("topic", topic);
+    params.put("callback", callbackUrl);
+    params.put("verify", mode.toString());
+    if (!JinxUtils.isNullOrEmpty(verificationToken)) {
+      params.put("verify_token", verificationToken);
+    }
+    if (leaseSeconds != null && leaseSeconds > 59) {
+      params.put("lease_seconds", leaseSeconds.toString());
+    }
+    if (woeIds != null) {
+      params.put("woe_ids", woeIds.toString());
+    }
+    if (!JinxUtils.isNullOrEmpty(placeIds)) {
+      params.put("place_ids", JinxUtils.buildCommaDelimitedList(placeIds));
+    }
+    if (latitude != null) {
+      params.put("lat", latitude.toString());
+    }
+    if (longitude != null) {
+      params.put("lon", longitude.toString());
+    }
+    if (radius != null) {
+      params.put("radius", radius.toString());
+    }
+    if (radiusUnits != null) {
+      params.put("radius_units", radiusUnits.toString());
+    }
+    if (accuracy != null) {
+      params.put("accuracy", accuracy.toString());
+    }
+    if (!JinxUtils.isNullOrEmpty(commonsNSIDs)) {
+      params.put("nsids", JinxUtils.buildCommaDelimitedList(commonsNSIDs));
+    }
+    if (!JinxUtils.isNullOrEmpty(tags)) {
+      params.put("tags", JinxUtils.buildCommaDelimitedList(tags));
+    }
+    return jinx.flickrGet(params, Response.class);
+  }
+
+  /**
+   * Unsubscribe from a push feed.
+   *
+   * (this method is experimental and may change)
+   *
+   * This method requires authentication with 'read' permission.
+   *
+   * @param topic             the type of subscription. Required.
+   * @param callbackUrl       url for the subscription endpoint. Must be the same url used when subscribing. Required.
+   * @param mode              verification mode. Required.
+   * @param verificationToken verification token to be echoed back to the subscriber during the
+   *                          verification callback. Optional.
+   * @return if successful, response.stat will be "ok".
+   * @throws JinxException if required parameters are missing, or if there are any errors.
+   * @see <a href="https://www.flickr.com/services/api/flickr.push.unsubscribe.html">flickr.push.unsubscribe</a>
+   */
+  public Response unsubscribe(String topic, String callbackUrl, JinxConstants.VerificationMode mode, String verificationToken) throws JinxException {
+    JinxUtils.validateParams(topic, callbackUrl, mode);
+    Map<String, String> params = new TreeMap<>();
+    params.put("method", "flickr.push.unsubscribe");
+    params.put("topic", topic);
+    params.put("callback", callbackUrl);
+    params.put("verify", mode.toString());
+    if (!JinxUtils.isNullOrEmpty(verificationToken)) {
+      params.put("verify_token", verificationToken);
+    }
+    return jinx.flickrGet(params, Response.class);
+  }
+}

src/main/java/net/jeremybrooks/jinx/response/push/Subscription.java

@@ -0,0 +1,64 @@
+package net.jeremybrooks.jinx.response.push;
+
+import com.google.gson.annotations.SerializedName;
+
+import java.io.Serializable;
+
+/**
+ * @author Jeremy Brooks
+ */
+public class Subscription implements Serializable {
+  private static final long serialVersionUID = 7910161546789424689L;
+  private String topic;
+  private String callback;
+  private Integer pending;
+  @SerializedName("date_create")
+  private Long dateCreate;
+  @SerializedName("lease_seconds")
+  private Integer leaseSeconds;
+  private Long expiry;
+  @SerializedName("verify_attempts")
+  private Integer verifyAttempts;
+
+
+  public String getTopic() {
+    return topic;
+  }
+
+  public String getCallback() {
+    return callback;
+  }
+
+  public Boolean getPending() {
+    return pending != 0;
+  }
+
+  public Long getDateCreate() {
+    return dateCreate;
+  }
+
+  public Integer getLeaseSeconds() {
+    return leaseSeconds;
+  }
+
+  public Long getExpiry() {
+    return expiry;
+  }
+
+  public Integer getVerifyAttempts() {
+    return verifyAttempts;
+  }
+
+  @Override
+  public String toString() {
+    return "net.jeremybrooks.jinx.response.push.Subscription{" +
+        "topic='" + topic + '\'' +
+        ", callback='" + callback + '\'' +
+        ", pending=" + pending +
+        ", dateCreate=" + dateCreate +
+        ", leaseSeconds=" + leaseSeconds +
+        ", expiry=" + expiry +
+        ", verifyAttempts=" + verifyAttempts +
+        '}';
+  }
+}

src/main/java/net/jeremybrooks/jinx/response/push/Subscriptions.java

@@ -0,0 +1,23 @@
+package net.jeremybrooks.jinx.response.push;
+
+import com.google.gson.annotations.SerializedName;
+import net.jeremybrooks.jinx.response.Response;
+
+import java.io.Serializable;
+import java.util.List;
+
+/**
+ * @author Jeremy Brooks
+ */
+public class Subscriptions extends Response {
+  private static final long serialVersionUID = 8630633471818855463L;
+  private _Subscriptions subscriptions;
+
+  public List<Subscription> getSubscriptionList() {return subscriptions == null ? null : subscriptions.subscriptionList; }
+
+  private class _Subscriptions implements Serializable {
+    private static final long serialVersionUID = -8063916700882783263L;
+    @SerializedName("subscription")
+    private List<Subscription> subscriptionList;
+  }
+}

src/main/java/net/jeremybrooks/jinx/response/push/Topic.java

@@ -0,0 +1,32 @@
+package net.jeremybrooks.jinx.response.push;
+
+import com.google.gson.annotations.SerializedName;
+
+import java.io.Serializable;
+
+/**
+ * @author Jeremy Brooks
+ */
+public class Topic implements Serializable {
+  private static final long serialVersionUID = 5023752769353675119L;
+  private String name;
+  @SerializedName("display_name")
+  private String displayName;
+
+
+  public String getName() {
+    return name;
+  }
+
+  public String getDisplayName() {
+    return displayName;
+  }
+
+  @Override
+  public String toString() {
+    return "net.jeremybrooks.jinx.response.push.Topic{" +
+        "name='" + name + '\'' +
+        ", displayName='" + displayName + '\'' +
+        '}';
+  }
+}

src/main/java/net/jeremybrooks/jinx/response/push/Topics.java

@@ -0,0 +1,23 @@
+package net.jeremybrooks.jinx.response.push;
+
+import com.google.gson.annotations.SerializedName;
+import net.jeremybrooks.jinx.response.Response;
+
+import java.io.Serializable;
+import java.util.List;
+
+/**
+ * @author Jeremy Brooks
+ */
+public class Topics extends Response {
+  private static final long serialVersionUID = -2509756704055116533L;
+  private _Topics topics;
+
+  public List<Topic> getTopicList() { return topics == null ? null : topics.topicList; }
+
+  private class _Topics implements Serializable {
+    private static final long serialVersionUID = 2391898605208304028L;
+    @SerializedName("topic")
+    private List<Topic> topicList;
+  }
+}

src/test/java/net/jeremybrooks/jinx/api/PrefsApiTest.java

@@ -27,7 +27,7 @@ public class PrefsApiTest {
   @BeforeClass
   public static void beforeClass() throws Exception {
     Properties p = new Properties();
-    p.load(OAuthApiTest.class.getResourceAsStream("/response/auth/secret.properties"));
+    p.load(PrefsApiTest.class.getResourceAsStream("/response/auth/secret.properties"));
     String filename = p.getProperty("path.to.oauth.token");
     assertNotNull(filename);
     File file = new File(filename);