bosonScala

Boson - Streaming for JSON and BSON

License

License

Categories

Categories

Scala Languages
GroupId

GroupId

io.zink
ArtifactId

ArtifactId

bosonscala
Last Version

Last Version

1.0.0
Release Date

Release Date

Type

Type

jar
Description

Description

bosonScala
Boson - Streaming for JSON and BSON
Project URL

Project URL

https://github.com/ZinkDigital/boson
Project Organization

Project Organization

io.zink
Source Code Management

Source Code Management

https://github.com/ZinkDigital/boson

Download bosonscala

How to add to project

<!-- https://jarcasting.com/artifacts/io.zink/bosonscala/ -->
<dependency>
    <groupId>io.zink</groupId>
    <artifactId>bosonscala</artifactId>
    <version>1.0.0</version>
</dependency>
// https://jarcasting.com/artifacts/io.zink/bosonscala/
implementation 'io.zink:bosonscala:1.0.0'
// https://jarcasting.com/artifacts/io.zink/bosonscala/
implementation ("io.zink:bosonscala:1.0.0")
'io.zink:bosonscala:jar:1.0.0'
<dependency org="io.zink" name="bosonscala" rev="1.0.0">
  <artifact name="bosonscala" type="jar" />
</dependency>
@Grapes(
@Grab(group='io.zink', module='bosonscala', version='1.0.0')
)
libraryDependencies += "io.zink" % "bosonscala" % "1.0.0"
[io.zink/bosonscala "1.0.0"]

Dependencies

compile (20)

Group / Artifact Type Version
io.zink : bosoncore jar 1.0.0
org.glassfish : javax.json jar 1.1
org.scala-lang.modules : scala-parser-combinators_2.12 jar 1.0.4
io.netty : netty-all jar 4.1.22.Final
org.scala-lang.modules : scala-java8-compat_2.12 jar 0.8.0
com.chuusai : shapeless_2.12 jar 2.3.3
org.parboiled : parboiled_2.12 jar 2.1.4
net.jodah : typetools jar 0.5.0
org.ow2.asm : asm jar 5.2
org.ow2.asm : asm-tree jar 5.2
org.ow2.asm : asm-analysis jar 5.2
org.ow2.asm : asm-util jar 5.2
de.undercouch : bson4jackson jar 2.7.0
io.vertx : vertx-core jar 3.5.0
com.jayway.jsonpath : json-path jar 2.4.0
com.google.code.gson : gson jar 2.3.1
org.slf4j : slf4j-simple jar 1.7.25
io.rest-assured : scala-support jar 3.0.6
io.rest-assured : rest-assured jar 3.0.6
com.squareup.okhttp3 : mockwebserver jar 3.9.1

test (3)

Group / Artifact Type Version
org.scalatest : scalatest_2.12 jar 3.0.5
junit : junit jar 4.12
com.novocode : junit-interface jar 0.11

Project Modules

There are no modules declared in this project.

Boson

Streaming Data Access for BSON and JSON encoded documents

Build Status -- Boson Scala Maven Central -- Boson Java Maven Central

Table of Contents

Introduction to Boson

Boson is a library, written in Scala with both Scala and Java APIs, built to extract and inject data to and from various ‘wire encodings’. It currently implements two input codecs, JSON documents encoded in the form of UTF8 strings, and BSON documents encoded in the form of binary arrays.

Through the use of Shapeless, Boson allows the use of user created classes as data extraction/injection types.

In the following points we show how to use Boson in both Scala and Java in a QuickStart Guide.

QuickStart Guide

Boson is available through the Central Maven Repository, divided into 3 parts, BosonScala, BosonJava and BosonCore. To include Boson in your project you can get the dependencies code for each part from Maven.

Boson

A "Boson" is an object created when constructing an extractor/injector that includes either a Bson encoded as an Array[Byte] or a Json encoded as a String in a Netty buffer and processes it according to a given expression, traversing the buffer only once.

Scala

Extraction

Extraction requires a "BsonPath" expression (see Documentation for examples and syntax), an encoded BSON and an Higher-Order Function. The Extractor instance is built only once and can be reused multiple times to extract from different encoded BSON.

// Valid Bson Event
val arrayObj = new BsonArray().add(10).add(20).add(30)
val bsonEvent = new BsonObject().put("name","SomeName").put("array", arrayObj)

// Encode Bson:  
val validBson : Array[Byte] = bsonEvent.encode.getBytes  

// BsonPath expression:  
val expression: String = ".array[1]"  

// Put the result onto a Stream.  
val valueStream : ValueStream = ValueStream()  

// Simple Extractor:  
val boson: Boson = Boson.extractor(expression, (in: Int) => {  
  valueStream.add(in) 
})  

// Trigger extraction with encoded Bson:  
boson.go(validBson)  

// Function will be called as a result of calling 'go'  

Injection

Injection requires a "BsonPath" expression (see Documentation table for examples and syntax), an encoded BSON and an Higher-Order Function. The returned result is a Future[Array[Byte]]. The Injector instance is built only once and can be reused to inject different encoded BSON.

// Valid Bson Event
val arrayObj = new BsonArray().add(10).add(20).add(30)
val bsonEvent = new BsonObject().put("name","SomeName").put("array", arrayObj)

// Encode Bson:  
val validBson: Array[Byte] = bsonEvent.encode.getBytes

// BsonPath expression:  
val expression: String = ".name"  

// Simple Injector:  
val boson: Boson = Boson.injector(expression, (in: String) => {
    in.toUpperCase
})  

// Trigger injection with encoded Bson:  
val result: Future[Array[Byte]] = boson.go(validBsonArray)

// Function will be called as a result of calling 'go'

Instead of passing a function to modify the value found throught the path, it is also possible to just inject a simple value by replacing the above injector with the following.

val boson: Boson = Boson.injector(expression, "SOMENAME")

Java

Extraction

Extraction requires a "BsonPath" expression (see Documentation table for examples and syntax), an encoded BSON and a lambda expression. The Extractor instance is built only once and can be reused multiple times to extract from different encoded BSON.

// Valid Bson Event
BsonArray arrayObj = new BsonArray().add(10).add(20).add(30);
BsonObject bsonEvent = new BsonObject().put("name","SomeName").put("array", arrayObj);
  
// Encode Bson:  
byte[] validatedByteArray = bsonEvent.encode().getBytes();  

// BsonPath expression:  
String expression = ".array[1]";  

// Want to put the result onto a Stream.  
ArrayList<Integer> mutableBuffer = new ArrayList<>();

// Simple Extractor:  
Boson boson = Boson.extractor(expression, (Integer obj)-> {  
   mutableBuffer.add(obj);
});  

// Trigger extraction with encoded Bson:  
boson.go(validatedByteArray);  

// Function will be called as a result of calling 'go'  

Injection

Injection requires a "BsonPath" expression (see Documentation table for examplesand syntax), an encoded BSON and a lambda expression. The returned result is a CompletableFuture<byte[]>. The Injector instance is built only once and can be reused to inject different encoded BSON.

//Valid Bson Event
BsonArray arrayObj = new BsonArray().add(10).add(20).add(30);
BsonObject bsonEvent = new BsonObject().put("name","SomeName").put("array", arrayObj);
 
// Encode Bson:  
byte[] validatedByteArray = bsonEvent.encode().getBytes();  

// BsonPath expression:  
String expression = ".name";  

// Simple Injector:  
Boson boson = Boson.injector(expression,  (String in) -> {  
   in.toUpperCase();  
   return in;  
});  

// Trigger injection with encoded Bson:  
byte[] result = boson.go(validatedByteArray).join();  

// Function will be called as a result of calling 'go'

Instead of passing a function to modify the value found throught the path, it is also possible to just inject a simple value by replacing the above injector with the following.

val boson: Boson = Boson.injector(expression, "SOMENAME");

Documentation

BsonPath

BosonPath expressions target a Bson structure with the same logic JsonPath expressions target a JSON structure and XPath target an XML document. Unlike in JsonPath, there is no reference of a "root member object", instead if you want to specify a path starting from the root the expression must begin with a dot (example: .key).

BsonPath expressions use the dot-notation: key1.key2[0].key3.

Expressions whose path doesn't necessarily start from the root can be expressed in two ways:

  • No dot: key
  • Two dots: ..key

Operators

Operator Description
. Child.
.. Deep scan. Available anywhere a name is required.
@ Current node.
[<number> ((to,until) <number>)] Array index or indexes.
[@<key>] Filter expression.
[first | end | all] Array index through condition.
* Wildcard. Available anywhere a name is required.

Path Examples and Comparison with JsonPath

Given the json

{  
   "Store":{  
      "Book":[  
           {  
               "Title":"Java",  
               "Price":15.5,  
               "SpecialEditions":[  
                   {  
                       "Title":"JavaMachine",  
                       "Price":39  
                   }  
                ]  
           },  
           {  
               "Title":"Scala",  
               "Pri":21.5,  
               "SpecialEditions":[  
                   {  
                       "Title":"ScalaMachine",  
                       "Price":40  
                   }  
                ]  
           },  
           {  
               "Title":"C++",  
               "Price":12.6,  
               "SpecialEditions":[  
                   {  
                       "Title":"C++Machine",  
                       "Price":38  
                   }  
                ]  
           }  
           ],  
       "Hat":[  
            {  
                "Price":48,  
                "Color":"Red"  
            },  
            {  
                "Price":35,  
                "Color":"White"  
            },  
            {  
                "Price":38,  
                "Color":"Blue"  
            }  
        ]  
    }  
}  
BsonPath JsonPath Result
.Store $.Store All Stores and what they contain
.Store.Book[@Price] $.Store.Book[?(@.Price)] All Books that contain the tag "Price"
Book[@Price]..Title $..Book[?(@.Price)]..Title All the "Titles" of the Books, available anywhere in the json, that contain the tag "Price"
Book[1] $..Book[1] The second Book of all the Book arrays available in the json
Book[0 to end]..Price $..Book[:]..Price All the values of the tag "Price" from all the Books, available in the json, and the objects they contain
Book[all].*..Title $..Book[:].*..Title All the values of the tag "Title" if the objects contained in Book, available anywhere in the json
Book[0 until end]..Price $..Book[:-1]..Price All the values of the tag "Price" from the Books, available in the json, and the objects they contain, excluding the last Book
Book[first until end].*..Title $..Book[:-1].*..Title All the values of the tag "Title" if the objects contained in each Book, available anywhere in the json, excluding the last Book
.* $.* All the objects contained in Store
Book.*.[first to end] $..Book.*.[:] An Array contained in all the objects in Book, available anywhere in the json(considering the case above, nothing)
.Store..Book[1 until end]..SpecialEditions[@Price] $.Store..Book[1:-1]..SpecialEditions[?(@.Price)] All the Special Editions, available anywhere in the Book, of Book that contain the tag "Price" from the second Book until the end, excluding
Bo*k, *ok or Bo* Non existent. Halfkeys of Book that return all Books
*ok[@Pri*]..SpecialEd*.Price Non existent. Prices of Halfkey of SpecialEditions,available anywhere in Book, of Halfkey of Book that contain the Halfkey of Price

Note: JsonPath doesn't support the halfkey (B*ok).

Java Profiler

Boson is a library that relies on high performance BSON/JSON data manipulation, and so performance monitoring is of paramount importance. The chosen java profiler is YourKit for being a supporter of open source projects and one of the most innovative and intelligent tools for profiling Java & .NET applications as well .

io.zink

Zink Digital

Versions

Version
1.0.0
0.9.0
0.8.0
0.7.0
0.6.0
0.5.0