refactor: modernize timestamps, rename fields, improve javadocs

common/src/main/java/com/github/twitch4j/common/util/TimeUtils.java

@@ -1,6 +1,10 @@
 package com.github.twitch4j.common.util;
 
+import java.time.Instant;
+import java.time.ZoneId;
+import java.time.ZonedDateTime;
 import java.util.Calendar;
+import java.util.GregorianCalendar;
 
 public class TimeUtils {
 
@@ -13,4 +17,12 @@ public static long getCurrentTimeInMillis() {
         return Calendar.getInstance().getTimeInMillis();
     }
 
+    /**
+     * @param time an {@link Instant}
+     * @return a {@link Calendar} instance for the instant, in the system default zone
+     */
+    public static Calendar fromInstant(Instant time) {
+        return GregorianCalendar.from(ZonedDateTime.ofInstant(time, ZoneId.systemDefault()));
+    }
+
 }

pubsub/src/main/java/com/github/twitch4j/pubsub/TwitchPubSub.java

@@ -30,13 +30,9 @@
 
 import java.time.Duration;
 import java.time.Instant;
-import java.time.ZoneId;
-import java.time.ZonedDateTime;
 import java.util.Arrays;
-import java.util.Calendar;
 import java.util.Collection;
 import java.util.Collections;
-import java.util.GregorianCalendar;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
@@ -391,21 +387,15 @@ public void onTextMessage(WebSocket ws, String text) {
                             } else if (topic.startsWith("community-points-channel-v1")) {
                                 String timestampText = msgData.path("timestamp").asText();
                                 Instant instant = Instant.parse(timestampText);
-                                Calendar timestamp = GregorianCalendar.from(
-                                    ZonedDateTime.ofInstant(
-                                        instant,
-                                        ZoneId.systemDefault()
-                                    )
-                                );
 
                                 switch (type) {
                                     case "reward-redeemed":
                                         ChannelPointsRedemption redemption = TypeConvert.convertValue(msgData.path("redemption"), ChannelPointsRedemption.class);
-                                        eventManager.publish(new RewardRedeemedEvent(timestamp, redemption));
+                                        eventManager.publish(new RewardRedeemedEvent(instant, redemption));
                                         break;
                                     case "redemption-status-update":
                                         ChannelPointsRedemption updatedRedemption = TypeConvert.convertValue(msgData.path("redemption"), ChannelPointsRedemption.class);
-                                        eventManager.publish(new RedemptionStatusUpdateEvent(timestamp, updatedRedemption));
+                                        eventManager.publish(new RedemptionStatusUpdateEvent(instant, updatedRedemption));
                                         break;
                                     case "custom-reward-created":
                                         ChannelPointsReward newReward = TypeConvert.convertValue(msgData.path("new_reward"), ChannelPointsReward.class);
@@ -507,9 +497,8 @@ public void onTextMessage(WebSocket ws, String text) {
                                         eventManager.publish(new PointsSpentEvent(pointsSpent));
                                         break;
                                     case "reward-redeemed":
-                                        final Calendar timestamp = GregorianCalendar.from(ZonedDateTime.ofInstant(Instant.parse(msgData.path("timestamp").asText()), ZoneId.systemDefault()));
                                         final ChannelPointsRedemption redemption = TypeConvert.convertValue(msgData.path("redemption"), ChannelPointsRedemption.class);
-                                        eventManager.publish(new RewardRedeemedEvent(timestamp, redemption));
+                                        eventManager.publish(new RewardRedeemedEvent(Instant.parse(msgData.path("timestamp").asText()), redemption));
                                         break;
                                     case "global-last-viewed-content-updated":
                                     case "channel-last-viewed-content-updated":

pubsub/src/main/java/com/github/twitch4j/pubsub/events/ChannelPointsRedemptionEvent.java

@@ -1,10 +1,12 @@
 package com.github.twitch4j.pubsub.events;
 
 import com.github.twitch4j.common.events.TwitchEvent;
+import com.github.twitch4j.common.util.TimeUtils;
 import com.github.twitch4j.pubsub.domain.ChannelPointsRedemption;
 import lombok.Data;
 import lombok.EqualsAndHashCode;
 
+import java.time.Instant;
 import java.util.Calendar;
 
 @Data
@@ -14,11 +16,19 @@ public class ChannelPointsRedemptionEvent extends TwitchEvent {
     /**
      * The time the pubsub message was sent
      */
-    private final Calendar timestamp;
+    private final Instant time;
 
     /**
      * Data about the redemption, includes unique id and user that redeemed it
      */
     private final ChannelPointsRedemption redemption;
 
+    /**
+     * @return the timestamp for this event, in the system default zone
+     * @deprecated in favor of getTime()
+     */
+    @Deprecated
+    public Calendar getTimestamp() {
+        return TimeUtils.fromInstant(time);
+    }
 }

pubsub/src/main/java/com/github/twitch4j/pubsub/events/RedemptionStatusUpdateEvent.java

@@ -4,14 +4,14 @@
 import lombok.EqualsAndHashCode;
 import lombok.ToString;
 
-import java.util.Calendar;
+import java.time.Instant;
 
 @ToString(callSuper = true)
 @EqualsAndHashCode(callSuper = true)
 public class RedemptionStatusUpdateEvent extends ChannelPointsRedemptionEvent {
 
-	public RedemptionStatusUpdateEvent(Calendar timestamp, ChannelPointsRedemption redemption) {
-		super(timestamp, redemption);
-	}
+    public RedemptionStatusUpdateEvent(Instant timestamp, ChannelPointsRedemption redemption) {
+        super(timestamp, redemption);
+    }
 
 }

pubsub/src/main/java/com/github/twitch4j/pubsub/events/RewardRedeemedEvent.java

@@ -4,14 +4,14 @@
 import lombok.EqualsAndHashCode;
 import lombok.ToString;
 
-import java.util.Calendar;
+import java.time.Instant;
 
 @ToString(callSuper = true)
 @EqualsAndHashCode(callSuper = true)
 public class RewardRedeemedEvent extends ChannelPointsRedemptionEvent {
 
-	public RewardRedeemedEvent(Calendar timestamp, ChannelPointsRedemption redemption) {
-		super(timestamp, redemption);
-	}
+    public RewardRedeemedEvent(Instant timestamp, ChannelPointsRedemption redemption) {
+        super(timestamp, redemption);
+    }
 
 }

rest-helix/src/main/java/com/github/twitch4j/helix/TwitchHelix.java

@@ -6,7 +6,7 @@
 import com.netflix.hystrix.HystrixCommand;
 import feign.*;
 
-import java.util.Date;
+import java.time.Instant;
 import java.util.List;
 import java.util.UUID;
 
@@ -289,8 +289,8 @@ HystrixCommand<ClipList> getClips(
         @Param("after") String after,
         @Param("before") String before,
         @Param("first") Integer limit,
-        @Param("started_at") Date startedAt,
-        @Param("ended_at") Date endedAt
+        @Param("started_at") Instant startedAt,
+        @Param("ended_at") Instant endedAt
     );
 
     /**

rest-helix/src/main/java/com/github/twitch4j/helix/domain/AnaylticsDateRange.java

@@ -1,13 +1,14 @@
 package com.github.twitch4j.helix.domain;
 
+import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.databind.PropertyNamingStrategy;
-import com.fasterxml.jackson.databind.annotation.JsonNaming;
+import com.fasterxml.jackson.annotation.JsonProperty;
 import lombok.AccessLevel;
 import lombok.Data;
 import lombok.NoArgsConstructor;
 import lombok.Setter;
 
+import java.time.Instant;
 import java.util.Date;
 
 /**
@@ -16,13 +17,34 @@
 @Data
 @Setter(AccessLevel.PRIVATE)
 @NoArgsConstructor
-@JsonNaming(PropertyNamingStrategy.SnakeCaseStrategy.class)
 @JsonIgnoreProperties(ignoreUnknown = true)
 public class AnaylticsDateRange {
 
     /** Starting date/time for returned reports, in RFC3339 format with the hours, minutes, and seconds zeroed out and the UTC timezone: YYYY-MM-DDT00:00:00Z. */
-    private Date startedAt;
+    @JsonProperty("started_at")
+    private Instant startedAtInstant;
 
     /** Ending date/time for returned reports, in RFC3339 format with the hours, minutes, and seconds zeroed out and the UTC timezone: YYYY-MM-DDT00:00:00Z. */
-    private Date endedAt;
+    @JsonProperty("ended_at")
+    private Instant endedAtInstant;
+
+    /**
+     * @return the starting timestamp for returned reports
+     * @deprecated in favor of getStartedAtInstant()
+     */
+    @JsonIgnore
+    @Deprecated
+    public Date getStartedAt() {
+        return Date.from(startedAtInstant);
+    }
+
+    /**
+     * @return the ending timestamp for returned reports
+     * @deprecated in favor of getEndedAtInstant()
+     */
+    @JsonIgnore
+    @Deprecated
+    public Date getEndedAt() {
+        return Date.from(endedAtInstant);
+    }
 }

rest-helix/src/main/java/com/github/twitch4j/helix/domain/Clip.java

@@ -1,13 +1,16 @@
 package com.github.twitch4j.helix.domain;
 
+import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
 import com.fasterxml.jackson.databind.PropertyNamingStrategy;
 import com.fasterxml.jackson.databind.annotation.JsonNaming;
 import lombok.AccessLevel;
 import lombok.Data;
 import lombok.NoArgsConstructor;
 import lombok.Setter;
 
+import java.time.Instant;
 import java.util.Date;
 
 /**
@@ -51,8 +54,19 @@ public class Clip {
     private Integer viewCount;
 
     /** Date when the clip was created. */
-    private Date createdAt;
+    @JsonProperty("created_at")
+    private Instant createdAtInstant;
 
     /** URL of the clip thumbnail. */
     private String thumbnailUrl;
+
+    /**
+     * @return the timestamp for the clip's creation
+     * @deprecated in favor of getCreatedAtInstant()
+     */
+    @JsonIgnore
+    @Deprecated
+    public Date getCreatedAt() {
+        return Date.from(createdAtInstant);
+    }
 }

rest-helix/src/main/java/com/github/twitch4j/helix/domain/Follow.java

@@ -1,14 +1,18 @@
 package com.github.twitch4j.helix.domain;
 
+import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
 import com.fasterxml.jackson.databind.PropertyNamingStrategy;
 import com.fasterxml.jackson.databind.annotation.JsonNaming;
 import lombok.AccessLevel;
 import lombok.Data;
 import lombok.NoArgsConstructor;
 import lombok.Setter;
 
+import java.time.Instant;
 import java.time.LocalDateTime;
+import java.time.ZoneOffset;
 
 /**
  * Follow
@@ -33,6 +37,17 @@ public class Follow {
     private String toName;
 
     /** Date and time when the from_id user followed the to_id user. */
-    private LocalDateTime followedAt;
+    @JsonProperty("followed_at")
+    private Instant followedAtInstant;
+
+    /**
+     * @return the date and time when the from_id user followed the to_id user.
+     * @deprecated in favor of getFollowedAtInstant
+     */
+    @JsonIgnore
+    @Deprecated
+    public LocalDateTime getFollowedAt() {
+        return LocalDateTime.ofInstant(followedAtInstant, ZoneOffset.UTC);
+    }
 
 }

rest-helix/src/main/java/com/github/twitch4j/helix/domain/Moderator.java

@@ -12,11 +12,11 @@
 @JsonIgnoreProperties(ignoreUnknown = true)
 public class Moderator {
 
-    /** ID of the subscribed user. */
+    /** ID of the moderator. */
     @NonNull
     private String userId;
 
-    /** Login name of the subscribed user. */
+    /** Display name of the moderator. */
     @NonNull
     private String userName;