Merge pull request #15 from LucaScorpion/rework-to-2.0

Rework to 2.0

Author: LucaScorpion

.gitattributes

@@ -5,62 +5,9 @@
 # Maven
 target/*
 
+# Java
 *.class
-
-# Mobile Tools for Java (J2ME)
-.mtj.tmp/
-
-# Package Files #
 *.jar
-*.war
-*.ear
 
 # virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
 hs_err_pid*
-
-# =========================
-# Operating System Files
-# =========================
-
-# OSX
-# =========================
-
-.DS_Store
-.AppleDouble
-.LSOverride
-
-# Thumbnails
-._*
-
-# Files that might appear on external disk
-.Spotlight-V100
-.Trashes
-
-# Directories potentially created on remote AFP share
-.AppleDB
-.AppleDesktop
-Network Trash Folder
-Temporary Items
-.apdisk
-
-# Windows
-# =========================
-
-# Windows image file caches
-Thumbs.db
-ehthumbs.db
-
-# Folder config file
-Desktop.ini
-
-# Recycle Bin used on file shares
-$RECYCLE.BIN/
-
-# Windows Installer files
-*.cab
-*.msi
-*.msm
-*.msp
-
-# Windows shortcuts
-*.lnk

.gitignore

@@ -0,0 +1,26 @@
+pipeline {
+    agent any
+
+    stages {
+        stage('Clean') {
+            steps {
+                mvn 'clean'
+            }
+        }
+        stage('Build') {
+            steps {
+                mvn 'install'
+            }
+        }
+        stage('Results') {
+            steps {
+                junit '**/target/*-reports/TEST-*.xml'
+            }
+        }
+    }
+}
+
+def mvn(String goals) {
+    def mvnHome = tool 'Maven 3'
+    sh "'${mvnHome}/bin/mvn' -Dmaven.test.failure.ignore $goals"
+}

Jenkinsfile

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016 Scorpiac
+Copyright (c) 2017 Scorpiac
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

LICENSE.md

@@ -1,151 +1,84 @@
 # JavaRant
 A devRant API wrapper for Java.
 
+[![Maven Central](https://img.shields.io/maven-central/v/com.scorpiac.javarant/javarant.svg)](https://mvnrepository.com/artifact/com.scorpiac.javarant/javarant)
+[![Jenkins](https://img.shields.io/jenkins/s/https/jenkins.scorpiac.com/job/JavaRant/job/rework-to-2.0.svg)]()
+[![Jenkins tests](https://img.shields.io/jenkins/t/https/jenkins.scorpiac.com/job/JavaRant/job/rework-to-2.0.svg)]()
+
 ## Using JavaRant
-JavaRant is available on Maven, simply add this dependency to your `pom.xml` file:
+JavaRant is available on [Maven](http://mvnrepository.com/artifact/com.scorpiac.javarant/javarant), simply add this dependency to your `pom.xml` file:
 
-```
+```xml
 <dependency>
 	<groupId>com.scorpiac.javarant</groupId>
 	<artifactId>javarant</artifactId>
-	<version>1.3</version>
+	<version>2.0.0</version>
 </dependency>
 ```
 
-## Class overview
+## Getting started
 
-### DevRant
-This is the main class to interact with devRant.
-To use it, you first need to create an instance of it.
+To access devRant simply create a new `DevRant` object:
 
 ```
 DevRant devRant = new DevRant();
 ```
 
-It can then be used to get rants and collabs from the feed or by searching.
+Most object that are returned from `DevRant` are wrapped in a `Result` object.
+This will contain an optional result value, along with an error message.
+If the optional result is empty, then an error occurred and the error message will be set.
+For example:
 
 ```
-List<Rant> rants = devRant.getRants(Sort.ALGO, 10, 0);
-List<Rant> wtf = devRant.search("wtf");
-List<Rant> weekly = devRant.getWeekly(Sort.TOP(Range.ALL), 20, 0);
-List<Rant> stories = devRant.getStories(Sort.RECENT, 20, 0);
-
-List<Collab> collabs = devRant.getCollabs(10, 0);
+Result<CommentedRant> result = devRant.getRant(832125);
 
-Rant random = devRant.getSurprise();
+if (!result.getValue().isPresent()) {
+    System.out.println("An error occurred: " + result.getError());
+} else {
+    CommentedRant rant = result.getValue().get();
+    System.out.println(rant.getUser().getUsername() + '\n' + rant.getText());
+}
 ```
 
-It can also be used to get specific items based on an id (or username).
-These methods will throw an exception if the specified item does not exist (`NoSuchRantException` for rants and `NoSuchUserException` for users).
-Additionally, `getCollab` will also throw a `NotACollabException` if the requested rant is a normal rant instead of a collab.
+The `DevRant` class itself can be used to get specific rants and users.
 
 ```
-Rant rant = devRant.getRant(422850);
-Collab collab = devRant.getCollab(420025);
+// Get a specific rant.
+Result<CommentedRant> rant = devRant.getRant(686001);
 
-User me = devRant.getUser("LucaScorpion");
-User me2 = devRant.getUser(102959);
+// Get a user by username.
+Result<User> me = devRant.getUser("LucaScorpion");
 ```
 
-To post or vote anything we first need to log in.
-This will make a request to get an authentication token, which is stored for later use.
-Your username and password will _not_ be stored.
-The login method uses `char[]` instead of `String` for the password parameter for security reasons (and most of the times you have a password it should already be in the form of a `char[]`).
+The `DevRant` class contains 2 methods for getting to specific parts of the api.
+First, `getFeed()` which returns a `DevRantFeed` object.
+This is used to access the rant and collab feeds.
 
 ```
-devRant.login("username", "password".toCharArray());
-```
+// Get the 10 latest rants.
+Result<List<Rant>> recent = devRant.getFeed().getRants(Sort.RECENT, 10, 0);
 
-Voting on rants and comments can be done by passing the `Rant` or `Comment` object to vote on, or by directly passing the id.
+// Get the 10 best stories.
+Result<List<Rant>> stories = devRant.getFeed().getStories(Sort.TOP, 0);
 
+// Get 10 collabs.
+Result<List<Collab>> collabs = devRant.getFeed().getCollabs(10);
 ```
-devRant.vote(rant, Vote.DOWN(Reason.NOT_FOR_ME));
-devRant.vote(comment, Vote.NONE);
 
-devRant.voteRant(429863, Vote.UP);
-devRant.voteComment(424558, Vote.UP);
-```
-
-To post a rant you simply need the content and tags.
-To post a comment you need the text and a `Rant` object, or the id of the rant to comment on.
+Second, `getAuth()` which returns a `DevRantAuth` object, which is used to access user functionality.
+Note that a user needs to be logged in before this can be accessed.
 
 ```
-devRant.postRant("Hello world!", "hello, not a rant");
+// Log in to devRant.
+char[] password = "<password>".toCharArray();
+devRant.login("<username>", password);
 
-devRant.postComment(rant, "This is a comment.");
-devRant.postComment(424553, "And another one.");
-```
+// Upvote a rant.
+devRant.getAuth().voteRant(832125, Vote.UP);
 
-You can log out to clear the authorization token.
+// Clear the vote on a comment.
+devRant.getAuth().voteComment(832169, Vote.NONE);
 
-```
+// Log out to clear the token.
 devRant.logout();
 ```
-
-### RantContent
-This is the base class for rants and comments, which have the following attributes:
-
-- id
-- user
-- upvotes
-- downvotes
-- score
-- voteState
-- content
-- image
-
-### Rant
-In addition to the `RantContent` attributes, rants also contain:
-
-- tags
-- commentCount
-- comments
-
-The comments can be accessed by calling `getComments()`.
-This will also fetch them if that has not been done yet.
-Alternatively you can call `fetchComments()` to fetch the comments, or `fetchComments(force)` to force fetch them (i.e. fetch them again).
-
-### Collab
-Collabs are an extension of rants.
-Besides the attributes from a rant, collabs contain the following:
-
-- projectType
-- description
-- techStack
-- teamSize
-- url
-
-Like with a rant the comments can be fetched or force fetched.
-There is also more data which needs to be fetched, similar to the comments this is done by calling `fetchData()` or `fetchData(force)` to force fetch it.
-
-### Comment
-A comment only contains the attributes from `RantContent`.
-
-### Image
-An image has the following attributes:
-
-- url
-- width
-- height
-
-### User
-Users can be get from rants, comments, by id or username.
-When they are get from a rant or comment, only the id, username and score are given.
-The other data will be fetched and stored as soon as it's accessed.
-Alternatively you can fetch the data by calling `fetchData()`, or `fetchData(force)` to force fetch the data (i.e. fetch it again).
-
-### Sort
-These are the different sort options, which are used when getting rants from the feed.
-You can pick between `ALGO`, `RECENT` or `TOP`.
-
-### Range
-The range is used for the `TOP` sorting method.
-The ranges are `DAY`, `WEEK`, `MONTH`, and `ALL`.
-
-### Vote
-These are the different vote options, which are used to vote on rants and comments.
-The vote options are `UP`, `NONE` and `DOWN`.
-
-### Reason
-These are the reasons for a downvote.
-The options are `NOT_FOR_ME`, `REPOST` and `OFFENSIVE_SPAM`.