Josson & Jossons

• Josson is a complete query and transformation language for JSON.
• Jossons is a template engine to generate text output.

Installation

https://mvnrepository.com/artifact/com.octomix.josson/josson

Maven

<dependency>
    <groupId>com.octomix.josson</groupId>
    <artifactId>josson</artifactId>
    <version>1.5.1</version>
</dependency>

Gradle

implementation group: 'com.octomix.josson', name: 'josson', version: '1.5.1'

Features and Capabilities

Josson

• Query a JSON dataset.
• There are 248 internal functions to manipulate and format data.
• Restructure JSON data and capable of grouping and unwind data.
• Multithreading capability for array elements manipulation.
• Support custom function to manipulate node.
• Can be used as an API parameter to trim down the response JSON result.

Jossons

• Is a template engine to fill in placeholders and generate text output.
• Support XML and HTML escaping.
• Resolve template placeholder by querying data from multiple Josson objects.
• Resolve template placeholder from external data source on demand.
• Join two JSON datasets to build a new dataset.
• Set operation on two datasets.
• I used Jossons to generate millions of SMS/Email notifications during the first year.
• I used Jossons to generate plain text and csv reports that retrieve data from MongoDB directly.
• I store the notification or report definitions in template documents. No need to write extra program coding for different template.

Table of Contents

• Operator Summary

  • Relational and Logical Operators
  • Join, Set and Compare Operators

• Josson Basic

• Josson Query Language

  • Josson Path
  • Path Chart Elements
  • Tutorial

• Josson Functions

  • Arithmetic Functions
  • String Functions
  • Date Functions
  • Format Functions
  • Logical Functions
  • Array Functions
  • Structural Functions
  • Programmable Functions

• Custom Function

• Jossons Basic

• Jossons Template Language

  • Placeholder
  • Nested Placeholders
  • Ternary Syntax
  • Join Operation
  • Set Operation
  • Join and Set Pipe Chaining
  • Implicit Variables
  • Fill In

• Jossons Resolver

  • Dictionary Finder
  • Data Finder
  • Dictionary Function
  • Put Together

• Appendix

  • MongoDB Adapter
  • Examples from Stack Overflow Question

---

Operator Summary

Relational and Logical Operators

| Operator | Description | |:---------|:----------------------------------------| | ( | Grouping | | ) | Grouping | | = | Is equal to (support object and array) | | != | Not equal to (support object and array) | | > | Greater than | | >= | Greater than or equal to | | < | Less than | | <= | Less than or equal to | | =~ | Left matches regular expression | | !=~ | Not match regular expression | | ! | Logical NOT | | & | Logical AND | | | | Logical OR |

Join, Set and Compare Operators

| Operator | Description | |:--------------|:---------------------------------| | >=< | Inner join | | <=< | Left join one | | >=> | Right join one | | <=<< | Left join many | | >>=> | Right join many | | <!< | Left excluding join | | >!> | Right excluding join | | <!> | Outer excluding join | | <+< | Left concatenate | | >+> | Right concatenate | | <-< | Subtract right from left | | >-> | Subtract left from right | | <-> | Symmetric difference | | <u> | Union | | >n< | Intersection | | | | Chaining pipe | | <==> | Equals (returns BooleanNode) | | <!=> | Not equals (returns BooleanNode) |

Josson Basic

Initial setup for date time formatting and JSON serialization.

Josson.setLocale(Locale.ENGLISH); // default Locale.getDefault()

Josson.setZoneId(ZoneId.of("Asia/Hong_Kong")); // default ZoneId.systemDefault()

Josson.setSerializationInclusion(JsonInclude.Include.NON_NULL);

Josson support multithreading for array elements manipulation. When thread pool size is 2 or above, a little more system resource is required to retain the array order. Turn it off if the array elements order of the result is negligible.

Josson.setMinArraySizeToUseMultiThread(200); // default size is 100

Josson.setThreadPoolSize(2); // default size is 4

Josson.setRetainArrayOrder(false); // default ture

To create a Josson object from a Jackson JsonNode.

Josson josson = Josson.create(jsonNode);

To create a Josson object from a Java object.

Josson josson = Josson.from(object);

To create a Josson object from a JSON string.

Josson josson = Josson.fromJsonString("...");

To apply a Josson query path and get the result JsonNode.

JsonNode node = josson.getNode(expression);

Define initial variables for a query. Variable name must start with "$".

Map<String, JsonNode> vars = new HashMap<>();
vars.put("$a", IntNode.valueOf(3));
JsonNode node = josson.getNode("concat('qty=',$a)", vars);

To apply a Josson query path and get the path trace along the main branch. The trace object contains all progressive nodes and variables defined along the main branch.

PathTrace trace = josson.getPathTrace(expression);

Josson Query Language

Josson Path

A Josson Path is constructed with Path Steps connected by ..

A path step can...

• Return an element of an object node by key name.
• Filter an array node, return the first matching element or all matching elements.
• Perform a transformation operation by a Josson Function.

| Step Syntax | Description | |:-----------------|:--------------------------------------------------------------------------| | key | A child element key name | | [number] | An array element by zero-based index | | [expression] | A boolean filter expression to find the first matching array element | | [expression]* | A boolean filter expression to query all matching array elements | | [expression]@ | Filter all matching elements and divert each to separate branches | | []@ | Divert each element of the current array node to separate branches | | array@ | Divert each array element to separate branches | | function() | A Josson function | | @function() | Merge all branch results into a single array before manipulation | | function()@ | Divert the function output array elements to separate branches | | * | Wildcard search that return the first resolvable non-null result | | ** | Wildcard search that return all object elements | | *@ | Wildcard search and divert each object element to separate branches | | *(expression) | Multi-level wildcard search and return the first resolvable element | | *[expression] | Wildcard search with filter and return the first matching element | | *[expression]* | Wildcard search with filter and return all matching elements | | *[expression]@ | Wildcard search with filter and divert each element to separate branches | | ~'regex' | Search by regular expression and return the first matching element | | ~'regex'* | Search by regular expression and return all matching elements | | ~'regex'@ | Search by regular expression and divert each element to separate branches |

To specify an array and then apply an index or a filter can be simplified by removing the . between them. The following two statements produce the same final result. But have different number of path steps. The