Crane4j Data Assembly Framework

Crane4j provides several key capabilities for managing data association and field filling:

• Out-of-the-box usage: Integrates with SpringBoot auto-configuration. You can enable framework functionality with a single annotation, avoiding tedious manual configuration.
• Simple API: Provides easy-to-understand APIs and comprehensive annotation-based configuration.
• Extensibility: Leverages Spring dependency injection, allowing you to easily replace default components with custom logic.
• Versatile Scenarios: Supports grouped or nested filling, as well as one-to-many or many-to-many batch filling. The granularity of operation can be as fine as an individual field.
• Rich Data Source Support: Supports dictionaries, enums, constant classes, and executable methods by default. Additional data sources can be added easily.
• Powerful Extensions: Includes features such as automatic filling, multi-threaded filling, caching, and dynamic expressions. It also supports extensions like mybatis-plus.

Specifying an execution order via @Assemble(sort = ...) causes all operations on that object to become synchronous. Even if multiple operations use the same data source, they will be executed as separate steps, which may impact performance.

To optimize performance, you can handle the cascading logic directly within a Method Container. Instead of multiple sequential queries, you write a single method that retrieves the entire hierarchy (e.g., fetching all parent departments for a list of child IDs in one go) and returns a combined result set.

In this approach, the @Assemble annotation simply maps the pre-assembled fields from the container's result to the target object.

// 1. Define a Method Container that performs the complex join/hierarchy logic
@Component
public class DeptService {
  	@ContainerMethod(
    		container = "thirdDept", resultType = Map.class, resultKey = "thirdDeptId"
    )
  	public List<Map<String, Object>> queryDeptWithParentByThirdDept(List<Integer> thirdDeptIds) {
      	// Logic to query 3rd, 2nd, and 1st level depts and assemble them into a Map
      	// ...
      	return results;
    } 
}

// 2. Reference the pre-assembled properties in your entity
public class Emp {
  	private Integer firstIdDeptId;
  	private String firstDeptName;
  	private Integer secondDeptId;
  	private String secondDeptName;
  	@Assemble(
      	container = "thirdDept", 
      	prop = { 
          "thirdDeptName", 
          "secondDeptId", "secondDeptName",
          "firstIdDeptId", "firstIdDeptName"
        },
    )
  	private Integer thirdDeptId;
  	private String thirdDeptName;
}

The @AssembleMp annotation is used to configure a BaseMapper query as a data source for assembly operations. The behavior depends on how you configure the mapper, selects, and where attributes.

Query Modes

• By Primary Key (All Fields): Use only mapper. It performs select * from table where id in ?.
• By Primary Key (Specific Fields): Use mapper and selects. It performs a selective query and groups by the primary key (marked with @TableId).
• By Foreign Key (All Fields): Use mapper and where. It performs select * from table where foreign_key in ? and groups by the specified foreign key.
• By Foreign Key (Specific Fields): Use mapper, selects, and where. It performs a selective query and groups by the specified foreign key.

Note: If you specify selects but omit the foreign key field, Crane4j will automatically append the foreign key field to the SQL query to ensure grouping works correctly.

// Example: Querying specific fields by primary key
@AssembleMp(
    mapper = "fooMapper",
    selects = {"userName", "userAge"}
)
private Integer id;

By default, a Container in Crane4j queries data sources using a specific key. However, if you need to match data based on multiple keys or complex custom conditions, you can use an Object Container.

To implement an Object Container:

1. Annotate the target class with @Assemble but do not specify a key value. This tells Crane4j to pass the object being filled directly as the key to the container.
2. Define the container using Containers.forLambda. The container's logic should accept the target object (or a collection of them) and return a dataset grouped by the object instance itself.

Warning: The data returned by the Container must be grouped by the input object instance itself. If you have overridden equals or hashCode in your target class, ensure the grouping logic remains consistent with those implementations.

// 1. Target class with @Assemble (no key specified)
@Assemble(container = "foo_info", props = @Mapping(ref = "name"))
@Data
public class Foo {
    private Integer id;
    private String code;
    private String name;
}

// 2. Container definition using forLambda
Container<Foo> objectContainer = Containers.forLambda("foo_info", fooList -> 
    fooList.stream().collect(Collectors.toMap(
    	foo -> foo, 
        foo -> foo.getId() + "#" + foo.getCode()
    ))
);

The Operator interface allows you to perform data filling (assembly) on arbitrary objects without requiring them to have specific annotations or a common parent class. This is particularly useful for filling Map or JSONObject types where annotations cannot be applied directly to the class.

To use it:

1. Define an interface annotated with @Operator.
2. Define abstract methods with @Assemble to configure how the parameters should be filled.
3. Inject the interface into your service or create a proxy manually.

// 1. Declare the operator interface
@Operator
private interface OperatorInterface {
    @Assemble(key = "id", container = "user", props = @Mapping("name"))
    void fill(Collection<Map<String, Object>> targets);
}

// 2. Inject and use the proxy
@Autowired
private OperatorInterface operator;

public void example() {
    List<Map<String, Object>> targets = new ArrayList<>();
    operator.fill(targets); // Performs the filling operation
}

Standard executors perform disassembly (extracting nested objects via @Disassemble) before assembly (filling properties via @Assemble). This can cause issues when the disassembly step needs data that hasn't been assembled yet.

To solve this for tree-like structures or deeply nested objects, use a Recursive Executor. These executors follow a pattern of:

1. Execute Assembly $\rightarrow$ 2. Execute Disassembly $\rightarrow$ 3. Recursively execute Assembly on the extracted nested objects.

Available Recursive Executors

• DisorderedBeanOperationRecursiveExecutor: Recursive version of the unordered executor.
• OrderedBeanOperationRecursiveExecutor: Recursive version of the ordered executor.
• AsyncBeanOperationRecursiveExecutor: Recursive version of the async executor.

Warning: Recursive executors are implemented using a stack. While stack overflow is unlikely, deep hierarchies will impact performance due to repeated queries at every level. Use them only when necessary.

@Component
public class NodeService {
	@ContainerMethod(namespace = "children", resultType = Node.class)
	public List<Node> selectChildrenNodesById(String nodeId) {
	    // Query child nodes by ID
	}
}

@Data
public static class Node {
	    // Fill children, then recursively repeat for the children
    @Assemble(container = "children", prop = ":children")
    private final Integer id;
    private String name;
    @Disassemble(type = Node.class)
    private List<Node> children;
}

@Service
public class ExampleService {
	// Use the ordered recursive executor to build the tree
	@AutoOperate(executorType = OrderedBeanOperationRecursiveExecutor.class)
	public Node getTree(String id) {
		return new Node(0);
	}
}