Implementation:Apache Shardingsphere YamlEngine Unmarshal

Knowledge Sources	Apache ShardingSphere
Domains	Configuration_Management, Shadow_Testing
Last Updated	2026-02-10 00:00 GMT

Overview

Concrete utility for deserializing YAML text into typed Java configuration objects, provided by the ShardingSphere infrastructure module.

Description

YamlEngine is a utility class (private constructor, all static methods) that provides safe YAML deserialization. It wraps SnakeYAML with a custom constructor (ShardingSphereYamlConstructor) that restricts which classes can be instantiated during parsing, preventing arbitrary code execution from malicious YAML input.

The class provides four overloaded unmarshal() methods:

• unmarshal(File, Class<T>): Reads a YAML file via BufferedReader and deserializes it into the target class. Returns a default instance if the file content is null.
• unmarshal(byte[], Class<T>): Wraps a byte array in an InputStream and deserializes it. Returns a default instance if the parsed result is null.
• unmarshal(String, Class<T>): Deserializes a YAML string directly. Returns a default instance if the parsed result is null.
• unmarshal(String, Class<T>, boolean): Deserializes a YAML string with an option to skip missing properties, enabling forward-compatible parsing.

All methods share a common null-safety guarantee: if the YAML parser returns null (e.g., for empty input), the method reflectively instantiates a default object of the target class using its no-argument constructor. This ensures callers never receive null.

The marshal(Object) method provides the reverse direction, converting a Java object back to a YAML string using ShardingSphereYamlRepresenter.

Usage

Use YamlEngine.unmarshal() to parse shadow rule YAML configuration from any source. In the shadow rule workflow, the typical call is YamlEngine.unmarshal(yamlContent, YamlShadowRuleConfiguration.class). This is an infrastructure utility external to the shadow module; the shadow module depends on it but does not contain it.

Code Reference

Source Location

• Repository: Apache ShardingSphere
• File: infra/util/src/main/java/org/apache/shardingsphere/infra/util/yaml/YamlEngine.java
• Lines: 42-127

Signature

@NoArgsConstructor(access = AccessLevel.PRIVATE)
public final class YamlEngine {

    @SneakyThrows(ReflectiveOperationException.class)
    public static <T extends YamlConfiguration> T unmarshal(final File yamlFile, final Class<T> classType) throws IOException

    @SneakyThrows(ReflectiveOperationException.class)
    public static <T extends YamlConfiguration> T unmarshal(final byte[] yamlBytes, final Class<T> classType) throws IOException

    @SneakyThrows(ReflectiveOperationException.class)
    public static <T> T unmarshal(final String yamlContent, final Class<T> classType)

    @SneakyThrows(ReflectiveOperationException.class)
    public static <T> T unmarshal(final String yamlContent, final Class<T> classType, final boolean skipMissingProps)

    public static String marshal(final Object value)
}

Import

import org.apache.shardingsphere.infra.util.yaml.YamlEngine;

I/O Contract

Inputs

For the primary unmarshal(String, Class) overload used in shadow configuration loading:

Name	Type	Required	Description
yamlContent	String	Yes	Raw YAML text to deserialize
classType	Class<T>	Yes	Target class type for deserialization (e.g., YamlShadowRuleConfiguration.class)

For the File-based overload:

Name	Type	Required	Description
yamlFile	File	Yes	YAML file to read and deserialize
classType	Class<T extends YamlConfiguration>	Yes	Target class type for deserialization

For the byte-array overload:

Name	Type	Required	Description
yamlBytes	byte[]	Yes	YAML content as byte array
classType	Class<T extends YamlConfiguration>	Yes	Target class type for deserialization

For the skip-missing-props overload:

Name	Type	Required	Description
yamlContent	String	Yes	Raw YAML text to deserialize
classType	Class<T>	Yes	Target class type for deserialization
skipMissingProps	boolean	Yes	If true, YAML keys with no matching Java field are silently ignored

Outputs

Name	Type	Description
return	T	Deserialized object of the target class; never null (returns default instance for empty/null input)

Usage Examples

// Example 1: Unmarshal from a YAML string
String yamlContent = "dataSources:\n"
    + "  shadow_ds:\n"
    + "    productionDataSourceName: ds\n"
    + "    shadowDataSourceName: ds_shadow\n";

YamlShadowRuleConfiguration yamlConfig = YamlEngine.unmarshal(yamlContent, YamlShadowRuleConfiguration.class);

// Example 2: Unmarshal from a file
File configFile = new File("/path/to/shadow-rule.yaml");
YamlShadowRuleConfiguration yamlConfig = YamlEngine.unmarshal(configFile, YamlShadowRuleConfiguration.class);

// Example 3: Unmarshal with missing property tolerance
YamlShadowRuleConfiguration yamlConfig = YamlEngine.unmarshal(yamlContent, YamlShadowRuleConfiguration.class, true);

// Example 4: Marshal back to YAML string
String output = YamlEngine.marshal(yamlConfig);

Related Pages

Implements Principle

• Principle:Apache_Shardingsphere_YAML_Deserialization

Requires Environment

• Environment:Apache_Shardingsphere_Java_Runtime_Environment