This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-fury.git
The following commit(s) were added to refs/heads/main by this push:
new 62607949 chore(doc): sync specification doc (#1452)
62607949 is described below
commit 6260794926ee13de02fadeb7bc5817883bba8f8e
Author: Shawn Yang <[email protected]>
AuthorDate: Wed Apr 3 01:22:06 2024 +0800
chore(doc): sync specification doc (#1452)
Since our serialization spec has been formulized, we can publish it to
our website now.
This PR sync specification files to incubator-fury-website
---------
Co-authored-by: LiangliangSui
<[email protected]>
---
.github/sync.yml | 2 ++
README.md | 34 ++++++++++------------
docs/README.md | 15 ++++++----
docs/protocols/README.md | 4 ---
docs/protocols/row_format.md | 2 --
.../java_serialization_spec.md} | 5 ++++
docs/specification/row_format_spec.md | 8 +++++
.../xlang_serialization_spec.md} | 8 ++++-
8 files changed, 48 insertions(+), 30 deletions(-)
diff --git a/.github/sync.yml b/.github/sync.yml
index bed00023..432f85c5 100644
--- a/.github/sync.yml
+++ b/.github/sync.yml
@@ -18,5 +18,7 @@
apache/incubator-fury-site@main:
- source: docs/guide/
dest: docs/guide/
+ - source: docs/specification/
+ dest: docs/specification/
- source: docs/benchmarks/
dest: static/img/benchmarks/
diff --git a/README.md b/README.md
index 11bb9c23..24543cbd 100644
--- a/README.md
+++ b/README.md
@@ -25,9 +25,9 @@ https://fury.apache.org
In addition to cross-language serialization, Fury also features at:
-- Drop-in replace Java serialization frameworks such as JDK/Kryo/Hessian, but
100x faster at most, which can greatly improve
+- Drop-in replace Java serialization frameworks such as JDK/Kryo/Hessian, but
100x faster at most, which can greatly improve
the efficiency of high-performance RPC calls, data transfer, and object
persistence.
-- **100% compatible** with JDK serialization API with much faster
implementation: supporting JDK
`writeObject`/`readObject`/`writeReplace`/`readResolve`/`readObjectNoData`/`Externalizable`
API.
+- **100% compatible** with JDK serialization API with much faster
implementation: supporting JDK
`writeObject`/`readObject`/`writeReplace`/`readResolve`/`readObjectNoData`/`Externalizable`
API.
- Supports **Java 8~21**, Java 17+ `record` is supported too.
- Supports [AOT compilation serialization](docs/guide/graalvm_guide.md) for
**GraalVM native image**, and no reflection/serialization json config are
needed.
- Supports shared and circular reference object serialization for golang.
@@ -35,19 +35,17 @@ In addition to cross-language serialization, Fury also
features at:
- Supports automatic object serialization for golang.
## Protocols
-Different scenarios have different serialization requirements. Fury designed
and implemented
-multiple binary protocols for those requirements:
-- **Cross-language object graph protocol**:
- - Cross-language serialize any object automatically, no need for IDL
definition, schema compilation and object to/from protocol
- conversion.
- - Support shared reference and circular reference, no duplicate data or
recursion error.
+Fury designed and implemented multiple binary protocols for different
scenarios:
+- **[xlang serialization
format](docs/specification/xlang_serialization_spec.md)**:
+ - Cross-language serialize any object automatically, no need for IDL
definition, schema compilation and object to/from
+ protocol conversion.
+ - Support optional shared reference and circular reference, no duplicate
data or recursion error.
- Support object polymorphism.
-- **Native java/python object graph protocol**: Highly-optimized based on type
system of the language.
-- **Row format protocol**: A cache-friendly binary random access format,
supports skipping serialization and partial serialization,
- and can convert to column-format automatically.
+- **[Java serialization
format](docs/specification/java_serialization_spec.md)**: Highly-optimized and
drop-in replacement for Java serialization.
+- **[Row format format](docs/specification/row_format_spec.md)**: A
cache-friendly binary random access format, supports skipping serialization and
+ partial serialization, and can convert to column-format automatically.
-New protocols can be easily added based on Fury existing buffer, encoding,
meta, codegen and other capabilities. All of those share the same codebase, and
the optimization for one protocol
-can be reused by another protocol.
+New protocols can be easily added based on Fury existing buffer, encoding,
meta, codegen and other capabilities. All of those share the same codebase, and
the optimization for one protocol can be reused by another protocol.
## Benchmarks
Different serialization frameworks are suitable for different scenarios, and
benchmark results here are for reference only.
@@ -149,7 +147,7 @@ go get github.com/apache/incubator-fury/go/fury
Here we give a quick start about how to use Fury, see [user
guide](https://github.com/apache/incubator-fury/blob/main/docs/README.md) for
more details about
[java](https://github.com/apache/incubator-fury/blob/main/docs/guide/java_object_graph_guide.md),
[cross
language](https://github.com/apache/incubator-fury/blob/main/docs/guide/xlang_object_graph_guide.md),
and [row
format](https://github.com/apache/incubator-fury/blob/main/docs/guide/row_format_guide.md).
### Fury java object graph serialization
-If you don't have cross-language requirements, using this mode will
+If you don't have cross-language requirements, using this mode will
result in better performance.
```java
import org.apache.fury.*;
@@ -159,11 +157,11 @@ import java.util.*;
public class Example {
public static void main(String[] args) {
SomeClass object = new SomeClass();
- // Note that Fury instances should be reused between
+ // Note that Fury instances should be reused between
// multiple serializations of different objects.
{
Fury fury = Fury.builder().withLanguage(Language.JAVA)
- // Allow to deserialize objects unknown types, more flexible
+ // Allow to deserialize objects unknown types, more flexible
// but may be insecure if the classes contains malicious code.
.requireClassRegistration(true)
.build();
@@ -175,7 +173,7 @@ public class Example {
}
{
ThreadSafeFury fury = Fury.builder().withLanguage(Language.JAVA)
- // Allow to deserialize objects unknown types, more flexible
+ // Allow to deserialize objects unknown types, more flexible
// but may be insecure if the classes contains malicious code.
.requireClassRegistration(true)
.buildThreadSafeFury();
@@ -251,7 +249,7 @@ data = fury.serialize(obj)
print(fury.deserialize(data))
```
-**Golang**
+**Golang**
```go
package main
diff --git a/docs/README.md b/docs/README.md
index ac11b744..bb09506d 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,10 +1,15 @@
# User Guide
-- For Cross Language Object Graph Guide, see
[xlang_object_graph_guide](guide/xlang_object_graph_guide.md) doc.
-- For Java Object Graph Guide, see
[java_object_graph_guide](guide/java_object_graph_guide.md) doc.
-- For Row Format Guide, see [row format_guide](guide/row_format_guide.md) doc.
-- For Scala Guide, see [scala_guide](guide/scala_guide.md) doc.
+- For Cross Language Object Graph Guide, see [xlang serialization
guide](guide/xlang_object_graph_guide.md) doc.
+- For Java Object Graph Guide, see [java serialization
guide](guide/java_object_graph_guide.md) doc.
+- For Row Format Guide, see [row format guide](guide/row_format_guide.md) doc.
+- For Scala Guide, see [scala guide](guide/scala_guide.md) doc.
- For using Fury with GraalVM native image, see [graalvm native image
guide](guide/graalvm_guide.md) doc.
+# Serialization Format
+- For Cross Language Serialization Format, see [xlang serialization
spec](specification/xlang_serialization_spec.md) doc.
+- For Java Object Graph Format, see [java serialization
spec](specification/java_serialization_spec.md) doc.
+- For Row Format, see [row format spec](specification/row_format_spec.md) doc.
+
# Development
-- For cpp debug, see [cpp_debug](cpp_debug.md) doc.
+- For cpp debug, see [cpp debug](cpp_debug.md) doc.
- For development, see [CONTRIBUTING](../CONTRIBUTING.md) doc.
diff --git a/docs/protocols/README.md b/docs/protocols/README.md
deleted file mode 100644
index 5e0a0557..00000000
--- a/docs/protocols/README.md
+++ /dev/null
@@ -1,4 +0,0 @@
-# Serialization Protocols
-- For Cross Language Object Graph Protocol, see
[xlang_object_graph_format_spec](./xlang_object_graph_spec.md) doc.
-- For Java Object Graph Protocol, see
[java_object_graph_format_spec](java_object_graph_spec.md) doc.
-- For Row Format Protocol, see [row format_spec](./row_format.md) doc.
diff --git a/docs/protocols/row_format.md b/docs/protocols/row_format.md
deleted file mode 100644
index 4fa35ffb..00000000
--- a/docs/protocols/row_format.md
+++ /dev/null
@@ -1,2 +0,0 @@
-# Row Format
-Coming soon
diff --git a/docs/protocols/java_object_graph_spec.md
b/docs/specification/java_serialization_spec.md
similarity index 99%
rename from docs/protocols/java_object_graph_spec.md
rename to docs/specification/java_serialization_spec.md
index 03573747..a5d0beca 100644
--- a/docs/protocols/java_object_graph_spec.md
+++ b/docs/specification/java_serialization_spec.md
@@ -1,3 +1,8 @@
+---
+title: Fury Java Serialization Format
+sidebar_position: 1
+id: fury_java_serialization_spec
+---
# Fury Java Serialization Specification
## Spec overview
diff --git a/docs/specification/row_format_spec.md
b/docs/specification/row_format_spec.md
new file mode 100644
index 00000000..d32c11ab
--- /dev/null
+++ b/docs/specification/row_format_spec.md
@@ -0,0 +1,8 @@
+---
+title: Fury Row Format
+sidebar_position: 2
+id: fury_row_format_spec
+---
+
+# Row Format
+Coming soon
diff --git a/docs/protocols/xlang_object_graph_spec.md
b/docs/specification/xlang_serialization_spec.md
similarity index 99%
rename from docs/protocols/xlang_object_graph_spec.md
rename to docs/specification/xlang_serialization_spec.md
index a423bd17..e01ec921 100644
--- a/docs/protocols/xlang_object_graph_spec.md
+++ b/docs/specification/xlang_serialization_spec.md
@@ -1,4 +1,10 @@
-# Cross language object graph serialization
+---
+title: Fury Xlang Serialization Format
+sidebar_position: 0
+id: fury_xlang_serialization_spec
+---
+
+# Cross-language Serialization Specification
> Format Version History:
> - Version 0.1 - serialization spec formalized
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
