Skip to content

Commit 5d696c1

Browse files
wenshaowenshao
committed
doc
1 parent 5379bf3 commit 5d696c1

File tree

2 files changed

+220
-0
lines changed

2 files changed

+220
-0
lines changed

‎introspect.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# Fastjson2 Introspect Package Documentation
2+
3+
## Overview
4+
5+
The `com.alibaba.fastjson2.introspect` package provides a comprehensive reflection-based property access functionality for fastjson2. This package contains classes and interfaces for efficient property access during JSON serialization and deserialization operations.
6+
7+
The core of this package is the `PropertyAccessor` interface, which provides a unified API for getting and setting object properties regardless of the underlying access mechanism (field access, method calls, or functional interfaces).
8+
9+
The `PropertyAccessorFactory` class serves as the main factory for creating optimized property accessors based on the property type and access method, providing implementations for primitive types, wrapper classes, and complex objects.
10+
11+
## Key Features
12+
13+
- Optimized accessors for primitive types to avoid boxing/unboxing overhead
14+
- Support for both field-based and method-based property access
15+
- Functional interface-based accessors for maximum performance
16+
- Automatic type conversion between compatible types
17+
- Exception handling with detailed error messages
18+
- Multiple implementation strategies for different performance requirements
19+
20+
## Architecture
21+
22+
The introspect package implements a hierarchical architecture with multiple access strategies:
23+
24+
### 1. PropertyAccessor Interface
25+
26+
The `PropertyAccessor` interface is the core abstraction that defines methods for accessing object properties generically. It provides unified methods for getting and setting properties of objects, supporting both primitive types and objects through various accessor methods.
27+
28+
Key methods include:
29+
- `getObject()`, `getByteValue()`, `getCharValue()`, `getShortValue()`, `getIntValue()`, `getLongValue()`, `getFloatValue()`, `getDoubleValue()`, `getBooleanValue()`
30+
- `setObject()`, `setByteValue()`, `setCharValue()`, `setShortValue()`, `setIntValue()`, `setLongValue()`, `setFloatValue()`, `setDoubleValue()`, `setBooleanValue()`
31+
32+
### 2. Base Accessor Classes
33+
34+
The package provides three abstract base classes that implement different access strategies:
35+
36+
#### FieldAccessor
37+
- Abstract base class for field-based property accessors
38+
- Provides common functionality for accessing object fields using reflection
39+
- Handles field metadata and determines if the field supports setting based on whether the field is declared as final
40+
- Implements PropertyAccessor interface using direct field access through reflection
41+
42+
#### MethodAccessor
43+
- Abstract base class for method-based property accessors
44+
- Provides common functionality for accessing object properties using getter and setter methods
45+
- Allows for accessing properties through standard getter/setter method pairs
46+
- Implements PropertyAccessor interface using method invocation for property access
47+
48+
#### FunctionAccessor
49+
- Abstract base class for function-based property accessors
50+
- Provides common functionality for accessing object properties using getter and setter functions
51+
- Allows for accessing properties through functional interfaces rather than direct field access or method invocation
52+
- Implements PropertyAccessor interface using functional interfaces for property access
53+
54+
### 3. Property Accessor Factory Hierarchy
55+
56+
The package includes a sophisticated factory hierarchy that provides multiple strategies for property access:
57+
58+
#### PropertyAccessorFactory
59+
- The main factory class that creates property accessors using reflection
60+
- Provides optimized accessor implementations for different data types (primitives, String, BigInteger, BigDecimal) to optimize performance and avoid boxing/unboxing overhead where possible
61+
- Creates specialized accessor implementations for different data types
62+
63+
#### PropertyAccessorFactoryLambda
64+
- Extends PropertyAccessorFactory and adds support for LambdaMetafactory-based access
65+
- Creates efficient functional interfaces for property access when possible
66+
- Provides optimized constructor instantiation using MethodHandle and LambdaMetafactory
67+
68+
#### PropertyAccessorFactoryMethodHandle
69+
- Available on JDK 11+, uses MethodHandles.Lookup for field and method access
70+
- Uses MethodHandles.Lookup's unreflectGetter/unreflectSetter instead of VarHandle for field access
71+
- Provides an alternative way to access object properties efficiently
72+
73+
#### PropertyAccessorFactoryVarHandle
74+
- Available on JDK 11+, uses VarHandle for field access
75+
- Provides high-performance property access using the VarHandle API which is more efficient than traditional reflection or Unsafe-based approaches
76+
77+
#### PropertyAccessorFactoryUnsafe
78+
- Uses Unsafe operations for field access to provide better performance compared to reflection-based access
79+
- Creates property accessors that use direct memory access via Unsafe to get and set field values, which is faster than traditional reflection
80+
- Note: Uses sun.misc.Unsafe, which is not part of the standard Java API and may not be available in all JVM implementations
81+
82+
## Type-Specific Accessor Interfaces
83+
84+
The package includes specialized interfaces for different data types to optimize performance:
85+
86+
- `PropertyAccessorBooleanValue`, `PropertyAccessorByteValue`, `PropertyAccessorShortValue`, `PropertyAccessorIntValue`, `PropertyAccessorLongValue`, `PropertyAccessorFloatValue`, `PropertyAccessorDoubleValue`, `PropertyAccessorCharValue`
87+
- `PropertyAccessorObject`, `PropertyAccessorString`, `PropertyAccessorBigInteger`, `PropertyAccessorBigDecimal`, `PropertyAccessorNumber`
88+
- These interfaces provide type-specific getter and setter methods and handle conversions between compatible types
89+
90+
## Constructor Support
91+
92+
The factory also provides methods to create constructor-based functions:
93+
- `createSupplier(Constructor)`: Creates a Supplier that can instantiate objects using the given constructor
94+
- `createFunction(Constructor)`: Creates a Function that can instantiate objects using the given constructor
95+
- `createIntFunction(Constructor)`, `createLongFunction(Constructor)`, `createDoubleFunction(Constructor)`: Create specialized function types for different parameter types
96+
97+
## Performance Considerations
98+
99+
The introspect package is designed with performance in mind:
100+
101+
1. **Type-Specific Accessors**: Different accessor implementations are created based on the field type to provide optimal performance for each specific type
102+
2. **Avoiding Boxing/Unboxing**: Specialized accessor interfaces for primitive types avoid the overhead of boxing and unboxing
103+
3. **Multiple Access Strategies**: The package provides multiple access strategies (reflection, MethodHandle, VarHandle, Unsafe) to choose the most efficient one for the runtime environment
104+
4. **LambdaMetafactory Integration**: Uses LambdaMetafactory to create efficient functional interfaces for property access
105+
106+
## Error Handling
107+
108+
All accessor implementations provide proper error handling with detailed exception messages. When errors occur during property access, the implementations create JSON exceptions with detailed information about the operation that failed.
109+
110+
## Usage in Fastjson2
111+
112+
The introspect package is used internally by fastjson2 for efficient property access during serialization and deserialization operations. It allows fastjson2 to efficiently read and write object properties regardless of whether they are accessed through fields, getter/setter methods, or functional interfaces.

‎introspect_cn.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# Fastjson2 内省包文档
2+
3+
## 概述
4+
5+
`com.alibaba.fastjson2.introspect` 包为 fastjson2 提供了基于反射的属性访问功能。该包包含用于在 JSON 序列化和反序列化操作期间进行高效属性访问的类和接口。
6+
7+
该包的核心是 `PropertyAccessor` 接口，无论底层访问机制（字段访问、方法调用或函数式接口）如何，它都提供了统一的 API 来获取和设置对象属性。
8+
9+
`PropertyAccessorFactory` 类是创建优化属性访问器的主要工厂，根据属性类型和访问方法提供针对基本类型、包装类和复杂对象的实现。
10+
11+
## 主要功能
12+
13+
- 针对基本类型优化的访问器，避免装箱/拆箱开销
14+
- 支持基于字段和基于方法的属性访问
15+
- 基于函数式接口的访问器以获得最大性能
16+
- 兼容类型之间的自动类型转换
17+
- 带有详细错误消息的异常处理
18+
- 针对不同性能要求的多种实现策略
19+
20+
## 架构
21+
22+
内省包实现了分层架构，具有多种访问策略：
23+
24+
### 1. PropertyAccessor 接口
25+
26+
`PropertyAccessor` 接口是核心抽象，定义了用于通用访问对象属性的方法。它提供了统一的方法来获取和设置对象的属性，通过各种访问器方法支持基本类型和对象。
27+
28+
主要方法包括：
29+
- `getObject()`、`getByteValue()`、`getCharValue()`、`getShortValue()`、`getIntValue()`、`getLongValue()`、`getFloatValue()`、`getDoubleValue()`、`getBooleanValue()`
30+
- `setObject()`、`setByteValue()`、`setCharValue()`、`setShortValue()`、`setIntValue()`、`setLongValue()`、`setFloatValue()`、`setDoubleValue()`、`setBooleanValue()`
31+
32+
### 2. 基础访问器类
33+
34+
该包提供了三个抽象基类，实现不同的访问策略：
35+
36+
#### FieldAccessor
37+
- 用于基于字段的属性访问器的抽象基类
38+
- 提供使用反射访问对象字段的通用功能
39+
- 处理字段元数据并根据字段是否声明为 final 来确定字段是否支持设置
40+
- 通过反射使用直接字段访问实现 PropertyAccessor 接口
41+
42+
#### MethodAccessor
43+
- 用于基于方法的属性访问器的抽象基类
44+
- 提供使用 getter 和 setter 方法访问对象属性的通用功能
45+
- 允许通过标准的 getter/setter 方法对访问属性
46+
- 使用方法调用实现 PropertyAccessor 接口进行属性访问
47+
48+
#### FunctionAccessor
49+
- 用于基于函数式的属性访问器的抽象基类
50+
- 提供使用 getter 和 setter 函数访问对象属性的通用功能
51+
- 允许通过函数式接口而不是直接字段访问或方法调用来访问属性
52+
- 使用函数式接口实现 PropertyAccessor 接口进行属性访问
53+
54+
### 3. 属性访问器工厂层次结构
55+
56+
该包包含一个复杂的工厂层次结构，提供多种属性访问策略：
57+
58+
#### PropertyAccessorFactory
59+
- 创建属性访问器的主要工厂类，使用反射
60+
- 为不同类型（基本类型、String、BigInteger、BigDecimal）提供优化的访问器实现，以优化性能并避免装箱/拆箱开销
61+
- 为不同类型创建专门的访问器实现
62+
63+
#### PropertyAccessorFactoryLambda
64+
- 扩展 PropertyAccessorFactory 并添加对 LambdaMetafactory 基于访问的支持
65+
- 创建用于属性访问的高效函数式接口
66+
- 使用 MethodHandle 和 LambdaMetafactory 提供优化的构造函数实例化
67+
68+
#### PropertyAccessorFactoryMethodHandle
69+
- 在 JDK 11+ 上可用，使用 MethodHandles.Lookup 进行字段和方法访问
70+
- 使用 MethodHandles.Lookup 的 unreflectGetter/unreflectSetter 而不是 VarHandle 进行字段访问
71+
- 提供访问对象属性的替代方式
72+
73+
#### PropertyAccessorFactoryVarHandle
74+
- 在 JDK 11+ 上可用，使用 VarHandle 进行字段访问
75+
- 使用 VarHandle API 提供高性能属性访问，这比传统的反射或基于 Unsafe 的方法更高效
76+
77+
#### PropertyAccessorFactoryUnsafe
78+
- 使用 Unsafe 操作进行字段访问，以提供比基于反射的访问更好的性能
79+
- 创建使用 Unsafe 直接内存访问来获取和设置字段值的属性访问器，这比传统反射更快
80+
- 注意：使用 sun.misc.Unsafe，这不是标准 Java API 的一部分，可能不是所有 JVM 实现都可用
81+
82+
## 类型特定的访问器接口
83+
84+
该包包含针对不同类型优化的专门接口：
85+
86+
- `PropertyAccessorBooleanValue`、`PropertyAccessorByteValue`、`PropertyAccessorShortValue`、`PropertyAccessorIntValue`、`PropertyAccessorLongValue`、`PropertyAccessorFloatValue`、`PropertyAccessorDoubleValue`、`PropertyAccessorCharValue`
87+
- `PropertyAccessorObject`、`PropertyAccessorString`、`PropertyAccessorBigInteger`、`PropertyAccessorBigDecimal`、`PropertyAccessorNumber`
88+
- 这些接口提供类型特定的 getter 和 setter 方法，并处理兼容类型之间的转换
89+
90+
## 构造函数支持
91+
92+
工厂还提供创建基于构造函数的函数的方法：
93+
- `createSupplier(Constructor)`：创建一个可以使用给定构造函数实例化对象的 Supplier
94+
- `createFunction(Constructor)`：创建一个可以使用给定构造函数实例化对象的 Function
95+
- `createIntFunction(Constructor)`、`createLongFunction(Constructor)`、`createDoubleFunction(Constructor)`：为不同类型参数创建专门的函数类型
96+
97+
## 性能考虑
98+
99+
内省包在设计时考虑了性能：
100+
101+
1. **类型特定的访问器**：根据字段类型创建不同的访问器实现，为每种特定类型提供最佳性能
102+
2. **避免装箱/拆箱**：针对基本类型的专门访问器接口避免了装箱和拆箱的开销
103+
3. **多种访问策略**：该包提供多种访问策略（反射、MethodHandle、VarHandle、Unsafe），以选择最适合运行时环境的最有效策略
104+
4. **LambdaMetafactory 集成**：使用 LambdaMetafactory 创建高效的函数式接口进行属性访问
105+
106+
## 在 Fastjson2 中的使用
107+
108+
内省包在 fastjson2 内部用于在序列化和反序列化操作期间进行高效的属性访问。它允许 fastjson2 高效地读取和写入对象属性，无论它们是通过字段、getter/setter 方法还是函数式接口访问的。

0 commit comments

Comments
 (0)