Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/syntifi/borshj
Borsh binary serialization format support for Java.
https://github.com/syntifi/borshj
borsh near-protocol serialization-libraries
Last synced: 2 months ago
JSON representation
Borsh binary serialization format support for Java.
- Host: GitHub
- URL: https://github.com/syntifi/borshj
- Owner: syntifi
- License: apache-2.0
- Created: 2022-02-24T12:08:40.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2022-03-03T16:58:08.000Z (almost 3 years ago)
- Last Synced: 2023-05-24T11:24:03.765Z (over 1 year ago)
- Topics: borsh, near-protocol, serialization-libraries
- Language: Java
- Homepage: https://syntifi.github.io/borshj/
- Size: 580 KB
- Stars: 4
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# BorshJ
[](https://github.com/syntifi/borshj/actions/workflows/gradle.yml)
[](https://www.apache.org/licenses/LICENSE-2.0.txt)
**BorshJ** is an implementation of the [Borsh] binary serialization format for
Java (and Kotlin, Scala, Clojure, Groovy, Jython, JRuby, etc.) projects.
Borsh stands for _Binary Object Representation Serializer for Hashing_. It is
meant to be used in security-critical projects as it prioritizes consistency,
safety, speed, and comes with a strict specification.
## Features
- Implements [`BorshBuffer`] on top of Java's [`ByteBuffer`].
- Implements [`BorshReader`] on top of any Java [`InputStream`].
- Implements [`BorshWriter`] on top of any Java [`OutputStream`].
- Provides [`BorshField`] with order parameter for including and sorting POJO fields.
- Provides [`BorshSubTypes`] and [`BorshSubType`] for supporting serialization of interface implementations.
- Based on Java NIO, enabling high-performance, zero-copy interoperability
with native code via JNI.
- GC friendly: avoids unnecessary copying wherever possible.
## Prerequisites
- [Java] 8+ (this library is compatible with Android)
- [Gradle] (when building from source code)
## Installation
We are working on building release binaries. They will be available here soon.
In the meantime, if you wish to try out BorshJ, you will need to build the JAR
file from source code yourself:
```bash
git clone https://github.com/syntifi/borshj.git
cd borshj
gradle jar
ls -l build/libs/borshj-$(cat VERSION).jar
```
## Usage
To use the Borsh object serializer/deserializer, you need add just one import:
```java
import com.syntifi.near.borshj.Borsh;
```
## Examples
The following code examples further below are all predicated on this simple
data class definition:
```java
public class Point2D implements Borsh {
@BorshField(order = 1)
public float x;
@BorshField(order = 2)
public float y;
public Point2D() {}
public Point2D(float x, float y) {
this.x = x;
this.y = y;
}
}
```
> **NOTE:** Only non-transient and annotated fields with [`BorshField`] will be serialized.
### Serializing an object
To serialize a [POJO], use the `Borsh.serialize()` method:
```java
Point2D point = new Point2D(123.0, 456.0);
byte[] bytes = Borsh.serialize(point);
```
### Deserializing an object
To deserialize a [POJO], use the `Borsh.deserialize()` method:
```java
Point2D point = Borsh.deserialize(bytes, Point2D.class);
```
## Type Mappings
| Borsh | Java | TypeScript |
|-----------------------|----------------|-------------|
| `u8` integer | `byte` | `number` |
| `u16` integer | `short` | `number` |
| `u32` integer | `int` | `number` |
| `u64` integer | `long` | `BN` |
| `u128` integer | [`BigInteger`] | `BN` |
| `f32` float | `float` | N/A |
| `f64` float | `double` | N/A |
| fixed-size byte array | `byte[]` | `Uint8Array` |
| UTF-8 string | `String` | `string` |
| option | [`Optional`] | `null` or type |
| map | [`Map`] | N/A |
| set | [`Set`] | N/A |
| structs | `Object` | `any` |
| enum | `Enum` | - |
| subtypes | `interface` | - |
## Frequently Asked Questions
### Q: Why does my class need a default constructor?
Classes used with `Borsh.deserialize()` must have a nullary default constructor
because instances of the class will be instantiated through Java's
[reflection API](https://www.baeldung.com/java-reflection).
[Borsh]: https://borsh.io
[Gradle]: https://gradle.org
[Java]: https://java.com
[POJO]: https://en.wikipedia.org/wiki/Plain_old_Java_object
[`BigInteger`]: https://docs.oracle.com/javase/10/docs/api/java/math/BigInteger.html
[`BorshBuffer`]: https://github.com/syntifi/borshj/blob/master/src/main/java/com/syntifi/near/borshj/BorshBuffer.java
[`BorshReader`]: https://github.com/syntifi/borshj/blob/master/src/main/java/com/syntifi/near/borshj/BorshReader.java
[`BorshWriter`]: https://github.com/syntifi/borshj/blob/master/src/main/java/com/syntifi/near/borshj/BorshWriter.java
[`BorshField`]: https://github.com/syntifi/borshj/blob/master/src/main/java/com/syntifi/near/borshj/annotation/BorshField.java
[`BorshSubTypes`]: https://github.com/syntifi/borshj/blob/master/src/main/java/com/syntifi/near/borshj/annotation/BorshSubTypes.java
[`BorshSubType`]: https://github.com/syntifi/borshj/blob/master/src/main/java/com/syntifi/near/borshj/annotation/BorshSubType.java
[`ByteBuffer`]: https://docs.oracle.com/javase/10/docs/api/java/nio/ByteBuffer.html
[`InputStream`]: https://docs.oracle.com/javase/10/docs/api/java/io/InputStream.html
[`Map`]: https://docs.oracle.com/javase/10/docs/api/java/util/Map.html
[`Optional`]: https://docs.oracle.com/javase/10/docs/api/java/util/Optional.html
[`OutputStream`]: https://docs.oracle.com/javase/10/docs/api/java/io/OutputStream.html
[`Set`]: https://docs.oracle.com/javase/10/docs/api/java/util/Set.html