diff --git a/README.md b/README.md index 18d9d6c..39ebcaf 100644 --- a/README.md +++ b/README.md @@ -28,21 +28,21 @@ - [getcookie-java-api](#documentr_heading_0) - [Table of Contents](#documentr_heading_1) - - [Building the Package](#documentr_heading_2) - - [*NIX/Mac OS X](#documentr_heading_3) - - [Windows](#documentr_heading_4) - - [Running the Tests](#documentr_heading_5) - - [*NIX/Mac OS X](#documentr_heading_6) - - [Windows](#documentr_heading_7) - - [Artefact Publishing - Github](#documentr_heading_8) - - [Artefact Publishing - Bintray](#documentr_heading_9) - - [maven setup](#documentr_heading_10) - - [gradle setup](#documentr_heading_11) - - [Dependencies - Gradle](#documentr_heading_12) - - [Dependencies - Maven](#documentr_heading_13) - - [Dependencies - Downloads](#documentr_heading_14) - - [License](#documentr_heading_19) - + - [Usage](#documentr_heading_2) + - [Building the Package](#documentr_heading_3) + - [*NIX/Mac OS X](#documentr_heading_4) + - [Windows](#documentr_heading_5) + - [Running the Tests](#documentr_heading_6) + - [*NIX/Mac OS X](#documentr_heading_7) + - [Windows](#documentr_heading_8) + - [Artefact Publishing - Github](#documentr_heading_9) + - [Artefact Publishing - Bintray](#documentr_heading_10) + - [maven setup](#documentr_heading_11) + - [gradle setup](#documentr_heading_12) + - [Dependencies - Gradle](#documentr_heading_13) + - [Dependencies - Maven](#documentr_heading_14) + - [Dependencies - Downloads](#documentr_heading_15) + - [License](#documentr_heading_20) @@ -50,12 +50,95 @@ -# Building the Package [top](documentr_top) +# Usage [top](documentr_top) + +The getcookie java API offers a **LIMITED, READ ONLY** interface to the +[https://getcookie.com/](https://getcookie.com/) website. You can retrieve: + + - Posts (and comments) from a specific group + - Posts (and comments) from a specific user + +An example is below: + + + + +``` +package synapticloop.getcookie.api.example; + +import java.util.List; + +import synapticloop.getcookie.api.GetCookieApiClient; +import synapticloop.getcookie.api.exception.GetCookieApiException; +import synapticloop.getcookie.api.model.Group; +import synapticloop.getcookie.api.model.Owner; +import synapticloop.getcookie.api.model.Post; +import synapticloop.getcookie.api.model.User; +import synapticloop.getcookie.api.response.GroupPostsResponse; +import synapticloop.getcookie.api.response.UserPostsResponse; + +public class QuickTest { + public static void main(String[] args) throws GetCookieApiException { + GetCookieApiClient getCookieApiClient = new GetCookieApiClient(); + + // get the posts for the 'shower-thoughts' group + + GroupPostsResponse groupPosts = getCookieApiClient.getGroupPosts("shower-thoughts"); + + // due to the JSON data structure - there is an array of groups - which + // only ever has one entry in the array + List groups = groupPosts.getData().getGroups(); + + // get the group + Group group = groups.get(0); + + // now get the posts + List posts = group.getPosts(); + for (Post post : posts) { + // now we can retrieve the information from the post + String title = post.getTitle(); + System.out.println(String.format("[ POST ] title: %s", title)); + + // we can also retrieve who posted it + Owner owner = post.getOwner(); + String username = owner.getUsername(); + + // anonymous posts don't have much information + if(!"anonymous".equals(username)) { + System.out.println(String.format(" [ USER ] name: %s", username)); + System.out.println(String.format(" [ USER ] from: %s", owner.getCountryName())); + + // and get the posts that they have done + UserPostsResponse userPosts = getCookieApiClient.getUserPosts(username); + List users = userPosts.getData().getUsers(); + // once again - there is only one user in the array + User user = users.get(0); + List postsFromUser = user.getPosts(); + for (Post postFromUser : postsFromUser) { + System.out.println(String.format(" [ USER_POST ] title: %s", postFromUser.getTitle())); + } + } else { + System.out.println(String.format(" [ USER ] [ anonymous ]")); + } + } + } +} + +``` + + + +# Building the Package [top](documentr_top) + + + + + ## *NIX/Mac OS X [top](documentr_top) From the root of the project, simply run @@ -65,7 +148,7 @@ From the root of the project, simply run - + ## Windows [top](documentr_top) @@ -78,13 +161,13 @@ Note that this may also run tests (if applicable see the Testing notes) - + # Running the Tests [top](documentr_top) - + ## *NIX/Mac OS X [top](documentr_top) @@ -98,7 +181,7 @@ if you do not have gradle installed, try: - + ## Windows [top](documentr_top) @@ -115,7 +198,7 @@ The `--info` switch will also output logging for the tests - + # Artefact Publishing - Github [top](documentr_top) @@ -127,7 +210,7 @@ As such, this is not a repository, but a location to download files from. - + # Artefact Publishing - Bintray [top](documentr_top) @@ -137,7 +220,7 @@ This project publishes artefacts to [bintray](https://bintray.com/) - + ## maven setup [top](documentr_top) @@ -183,7 +266,7 @@ this comes from the jcenter bintray, to set up your repository: - + ## gradle setup [top](documentr_top) @@ -215,7 +298,7 @@ repositories { - + ## Dependencies - Gradle [top](documentr_top) @@ -223,9 +306,9 @@ repositories { ``` dependencies { - runtime(group: 'synapticloop', name: 'getcookie-java-api', version: '1.0.0', ext: 'jar') + runtime(group: 'synapticloop', name: 'getcookie-java-api', version: '1.0.1', ext: 'jar') - compile(group: 'synapticloop', name: 'getcookie-java-api', version: '1.0.0', ext: 'jar') + compile(group: 'synapticloop', name: 'getcookie-java-api', version: '1.0.1', ext: 'jar') } ``` @@ -237,9 +320,9 @@ or, more simply for versions of gradle greater than 2.1 ``` dependencies { - runtime 'synapticloop:getcookie-java-api:1.0.0' + runtime 'synapticloop:getcookie-java-api:1.0.1' - compile 'synapticloop:getcookie-java-api:1.0.0' + compile 'synapticloop:getcookie-java-api:1.0.1' } ``` @@ -247,7 +330,7 @@ dependencies { - + ## Dependencies - Maven [top](documentr_top) @@ -257,7 +340,7 @@ dependencies { synapticloop getcookie-java-api - 1.0.0 + 1.0.1 jar ``` @@ -266,7 +349,7 @@ dependencies { - + ## Dependencies - Downloads [top](documentr_top) @@ -310,7 +393,7 @@ You will also need to download the following dependencies: - + # License [top](documentr_top) diff --git a/build.gradle b/build.gradle index b0170c6..54c3534 100644 --- a/build.gradle +++ b/build.gradle @@ -13,7 +13,7 @@ plugins { id 'eclipse' id 'maven-publish' id 'co.riiid.gradle' version '0.4.2' - id 'com.jfrog.bintray' version '1.6' + id "com.jfrog.bintray" version "1.7.3" id 'synapticloop.copyrightr' version '1.1.2' id 'synapticloop.documentr' version '2.8.2' @@ -24,7 +24,7 @@ group = 'synapticloop' archivesBaseName = 'getcookie-java-api' description = """A Java API for getcookie.com""" -version = '1.0.0' +version = '1.0.1' sourceCompatibility = 1.8 targetCompatibility = 1.8 @@ -130,7 +130,7 @@ publishing { github { - owner = group + owner = 'synapticloopltd' repo = archivesBaseName if(System.getenv('GITHUB_TOKEN')) { token = System.getenv('GITHUB_TOKEN') @@ -155,4 +155,4 @@ bintray { repo = 'maven' name = 'getcookie-java-api' } -} \ No newline at end of file +} diff --git a/documentr.json b/documentr.json index bd56dd8..5660e8e 100644 --- a/documentr.json +++ b/documentr.json @@ -14,6 +14,12 @@ { "type": "toplink", "value": " " }, { "type": "tocbacktotop", "value": " [top](documentr_top)" }, + { "type":"file", "value":"src/docs/usage-001.md" }, + + { "type": "markup", "value":"\n```\n" }, + { "type": "file", "value":"src/test/java/synapticloop/getcookie/api/example/QuickTest.java" }, + { "type": "markup", "value":"\n```\n" }, + { "type":"inbuilt", "value":"gradle-build" }, { "type":"inbuilt", "value":"gradle-test" }, diff --git a/src/docs/usage-001.md b/src/docs/usage-001.md new file mode 100644 index 0000000..4e74cdc --- /dev/null +++ b/src/docs/usage-001.md @@ -0,0 +1,11 @@ + +# Usage + +The getcookie java API offers a **LIMITED, READ ONLY** interface to the +[https://getcookie.com/](https://getcookie.com/) website. You can retrieve: + + - Posts (and comments) from a specific group + - Posts (and comments) from a specific user + +An example is below: + diff --git a/src/main/java/synapticloop/getcookie/api/GetCookieApiClient.java b/src/main/java/synapticloop/getcookie/api/GetCookieApiClient.java index 1fa15eb..0fa6ec5 100644 --- a/src/main/java/synapticloop/getcookie/api/GetCookieApiClient.java +++ b/src/main/java/synapticloop/getcookie/api/GetCookieApiClient.java @@ -25,6 +25,7 @@ import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.impl.client.HttpClientBuilder; import org.apache.http.impl.client.HttpClients; +import org.apache.http.util.EntityUtils; /* * Copyright (c) 2017 Synapticloop. @@ -137,11 +138,15 @@ public GroupPostsResponse getGroupPosts(String group, Long offset) throws GetCoo * @throws GetCookieApiException if there was an error with the API call. */ public PostResponse getPost(String postId) throws GetCookieApiException { - return(execute(Constants.HTTP_METHOD_GET, - Constants.URL_GETCOOKIE_DOT_COM, - String.format(Constants.PATH_GET_POST, postId), - 200, - PostResponse.class)); + try { + return(execute(Constants.HTTP_METHOD_GET, + Constants.URL_GETCOOKIE_DOT_COM, + String.format(Constants.PATH_GET_POST, postId), + 200, + PostResponse.class)); + } catch(GetCookieApiException ex) { + throw(ex); + } } /** @@ -176,7 +181,11 @@ private T execute(String httpMethod, String url, String path, int allowableS LOGGER.debug("Status code received: {}, wanted: {}.", statusCode, allowableStatusCode); if(null != returnClass) { try { - return parseResponse(response, returnClass); + T parseResponse = parseResponse(response, returnClass); + if( response.getEntity() != null ) { + EntityUtils.consume(response.getEntity()); + } + return parseResponse; } catch (IOException ex) { throw new GetCookieApiException(ex); } diff --git a/src/test/java/synapticloop/getcookie/api/UserTest.java b/src/test/java/synapticloop/getcookie/api/UserTest.java deleted file mode 100644 index 27544d3..0000000 --- a/src/test/java/synapticloop/getcookie/api/UserTest.java +++ /dev/null @@ -1,35 +0,0 @@ -package synapticloop.getcookie.api; - -import java.util.List; - -import org.junit.Before; - -import synapticloop.getcookie.api.exception.GetCookieApiException; -import synapticloop.getcookie.api.model.Post; -import synapticloop.getcookie.api.response.UserPostsResponse; - -public class UserTest { - private GetCookieApiClient getCookieApiClient; - - @Before - public void setup() { - getCookieApiClient = new GetCookieApiClient(); - } - -// @Test - public void testGetUser() throws GetCookieApiException { - UserPostsResponse userPosts = getCookieApiClient.getUserPosts("bob_the_pirate", 0l); - - List posts = userPosts.getData().getUsers().get(0).getPosts(); - - Long nextOffset = userPosts.getData().getUsers().get(0).getNextOffset(); - - while(null != nextOffset) { - getCookieApiClient = new GetCookieApiClient(); - nextOffset = userPosts.getData().getUsers().get(0).getNextOffset(); - userPosts = getCookieApiClient.getUserPosts("bob_the_pirate", nextOffset); - } - - } - -} diff --git a/src/test/java/synapticloop/getcookie/api/example/QuickTest.java b/src/test/java/synapticloop/getcookie/api/example/QuickTest.java new file mode 100644 index 0000000..03d2466 --- /dev/null +++ b/src/test/java/synapticloop/getcookie/api/example/QuickTest.java @@ -0,0 +1,59 @@ +package synapticloop.getcookie.api.example; + +import java.util.List; + +import synapticloop.getcookie.api.GetCookieApiClient; +import synapticloop.getcookie.api.exception.GetCookieApiException; +import synapticloop.getcookie.api.model.Group; +import synapticloop.getcookie.api.model.Owner; +import synapticloop.getcookie.api.model.Post; +import synapticloop.getcookie.api.model.User; +import synapticloop.getcookie.api.response.GroupPostsResponse; +import synapticloop.getcookie.api.response.UserPostsResponse; + +public class QuickTest { + public static void main(String[] args) throws GetCookieApiException { + GetCookieApiClient getCookieApiClient = new GetCookieApiClient(); + + // get the posts for the 'shower-thoughts' group + + GroupPostsResponse groupPosts = getCookieApiClient.getGroupPosts("shower-thoughts"); + + // due to the JSON data structure - there is an array of groups - which + // only ever has one entry in the array + List groups = groupPosts.getData().getGroups(); + + // get the group + Group group = groups.get(0); + + // now get the posts + List posts = group.getPosts(); + for (Post post : posts) { + // now we can retrieve the information from the post + String title = post.getTitle(); + System.out.println(String.format("[ POST ] title: %s", title)); + + // we can also retrieve who posted it + Owner owner = post.getOwner(); + String username = owner.getUsername(); + + // anonymous posts don't have much information + if(!"anonymous".equals(username)) { + System.out.println(String.format(" [ USER ] name: %s", username)); + System.out.println(String.format(" [ USER ] from: %s", owner.getCountryName())); + + // and get the posts that they have done + UserPostsResponse userPosts = getCookieApiClient.getUserPosts(username); + List users = userPosts.getData().getUsers(); + // once again - there is only one user in the array + User user = users.get(0); + List postsFromUser = user.getPosts(); + for (Post postFromUser : postsFromUser) { + System.out.println(String.format(" [ USER_POST ] title: %s", postFromUser.getTitle())); + } + } else { + System.out.println(String.format(" [ USER ] [ anonymous ]")); + } + } + } +}