Skip to content

configuration.md

Latest commit

 

History

History
101 lines (86 loc) · 17.9 KB

configuration.md

File metadata and controls

101 lines (86 loc) · 17.9 KB
title Configuration
sidebar_position 4
id configuration
license Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

This page documents all configuration options available through ForyBuilder.

ForyBuilder Options

Option Name Description Default Value
timeRefIgnored Whether to ignore reference tracking of all time types registered in TimeSerializers and subclasses of those types when ref tracking is enabled. If ignored, ref tracking of every time type can be enabled by invoking Fory#registerSerializer(Class, Serializer). For example, fory.registerSerializer(Date.class, new DateSerializer(fory.getConfig(), true)). Note that enabling ref tracking should happen before serializer codegen of any types which contain time fields. Otherwise, those fields will still skip ref tracking. true
compressInt Enables or disables int compression for smaller size. true
compressLong Enables or disables long compression for smaller size. true
compressIntArray Enables or disables SIMD-accelerated compression for int arrays when values can fit in smaller data types. Requires Java 16+. false
compressLongArray Enables or disables SIMD-accelerated compression for long arrays when values can fit in smaller data types. Requires Java 16+. false
compressString Enables or disables string compression for smaller size. false
classLoader The classloader is fixed per Fory instance because Fory caches class metadata. To use a different loader, create a new Fory or ThreadSafeFory configured with that loader, or rely on the thread context classloader before first class resolution. Thread.currentThread().getContextClassLoader()
compatible Type forward/backward compatibility config. false: class schema must be consistent between serialization peer and deserialization peer. true: class schema can be different between serialization peer and deserialization peer. They can add/delete fields independently. When unset, the default follows the wire mode: xlang mode uses true, and native mode uses false. See more. xlang: true; native: false
checkClassVersion Determines whether to check the consistency of the class schema. If enabled, Fory checks, writes, and checks consistency using the classVersionHash. It will be automatically disabled when compatible mode is enabled. Disabling is not recommended unless you can ensure the class won't evolve. false
checkJdkClassSerializable Enables or disables checking of Serializable interface for classes under java.*. If a class under java.* is not Serializable, Fory will throw an UnsupportedOperationException. true
registerGuavaTypes Whether to pre-register Guava types such as RegularImmutableMap/RegularImmutableList. These types are not public API, but seem pretty stable. true
requireClassRegistration Disabling may allow unknown classes to be deserialized, potentially causing security risks. true
maxDepth Set max depth for deserialization, when depth exceeds, an exception will be thrown. This can be used to refuse deserialization DDOS attack. 50
suppressClassRegistrationWarnings Whether to suppress class registration warnings. The warnings can be used for security audit, but may be annoying, this suppression will be enabled by default. true
metaShareEnabled Enables or disables meta share mode. true if compatible mode is enabled, otherwise false.
scopedMetaShareEnabled Scoped meta share focuses on a single serialization process. Metadata created or identified during this process is exclusive to it and is not shared with by other serializations. true if compatible mode is enabled, otherwise false.
metaCompressor Set a compressor for meta compression. Note that the passed MetaCompressor should be thread-safe. By default, a Deflater based compressor DeflaterMetaCompressor will be used. Users can pass other compressor such as zstd for better compression rate. DeflaterMetaCompressor
deserializeUnknownClass Enables or disables deserialization/skipping of data for non-existent or unknown classes. true if compatible mode is enabled, otherwise false.
codeGenEnabled Disabling may result in faster initial serialization but slower subsequent serializations. When unset, codegen defaults to enabled on ordinary JVMs and disabled on Android and GraalVM native image. Explicit withCodegen(true) on Android or GraalVM native image is accepted, but final build configuration forces interpreter serializers and emits a warning. If a build-time @ForyStruct static serializer is available, ordinary JVM withCodegen(false) and Android use it instead of the interpreter object serializer. true on ordinary JVMs; false on Android and GraalVM native image
asyncCompilationEnabled If enabled, serialization uses interpreter mode first and switches to JIT serialization after async serializer JIT for a class is finished. This option is forced off on Android and GraalVM native image because runtime code generation is unavailable there. false
copyRef When disabled, the copy performance will be better. But fory deep copy will ignore circular and shared reference. Same reference of an object graph will be copied into different objects in one Fory#copy. false
serializeEnumByName When enabled, Fory serializes enum names instead of numeric enum tags. Without this option, Fory writes declaration ordinals by default, or explicit stable ids when the enum is configured with @ForyEnumId. false

Example Configuration

Fory fory = Fory.builder()
  .withXlang(false)
  // enable reference tracking for shared/circular reference.
  // Disable it will have better performance if no duplicate reference.
  .withRefTracking(false)
  // compress int for smaller size
  .withIntCompressed(true)
  // compress long for smaller size
  .withLongCompressed(true)
  .withCompatible(false)
  // enable type forward/backward compatibility
  // disable it for small size and better performance.
  // .withCompatible(true)
  // enable async multi-threaded compilation.
  .withAsyncCompilation(true)
  .build();

Security

Keep class registration enabled for production and any untrusted payload source:

Fory fory = Fory.builder()
    .requireClassRegistration(true)
    .withMaxDepth(50)
    .build();

Security-related options:

  • requireClassRegistration(true) restricts deserialization to registered classes.
  • withMaxDepth(...) rejects unexpectedly deep object graphs.
  • withDeserializeUnknownClass(false) avoids materializing unknown classes from metadata.
  • checkJdkClassSerializable(true) keeps the JDK serializability check for java.* classes.
  • Class registration warnings can be useful during security audits; use suppressClassRegistrationWarnings(false) when you need to surface unexpected types.

Use requireClassRegistration(false) only for trusted payloads, and pair it with a TypeChecker allow list when dynamic class loading is required.

Related Topics