Pengantar JsonPath

1. Ikhtisar

Salah satu keunggulan XML adalah ketersediaan pemrosesan - termasuk XPath - yang didefinisikan sebagai standar W3C. Untuk JSON, alat serupa yang disebut JSONPath telah muncul.

Artikel ini akan memberikan pengantar ke Jayway JsonPath , implementasi Java dari spesifikasi JSONPath. Ini menjelaskan penyiapan, sintaksis, API umum, dan demonstrasi kasus penggunaan.

2. Penyiapan

Untuk menggunakan JsonPath, kita hanya perlu menyertakan dependensi di pom Maven:

 com.jayway.jsonpath json-path 2.4.0 

3. Sintaks

Struktur JSON berikut akan digunakan di bagian ini untuk mendemonstrasikan sintaksis dan API JsonPath:

{ "tool": { "jsonpath": { "creator": { "name": "Jayway Inc.", "location": [ "Malmo", "San Francisco", "Helsingborg" ] } } }, "book": [ { "title": "Beginning JSON", "price": 49.99 }, { "title": "JSON at Work", "price": 29.99 } ] }

3.1. Notasi

JsonPath menggunakan notasi khusus untuk merepresentasikan node dan koneksinya ke node yang berdekatan di jalur JsonPath. Ada dua gaya notasi, yaitu titik dan tanda kurung.

Kedua jalur berikut merujuk ke node yang sama dari dokumen JSON di atas, yang merupakan elemen ketiga dalam bidang lokasi node pembuat , yang merupakan turunan dari objek jsonpath milik alat di bawah node root.

Dengan notasi titik:

$.tool.jsonpath.creator.location[2]

Dengan notasi braket:

$['tool']['jsonpath']['creator']['location'][2]

Tanda dolar ($) mewakili objek anggota root.

3.2. Operator

Kami memiliki beberapa operator yang membantu di JsonPath:

Node root ($) : Simbol ini menunjukkan anggota root dari struktur JSON tidak peduli itu objek atau array. Contoh penggunaannya sudah termasuk dalam sub-bagian sebelumnya.

Node saat ini (@) : Mewakili node yang sedang diproses, sebagian besar digunakan sebagai bagian dari ekspresi input untuk predikat. Misalkan kita berurusan dengan larik buku dalam dokumen JSON di atas, buku ekspresi [? (@. Price == 49,99)] merujuk ke buku pertama dalam larik itu.

Karakter pengganti (*) : Mengekspresikan semua elemen dalam cakupan yang ditentukan. Misalnya, book [*] menunjukkan semua node di dalam larik buku .

3.3. Fungsi dan Filter

JsonPath juga memiliki fungsi yang dapat digunakan di akhir jalur untuk mensintesis ekspresi output jalur tersebut: min () , max () , avg () , stddev () , length () .

Akhirnya - kami memiliki filter; ini adalah ekspresi boolean untuk membatasi daftar node yang dikembalikan ke hanya yang diperlukan metode pemanggilan.

Beberapa contohnya adalah persamaan ( == ), pencocokan ekspresi reguler ( = ~ ), inklusi ( dalam ), periksa kekosongan ( kosong ). Filter terutama digunakan untuk predikat.

Untuk daftar lengkap dan penjelasan rinci tentang berbagai operator, fungsi, dan filter, silakan merujuk ke proyek GitHub JsonPath.

4. Operasi

Sebelum kita masuk ke operasi, catatan singkat - bagian ini menggunakan struktur contoh JSON yang kita tentukan sebelumnya.

4.1. Akses ke Dokumen

JsonPath memiliki cara mudah untuk mengakses dokumen JSON, yaitu melalui API baca statis :

 T JsonPath.read(String jsonString, String jsonPath, Predicate... filters);

The read API dapat bekerja dengan API fasih statis untuk memberikan lebih banyak fleksibilitas:

 T JsonPath.parse(String jsonString).read(String jsonPath, Predicate... filters);

Varian baca berlebih lainnya dapat digunakan untuk berbagai jenis sumber JSON, termasuk Object , InputStream , URL , dan File .

Untuk membuat hal-hal sederhana, tes untuk bagian ini tidak termasuk predikat dalam daftar parameter (kosong varargs ); predikat akan dibahas di sub-bagian selanjutnya.

Mari kita mulai dengan menentukan dua jalur sampel untuk dikerjakan:

String jsonpathCreatorNamePath = "$['tool']['jsonpath']['creator']['name']"; String jsonpathCreatorLocationPath = "$['tool']['jsonpath']['creator']['location'][*]";

Selanjutnya, kita akan membuat objek DocumentContext dengan mengurai sumber JSON jsonDataSourceString yang diberikan . Objek yang baru dibuat kemudian akan digunakan untuk membaca konten menggunakan jalur yang ditentukan di atas:

DocumentContext jsonContext = JsonPath.parse(jsonDataSourceString); String jsonpathCreatorName = jsonContext.read(jsonpathCreatorNamePath); List jsonpathCreatorLocation = jsonContext.read(jsonpathCreatorLocationPath);

API baca pertama mengembalikan String yang berisi nama pembuat JsonPath, sedangkan yang kedua mengembalikan daftar alamatnya. Dan kami akan menggunakan JUnit Assert API untuk mengonfirmasi bahwa metode berfungsi seperti yang diharapkan:

assertEquals("Jayway Inc.", jsonpathCreatorName); assertThat(jsonpathCreatorLocation.toString(), containsString("Malmo")); assertThat(jsonpathCreatorLocation.toString(), containsString("San Francisco")); assertThat(jsonpathCreatorLocation.toString(), containsString("Helsingborg"));

4.2. Predikat

Sekarang setelah kita selesai dengan dasar-dasarnya, mari kita tentukan contoh JSON baru untuk dikerjakan dan menggambarkan pembuatan dan penggunaan predikat:

{ "book": [ { "title": "Beginning JSON", "author": "Ben Smith", "price": 49.99 }, { "title": "JSON at Work", "author": "Tom Marrs", "price": 29.99 }, { "title": "Learn JSON in a DAY", "author": "Acodemy", "price": 8.99 }, { "title": "JSON: Questions and Answers", "author": "George Duckett", "price": 6.00 } ], "price range": { "cheap": 10.00, "medium": 20.00 } }

Predicates determine true or false input values for filters to narrow down returned lists to only matched objects or arrays. A Predicate may easily be integrated into a Filter by using as an argument for its static factory method. The requested content can then be read out of a JSON string using that Filter:

Filter expensiveFilter = Filter.filter(Criteria.where("price").gt(20.00)); List expensive = JsonPath.parse(jsonDataSourceString) .read("$['book'][?]", expensiveFilter); predicateUsageAssertionHelper(expensive);

We may also define our customized Predicate and use it as an argument for the read API:

Predicate expensivePredicate = new Predicate() { public boolean apply(PredicateContext context) { String value = context.item(Map.class).get("price").toString(); return Float.valueOf(value) > 20.00; } }; List expensive = JsonPath.parse(jsonDataSourceString) .read("$['book'][?]", expensivePredicate); predicateUsageAssertionHelper(expensive);

Finally, a predicate may be directly applied to read API without the creation of any objects, which is called inline predicate:

List expensive = JsonPath.parse(jsonDataSourceString) .read("$['book'][?(@['price'] > $['price range']['medium'])]"); predicateUsageAssertionHelper(expensive);

All the three of the Predicate examples above are verified with the help of the following assertion helper method:

private void predicateUsageAssertionHelper(List predicate) { assertThat(predicate.toString(), containsString("Beginning JSON")); assertThat(predicate.toString(), containsString("JSON at Work")); assertThat(predicate.toString(), not(containsString("Learn JSON in a DAY"))); assertThat(predicate.toString(), not(containsString("JSON: Questions and Answers"))); }

5. Configuration

5.1. Options

Jayway JsonPath provides several options to tweak the default configuration:

  • Option.AS_PATH_LIST: Returns paths of the evaluation hits instead of their values.
  • Option.DEFAULT_PATH_LEAF_TO_NULL: Returns null for missing leaves.
  • Option.ALWAYS_RETURN_LIST: Returns a list even when the path is definite.
  • Option.SUPPRESS_EXCEPTIONS: Makes sure no exceptions are propagated from path evaluation.
  • Option.REQUIRE_PROPERTIES: Requires properties defined in the path when an indefinite path is evaluated.

Here is how Option is applied from scratch:

Configuration configuration = Configuration.builder().options(Option.).build();

and how to add it to an existing configuration:

Configuration newConfiguration = configuration.addOptions(Option.);

5.2. SPIs

JsonPath's default configuration with the help of Option should be enough for the majority of tasks. However, users with more complex use cases can modify the behavior of JsonPath according to their specific requirements – using three different SPIs:

  • JsonProvider SPI: Lets us change the ways JsonPath parses and handles JSON documents
  • MappingProvider SPI: Allows for customization of bindings between node values and returned object types
  • CacheProvider SPI: Adjusts the manners that paths are cached, which can help to increase performance

6. An Example Use Cases

Now that we have a good understanding of the functionality that JsonPath can be used for – let's look at an example.

This section illustrates dealing with JSON data returned from a web service – assume we have a movie information service, which returns the following structure:

[ { "id": 1, "title": "Casino Royale", "director": "Martin Campbell", "starring": [ "Daniel Craig", "Eva Green" ], "desc": "Twenty-first James Bond movie", "release date": 1163466000000, "box office": 594275385 }, { "id": 2, "title": "Quantum of Solace", "director": "Marc Forster", "starring": [ "Daniel Craig", "Olga Kurylenko" ], "desc": "Twenty-second James Bond movie", "release date": 1225242000000, "box office": 591692078 }, { "id": 3, "title": "Skyfall", "director": "Sam Mendes", "starring": [ "Daniel Craig", "Naomie Harris" ], "desc": "Twenty-third James Bond movie", "release date": 1350954000000, "box office": 1110526981 }, { "id": 4, "title": "Spectre", "director": "Sam Mendes", "starring": [ "Daniel Craig", "Lea Seydoux" ], "desc": "Twenty-fourth James Bond movie", "release date": 1445821200000, "box office": 879376275 } ]

Where the value of release date field is duration since the Epoch in milliseconds and box office is revenue of a movie in the cinema in US dollars.

We are going to handle five different working scenarios related to GET requests, supposing that the above JSON hierarchy has been extracted and stored in a String variable named jsonString.

6.1. Getting Object Data Given IDs

In this use case, a client requests detailed information on a specific movie by providing the server with the exact id of that one. This example demonstrates how the server looks for requested data before returning to the client.

Say we need to find a record with id equaling to 2. Below is how the process is implemented and tested.

The first step is to pick up the correct data object:

Object dataObject = JsonPath.parse(jsonString).read("$[?(@.id == 2)]"); String dataString = dataObject.toString();

The JUnit Assert API confirms the existence of several fields:

assertThat(dataString, containsString("2")); assertThat(dataString, containsString("Quantum of Solace")); assertThat(dataString, containsString("Twenty-second James Bond movie"));

6.2. Getting the Movie Title Given Starring

Let's say we want to look for a movie starring an actress called Eva Green. The server needs to return title of the movie that Eva Green is included in the starring array.

The succeeding test will illustrate how to do that and validate the returned result:

@Test public void givenStarring_whenRequestingMovieTitle_thenSucceed() { List dataList = JsonPath.parse(jsonString) .read("$[?('Eva Green' in @['starring'])]"); String title = (String) dataList.get(0).get("title"); assertEquals("Casino Royale", title); }

6.3. Calculation of the Total Revenue

This scenario makes use of a JsonPath function called length() to figure out the number of movie records, to calculate the total revenue of all the movies. The implementation and testing are demonstrated as follows:

@Test public void givenCompleteStructure_whenCalculatingTotalRevenue_thenSucceed() { DocumentContext context = JsonPath.parse(jsonString); int length = context.read("$.length()"); long revenue = 0; for (int i = 0; i < length; i++) { revenue += context.read("$[" + i + "]['box office']", Long.class); } assertEquals(594275385L + 591692078L + 1110526981L + 879376275L, revenue); }

6.4. Highest Revenue Movie

This use case exemplifies the usage of a non-default JsonPath configuration option, namely Option.AS_PATH_LIST, to find out the movie with the highest revenue. The particular steps are described underneath.

At first, we need to extract a list of all the movies' box office revenue, then convert it to an array for sorting:

DocumentContext context = JsonPath.parse(jsonString); List revenueList = context.read("$[*]['box office']"); Integer[] revenueArray = revenueList.toArray(new Integer[0]); Arrays.sort(revenueArray);

The highestRevenue variable may easily be picked up from the revenueArray sorted array, then used for working out the path to the movie record with the highest revenue:

int highestRevenue = revenueArray[revenueArray.length - 1]; Configuration pathConfiguration = Configuration.builder().options(Option.AS_PATH_LIST).build(); List pathList = JsonPath.using(pathConfiguration).parse(jsonString) .read("$[?(@['box office'] == " + highestRevenue + ")]");

Based on that calculated path, title of the corresponding movie can be determined and returned:

Map dataRecord = context.read(pathList.get(0)); String title = dataRecord.get("title");

The whole process is verified by the Assert API:

assertEquals("Skyfall", title);

6.5. Latest Movie of a Director

This example will illustrate the way to figure out the lasted movie directed by a director named Sam Mendes.

To begin with, a list of all the movies directed by Sam Mendes is created:

DocumentContext context = JsonPath.parse(jsonString); List dataList = context.read("$[?(@.director == 'Sam Mendes')]");

That list is used for extraction of release dates. Those dates will be stored in an array and then sorted:

List dateList = new ArrayList(); for (Map item : dataList) { Object date = item.get("release date"); dateList.add(date); } Long[] dateArray = dateList.toArray(new Long[0]); Arrays.sort(dateArray);

The lastestTime variable, which is the last element of the sorted array, is used in combination with the director field's value to determine the title of the requested movie:

long latestTime = dateArray[dateArray.length - 1]; List finalDataList = context.read("$[?(@['director'] == 'Sam Mendes' && @['release date'] == " + latestTime + ")]"); String title = (String) finalDataList.get(0).get("title");

The following assertion proved that everything works as expected:

assertEquals("Spectre", title);

7. Conclusion

This tutorial has covered fundamental features of Jayway JsonPath – a powerful tool to traverse and parse JSON documents.

Meskipun JsonPath memiliki beberapa kekurangan, seperti kurangnya operator untuk menjangkau node induk atau saudara, JsonPath bisa sangat berguna dalam banyak skenario.

Penerapan semua contoh dan cuplikan kode ini dapat ditemukan di proyek GitHub .