Support new resource for interacting with playlists

src/main/java/engineer/nightowl/sonos/api/domain/SonosPlaylist.java

@@ -0,0 +1,120 @@
+package engineer.nightowl.sonos.api.domain;
+
+import org.apache.commons.lang3.builder.EqualsBuilder;
+import org.apache.commons.lang3.builder.HashCodeBuilder;
+
+import java.util.List;
+
+public class SonosPlaylist
+{
+    private String id;
+    private String name;
+    private String type;
+    private Integer trackCount;
+    private List<SonosPlaylistTrack> tracks;
+
+    public SonosPlaylist()
+    {
+    }
+
+    public SonosPlaylist(String id, String name, String type, Integer trackCount, List<SonosPlaylistTrack> tracks)
+    {
+        this.id = id;
+        this.name = name;
+        this.type = type;
+        this.trackCount = trackCount;
+        this.tracks = tracks;
+    }
+
+    public String getId()
+    {
+        return id;
+    }
+
+    public void setId(String id)
+    {
+        this.id = id;
+    }
+
+    public String getName()
+    {
+        return name;
+    }
+
+    public void setName(String name)
+    {
+        this.name = name;
+    }
+
+    public String getType()
+    {
+        return type;
+    }
+
+    public void setType(String type)
+    {
+        this.type = type;
+    }
+
+    public Integer getTrackCount()
+    {
+        return trackCount;
+    }
+
+    public void setTrackCount(Integer trackCount)
+    {
+        this.trackCount = trackCount;
+    }
+
+    public List<SonosPlaylistTrack> getTracks()
+    {
+        return tracks;
+    }
+
+    public void setTracks(List<SonosPlaylistTrack> tracks)
+    {
+        this.tracks = tracks;
+    }
+
+    @Override
+    public String toString()
+    {
+        return "SonosPlaylist{" +
+                "id='" + id + '\'' +
+                ", name='" + name + '\'' +
+                ", type='" + type + '\'' +
+                ", trackCount=" + trackCount +
+                ", tracks=" + tracks +
+                '}';
+    }
+
+    @Override
+    public boolean equals(Object o)
+    {
+        if (this == o) return true;
+
+        if (o == null || getClass() != o.getClass()) return false;
+
+        SonosPlaylist that = (SonosPlaylist) o;
+
+        return new EqualsBuilder()
+                .append(id, that.id)
+                .append(name, that.name)
+                .append(type, that.type)
+                .append(trackCount, that.trackCount)
+                .append(tracks, that.tracks)
+                .isEquals();
+    }
+
+    @Override
+    public int hashCode()
+    {
+        return new HashCodeBuilder(17, 37)
+                .append(id)
+                .append(name)
+                .append(type)
+                .append(trackCount)
+                .append(tracks)
+                .toHashCode();
+    }
+}

src/main/java/engineer/nightowl/sonos/api/domain/SonosPlaylistList.java

@@ -0,0 +1,75 @@
+package engineer.nightowl.sonos.api.domain;
+
+import org.apache.commons.lang3.builder.EqualsBuilder;
+import org.apache.commons.lang3.builder.HashCodeBuilder;
+
+import java.util.List;
+
+public class SonosPlaylistList
+{
+    private String version;
+    private List<SonosPlaylist> playlists;
+
+    public SonosPlaylistList()
+    {
+    }
+
+    public SonosPlaylistList(String version, List<SonosPlaylist> playlists)
+    {
+        this.version = version;
+        this.playlists = playlists;
+    }
+
+    public String getVersion()
+    {
+        return version;
+    }
+
+    public void setVersion(String version)
+    {
+        this.version = version;
+    }
+
+    public List<SonosPlaylist> getPlaylists()
+    {
+        return playlists;
+    }
+
+    public void setPlaylists(List<SonosPlaylist> playlists)
+    {
+        this.playlists = playlists;
+    }
+
+    @Override
+    public String toString()
+    {
+        return "SonosPlaylistList{" +
+                "version='" + version + '\'' +
+                ", playlists=" + playlists +
+                '}';
+    }
+
+    @Override
+    public boolean equals(Object o)
+    {
+        if (this == o) return true;
+
+        if (o == null || getClass() != o.getClass()) return false;
+
+        SonosPlaylistList that = (SonosPlaylistList) o;
+
+        return new EqualsBuilder()
+                .append(version, that.version)
+                .append(playlists, that.playlists)
+                .isEquals();
+    }
+
+    @Override
+    public int hashCode()
+    {
+        return new HashCodeBuilder(17, 37)
+                .append(version)
+                .append(playlists)
+                .toHashCode();
+    }
+}

src/main/java/engineer/nightowl/sonos/api/domain/SonosPlaylistTrack.java

@@ -0,0 +1,88 @@
+package engineer.nightowl.sonos.api.domain;
+
+import org.apache.commons.lang3.builder.EqualsBuilder;
+import org.apache.commons.lang3.builder.HashCodeBuilder;
+
+public class SonosPlaylistTrack
+{
+    private String name;
+    private String artist;
+    private String album;
+
+    public SonosPlaylistTrack()
+    {
+    }
+
+    public SonosPlaylistTrack(String name, String artist, String album)
+    {
+        this.name = name;
+        this.artist = artist;
+        this.album = album;
+    }
+
+    public String getName()
+    {
+        return name;
+    }
+
+    public void setName(String name)
+    {
+        this.name = name;
+    }
+
+    public String getArtist()
+    {
+        return artist;
+    }
+
+    public void setArtist(String artist)
+    {
+        this.artist = artist;
+    }
+
+    public String getAlbum()
+    {
+        return album;
+    }
+
+    public void setAlbum(String album)
+    {
+        this.album = album;
+    }
+
+    @Override
+    public String toString()
+    {
+        return "SonosPlaylistTrack{" +
+                "name='" + name + '\'' +
+                ", artist='" + artist + '\'' +
+                ", album='" + album + '\'' +
+                '}';
+    }
+
+    @Override
+    public boolean equals(Object o)
+    {
+        if (this == o) return true;
+
+        if (o == null || getClass() != o.getClass()) return false;
+
+        SonosPlaylistTrack that = (SonosPlaylistTrack) o;
+
+        return new EqualsBuilder()
+                .append(name, that.name)
+                .append(artist, that.artist)
+                .append(album, that.album)
+                .isEquals();
+    }
+
+    @Override
+    public int hashCode()
+    {
+        return new HashCodeBuilder(17, 37)
+                .append(name)
+                .append(artist)
+                .append(album)
+                .toHashCode();
+    }
+}

src/main/java/engineer/nightowl/sonos/api/resource/PlaylistResource.java

@@ -0,0 +1,99 @@
+package engineer.nightowl.sonos.api.resource;
+
+import engineer.nightowl.sonos.api.SonosApiClient;
+import engineer.nightowl.sonos.api.domain.SonosPlayMode;
+import engineer.nightowl.sonos.api.domain.SonosPlaylist;
+import engineer.nightowl.sonos.api.domain.SonosPlaylistList;
+import engineer.nightowl.sonos.api.domain.SonosSuccess;
+import engineer.nightowl.sonos.api.exception.SonosApiClientException;
+import engineer.nightowl.sonos.api.exception.SonosApiError;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Control playlists in a household.
+ *
+ * @see <a href="https://developer.sonos.com/reference/control-api/playlists/">Sonos docs</a>
+ */
+public class PlaylistResource extends SubscribableResource
+{
+    /**
+     * <p>Constructor for PlaylistResource.</p>
+     *
+     * @param apiClient a {@link engineer.nightowl.sonos.api.SonosApiClient} object.
+     */
+    public PlaylistResource(final SonosApiClient apiClient)
+    {
+        super(apiClient);
+    }
+
+    /** {@inheritDoc} */
+    @Override
+    String getSubscriptionPath()
+    {
+        return "/v1/households/%s/playlists/subscription";
+    }
+
+    /**
+     * Get playlists for a household
+     *
+     * @see <a href="https://developer.sonos.com/reference/control-api/playlists/getplaylists/">Sonos docs</a>
+     * @param clientToken for the user
+     * @param householdId the household for which you want to retrieve playlists
+     * @return the playlists for the specified household
+     * @throws engineer.nightowl.sonos.api.exception.SonosApiClientException if an error occurs during the call
+     * @throws engineer.nightowl.sonos.api.exception.SonosApiError if there is an error from the API
+     */
+    public SonosPlaylistList getPlaylists(final String clientToken, final String householdId) throws SonosApiClientException, SonosApiError
+    {
+        return getFromApi(SonosPlaylistList.class, clientToken, String.format("/v1/households/%s/playlists", householdId));
+    }
+
+    /**
+     * Get a playlist for a household
+     *
+     * @see <a href="https://developer.sonos.com/reference/control-api/playlists/getplaylist/">Sonos docs</a>
+     * @param clientToken for the user
+     * @param householdId the household for which the playlist belongs to
+     * @param playlistId  the specific playlist you want to retrieve
+     * @return the specified playlist
+     * @throws engineer.nightowl.sonos.api.exception.SonosApiClientException if an error occurs during the call
+     * @throws engineer.nightowl.sonos.api.exception.SonosApiError if there is an error from the API
+     */
+    public SonosPlaylist getPlaylist(final String clientToken, final String householdId, final String playlistId) throws SonosApiClientException, SonosApiError
+    {
+        return getFromApi(SonosPlaylist.class, clientToken, String.format("/v1/households/%s/playlists/%s", householdId, playlistId));
+    }
+
+    /**
+     * Activate a playlist in a group
+     *
+     * @see <a href="https://developer.sonos.com/reference/control-api/playlists/loadplaylist/">Sonos docs</a>
+     * @param clientToken for the user
+     * @param groupId to load the playlist in
+     * @param playlistId of the playlist
+     * @param playOnCompletion (optional) start playing once loaded
+     * @param playMode (optional) provide playback options, where supported
+     * @return if the call was successful
+     * @throws engineer.nightowl.sonos.api.exception.SonosApiClientException if an error occurs during the call.
+     * @throws engineer.nightowl.sonos.api.exception.SonosApiError if there is an error from the API.
+     */
+    public SonosSuccess loadPlaylist(final String clientToken, final String groupId, final String playlistId, final Boolean playOnCompletion,
+                                     final SonosPlayMode playMode) throws SonosApiClientException, SonosApiError
+    {
+        validateNotNull(playlistId, "playlistId");
+        final Map<String, Object> payload = new HashMap<>();
+        if (playOnCompletion != null)
+        {
+            payload.put("playOnCompletion", playOnCompletion);
+        }
+        if (playMode != null)
+        {
+            payload.put("playModes", playMode);
+        }
+        payload.put("playlistId", playlistId);
+
+        return postToApi(SonosSuccess.class, clientToken, String.format("/v1/groups/%s/playlists", groupId), payload);
+    }
+}