From 9bab900b653a13d7926ff25cc9093799499e1f58 Mon Sep 17 00:00:00 2001 From: Fagner Brack Date: Tue, 9 Jun 2015 22:53:20 -0300 Subject: [PATCH 01/20] Add basic usage --- README.md | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 65 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 747a730..f3b8fe1 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,66 @@ # Java Cookie -A simple Java Servlet API for handling cookies + +A simple Java API for handling cookies + +## Basic Usage + +Create a cookie, valid across the entire site + +```java +Cookies cookies = Cookies.initFromServlet( request, response ); +cookies.set( "name", "value" ); +``` + +Create a cookie that expires 7 days from now, valid across the entire site: + +```java +Cookies cookies = Cookies.initFromServlet( request, response ); +cookies.set( "name", "value", Attributes.empty() + .expires( Expiration.days( 7 ) ) +); +``` + +Create an expiring cookie, valid to the path of the current page: + +```java +Cookies cookies = Cookies.initFromServlet( request, response ); +cookies.set( "name", "value", Attributes.empty() + .expires( Expiration.days( 7 ) ) + .path( "" ) +); +``` + +Read cookie: + +```java +Cookies cookies = Cookies.initFromServlet( request, response ); +cookies.get( "name" ); // => "value" +cookies.get( "nothing" ); // => null +``` + +Read all available cookies: + +```java +Cookies cookies = Cookies.initFromServlet( request, response ); +Map all = cookies.get(); // => {name=value} +``` + +Delete cookie: + +```java +Cookies cookies = Cookies.initFromServlet( request, response ); +cookies.remove( "name" ); +``` + +Delete a cookie valid to the path of the current page: + +```java +Cookies cookies = Cookies.initFromServlet( request, response ); +cookies.set( "name", "value", Attributes.empty() + .path( "" ) +); +cookies.remove( "name" ); // fail! +cookies.remove( "name", Attributes.empty().path( "path" ) ); // removed! +``` + +*IMPORTANT! when deleting a cookie, you must pass the exact same path, domain and secure attributes that were used to set the cookie, unless you're relying on the [default attributes](#cookie-attributes).* From 71d1553e187055a57729ec95ac676337322b5095 Mon Sep 17 00:00:00 2001 From: Fagner Brack Date: Tue, 9 Jun 2015 23:23:03 -0300 Subject: [PATCH 02/20] Add JSON and Data Binding docs --- README.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/README.md b/README.md index f3b8fe1..aa7045f 100644 --- a/README.md +++ b/README.md @@ -64,3 +64,47 @@ cookies.remove( "name", Attributes.empty().path( "path" ) ); // removed! ``` *IMPORTANT! when deleting a cookie, you must pass the exact same path, domain and secure attributes that were used to set the cookie, unless you're relying on the [default attributes](#cookie-attributes).* + +## JSON and Data Binding + +java-cookie provides unobstrusive JSON storage for cookies and data binding. + +When creating a cookie, you can pass an Object instead of String in the value. If you do so, java-cookie will store the stringified JSON representation of the value using [jackson databind](https://github.com/FasterXML/jackson-databind/#use-it). + +Consider the following class: + +```java +public class Person { + private int age; + public Person( int age ) { + this.age = age; + } + public int getAge() { + return age; + } +} +``` + +And the following usage: + +```java +Cookies cookies = Cookies.initFromServlet( request, response ); +cookies.set( "name", new Person( 25 ) ); +``` + +When reading a cookie with the default `get()` api, you receive the string representation stored in the cookie: + +```java +Cookies cookies = Cookies.initFromServlet( request, response ); +String value = cookies.get( "name" ); // => "{\"age\":25}" +``` + +If you pass the type reference, it will parse the JSON into a new instance: + +```java +Cookies cookies = Cookies.initFromServlet( request, response ); +Person adult = cookies.get( "name", Person.class ); +if ( adult != null ) { + adult.getAge(); // => 25 +} +``` From c2e426f3aac9c50bd79d29edad6b5e4aaa847355 Mon Sep 17 00:00:00 2001 From: Fagner Brack Date: Tue, 9 Jun 2015 23:24:42 -0300 Subject: [PATCH 03/20] Add encoding docs (same as js-cookie) --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index aa7045f..dd4ef08 100644 --- a/README.md +++ b/README.md @@ -108,3 +108,9 @@ if ( adult != null ) { adult.getAge(); // => 25 } ``` + +## Encoding + +This project is [RFC 6265](http://tools.ietf.org/html/rfc6265#section-4.1.1) compliant. All special characters that are not allowed in the cookie-name or cookie-value are encoded with each one's UTF-8 Hex equivalent using [percent-encoding](http://en.wikipedia.org/wiki/Percent-encoding). +The only character in cookie-name or cookie-value that is allowed and still encoded is the percent `%` character, it is escaped in order to interpret percent input as literal. +To override the default cookie decoding you need to use a [converter](#converter). From ff5c2b5cbed4dca0044bdedba2b533530a5a5a3d Mon Sep 17 00:00:00 2001 From: Fagner Brack Date: Tue, 9 Jun 2015 23:34:10 -0300 Subject: [PATCH 04/20] Add docs for default attributes --- README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/README.md b/README.md index dd4ef08..ac1c39a 100644 --- a/README.md +++ b/README.md @@ -114,3 +114,17 @@ if ( adult != null ) { This project is [RFC 6265](http://tools.ietf.org/html/rfc6265#section-4.1.1) compliant. All special characters that are not allowed in the cookie-name or cookie-value are encoded with each one's UTF-8 Hex equivalent using [percent-encoding](http://en.wikipedia.org/wiki/Percent-encoding). The only character in cookie-name or cookie-value that is allowed and still encoded is the percent `%` character, it is escaped in order to interpret percent input as literal. To override the default cookie decoding you need to use a [converter](#converter). + +## Cookie Attributes + +the default cookie attributes can be set globally by setting properties of the `.defaults()` instance or individually for each call to `.set(...)` by passing an `Attributes` instance in the last argument. Per-call attributes override the default attributes. + +```java +Cookies cookies = Cookies.initFromServlet( request, response ); +cookies.defaults() + .secure( true ) + .httpOnly( true ); +cookies.set( "name", "value", Attributes.empty() + .httpOnly( false ) // override defaults +); +``` From a1f52ffb9c8da06fbfe7ec81917fe82559124a3f Mon Sep 17 00:00:00 2001 From: Fagner Brack Date: Thu, 11 Jun 2015 22:11:19 -0300 Subject: [PATCH 05/20] Add expiration docs --- README.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/README.md b/README.md index ac1c39a..1e08cad 100644 --- a/README.md +++ b/README.md @@ -128,3 +128,20 @@ cookies.set( "name", "value", Attributes.empty() .httpOnly( false ) // override defaults ); ``` + +### expires + +Define when the cookie will be removed. Value can be an `Expiration.days()` which will be interpreted as days from time of creation, a `java.util.Date` or an `org.joda.time.DateTime` instance. If omitted, the cookie becomes a session cookie. + +**Default:** Cookie is removed when the user closes the browser. + +**Examples:** + +```java +DateTime date_2015_06_07_23h38m46s = new DateTime( 2015, 6, 7, 23, 38, 46 ); +cookies.set( "name", "value", Attributes.empty() + .expires( Expiration.date( date_2015_06_07_23h38m46s ) ) +); +cookies.get( "name" ); // => "value" +cookies.remove( "name" ); +``` From 4e66c8aeb7669c9c8fc9eeb61feff05480d3bc7e Mon Sep 17 00:00:00 2001 From: Fagner Brack Date: Thu, 11 Jun 2015 22:17:31 -0300 Subject: [PATCH 06/20] Add path docs --- README.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/README.md b/README.md index 1e08cad..e3aac90 100644 --- a/README.md +++ b/README.md @@ -139,9 +139,26 @@ Define when the cookie will be removed. Value can be an `Expiration.days()` whic ```java DateTime date_2015_06_07_23h38m46s = new DateTime( 2015, 6, 7, 23, 38, 46 ); +Cookies cookies = Cookies.initFromServlet( request, response ); cookies.set( "name", "value", Attributes.empty() .expires( Expiration.date( date_2015_06_07_23h38m46s ) ) ); cookies.get( "name" ); // => "value" cookies.remove( "name" ); ``` + +### path + +Define the path where the cookie is available. + +**Default:** `/` + +**Examples:** + +```java +Cookies cookies = Cookies.initFromServlet( request, response ); +Attributes validToTheCurrentPage = Attributes.empty().path( "" ); +cookies.set( "name", "value", validToTheCurrentPath ); +cookies.get( "name" ); // => "value" +cookies.remove( "name", validToTheCurrentPath ); +``` From 033aac4667b532981b0ffa38b3524168003893ec Mon Sep 17 00:00:00 2001 From: Fagner Brack Date: Thu, 11 Jun 2015 22:20:30 -0300 Subject: [PATCH 07/20] Add domain docs --- README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/README.md b/README.md index e3aac90..f1a4258 100644 --- a/README.md +++ b/README.md @@ -162,3 +162,17 @@ cookies.set( "name", "value", validToTheCurrentPath ); cookies.get( "name" ); // => "value" cookies.remove( "name", validToTheCurrentPath ); ``` + +### domain + +Define the domain where the cookie is available + +**Default:** Domain of the page where the cookie was created + +**Examples:** + +```java +Cookies cookies = Cookies.initFromServlet( request, response ); +cookies.set( "name", "value", Attributes.empty().domain( "sub.domain.com" ) ); +cookies.get( "name" ); // => null (need to read at "sub.domain.com") +``` From d3165064d168ea4ed94612121f338d3926f5f6e2 Mon Sep 17 00:00:00 2001 From: Fagner Brack Date: Thu, 11 Jun 2015 22:24:46 -0300 Subject: [PATCH 08/20] Add docs for secure attribute --- README.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/README.md b/README.md index f1a4258..1919915 100644 --- a/README.md +++ b/README.md @@ -176,3 +176,19 @@ Cookies cookies = Cookies.initFromServlet( request, response ); cookies.set( "name", "value", Attributes.empty().domain( "sub.domain.com" ) ); cookies.get( "name" ); // => null (need to read at "sub.domain.com") ``` + +### secure + +A `Boolean` indicating if the cookie transmission requires a secure protocol (https) + +**Default:** No secure protocol requirement + +**Examples:** + +```java +Cookies cookies = Cookies.initFromServlet( request, response ); +Attributes secureCookie = Attributes.empty().secure( true ); +cookies.set( "name", "value", secureCookie ); +cookies.get( "name" ); // => "value" +cookies.remove( "name", secureCookie ); +``` From 96bcae2d63baf470876f5f9192afb75ab4f70cc0 Mon Sep 17 00:00:00 2001 From: Fagner Brack Date: Thu, 11 Jun 2015 22:31:25 -0300 Subject: [PATCH 09/20] Add docs for http only attribute --- README.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/README.md b/README.md index 1919915..fda5171 100644 --- a/README.md +++ b/README.md @@ -192,3 +192,19 @@ cookies.set( "name", "value", secureCookie ); cookies.get( "name" ); // => "value" cookies.remove( "name", secureCookie ); ``` + +### httpOnly + +A `Boolean` indicating if the cookie should be restricted to be manipulated only in the server. + +**Default:** The cookie can be manipulated in the server and in the client + +**Examples:** + +```java +Cookies cookies = Cookies.initFromServlet( request, response ); +Attributes httpOnlyCookie = Attributes.empty().httpOnly( true ); +cookies.set( "name", "value", httpOnlyCookie ); +cookies.get( "name" ); // => "value" +cookies.remove( "name", httpOnlyCookie ); +``` From 6a03ca06f1cfbdfec04f66954feb51e5d8ce1a66 Mon Sep 17 00:00:00 2001 From: Fagner Brack Date: Thu, 11 Jun 2015 22:40:41 -0300 Subject: [PATCH 10/20] Add docs for inline converter strategy --- README.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/README.md b/README.md index fda5171..4f3f9ff 100644 --- a/README.md +++ b/README.md @@ -208,3 +208,36 @@ cookies.set( "name", "value", httpOnlyCookie ); cookies.get( "name" ); // => "value" cookies.remove( "name", httpOnlyCookie ); ``` + +## Converter + +Create a new instance of the api that overrides the default decoding implementation. +All methods that rely in a proper decoding to work, such as `remove()` and `get()`, will run the converter first for each cookie. +The returning String will be used as the cookie value. + +Example from reading one of the cookies that can only be decoded using the Javascript `escape` function: + +``` java +// document.cookie = 'escaped=%u5317'; +// document.cookie = 'default=%E5%8C%97'; + +Cookies cookies = Cookies.initFromServlet( request, response ); +Cookies escapedCookies = cookies.withConverter(new Cookies.Converter() { + @Override + public String convert( String value, String name ) throws ConverterException { + ScriptEngine javascript = new ScriptEngineManager().getEngineByName( "JavaScript" ); + if ( name.equals( "escaped" ) ) { + try { + return javascript.eval( "unescape('" + value + "')" ).toString(); + } catch ( ScriptException e ) { + throw new ConverterException( e ); + } + } + return null; + } +}); + +escapedCookies.get( "escaped" ); // => 北 +escapedCookies.get( "default" ); // => 北 +escapedCookies.get(); // => {escaped=北, default=北} +``` From a0d12aa9198ba5e95ed54bc2e3863aac618a9afe Mon Sep 17 00:00:00 2001 From: Fagner Brack Date: Thu, 11 Jun 2015 22:52:18 -0300 Subject: [PATCH 11/20] Add docs for the converter strategy --- README.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/README.md b/README.md index 4f3f9ff..1bc9930 100644 --- a/README.md +++ b/README.md @@ -241,3 +241,19 @@ escapedCookies.get( "escaped" ); // => 北 escapedCookies.get( "default" ); // => 北 escapedCookies.get(); // => {escaped=北, default=北} ``` + +Instead of passing a converter inline, you can also create a custom strategy by implementing the `ConverterStrategy` interface: + +```java +class CustomConverter implements ConverterStrategy { + @Override + public String convert( String value, String name ) throws ConverterException { + return value; + } +} +``` + +```java +Cookies cookies = Cookies.initFromServlet( request, response ); +Cookies cookiesWithCustomConverter = cookies.withConverter( new CustomConverter() ); +``` From 39bcc47200ba5a5f9aa2659f731620a4811078a0 Mon Sep 17 00:00:00 2001 From: Fagner Date: Thu, 11 Jun 2015 22:56:46 -0300 Subject: [PATCH 12/20] Fix some visibility issues to comply with the docs --- src/main/java/org/jscookie/ConverterStrategy.java | 2 +- .../java/org/jscookie/CookieParseException.java | 4 +++- .../org/jscookie/CookieSerializationException.java | 2 ++ .../jscookie/test/unit/CookiesConverterTest.java | 13 +++++++++++++ 4 files changed, 19 insertions(+), 2 deletions(-) diff --git a/src/main/java/org/jscookie/ConverterStrategy.java b/src/main/java/org/jscookie/ConverterStrategy.java index bc2c7ce..f16a5b8 100644 --- a/src/main/java/org/jscookie/ConverterStrategy.java +++ b/src/main/java/org/jscookie/ConverterStrategy.java @@ -1,6 +1,6 @@ package org.jscookie; -interface ConverterStrategy { +public interface ConverterStrategy { /** * Apply the decoding strategy of a cookie. The return will be used as the cookie value * diff --git a/src/main/java/org/jscookie/CookieParseException.java b/src/main/java/org/jscookie/CookieParseException.java index 8d951c9..c6ebec9 100644 --- a/src/main/java/org/jscookie/CookieParseException.java +++ b/src/main/java/org/jscookie/CookieParseException.java @@ -1,7 +1,9 @@ package org.jscookie; -public class CookieParseException extends Exception { +public final class CookieParseException extends Exception { private static final long serialVersionUID = 1; + @SuppressWarnings( "unused" ) + private CookieParseException() {} CookieParseException( Throwable cause ) { super( cause ); } diff --git a/src/main/java/org/jscookie/CookieSerializationException.java b/src/main/java/org/jscookie/CookieSerializationException.java index 7a5d3cb..4463161 100644 --- a/src/main/java/org/jscookie/CookieSerializationException.java +++ b/src/main/java/org/jscookie/CookieSerializationException.java @@ -2,6 +2,8 @@ public class CookieSerializationException extends Exception { private static final long serialVersionUID = 1; + @SuppressWarnings( "unused" ) + private CookieSerializationException() {} CookieSerializationException( Throwable cause ) { super( cause ); } diff --git a/src/test/java/org/jscookie/test/unit/CookiesConverterTest.java b/src/test/java/org/jscookie/test/unit/CookiesConverterTest.java index 9e7d922..7f46cd2 100644 --- a/src/test/java/org/jscookie/test/unit/CookiesConverterTest.java +++ b/src/test/java/org/jscookie/test/unit/CookiesConverterTest.java @@ -5,6 +5,7 @@ import javax.script.ScriptException; import org.jscookie.ConverterException; +import org.jscookie.ConverterStrategy; import org.jscookie.Cookies; import org.jscookie.test.unit.utils.BaseTest; import org.junit.Assert; @@ -51,4 +52,16 @@ public String convert( String value, String name ) throws ConverterException { expected = "京"; Assert.assertEquals( expected, actual ); } + + @Test + public void should_be_able_to_create_a_custom_strategy() { + this.cookies.withConverter( new CustomConverter() ); + } + + private class CustomConverter implements ConverterStrategy { + @Override + public String convert( String value, String name ) throws ConverterException { + return value; + } + } } From 572a714524412066cdf74c684062f32a456a39b5 Mon Sep 17 00:00:00 2001 From: Fagner Brack Date: Fri, 12 Jun 2015 23:44:53 -0300 Subject: [PATCH 13/20] Document the CookieValue interface --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 1bc9930..0fef841 100644 --- a/README.md +++ b/README.md @@ -69,12 +69,12 @@ cookies.remove( "name", Attributes.empty().path( "path" ) ); // removed! java-cookie provides unobstrusive JSON storage for cookies and data binding. -When creating a cookie, you can pass an Object instead of String in the value. If you do so, java-cookie will store the stringified JSON representation of the value using [jackson databind](https://github.com/FasterXML/jackson-databind/#use-it). +When creating a cookie, you can pass a few supported types instead of String in the value. If you do so, java-cookie will store the stringified JSON representation of the value using [jackson databind](https://github.com/FasterXML/jackson-databind/#use-it). -Consider the following class: +Consider the following class that implements the `CookieValue` interface: ```java -public class Person { +public class Person implements CookieValue { private int age; public Person( int age ) { this.age = age; From e539e9e33d92f1caa954971f4508f537ab9acca0 Mon Sep 17 00:00:00 2001 From: Fagner Brack Date: Fri, 12 Jun 2015 23:49:09 -0300 Subject: [PATCH 14/20] Link the CONTRIBUTING.md file --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 0fef841..c909692 100644 --- a/README.md +++ b/README.md @@ -257,3 +257,7 @@ class CustomConverter implements ConverterStrategy { Cookies cookies = Cookies.initFromServlet( request, response ); Cookies cookiesWithCustomConverter = cookies.withConverter( new CustomConverter() ); ``` + +## Contributing + +Check out the [Contributing Guidelines](CONTRIBUTING.md). From 0d31e8c03316002937d6cf429bb7d74a38506467 Mon Sep 17 00:00:00 2001 From: Fagner Brack Date: Fri, 12 Jun 2015 23:57:12 -0300 Subject: [PATCH 15/20] Create CONTRIBUTING.md --- CONTRIBUTING.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..d6306ab --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,13 @@ +## Issues + +- Report issues or feature requests on [GitHub Issues](https://github.com/js-cookie/java-cookie/issues). +- If reporting a bug, please add a [simplified example](http://sscce.org/). + +## Pull requests +- Create a new topic branch for every separate change you make. +- Create a test case if you are fixing a bug or implementing an important feature. +- Make sure the build runs successfully [(see below)](#development). + +## Development + +// TODO From 6352baf65da38a492a064082079329f603f04549 Mon Sep 17 00:00:00 2001 From: Fagner Brack Date: Sat, 13 Jun 2015 17:22:30 -0300 Subject: [PATCH 16/20] Add docs to build the project --- CONTRIBUTING.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d6306ab..07b4883 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,4 +10,24 @@ ## Development -// TODO +### Tools +We use the following tools for development: + +- [Maven](https://maven.apache.org/) for Java Build. +- [NodeJS](http://nodejs.org/download/) required to run grunt. +- [Grunt](http://gruntjs.com/getting-started) for JavaScript task management. + +### Getting started + +Install [NodeJS](http://nodejs.org/). +Install [Maven](https://maven.apache.org/download.cgi) and add `mvn` as a global alias to run the `/bin/mvn` command inside Maven folder. + +Browse to the project root directory and run the build: + + $ mvn install + +After the build completes you should be the following message in the console: + + ---------------------------------------------------------------------------- + BUILD SUCCESS + ---------------------------------------------------------------------------- From b8b8f03bce04b90a612456eb73abacc9b8df72a1 Mon Sep 17 00:00:00 2001 From: Fagner Brack Date: Sat, 13 Jun 2015 17:42:49 -0300 Subject: [PATCH 17/20] typo --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 07b4883..66e799b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,7 +26,7 @@ Browse to the project root directory and run the build: $ mvn install -After the build completes you should be the following message in the console: +After the build completes, you should see the following message in the console: ---------------------------------------------------------------------------- BUILD SUCCESS From 0a8b7d96aebe5fa4bca57a426dadc867b7adc012 Mon Sep 17 00:00:00 2001 From: Fagner Brack Date: Sat, 13 Jun 2015 18:01:17 -0300 Subject: [PATCH 18/20] Add docs for running the tests --- CONTRIBUTING.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 66e799b..9b73891 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,3 +31,16 @@ After the build completes, you should see the following message in the console: ---------------------------------------------------------------------------- BUILD SUCCESS ---------------------------------------------------------------------------- + +### Tests +When executing the build, maven runs all unit and integration tests. + +To run the unit tests separately, execute the following command: + + $ mvn test + +If you want to debug the integration tests in the browser, switch `Debug.FALSE` to `Debug.TRUE` in `CookiesEncodingIT.java` and run the build: + + $ mvn install + +[Arquillian](http://arquillian.org/) will start the server, [Selenium](http://www.seleniumhq.org/) will run the tests in Firefox, but the build will hang to allow debugging in the browser. From 3e42f8bb5143ebbfdbb247cf957f21dc383b4db7 Mon Sep 17 00:00:00 2001 From: Fagner Brack Date: Sat, 13 Jun 2015 18:02:38 -0300 Subject: [PATCH 19/20] Create separate sections --- CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9b73891..67a5e18 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -32,13 +32,13 @@ After the build completes, you should see the following message in the console: BUILD SUCCESS ---------------------------------------------------------------------------- -### Tests -When executing the build, maven runs all unit and integration tests. - -To run the unit tests separately, execute the following command: +### Unit tests +To run the unit tests, execute the following command: $ mvn test +### Integration tests + If you want to debug the integration tests in the browser, switch `Debug.FALSE` to `Debug.TRUE` in `CookiesEncodingIT.java` and run the build: $ mvn install From 32ea97c476d15f9a16fe63174a8c9d1325c0199a Mon Sep 17 00:00:00 2001 From: Fagner Brack Date: Sat, 13 Jun 2015 18:09:03 -0300 Subject: [PATCH 20/20] Highlight features --- README.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c909692..654bfcd 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,10 @@ A simple Java API for handling cookies +* [Unobstrusive](#json-data-binding) JSON Data Binding support +* [RFC 6265](http://www.rfc-editor.org/rfc/rfc6265.txt) compliant +* Enable [custom decoding](#converter) + ## Basic Usage Create a cookie, valid across the entire site @@ -65,9 +69,9 @@ cookies.remove( "name", Attributes.empty().path( "path" ) ); // removed! *IMPORTANT! when deleting a cookie, you must pass the exact same path, domain and secure attributes that were used to set the cookie, unless you're relying on the [default attributes](#cookie-attributes).* -## JSON and Data Binding +## JSON Data Binding -java-cookie provides unobstrusive JSON storage for cookies and data binding. +java-cookie provides unobstrusive JSON storage for cookies with data binding. When creating a cookie, you can pass a few supported types instead of String in the value. If you do so, java-cookie will store the stringified JSON representation of the value using [jackson databind](https://github.com/FasterXML/jackson-databind/#use-it).