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-site.git
commit dd1031efcc3b6b0f0b499c638a701b5b3dc26fc6
Author: chaokunyang <shawn.ck.y...@gmail.com>
AuthorDate: Wed Dec 27 00:47:25 2023 +0000
🔄 synced local 'docs/guide/' with remote 'docs/guide/'
---
docs/guide/DEVELOPMENT.md | 2 +-
docs/guide/graalvm_guide.md | 38 +++++++++++++++++-----------------
docs/guide/java_object_graph_guide.md | 36 ++++++++++++++++----------------
docs/guide/scala_guide.md | 17 ++++++++-------
docs/guide/xlang_object_graph_guide.md | 32 ++++++++++++++--------------
5 files changed, 64 insertions(+), 61 deletions(-)
diff --git a/docs/guide/DEVELOPMENT.md b/docs/guide/DEVELOPMENT.md
index cd0223f..65b95b9 100644
--- a/docs/guide/DEVELOPMENT.md
+++ b/docs/guide/DEVELOPMENT.md
@@ -6,7 +6,7 @@ order: 6
## Get the source code
-Github repo: https://github.com/alipay/fury
+Github repo: https://github.com/apache/incubator-fury
## Building Fury 🏋🏿♀️
diff --git a/docs/guide/graalvm_guide.md b/docs/guide/graalvm_guide.md
index d94fd72..9229d0e 100644
--- a/docs/guide/graalvm_guide.md
+++ b/docs/guide/graalvm_guide.md
@@ -14,15 +14,15 @@ any extra cost, the performance is great.
In order to use Fury on graalvm native image, you must create Fury as an
**static** field of a class, and **register** all classes at
the enclosing class initialize time. Then configure `native-image.properties`
under
`resources/META-INF/native-image/$xxx/native-image.propertie` to tell graalvm
to init the class at native image
-build time. For example, here we configure `io.fury.graalvm.Example` class be
init at build time:
+build time. For example, here we configure `org.apache.fury.graalvm.Example`
class be init at build time:
```properties
-Args = --initialize-at-build-time=io.fury.graalvm.Example
+Args = --initialize-at-build-time=org.apache.fury.graalvm.Example
```
Another benefit using fury is that you don't have to configure [reflection
json](https://www.graalvm.org/latest/reference-manual/native-image/metadata/#specifying-reflection-metadata-in-json)
and
[serialization
json](https://www.graalvm.org/latest/reference-manual/native-image/metadata/#serialization),
which is
very tedious, cumbersome and inconvenient. When using fury, you just need to
invoke
-`io.fury.Fury.register(Class<?>, boolean)` for every type you want to
serialize.
+`org.apache.fury.Fury.register(Class<?>, boolean)` for every type you want to
serialize.
Note that Fury `asyncCompilationEnabled` option will be disabled automatically
for graalvm native image since graalvm
native image doesn't support JIT at the image run time.
@@ -30,8 +30,8 @@ native image doesn't support JIT at the image run time.
## Not thread-safe Fury
Example:
```java
-import io.fury.Fury;
-import io.fury.util.Preconditions;
+import org.apache.fury.Fury;
+import org.apache.fury.util.Preconditions;
import java.util.List;
import java.util.Map;
@@ -62,17 +62,17 @@ public class Example {
}
}
```
-Then add `io.fury.graalvm.Example` build time init to
`native-image.properties` configuration:
+Then add `org.apache.fury.graalvm.Example` build time init to
`native-image.properties` configuration:
```properties
-Args = --initialize-at-build-time=io.fury.graalvm.Example
+Args = --initialize-at-build-time=org.apache.fury.graalvm.Example
```
## Thread-safe Fury
```java
-import io.fury.Fury;
-import io.fury.ThreadLocalFury;
-import io.fury.ThreadSafeFury;
-import io.fury.util.Preconditions;
+import org.apache.fury.Fury;
+import org.apache.fury.ThreadLocalFury;
+import org.apache.fury.ThreadSafeFury;
+import org.apache.fury.util.Preconditions;
import java.util.List;
import java.util.Map;
@@ -108,15 +108,15 @@ public class ThreadSafeExample {
}
}
```
-Then add `io.fury.graalvm.ThreadSafeExample` build time init to
`native-image.properties` configuration:
+Then add `org.apache.fury.graalvm.ThreadSafeExample` build time init to
`native-image.properties` configuration:
```properties
-Args = --initialize-at-build-time=io.fury.graalvm.ThreadSafeExample
+Args = --initialize-at-build-time=org.apache.fury.graalvm.ThreadSafeExample
```
## Framework Integration
For framework developers, if you want to integrate fury for serialization, you
can provided a configuration file to let
the users to list all the classes they want to serialize, then you can load
those classes and invoke
-`io.fury.Fury.register(Class<?>, boolean)` to register those classes in your
Fury integration class, and configure that
+`org.apache.fury.Fury.register(Class<?>, boolean)` to register those classes
in your Fury integration class, and configure that
class be initialized at graalvm native image build time.
## Benchmark
@@ -130,7 +130,7 @@ When Fury compression is enabled:
- Struct: Fury is `24x speed, 31% size` compared to JDK.
- Pojo: Fury is `12x speed, 48% size` compared to JDK.
-See
[[Benchmark.java](../../integration_tests/graalvm_tests/src/main/java/io/fury/graalvm/Benchmark.java)]
for benchmark code.
+See
[[Benchmark.java](../../integration_tests/graalvm_tests/src/main/java/org/apache/fury/graalvm/Benchmark.java)]
for benchmark code.
### Struct Benchmark
#### Class Fields
@@ -154,7 +154,7 @@ public class Struct implements Serializable {
No compression:
```
Benchmark repeat number: 400000
-Object type: class io.fury.graalvm.Struct
+Object type: class org.apache.fury.graalvm.Struct
Compress number: false
Fury size: 76.0
JDK size: 178.0
@@ -166,7 +166,7 @@ Compare size: Fury is 0.43x size of JDK
Compress number:
```
Benchmark repeat number: 400000
-Object type: class io.fury.graalvm.Struct
+Object type: class org.apache.fury.graalvm.Struct
Compress number: true
Fury size: 55.0
JDK size: 178.0
@@ -190,7 +190,7 @@ public class Foo implements Serializable {
No compression:
```
Benchmark repeat number: 400000
-Object type: class io.fury.graalvm.Foo
+Object type: class org.apache.fury.graalvm.Foo
Compress number: false
Fury size: 541.0
JDK size: 964.0
@@ -202,7 +202,7 @@ Compare size: Fury is 0.56x size of JDK
Compress number:
```
Benchmark repeat number: 400000
-Object type: class io.fury.graalvm.Foo
+Object type: class org.apache.fury.graalvm.Foo
Compress number: true
Fury size: 459.0
JDK size: 964.0
diff --git a/docs/guide/java_object_graph_guide.md
b/docs/guide/java_object_graph_guide.md
index 4c38e02..b4dff62 100644
--- a/docs/guide/java_object_graph_guide.md
+++ b/docs/guide/java_object_graph_guide.md
@@ -20,8 +20,8 @@ Fury for single-thread usage:
import java.util.List;
import java.util.Arrays;
-import io.fury.*;
-import io.fury.config.*;
+import org.apache.fury.*;
+import org.apache.fury.config.*;
public class Example {
public static void main(String[] args) {
@@ -31,7 +31,7 @@ public class Example {
Fury fury = Fury.builder().withLanguage(Language.JAVA)
// Allow to deserialize objects unknown types, more flexible
// but may be insecure if the classes contains malicious code.
- .requireClassRegistration(false)
+ .requireClassRegistration(true)
.build();
// Registering types can reduce class name serialization overhead, but not
mandatory.
// If class registration enabled, all custom types must be registered.
@@ -48,8 +48,8 @@ Fury for multiple-thread usage:
import java.util.List;
import java.util.Arrays;
-import io.fury.*;
-import io.fury.config.*;
+import org.apache.fury.*;
+import org.apache.fury.config.*;
public class Example {
public static void main(String[] args) {
@@ -74,15 +74,15 @@ Fury instances reuse example:
import java.util.List;
import java.util.Arrays;
-import io.fury.*;
-import io.fury.config.*;
+import org.apache.fury.*;
+import org.apache.fury.config.*;
public class Example {
// reuse fury.
private static final ThreadSafeFury fury = Fury.builder()
// Allow to deserialize objects unknown types, more flexible
// but may be insecure if the classes contains malicious code.
- .requireClassRegistration(false)
+ .requireClassRegistration(true)
.buildThreadSafeFury();
public static void main(String[] args) {
@@ -244,7 +244,7 @@ fury.register(SomeClass1.class, 200);
```
If you invoke `FuryBuilder#requireClassRegistration(false)` to disable class
registration check,
-you can set `io.fury.resolver.ClassChecker` by `ClassResolver#setClassChecker`
to control which classes are allowed
+you can set `org.apache.fury.resolver.ClassChecker` by
`ClassResolver#setClassChecker` to control which classes are allowed
for serialization. For example,you can allow classes started with
`org.example.*` by:
```java
Fury fury = xxx;
@@ -253,7 +253,7 @@ fury.getClassResolver().setClassChecker((classResolver,
className) -> className.
```java
AllowListChecker checker = new
AllowListChecker(AllowListChecker.CheckLevel.STRICT);
ThreadSafeFury fury = new ThreadLocalFury(classLoader -> {
- Fury f =
Fury.builder().requireClassRegistration(false).withClassLoader(classLoader).build();
+ Fury f =
Fury.builder().requireClassRegistration(true).withClassLoader(classLoader).build();
f.getClassResolver().setClassChecker(checker);
checker.addListener(f.getClassResolver());
return f;
@@ -261,7 +261,7 @@ ThreadSafeFury fury = new ThreadLocalFury(classLoader -> {
checker.allowClass("org.example.*");
```
-Fury also provided a `io.fury.resolver.AllowListChecker` which is
white/blacklist based checker to simplify
+Fury also provided a `org.apache.fury.resolver.AllowListChecker` which is
white/blacklist based checker to simplify
the customization of class check mechanism. You can use this checker or
implement more sophisticated checker by yourself.
### Serializer Registration
@@ -273,10 +273,10 @@ Or implement `java.io.Externalizable` for a class.
### Zero-Copy Serialization
```java
-import io.fury.*;
-import io.fury.config.*;
-import io.fury.serializers.BufferObject;
-import io.fury.memory.MemoryBuffer;
+import org.apache.fury.*;
+import org.apache.fury.config.*;
+import org.apache.fury.serializers.BufferObject;
+import org.apache.fury.memory.MemoryBuffer;
import java.util.*;
import java.util.stream.Collectors;
@@ -355,7 +355,7 @@ returned.
### JDK migration
If you use jdk serialization before, and you can't upgrade your client and
server at the same time, which is common for
-online application. Fury provided an util method
`io.fury.serializer.JavaSerializer.serializedByJDK` to check whether
+online application. Fury provided an util method
`org.apache.fury.serializer.JavaSerializer.serializedByJDK` to check whether
the binary are generated by jdk serialization, you use following pattern to
make exiting serialization protocol-aware,
then upgrade serialization to fury in an async rolling-up way:
@@ -396,10 +396,10 @@ no need to `versioning` the data.
## Trouble shooting
### Class inconsistency and class version check
-If you create fury without setting `CompatibleMode` to
`io.fury.config.CompatibleMode.COMPATIBLE`, and you got a strange
+If you create fury without setting `CompatibleMode` to
`org.apache.fury.config.CompatibleMode.COMPATIBLE`, and you got a strange
serialization error, it may be caused by class inconsistency between
serialization peer and deserialization peer.
-In such cases, you can invoke `FuryBuilder#withClassVersionCheck` to create
fury to validate it, if deserialization throws
`io.fury.exception.ClassNotCompatibleException`, it shows class are
inconsistent, and you should create fury with
+In such cases, you can invoke `FuryBuilder#withClassVersionCheck` to create
fury to validate it, if deserialization throws
`org.apache.fury.exception.ClassNotCompatibleException`, it shows class are
inconsistent, and you should create fury with
`FuryBuilder#withCompaibleMode(CompatibleMode.COMPATIBLE)`.
`CompatibleMode.COMPATIBLE` has more performance and space cost, do not set it
by default if your classes are always consistent between serialization and
deserialization.
diff --git a/docs/guide/scala_guide.md b/docs/guide/scala_guide.md
index 6fdf220..abce514 100644
--- a/docs/guide/scala_guide.md
+++ b/docs/guide/scala_guide.md
@@ -15,7 +15,7 @@ Scala 2 and 3 are both supported.
## Install
```sbt
-libraryDependencies += "org.furyio" % "fury-core" % "0.4.1"
+libraryDependencies += "org.apache.fury" % "fury-core" % "0.4.1"
```
## Fury creation
@@ -23,16 +23,19 @@ When using fury for scala serialization, you should create
fury at least with fo
```scala
val fury = Fury.builder()
.withScalaOptimizationEnabled(true)
- .requireClassRegistration(false)
+ .requireClassRegistration(true)
.withRefTracking(true)
.build()
```
-Otherwise if you serialize some scala types such as `collection/Enumeration`,
you will need to register some scala internal types:
+Depending on the object types you serialize, you may need to register some
scala internal types:
```scala
fury.register(Class.forName("scala.collection.generic.DefaultSerializationProxy"))
fury.register(Class.forName("scala.Enumeration.Val"))
```
-And circular references are common in scala, `Reference tracking` should be
enabled by `FuryBuilder#withRefTracking(true)`. If you don't enable reference
tracking, [StackOverflowError](https://github.com/alipay/fury/issues/1032) may
happen for some scala versions when serializing scala Enumeration.
+If you want to avoid such registration, you can disable class registration by
`FuryBuilder#requireClassRegistration(false)`.
+Note that this option allow to deserialize objects unknown types, more
flexible but may be insecure if the classes contains malicious code.
+
+And circular references are common in scala, `Reference tracking` should be
enabled by `FuryBuilder#withRefTracking(true)`. If you don't enable reference
tracking,
[StackOverflowError](https://github.com/apache/incubator-fury/issues/1032) may
happen for some scala versions when serializing scala Enumeration.
Note that fury instance should be shared between multiple serialization, the
creation of fury instance is not cheap.
@@ -109,8 +112,8 @@ Scala `pojo/bean/case/object` are supported by fury jit
well, the performance is
Scala collections and generics doesn't follow java collection framework, and
is not fully integrated with Fury JIT in current release version. The
performance won't be as good as fury collections serialization for java.
-The execution for scala collections will invoke Java serialization API
`writeObject/readObject/writeReplace/readResolve/readObjectNoData/Externalizable`
with fury `ObjectStream` implementation. Although
`io.fury.serializer.ObjectStreamSerializer` is much faster than JDK
`ObjectOutputStream/ObjectInputStream`, but it still doesn't know how use scala
collection generics.
+The execution for scala collections will invoke Java serialization API
`writeObject/readObject/writeReplace/readResolve/readObjectNoData/Externalizable`
with fury `ObjectStream` implementation. Although
`org.apache.fury.serializer.ObjectStreamSerializer` is much faster than JDK
`ObjectOutputStream/ObjectInputStream`, but it still doesn't know how use scala
collection generics.
-In future we plan to provide more optimization for scala types, see
https://github.com/alipay/fury/issues/682, stay tuned!
+In future we plan to provide more optimization for scala types, see
https://github.com/apache/incubator-fury/issues/682, stay tuned!
-Scala collections serialization is finished in
https://github.com/alipay/fury/pull/1073, if you want better performance,
please use fury snapshot version.
+Scala collections serialization is finished in
https://github.com/apache/incubator-fury/pull/1073, if you want better
performance, please use fury snapshot version.
diff --git a/docs/guide/xlang_object_graph_guide.md
b/docs/guide/xlang_object_graph_guide.md
index 40c2f72..9a65cb3 100644
--- a/docs/guide/xlang_object_graph_guide.md
+++ b/docs/guide/xlang_object_graph_guide.md
@@ -12,8 +12,8 @@ Common types can be serialized automatically: primitive
numeric types, string, b
**Java**
```java
-import io.fury.*;
-import io.fury.config.*;
+import org.apache.fury.*;
+import org.apache.fury.config.*;
import java.util.*;
@@ -59,7 +59,7 @@ print(new_map)
```go
package main
-import furygo "github.com/alipay/fury/fury/go/fury"
+import furygo "github.com/apache/incubator-fury/fury/go/fury"
import "fmt"
func main() {
@@ -131,8 +131,8 @@ Serializing user-defined types needs registering the custom
type using the regis
**Java**
```java
-import io.fury.*;
-import io.fury.config.*;
+import org.apache.fury.*;
+import org.apache.fury.config.*;
import java.util.*;
public class Example2 {
@@ -176,7 +176,7 @@ public class Example2 {
return obj;
}
- // mvn exec:java -Dexec.mainClass="io.fury.examples.Example2"
+ // mvn exec:java -Dexec.mainClass="org.apache.fury.examples.Example2"
public static void main(String[] args) {
Fury fury = Fury.builder().withLanguage(Language.XLANG).build();
fury.register(SomeClass1.class, "example.SomeClass1");
@@ -251,7 +251,7 @@ if __name__ == "__main__":
```go
package main
-import furygo "github.com/alipay/fury/fury/go/fury"
+import furygo "github.com/apache/incubator-fury/fury/go/fury"
import "fmt"
func main() {
@@ -400,8 +400,8 @@ Shared reference and circular reference can be serialized
automatically, no dupl
**Java**
```java
-import io.fury.*;
-import io.fury.config.*;
+import org.apache.fury.*;
+import org.apache.fury.config.*;
import java.util.*;
public class ReferenceExample {
@@ -419,7 +419,7 @@ public class ReferenceExample {
return obj;
}
- // mvn exec:java -Dexec.mainClass="io.fury.examples.ReferenceExample"
+ // mvn exec:java -Dexec.mainClass="org.apache.fury.examples.ReferenceExample"
public static void main(String[] args) {
Fury fury = Fury.builder().withLanguage(Language.XLANG)
.withRefTracking(true).build();
@@ -457,7 +457,7 @@ print(fury.deserialize(data))
```go
package main
-import furygo "github.com/alipay/fury/fury/go/fury"
+import furygo "github.com/apache/incubator-fury/fury/go/fury"
import "fmt"
func main() {
@@ -521,10 +521,10 @@ Reference cannot be implemented because of rust ownership
restrictions
**Java**
```java
-import io.fury.*;
-import io.fury.config.*;
-import io.fury.serializers.BufferObject;
-import io.fury.memory.MemoryBuffer;
+import org.apache.fury.*;
+import org.apache.fury.config.*;
+import org.apache.fury.serializers.BufferObject;
+import org.apache.fury.memory.MemoryBuffer;
import java.util.*;
import java.util.stream.Collectors;
@@ -566,7 +566,7 @@ print(fury.deserialize(data, buffers=buffers))
```go
package main
-import furygo "github.com/alipay/fury/fury/go/fury"
+import furygo "github.com/apache/incubator-fury/fury/go/fury"
import "fmt"
func main() {
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@fury.apache.org
For additional commands, e-mail: commits-h...@fury.apache.org
