Made provider names more symmetrical. Some documentation.

README.md

@@ -6,4 +6,194 @@ JSONPath
 [![Build Status](https://travis-ci.org/jayway/JsonPath.svg?branch=master)](https://travis-ci.org/jayway/JsonPath)
 [![Analytics](https://ga-beacon.appspot.com/UA-54945131-1/jsonpath/index)](https://github.com/igrigorik/ga-beacon)
 
-[read more](http://code.google.com/p/json-path/)
+[read more](http://code.google.com/p/json-path/)
+
+JSONPath expressions always refer to a JSON structure in the same way as XPath expression are used in combination 
+with an XML document. The "root member object" in JSONPath is always referred to as `$` regardless if it is an 
+object or array.
+
+JSONPath expressions can use the dot–notation
+
+`$.store.book[0].title`
+
+or the bracket–notation
+
+`$['store']['book'][0]['title']`
+
+Operators
+---------
+
+| Operator                  | Description                                                        |
+| :------------------------ | :----------------------------------------------------------------- |
+| `$`                       | The root element to query. This starts all path expressions.       |
+| `@`                       | The current node being processed by a filter predicate.            |
+| `*`                       | Wildcard. Available anywhere a name or numeric are required.       |
+| `..`                      | Deep scan. Available anywhere a name is required.                  |
+| `.<name>`                 | Dot-notated child                                                  |
+| `['<name>' (, '<name>)']` | Bracket-notated child or children                                  |
+| `[<number> (, <number>)]` | Array index or indexes                                             |
+| `[start:end]`             | Array slice operator                                               |
+| `[?(<expression>)]`       | Filter expression. Expression must evaluate to a boolean value.    |
+
+Path Examples
+-------------
+
+Given the 
+
+```javascript
+{
+    "store": {
+        "book": [
+            {
+                "category": "reference",
+                "author": "Nigel Rees",
+                "title": "Sayings of the Century",
+                "price": 8.95
+            },
+            {
+                "category": "fiction",
+                "author": "Evelyn Waugh",
+                "title": "Sword of Honour",
+                "price": 12.99
+            },
+            {
+                "category": "fiction",
+                "author": "Herman Melville",
+                "title": "Moby Dick",
+                "isbn": "0-553-21311-3",
+                "price": 8.99
+            },
+            {
+                "category": "fiction",
+                "author": "J. R. R. Tolkien",
+                "title": "The Lord of the Rings",
+                "isbn": "0-395-19395-8",
+                "price": 22.99
+            }
+        ],
+        "bicycle": {
+            "color": "red",
+            "price": 19.95
+        }
+    }
+}
+```
+
+| JSONPath | Result |
+| :------- | :----- |
+| `$.store.book[*].author`      | The authors of all books            |
+| `$..author`                   | All authors                         |
+| `$.store.*`                   | All things, both books and bicycles |
+| `$.store..price`              | The price of everything             |
+| `$..book[2]`                  | The third book                      |
+| `$..book[(@.length-1)]`       | The last book                       |
+| `$..book[0,1]`                | The first two books                 |
+| `$..book[:2]`                 | All books from index 0 (inclusive) until index 2 (exclusive) |
+| `$..book[1:2]`                | All books from index 1 (inclusive) until index 2 (exclusive) |
+| `$..book[-2:]`                | Last two books                      |
+| `$..book[2:]`                 | Book number two from tail           |
+| `$..book[?(@.isbn)]`          | All books with an ISBN number       |
+| `$.store.book[?(@.price<10)]` | All books in store cheaper than 10  |
+| `$..*`                        | Give me every thing you got         |
+
+
+Reading a JSON document
+-----------------------
+The simplest most straight forward way to use JsonPath is via the static convenience API.
+
+```java
+
+String json = "...";
+
+List<String> authors = JsonPath.read(json, "$.store.book[*].author");
+
+```
+
+If you only want to read once this is OK. In case you need to read an other path as well this is not the way 
+to go since the document will be parsed every time you call JsonPath.read(...). To avoid the problem you can 
+parse the json first.
+
+```java
+
+String json = "...";
+Object document = Configuration.defaultConfiguration().jsonProvider().parse(json);
+
+String author1 = JsonPath.read(document, "$.store.book[0].author");
+String author2 = JsonPath.read(document, "$.store.book[1].author");
+
+```
+Personally I prefer the more flexible `ReadContext` API.
+
+```java
+
+String json = "...";
+
+ReadContext ctx = JsonPath.parse(json);
+
+List<String> authorsOfBooksWithISBN = ctx.read("$.store.book[?(@.isbn)].author");
+
+
+List<Map<String, Object>> expensiveBooks = JsonPath
+                            .using(configuration)
+                            .parse(json)
+                            .read("$.store.book[?(@.price > 10)]", List.class);
+
+```
+
+
+
+PATH vs VALUE
+-------------
+
+
+
+Advanced
+--------
+
+The default JsonProvider is `JsonSmartJsonProvider` backed by [json-smart](https://code.google.com/p/json-smart/), a small and fast JSONParser. If you
+prefer Jackson there is a `JacksonJsonProvider` available. There is also an experimental `GsonJsonProvider`. 
+
+* JacksonJsonProvider requires `com.fasterxml.jackson.core:jackson-databind:2.4.1.3` on your classpath. 
+* GsonJsonProvider requires `com.google.code.gson:gson:2.3` on your classpath. 
+
+```java
+Configuration.setDefaults(new Configuration.Defaults() {
+
+    private final JsonProvider jsonProvider = new com.jayway.jsonpath.internal.spi.json.JacksonJsonProvider();
+      
+    @Override
+    public JsonProvider jsonProvider() {
+        return jsonProvider;
+    }
+
+    @Override
+    public Set<Option> options() {
+        return EnumSet.noneOf(Option.class);
+    }
+
+    @Override
+    public ConversionProvider conversionProvider() {
+        return new DefaultConversionProvider();
+    }
+});
+```
+
+Binaries
+--------
+
+JsonPath is available at the Central Maven Repository. Maven users add this to your POM.
+
+```xml
+<dependency>
+    <groupId>com.jayway.jsonpath</groupId>
+    <artifactId>json-path</artifactId>
+    <version>0.9.1</version>
+</dependency>
+```
+
+Gradle users
+ 
+ 
+```
+compile 'com.jayway.jsonpath:json-path:0.9.1'
+``` 

json-path-web-test/src/main/java/com/jayway/jsonpath/web/bench/Bench.java

@@ -3,7 +3,7 @@ package com.jayway.jsonpath.web.bench;
 import com.jayway.jsonpath.Configuration;
 import com.jayway.jsonpath.JsonPath;
 import com.jayway.jsonpath.Option;
-import com.jayway.jsonpath.internal.spi.json.JacksonProvider;
+import com.jayway.jsonpath.internal.spi.json.JacksonJsonProvider;
 import io.gatling.jsonpath.JsonPath$;
 import org.boon.json.JsonParser;
 import org.boon.json.ObjectMapper;
@@ -115,7 +115,7 @@ public class Bench {
         String error = null;
         long time;
         Object res = null;
-        JacksonProvider jacksonProvider = new JacksonProvider();
+        JacksonJsonProvider jacksonProvider = new JacksonJsonProvider();
 
         long now = System.currentTimeMillis();
         try {

json-path/src/main/java/com/jayway/jsonpath/Configuration.java

@@ -29,7 +29,9 @@ import static java.util.Arrays.asList;
 public class Configuration {
 
     private static Defaults DEFAULTS = new Defaults() {
-        @Override
+
+        private final ConversionProvider conversionProvider = new DefaultConversionProvider();
+
         public JsonProvider jsonProvider() {
             return new JsonSmartJsonProvider();
         }
@@ -41,7 +43,7 @@ public class Configuration {
 
         @Override
         public ConversionProvider conversionProvider() {
-            return new DefaultConversionProvider();
+            return conversionProvider;
         }
     };
 

json-path/src/main/java/com/jayway/jsonpath/internal/spi/converter/GsonConverter.java

@@ -6,7 +6,7 @@ import com.google.gson.JsonNull;
 import com.google.gson.JsonObject;
 import com.google.gson.JsonPrimitive;
 import com.jayway.jsonpath.Configuration;
-import com.jayway.jsonpath.internal.spi.json.GsonProvider;
+import com.jayway.jsonpath.internal.spi.json.GsonJsonProvider;
 import com.jayway.jsonpath.spi.converter.ConversionException;
 
 import java.math.BigDecimal;
@@ -90,7 +90,7 @@ public class GsonConverter extends ConverterBase {
                     Object val = null;
                     JsonElement element = entry.getValue();
                     if(element.isJsonPrimitive()) {
-                        val = GsonProvider.unwrap(element);
+                        val = GsonJsonProvider.unwrap(element);
                     } else if(element.isJsonArray()){
                         val = convert(element, element.getClass(), List.class, conf);
                     } else if(element.isJsonObject()){
@@ -109,7 +109,7 @@ public class GsonConverter extends ConverterBase {
                 List<Object> targetList = new ArrayList<Object>();
                 for (JsonElement element : srcArray) {
                     if(element.isJsonPrimitive()) {
-                        targetList.add(GsonProvider.unwrap(element));
+                        targetList.add(GsonJsonProvider.unwrap(element));
                     } else if(element.isJsonArray()){
                         targetList.add(convert(element, element.getClass(), List.class, conf));
                     } else if(element.isJsonObject()){

json-path/src/main/java/com/jayway/jsonpath/internal/spi/json/GsonJsonProvider.java

@@ -21,9 +21,9 @@ import java.util.Collection;
 import java.util.List;
 import java.util.Map;
 
-public class GsonProvider extends AbstractJsonProvider {
+public class GsonJsonProvider extends AbstractJsonProvider {
 
-    private static final Logger logger = LoggerFactory.getLogger(GsonProvider.class);
+    private static final Logger logger = LoggerFactory.getLogger(GsonJsonProvider.class);
 
     private static final JsonParser parser = new JsonParser();
     private static final Gson gson = new GsonBuilder().create();

json-path/src/main/java/com/jayway/jsonpath/internal/spi/json/JacksonJsonProvider.java

@@ -27,9 +27,9 @@ import java.io.StringWriter;
 import java.util.LinkedList;
 import java.util.List;
 
-public class JacksonProvider extends AbstractJsonProvider {
+public class JacksonJsonProvider extends AbstractJsonProvider {
 
-    private static final Logger logger = LoggerFactory.getLogger(JacksonProvider.class);
+    private static final Logger logger = LoggerFactory.getLogger(JacksonJsonProvider.class);
 
     private static final ObjectMapper defaultObjectMapper = new ObjectMapper();
     private static final ObjectReader defaultObjectReader = defaultObjectMapper.reader().withType(Object.class);
@@ -40,7 +40,7 @@ public class JacksonProvider extends AbstractJsonProvider {
     /**
      * Initialize the JacksonProvider with the default ObjectMapper and ObjectReader
      */
-    public JacksonProvider() {
+    public JacksonJsonProvider() {
       this(defaultObjectMapper, defaultObjectReader);
     }
 
@@ -48,7 +48,7 @@ public class JacksonProvider extends AbstractJsonProvider {
      * Initialize the JacksonProvider with a custom ObjectMapper.
      * @param objectMapper the ObjectMapper to use
      */
-    public JacksonProvider(ObjectMapper objectMapper) {
+    public JacksonJsonProvider(ObjectMapper objectMapper) {
       this(objectMapper, objectMapper.reader().withType(Object.class));
     }
 
@@ -57,7 +57,7 @@ public class JacksonProvider extends AbstractJsonProvider {
      * @param objectMapper the ObjectMapper to use
      * @param objectReader the ObjectReader to use
      */
-    public JacksonProvider(ObjectMapper objectMapper, ObjectReader objectReader) {
+    public JacksonJsonProvider(ObjectMapper objectMapper, ObjectReader objectReader) {
       this.objectMapper = objectMapper;
       this.objectReader = objectReader;
     }

json-path/src/test/java/com/jayway/jsonpath/ReturnTypeTest.java

@@ -5,13 +5,14 @@ import org.junit.Test;
 import java.util.List;
 import java.util.Map;
 
+import static com.jayway.jsonpath.JsonPath.parse;
 import static org.assertj.core.api.Assertions.assertThat;
 
 @SuppressWarnings("ALL")
 public class ReturnTypeTest extends BaseTest {
 
 
-    private static ReadContext reader = JsonPath.parse(JSON_DOCUMENT);
+    private static ReadContext reader = parse(JSON_DOCUMENT);
 
     @Test
     public void assert_strings_can_be_read() {

json-path/src/test/java/com/jayway/jsonpath/old/IssuesTest.java

@@ -18,6 +18,7 @@ import java.util.Collections;
 import java.util.List;
 import java.util.Map;
 
+import static com.jayway.jsonpath.JsonPath.read;
 import static junit.framework.Assert.assertNull;
 import static junit.framework.Assert.assertTrue;
 import static org.assertj.core.api.Assertions.failBecauseExceptionWasNotThrown;
@@ -36,10 +37,12 @@ public class IssuesTest {
                 " {\"kind\" : \"empty\"}\n" +
                 "]";
 
-        List<Map<String, String>> fullOnes = JsonPath.read(json, "$[?(@.kind == full)]");
+        List<Map<String, String>> fullOnes = read(json, "$[?(@.kind == full)]");
 
         assertEquals(1, fullOnes.size());
         assertEquals("full", fullOnes.get(0).get("kind"));
+
+
     }
 
     @Test
@@ -52,8 +55,8 @@ public class IssuesTest {
                 "\n" +
                 " }";
 
-        Object o1 = JsonPath.read(json, "$.arrayOfObjectsAndArrays..k ");
-        Object o2 = JsonPath.read(json, "$.arrayOfObjects..k ");
+        Object o1 = read(json, "$.arrayOfObjectsAndArrays..k ");
+        Object o2 = read(json, "$.arrayOfObjects..k ");
 
         assertEquals("[[\"json\"],[\"path\"],[\"is\"],[\"cool\"]]", jp.toJson(o1));
         assertEquals("[\"json\",\"path\",\"is\",\"cool\"]", jp.toJson(o2));
@@ -62,14 +65,14 @@ public class IssuesTest {
     @Test
     public void issue_11() throws Exception {
         String json = "{ \"foo\" : [] }";
-        List<String> result = JsonPath.read(json, "$.foo[?(@.rel == 'item')][0].uri");
+        List<String> result = read(json, "$.foo[?(@.rel == 'item')][0].uri");
         assertTrue(result.isEmpty());
     }
 
     @Test(expected = PathNotFoundException.class)
     public void issue_11b() throws Exception {
         String json = "{ \"foo\" : [] }";
-        JsonPath.read(json, "$.foo[0].uri");
+        read(json, "$.foo[0].uri");
     }
 
     @Test
@@ -102,7 +105,7 @@ public class IssuesTest {
                 "  }\n" +
                 "}";
 
-        List<String> titles = JsonPath.read(json, "$.store.book[?(@.children==true)].title");
+        List<String> titles = read(json, "$.store.book[?(@.children==true)].title");
 
         assertThat(titles, Matchers.contains("Moby Dick"));
         assertEquals(1, titles.size());
@@ -118,7 +121,7 @@ public class IssuesTest {
 
 
             //Object o = JsonPath.read(is, "$.project[?(@.template.@key == 'foo')].field[*].@key");
-            Object o = JsonPath.read(is, "$.project.field[*].@key");
+            Object o = read(is, "$.project.field[*].@key");
             //Object o = JsonPath.read(is, "$.project.template[?(@.@key == 'foo')].field[*].@key");
 
 
@@ -134,7 +137,7 @@ public class IssuesTest {
     public void issue_28_string() {
         String json = "{\"contents\": [\"one\",\"two\",\"three\"]}";
 
-        List<String> result = JsonPath.read(json, "$.contents[?(@  == 'two')]");
+        List<String> result = read(json, "$.contents[?(@  == 'two')]");
 
         assertThat(result, Matchers.contains("two"));
         assertEquals(1, result.size());
@@ -160,7 +163,7 @@ public class IssuesTest {
                 "    }\n" +
                 "]";
 
-        List<Double> result = JsonPath.read(json, "$.[?(@.compatible == true)].sku");
+        List<Double> result = read(json, "$.[?(@.compatible == true)].sku");
 
         System.out.println(result);
 
@@ -184,7 +187,7 @@ public class IssuesTest {
                 "   ]\n" +
                 "}";
 
-        List<Double> result = JsonPath.read(json, "$.datapoints.[*].[0]");
+        List<Double> result = read(json, "$.datapoints.[*].[0]");
 
         assertThat(result.get(0), is(new Double(10.1)));
         assertThat(result.get(1), is(new Double(21.0)));
@@ -201,7 +204,7 @@ public class IssuesTest {
                 "    }\n" +
                 "}\n";
 
-        List<String> result = JsonPath.read(json, "$..arr");
+        List<String> result = read(json, "$..arr");
         assertThat(result.size(), is(2));
     }
 
@@ -209,7 +212,7 @@ public class IssuesTest {
     public void issue_28_int() {
         String json = "{\"contents\": [1,2,3]}";
 
-        List<Integer> result = JsonPath.read(json, "$.contents[?(@ == 2)]");
+        List<Integer> result = read(json, "$.contents[?(@ == 2)]");
 
         assertThat(result, Matchers.contains(2));
         assertEquals(1, result.size());
@@ -219,7 +222,7 @@ public class IssuesTest {
     public void issue_28_boolean() {
         String json = "{\"contents\": [true, true, false]}";
 
-        List<Boolean> result = JsonPath.read(json, "$.contents[?(@  == true)]");
+        List<Boolean> result = read(json, "$.contents[?(@  == true)]");
 
         assertThat(result, Matchers.contains(true, true));
         assertEquals(2, result.size());
@@ -255,19 +258,19 @@ public class IssuesTest {
     @Test(expected = PathNotFoundException.class)
     public void issue_26() throws Exception {
         String json = "[{\"a\":[{\"b\":1,\"c\":2}]}]";
-        Object o = JsonPath.read(json, "$.a");
+        Object o = read(json, "$.a");
     }
 
     @Test
     public void issue_29_a() throws Exception {
         String json = "{\"list\": [ { \"a\":\"atext\", \"b.b-a\":\"batext2\", \"b\":{ \"b-a\":\"batext\", \"b-b\":\"bbtext\" } }, { \"a\":\"atext2\", \"b\":{ \"b-a\":\"batext2\", \"b-b\":\"bbtext2\" } } ] }";
 
-        List<Map<String, Object>> result = JsonPath.read(json, "$.list[?(@['b.b-a']=='batext2')]");
+        List<Map<String, Object>> result = read(json, "$.list[?(@['b.b-a']=='batext2')]");
         assertEquals(1, result.size());
         Object a = result.get(0).get("a");
         assertEquals("atext", a);
 
-        result = JsonPath.read(json, "$.list[?(@.b.b-a=='batext2')]");
+        result = read(json, "$.list[?(@.b.b-a=='batext2')]");
         assertEquals(1, result.size());
         assertEquals("atext2", result.get(0).get("a"));
 
@@ -277,7 +280,7 @@ public class IssuesTest {
     @Test
     public void issue_29_b() throws Exception {
         String json = "{\"list\": [ { \"a\":\"atext\", \"b\":{ \"b-a\":\"batext\", \"b-b\":\"bbtext\" } }, { \"a\":\"atext2\", \"b\":{ \"b-a\":\"batext2\", \"b-b\":\"bbtext2\" } } ] }";
-        List<String> result = JsonPath.read(json, "$.list[?]", Filter.filter(Criteria.where("b.b-a").eq("batext2")));
+        List<String> result = read(json, "$.list[?]", Filter.filter(Criteria.where("b.b-a").eq("batext2")));
 
         assertTrue(result.size() == 1);
     }
@@ -285,14 +288,14 @@ public class IssuesTest {
     public void issue_30() throws Exception {
         String json = "{\"foo\" : {\"@id\" : \"123\", \"$\" : \"hello\"}}";
 
-        assertEquals("123", JsonPath.read(json, "foo.@id"));
-        assertEquals("hello", JsonPath.read(json, "foo.$"));
+        assertEquals("123", read(json, "foo.@id"));
+        assertEquals("hello", read(json, "foo.$"));
     }
 
     @Test
     public void issue_32(){
         String json = "{\"text\" : \"skill: \\\"Heuristic Evaluation\\\"\", \"country\" : \"\"}";
-        assertEquals("skill: \"Heuristic Evaluation\"", JsonPath.read(json, "$.text"));
+        assertEquals("skill: \"Heuristic Evaluation\"", read(json, "$.text"));
     }
 
     @Test
@@ -321,7 +324,7 @@ public class IssuesTest {
                 "  }\n" +
                 "}";
 
-        List<Map<String, Object>> result = JsonPath.read(json, "$.store.book[?(@.author.age == 36)]");
+        List<Map<String, Object>> result = read(json, "$.store.book[?(@.author.age == 36)]");
 
         System.out.println(result);
 
@@ -338,7 +341,7 @@ public class IssuesTest {
                 "]";
 
 
-        assertEquals(1, JsonPath.read(json, "$[0].a"));
+        assertEquals(1, read(json, "$[0].a"));
     }
 
     @Test(expected = PathNotFoundException.class)
@@ -355,7 +358,7 @@ public class IssuesTest {
                 "  \"version\": 1371160528774\n" +
                 "}";
 
-        Object read = JsonPath.read(json, "$.data.passes[0].id");
+        Object read = read(json, "$.data.passes[0].id");
     }
 
 
@@ -368,7 +371,7 @@ public class IssuesTest {
                 "        }] " +
                 "    }";
 
-        List<Map<String, String>> result = JsonPath.read(json, "$.list[?(@.name == 'My (String)')]");
+        List<Map<String, String>> result = read(json, "$.list[?(@.name == 'My (String)')]");
 
         Assertions.assertThat(result).containsExactly(Collections.singletonMap("name", "My (String)"));
     }
@@ -378,12 +381,12 @@ public class IssuesTest {
 
         String json = "{\"test\":null}";
 
-        Assertions.assertThat(JsonPath.read(json, "test")).isNull();
+        Assertions.assertThat(read(json, "test")).isNull();
 
         Assertions.assertThat(JsonPath.using(Configuration.defaultConfiguration().options(Option.SUPPRESS_EXCEPTIONS)).parse(json).read("nonExistingProperty")).isNull();
 
         try {
-            JsonPath.read(json, "nonExistingProperty");
+            read(json, "nonExistingProperty");
 
             failBecauseExceptionWasNotThrown(PathNotFoundException.class);
         } catch (PathNotFoundException e){
@@ -392,7 +395,7 @@ public class IssuesTest {
 
 
         try {
-            JsonPath.read(json, "nonExisting.property");
+            read(json, "nonExisting.property");
 
             failBecauseExceptionWasNotThrown(PathNotFoundException.class);
         } catch (PathNotFoundException e){
@@ -405,7 +408,7 @@ public class IssuesTest {
     public void issue_45() {
         String json = "{\"rootkey\":{\"sub.key\":\"value\"}}";
 
-        Assertions.assertThat(JsonPath.read(json, "rootkey['sub.key']")).isEqualTo("value");
+        Assertions.assertThat(read(json, "rootkey['sub.key']")).isEqualTo("value");
     }
 
     @Test
@@ -420,7 +423,7 @@ public class IssuesTest {
         Assertions.assertThat(JsonPath.using(configuration).parse(json).read("a.x")).isNull();
 
         try {
-            JsonPath.read(json, "a.x");
+            read(json, "a.x");
 
             failBecauseExceptionWasNotThrown(PathNotFoundException.class);
         } catch (PathNotFoundException e){

json-path/src/test/java/com/jayway/jsonpath/old/JsonProviderTest.java

@@ -1,6 +1,6 @@
 package com.jayway.jsonpath.old;
 
-import com.jayway.jsonpath.internal.spi.json.JacksonProvider;
+import com.jayway.jsonpath.internal.spi.json.JacksonJsonProvider;
 import org.junit.Test;
 
 public class JsonProviderTest {
@@ -50,7 +50,7 @@ public class JsonProviderTest {
     @Test
     public void parse_document() throws Exception {
 
-        JacksonProvider provider = new JacksonProvider();
+        JacksonJsonProvider provider = new JacksonJsonProvider();
 
         Object o = provider.parse(DOCUMENT);
 
@@ -60,7 +60,7 @@ public class JsonProviderTest {
 
     @Test
     public void parse_array() throws Exception {
-        JacksonProvider provider = new JacksonProvider();
+        JacksonJsonProvider provider = new JacksonJsonProvider();
 
         Object o = provider.parse(ARRAY);