Merge pull request #2 from jossemarGT/feature/cookie-value-serialize

Feature: Cookie value serialize

.editorconfig

@@ -6,7 +6,8 @@ end_of_line = lf
 indent_style = space
 indent_size = 4
 insert_final_newline = true
+max_line_length = 80
 
 [*.{java,groovy,gradle}]
 trim_trailing_whitespace = true
-max_line_length = 120
+max_line_length = 120

.travis.yml

@@ -1,5 +1,4 @@
 language: java
-script: ./gradlew build
 deploy:
   - provider: script
     script: ./gradlew -Pversion=$TRAVIS_TAG bintrayUpload

README.md

@@ -3,9 +3,73 @@
 > Did you hear about the secure cookie handling in Tornado web framework?
 > There is a twist at the end! ＞▽＜
 
-[Tornado web framework](https://github.com/tornadoweb/tornado) even from early
-releases goes beyond setting cookies' [secure attribute flag](https://tools.ietf.org/html/rfc6265.html#section-5.2.5)
-by [symmetric signing the cookie value](http://www.tornadoweb.org/en/stable/guide/security.html)
-in order to prevent forgery. `cookie-twist` library aims to integrate this
-behavior in Java using plain old [javax.servlet.http.Cookie](https://docs.oracle.com/javaee/6/api/javax/servlet/http/Cookie.html)
+The [Tornado web framework](https://github.com/tornadoweb/tornado) even from
+early releases goes beyond setting the cookies' [secure attribute  flag](https://tools.ietf.org/html/rfc6265.html#section-5.2.5)
+by [symmetric  signing](http://www.tornadoweb.org/en/stable/guide/security.html)
+its value in order to prevent forgery. `cookie-twist` library aims to
+integrate the same behavior in Java by composing a plain old [javax.servlet.http.Cookie](https://docs.oracle.com/javaee/6/api/javax/servlet/http/Cookie.html)
 object.
+
+## Install
+
+Using [maven](https://maven.apache.org/) build tool:
+
+```xml
+<!-- in the pom.xml -->
+<dependencies>
+    <dependency>
+        <groupId>com.jossemargt</groupId>
+        <artifactId>cookie-twist</artifactId>
+        <version>0.1.0</version>
+    </dependency>
+</dependencies>
+```
+
+Using [gradle](https://gradle.org/) build tool:
+
+```groovy
+// In the build.gradle file
+dependencies {
+    // ... Other dependencies
+    compile 'com.jossemargt:cookie-twist:0.1.0'
+}
+```
+
+## Usage
+
+The simplified example:
+
+```java
+import javax.servlet.http.Cookie;
+import com.jossemargt.cookietwist.CookiePot;
+
+public static void main(String[] args){
+    final String mySecretKey = 'like a ninja!';
+
+    // Instantiate your Cookie Pot with your secret key
+    CookiePot tornadoPot = new CookiePot(mySecretKey);
+
+    // Generate a Tornado Signed Secure Cookie (with signing V2 by default);
+    Cookie secureCookie = tornadoPot.encodeCookie(new Cookie('the_name', 'a value'));
+    String hashedValue = secureCookie.getValue();
+
+    // Generate a plain/flat cookie from a  hashed/signed one
+    Cookie flatCookie = tornadoPot.decodeCookie(secureCookie);
+    String flatValue = flatCookie.getValue();
+}
+
+```
+
+## FAQ
+
+**Why should I use this library?** I created `cookie-twist` with the sole goal
+of integrating a Java application with a Python one (that happens to use Tornado
+web framework) in the same distributed ecosystem without making use of some
+heavy solution like [Jython](http://www.jython.org/) or so. If you stumble with
+a similar scenario then go ahead, otherwise I suggest you to stick with the main
+stream `¯\_(ツ)_/¯`
+
+**How about using the word `jar` instead of `pot`?** I thought about it for
+while, but something that I have learned is how important is to *not confuse the
+user*, since the term `jar` is widely used to reference a Java artifact I
+deliberately picked `pot` instead.

build.gradle

@@ -5,10 +5,14 @@ plugins {
     id 'java-library'
     // Built-in gradle tasks and configurations for maven repository publishing
     id 'maven-publish'
+    // Built-in gradle tasks and configurations for Java code linting
+    id 'findbugs'
     // Bintray artifact publishing
     id 'com.jfrog.bintray' version '1.8.0'
     // Auto-magic version from SCM (git) metadata
     id 'net.nemerosa.versioning' version '2.6.1'
+    // A pretty test result logger 
+    id 'com.adarshr.test-logger' version '1.1.2'
 }
 
 group = 'com.jossemargt'
@@ -23,7 +27,22 @@ repositories {
 }
 
 dependencies {
+    api 'javax.servlet:javax.servlet-api:3.1.0'
     testImplementation 'junit:junit:4.12'
+    testImplementation 'pl.pragmatists:JUnitParams:1.1.1'
+}
+
+tasks.withType(FindBugs) {
+    reports {
+        xml.enabled false
+        html.enabled true
+    }
+}
+
+compileTestJava.options.encoding = 'UTF-8'
+
+testlogger {
+    theme 'mocha'
 }
 
 task resolveVersion {

src/main/java/com/jossemargt/cookietwist/CookiePot.java

@@ -0,0 +1,32 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (C) 2018 Jonnatan Jossemar Cordero
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package com.jossemargt.cookietwist;
+
+/**
+ * @author Jonnatan Jossemar Cordero
+ * 
+ */
+public class CookiePot {
+
+}

src/main/java/com/jossemargt/cookietwist/exception/InvalidFormatException.java

@@ -0,0 +1,79 @@
+/*
+ * The MIT License
+ *
+ * Copyright (C) 2018 Jonnatan Jossemar Cordero
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package com.jossemargt.cookietwist.exception;
+
+/**
+ * The Class InvalidFormatException is meant to describe any CookieValue model
+ * de-serialization fault, mostly related to String formatting, numeric parsing
+ * or unexpected amount of String tokens.
+ */
+public class InvalidFormatException extends RuntimeException {
+
+    /**
+     * Serial Version unique identifier constant.
+     */
+    private static final long serialVersionUID = 6562287543509308822L;
+
+    /**
+     * Instantiates a new invalid format exception without message string or cause.
+     */
+    public InvalidFormatException() {
+        super();
+    }
+
+    /**
+     * Instantiates a new invalid format exception with a string message describing
+     * the occurrence.
+     *
+     * @param message
+     *            the description of the occurrence.
+     */
+    public InvalidFormatException(String message) {
+        super(message);
+    }
+
+    /**
+     * Instantiates a new invalid format exception with a string message describing
+     * the occurrence and the Exception that triggered it.
+     *
+     * @param message
+     *            the description of the occurrence.
+     * @param cause
+     *            the Exception which triggered this one.
+     */
+    public InvalidFormatException(String message, Throwable cause) {
+        super(message, cause);
+    }
+
+    /**
+     * Instantiates a new invalid format exception with the one that triggered it.
+     *
+     * @param cause
+     *            the Exception which triggered this one.
+     */
+    public InvalidFormatException(Throwable cause) {
+        super(cause);
+    }
+
+}

src/main/java/com/jossemargt/cookietwist/exception/package-info.java

@@ -0,0 +1,28 @@
+/*
+ * The MIT License
+ *
+ * Copyright (C) 2018 Jonnatan Jossemar Cordero
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+ /**
+ * Contains all the possible Exceptions thrown by cookie-twist library.
+ */
+package com.jossemargt.cookietwist.exception;