Merge pull request #15 from Gruncan/v1.3.0

V1.3.0a

Author: Gruncan

pom.xml

@@ -7,7 +7,7 @@
 
     <groupId>com.spotstat</groupId>
     <artifactId>S4J</artifactId>
-    <version>1.1.2a</version>
+    <version>1.2.0a</version>
 
     <properties>
         <maven.compiler.source>17</maven.compiler.source>

src/main/HowRequestsWork.md

@@ -0,0 +1,95 @@
+## Want to add your own request? and serialize them into objects?
+
+1. Simply create a new class with any name you want
+2. Make `AbstractRequest` its super class
+
+```java
+public class MyClass extends AbstractRequest {
+}
+```
+
+3. Annotated it with
+
+```Java 
+@SpotifyRequest("<request>")
+```
+
+replacing `<request>` with the request you are wanting to call E.g. It will be evaluated
+as `"https://api.spotify.com/v1/<request>"`
+
+So for `<request> = albums`,
+
+```java
+
+@SpotifyRequest("albums")
+public class MyClass extends AbstractRequest {
+}
+```
+
+the url will be `"https://api.spotify.com/v1/albums"`
+
+4. If there are variables within the URL like `"https://api.spotify.com/v1/albums/{id}"`
+
+Add `@SpotifySubRequest` to the required field
+
+```java
+@SpotifyRequest("albums")
+public class MyClass extends AbstractRequest {
+
+    @SpotifySubRequest
+    private final String id;
+}
+```
+
+(For SubRequest annotated fields, they will be evaluated in order of declaration in the class, therefore **order
+matters**)
+
+5. For parameters within the url like `https://api.spotify.com/v1/albums/{id}?parameter=value`
+
+Add `@SpotifyRequestField` to the required fields
+
+```java
+@SpotifyRequest("albums")
+public class MyClass extends AbstractRequest {
+
+    @SpotifySubRequest
+    private final String id;
+
+    @SpotifyRequestField
+    private Market market;
+}
+```
+
+Where `parameter = market`, the field name. The `value` is the value within the specific field
+
+So for
+
+```java
+@SpotifyRequest("albums")
+public class MyClass extends AbstractRequest {
+
+    @SpotifySubRequest
+    private final String id = "382ObEPsp2rxGrnsizN5TX";
+
+    @SpotifyRequestField
+    private Market market = Market.ES;
+}
+```
+
+the url will be evaluated as `https://api.spotify.com/v1/albums/382ObEPsp2rxGrnsizN5TX?market=ES`
+
+Fields with types other than String will call `toString`
+
+Fields with the type of array, the array contents will be put into a comma seperated list of their respected string
+contents.
+
+(RequestField will again be evaluated in order of declaration within the class however order doesn't matter with url
+parameters)
+
+and finally to execute the request, after creating a SpotifyClient instance,
+
+```java
+MyClass myClass=new MyClass();
+        SpotifyRepsonse sr=spotifyClient.executeRequest(myClass);
+        JSONObject json=sr.getJsonObject();
+```

src/main/java/com/spotify/SpotifyResponse.java

@@ -27,8 +27,8 @@ public SpotifyResponse(RequestResponse response, Class<? extends SpotifyObject>
 
     }
 
-    public RequestResponse getRequestResponse() {
-        return this.requestResponse;
+    public JSONObject getJsonObject() {
+        return this.requestResponse.ok();
     }
 
     @SuppressWarnings("unchecked")

src/main/java/com/spotify/objects/SpotifySerializer.java

@@ -83,7 +83,6 @@ else if (jsonPath == null || jsonPath.isNull(name))
                     Class<?> componentRawType = fieldType.getComponentType();
                     Class<? extends Serializable> componentType = (Class<? extends Serializable>) componentRawType;
 
-
                     JSONArray jsonArray = jsonPath.getJSONArray(name);
                     field.set(e, this.createArray(componentType, jsonArray));
                 } else {

…va/com/spotify/objects/tracks/Album.java …va/com/spotify/objects/albums/Album.javasrc/main/java/com/spotify/objects/tracks/Album.java renamed to src/main/java/com/spotify/objects/albums/Album.java src/main/java/com/spotify/objects/tracks/Album.java renamed to src/main/java/com/spotify/objects/albums/Album.java

@@ -1,8 +1,9 @@
-package com.spotify.objects.tracks;
+package com.spotify.objects.albums;
 
 import com.spotify.objects.SpotifyField;
 import com.spotify.objects.SpotifyObject;
 import com.spotify.objects.SpotifyOptional;
+import com.spotify.objects.artists.SimplifiedArtist;
 import com.spotify.objects.wrappers.Market;
 import com.spotify.objects.wrappers.SpotifyCopyright;
 import com.spotify.objects.wrappers.SpotifyExternalID;
@@ -23,6 +24,7 @@ public class Album implements SpotifyObject {
     @SpotifyField("total_tracks")
     private int totalTracks;
 
+    @SpotifyOptional
     @SpotifyField("available_markets")
     private Market[] markets;
 
@@ -90,7 +92,7 @@ public String toString() {
         return "Album{" +
                 "albumType='" + albumType + '\'' +
                 ", totalTracks=" + totalTracks +
-                ", markets=" + markets.length +
+                ", markets=" + (this.markets != null ? String.valueOf(markets.length) : "null") +
                 ", externalIDs='" + externalIDs + '\'' +
                 ", href='" + href + '\'' +
                 ", id='" + id + '\'' +

…a/com/spotify/objects/tracks/Artist.java …/com/spotify/objects/artists/Artist.javasrc/main/java/com/spotify/objects/tracks/Artist.java renamed to src/main/java/com/spotify/objects/artists/Artist.java src/main/java/com/spotify/objects/tracks/Artist.java renamed to src/main/java/com/spotify/objects/artists/Artist.java

@@ -1,7 +1,6 @@
-package com.spotify.objects.tracks;
+package com.spotify.objects.artists;
 
 import com.spotify.objects.SpotifyField;
-import com.spotify.objects.SpotifyObject;
 import com.spotify.objects.SpotifyOptional;
 import com.spotify.objects.wrappers.SpotifyImage;
 import lombok.Getter;
@@ -11,22 +10,19 @@
 
 @Getter
 @Setter
-public class Artist extends SimplifiedArtist implements SpotifyObject {
+@SpotifyOptional
+public class Artist extends SimplifiedArtist {
 
 
-    @SpotifyOptional
     @SpotifyField(value = "total", path = {"followers"})
     private int followers;
 
-    @SpotifyOptional
     @SpotifyField
     private String[] genres;
 
-    @SpotifyOptional
     @SpotifyField
     private SpotifyImage[] images;
 
-    @SpotifyOptional
     @SpotifyField
     private int popularity;
 

…ify/objects/tracks/SimplifiedArtist.java …fy/objects/artists/SimplifiedArtist.javasrc/main/java/com/spotify/objects/tracks/SimplifiedArtist.java renamed to src/main/java/com/spotify/objects/artists/SimplifiedArtist.java src/main/java/com/spotify/objects/tracks/SimplifiedArtist.java renamed to src/main/java/com/spotify/objects/artists/SimplifiedArtist.java

@@ -1,4 +1,4 @@
-package com.spotify.objects.tracks;
+package com.spotify.objects.artists;
 
 import com.spotify.objects.SpotifyField;
 import com.spotify.objects.SpotifyObject;

src/main/java/com/spotify/objects/audiobooks/Audiobook.java

@@ -0,0 +1,10 @@
+package com.spotify.objects.audiobooks;
+
+import com.spotify.objects.SpotifyObject;
+
+public class Audiobook implements SpotifyObject {
+
+    public Audiobook() {
+    }
+
+}

src/main/java/com/spotify/objects/episodes/Episode.java

@@ -0,0 +1,10 @@
+package com.spotify.objects.episodes;
+
+import com.spotify.objects.SpotifyObject;
+
+public class Episode implements SpotifyObject {
+
+    public Episode() {
+    }
+
+}

src/main/java/com/spotify/objects/playlists/Playlist.java

@@ -0,0 +1,10 @@
+package com.spotify.objects.playlists;
+
+import com.spotify.objects.SpotifyObject;
+
+public class Playlist implements SpotifyObject {
+
+
+    public Playlist() {
+    }
+}