Merge branch 'dev' into doc

doc/docs/mapping/advanced/on-dissociate.mdx

@@ -57,4 +57,4 @@ DissociateAction has 3 options, corresponding to the foreign key behaviors in th
 -   SET_NULL: Automatically clear the foreign key. For parent delete operations, it looks very much like `on delete set null`.
 -   DELETE: Automatically delete child objects. For parent delete operations, it looks very much like `on delete cascade`.
 
-This article only introduces the configuration of OnDissociate. For how to use it further, please refer to [Delete Command](../../mutation/delete-command).
+This article only introduces the configuration of OnDissociate. For how to use it further, please refer to [SaveCommand/Dissociation](../../mutation/save-command/dissociation) and [Delete Command](../../mutation/delete-command).

doc/docs/spring/client/error.mdx

@@ -12,7 +12,7 @@ This part is actually unrelated to ORM.
 
 However, since [backend and frontend API integration](./api) is provided, this part of the functionality must also be provided to make it a complete solution.
 
-## Exception Clusters
+## Exception Families
 
 We need to define special Java/Kotlin business exceptions that can be directly translated into data that the client can understand.
 
@@ -28,7 +28,7 @@ So, Jimmer chooses a compromise: dividing business exceptions into multiple fami
 
 Jimmer uses enums to define exception families, where the enum also serves as the error code for that family, e.g.
 
-### Define Exception Clusters
+### Define Exception Families
 
 <Tabs groupId="language">
 <TabItem value="java" label="Java">
@@ -454,7 +454,7 @@ public abstract class UserInfoException private constructor(
 
 ## Declare Exceptions for REST APIs  
 
-### Allow All Exceptions in Cluster
+### Allow To Throw All Exceptions Of Family
 
 <Tabs groupId="language">
 <TabItem value="java" label="Java">
@@ -495,7 +495,7 @@ fun registerUser(@RequestBody input: RegisterUserInput) {
 The `@org.babyfish.jimmer.client.ThrowsAll` annotation allows the REST API to throw all exceptions in the family.
 :::
 
-### Allow Some Exceptions in Cluster
+### Allow To Throw Some Exceptions Of Family
 
 Let's locate another business exception family:
 

doc/i18n/zh/docusaurus-plugin-content-docs/current/mapping/advanced/on-dissociate.mdx

@@ -57,4 +57,4 @@ DissociateAction具有3个选项，对应数据库的外键行为：
 - SET_NULL: 自动清空外键。对于父对象的删除操作而言，看起来很像`on delete set null`。
 - DELETE: 自动删除子对象。对于父对象的删除操作而言，看起来很像`on delete cascade`。
 
-本文只介绍OnDissociate的配置，至于如何进一步使用，请参见[删除指令](../../mutation/delete-command)。
+本文只介绍OnDissociate的配置，至于如何进一步使用，请参见[保存指定/脱钩操作](../../mutation/save-command/dissociation)和[删除指令](../../mutation/delete-command)。

example/java/jimmer-sql/src/main/java/org/babyfish/jimmer/sql/example/business/AuthorService.java

@@ -38,12 +38,12 @@ public AuthorService(AuthorRepository authorRepository) {
     }
 
     @GetMapping("/simpleList")
-    public List<@FetchBy("SIMPLE_FETCHER") Author> findSimpleAuthors() {
+    public List<@FetchBy("SIMPLE_FETCHER") Author> findSimpleAuthors() { // ❶ ❷ ❸
         return authorRepository.findAll(SIMPLE_FETCHER, AuthorProps.FIRST_NAME, AuthorProps.LAST_NAME);
     }
 
     @GetMapping("/list")
-    public List<@FetchBy("DEFAULT_FETCHER") Author> findAuthors(
+    public List<@FetchBy("DEFAULT_FETCHER") Author> findAuthors( // ❷
             AuthorSpecification specification
             //@RequestParam(defaultValue = "firstName asc, lastName asc") String sortCode
     ) {
@@ -56,7 +56,7 @@ public AuthorService(AuthorRepository authorRepository) {
 
     @GetMapping("/{id}")
     @Nullable
-    public @FetchBy("COMPLEX_FETCHER") Author findComplexAuthor(
+    public @FetchBy("COMPLEX_FETCHER") Author findComplexAuthor( // ❸
             @PathVariable("id") long id
     ) {
         return authorRepository.findNullable(id, COMPLEX_FETCHER);
@@ -86,8 +86,8 @@ public AuthorService(AuthorRepository authorRepository) {
                     );
 
     @PutMapping
-    @ThrowsAll(SaveErrorCode.class)
-    public Author saveAuthor(AuthorInput input) {
+    @ThrowsAll(SaveErrorCode.class) // ❹
+    public Author saveAuthor(AuthorInput input) { // ❺
         return authorRepository.save(input);
     }
 
@@ -96,3 +96,9 @@ public void deleteAuthor(@PathVariable("id") long id) {
         authorRepository.deleteById(id);
     }
 }
+
+/*----------------Documentation Links----------------
+❶ ❷ ❸ https://babyfish-ct.github.io/jimmer/docs/spring/client/api#declare-fetchby
+❹ https://babyfish-ct.github.io/jimmer/docs/spring/client/error#allow-to-throw-all-exceptions-of-family
+❺ https://babyfish-ct.github.io/jimmer/docs/mutation/save-command/input-dto/
+---------------------------------------------------*/

example/java/jimmer-sql/src/main/java/org/babyfish/jimmer/sql/example/business/BookService.java

@@ -38,12 +38,12 @@ public BookService(BookRepository bookRepository) {
     }
 
     @GetMapping("/simpleList")
-    public List<@FetchBy("SIMPLE_FETCHER") Book> findSimpleBooks() {
+    public List<@FetchBy("SIMPLE_FETCHER") Book> findSimpleBooks() { // ❶
         return bookRepository.findAll(SIMPLE_FETCHER, BookProps.NAME, BookProps.EDITION.desc());
     }
 
     @GetMapping("/list")
-    public Page<@FetchBy("DEFAULT_FETCHER") Book> findBooks(
+    public Page<@FetchBy("DEFAULT_FETCHER") Book> findBooks( // ❷
             @RequestParam(defaultValue = "0") int pageIndex,
             @RequestParam(defaultValue = "5") int pageSize,
             // The `sortCode` also support implicit join, like `store.name asc`
@@ -63,7 +63,7 @@ public BookService(BookRepository bookRepository) {
 
     @GetMapping("/{id}")
     @Nullable
-    public @FetchBy("COMPLEX_FETCHER") Book findComplexBook(
+    public @FetchBy("COMPLEX_FETCHER") Book findComplexBook( // ❸
             @PathVariable("id") long id
     ) {
         return bookRepository.findNullable(id, COMPLEX_FETCHER);
@@ -101,14 +101,14 @@ public BookService(BookRepository bookRepository) {
                     );
 
     @PutMapping
-    @ThrowsAll(SaveErrorCode.class)
-    public Book saveBook(@RequestBody BookInput input) {
+    @ThrowsAll(SaveErrorCode.class) // ❹
+    public Book saveBook(@RequestBody BookInput input) { // ❺
         return bookRepository.save(input);
     }
 
     @PutMapping("/composite")
-    @ThrowsAll(SaveErrorCode.class)
-    public Book saveCompositeBook(@RequestBody CompositeBookInput input) {
+    @ThrowsAll(SaveErrorCode.class) // ❻
+    public Book saveCompositeBook(@RequestBody CompositeBookInput input) { // ❼
         return bookRepository.save(input);
     }
 
@@ -117,3 +117,9 @@ public void deleteBook(@PathVariable("id") long id) {
         bookRepository.deleteById(id);
     }
 }
+
+/*----------------Documentation Links----------------
+❶ ❷ ❸ https://babyfish-ct.github.io/jimmer/docs/spring/client/api#declare-fetchby
+❹ ❻ https://babyfish-ct.github.io/jimmer/docs/spring/client/error#allow-to-throw-all-exceptions-of-family
+❺ ❼ https://babyfish-ct.github.io/jimmer/docs/mutation/save-command/input-dto/
+---------------------------------------------------*/

example/java/jimmer-sql/src/main/java/org/babyfish/jimmer/sql/example/business/BookStoreService.java

@@ -34,23 +34,23 @@ public BookStoreService(BookStoreRepository bookStoreRepository) {
     }
 
     @GetMapping("/simpleList")
-    public List<@FetchBy("SIMPLE_FETCHER") BookStore> findSimpleStores() {
+    public List<@FetchBy("SIMPLE_FETCHER") BookStore> findSimpleStores() { // ❶
         return bookStoreRepository.findAll(
                 SIMPLE_FETCHER,
                 BookStoreProps.NAME
         );
     }
 
     @GetMapping("/list")
-    public List<@FetchBy("DEFAULT_FETCHER") BookStore> findStores() {
+    public List<@FetchBy("DEFAULT_FETCHER") BookStore> findStores() { // ❷
         return bookStoreRepository.findAll(
                 DEFAULT_FETCHER,
                 BookStoreProps.NAME
         );
     }
 
     @GetMapping("/complexList")
-    public List<@FetchBy("WITH_ALL_BOOKS_FETCHER") BookStore> findComplexStores() {
+    public List<@FetchBy("WITH_ALL_BOOKS_FETCHER") BookStore> findComplexStores() { // ❸
         return bookStoreRepository.findAll(
                 WITH_ALL_BOOKS_FETCHER,
                 BookStoreProps.NAME
@@ -59,15 +59,15 @@ public BookStoreService(BookStoreRepository bookStoreRepository) {
 
     @GetMapping("/{id}/withAllBooks")
     @Nullable
-    public @FetchBy("WITH_ALL_BOOKS_FETCHER") BookStore findComplexStoreWithAllBooks(
+    public @FetchBy("WITH_ALL_BOOKS_FETCHER") BookStore findComplexStoreWithAllBooks( // ❹
             @PathVariable("id") long id
     ) {
         return bookStoreRepository.findNullable(id, WITH_ALL_BOOKS_FETCHER);
     }
 
     @GetMapping("/{id}/withNewestBooks")
     @Nullable
-    public @FetchBy("WITH_NEWEST_BOOKS_FETCHER") BookStore findComplexStoreWithNewestBooks(
+    public @FetchBy("WITH_NEWEST_BOOKS_FETCHER") BookStore findComplexStoreWithNewestBooks( // ❺
             @PathVariable("id") long id
     ) {
         return bookStoreRepository.findNullable(id, WITH_NEWEST_BOOKS_FETCHER);
@@ -108,8 +108,8 @@ public BookStoreService(BookStoreRepository bookStoreRepository) {
                     );
 
     @PutMapping
-    @ThrowsAll(SaveErrorCode.class)
-    public BookStore saveBookStore(@RequestBody BookStoreInput input) {
+    @ThrowsAll(SaveErrorCode.class) // ❻
+    public BookStore saveBookStore(@RequestBody BookStoreInput input) { // ❼
         return bookStoreRepository.save(input);
     }
 
@@ -118,3 +118,9 @@ public void deleteBookStore(@PathVariable("id") long id) {
         bookStoreRepository.deleteById(id);
     }
 }
+
+/*----------------Documentation Links----------------
+❶ ❷ ❸ ❹ ❺ https://babyfish-ct.github.io/jimmer/docs/spring/client/api#declare-fetchby
+❻ https://babyfish-ct.github.io/jimmer/docs/spring/client/error#allow-to-throw-all-exceptions-of-family
+❼ https://babyfish-ct.github.io/jimmer/docs/mutation/save-command/input-dto/
+---------------------------------------------------*/

example/java/jimmer-sql/src/main/java/org/babyfish/jimmer/sql/example/business/TreeService.java

@@ -52,7 +52,7 @@ public List<FlatTreeNodeView> flatNodes(
     }
 
     @GetMapping("/roots/recursive")
-    public List<@FetchBy("RECURSIVE_FETCHER") TreeNode> findRootTrees(
+    public List<@FetchBy("RECURSIVE_FETCHER") TreeNode> findRootTrees( // ❶
             @RequestParam(required = false) String rootName
     ) {
         return treeNodeRepository.findByParentIsNullAndName(
@@ -63,7 +63,7 @@ public List<FlatTreeNodeView> flatNodes(
 
     @PutMapping("/root/recursive")
     @ThrowsAll(SaveErrorCode.class)
-    public TreeNode saveTree(@RequestBody RecursiveTreeInput input) {
+    public TreeNode saveTree(@RequestBody RecursiveTreeInput input) { // ❷
         TreeNode rootNode = TreeNodeDraft.$.produce(
 
                 input.toEntity(),
@@ -99,3 +99,11 @@ public void deleteTree(@PathVariable long id) {
                             RecursiveListFieldConfig::recursive
                     );
 }
+
+/*----------------Documentation Links----------------
+❶ https://babyfish-ct.github.io/jimmer/docs/spring/client/api#declare-fetchby
+  https://babyfish-ct.github.io/jimmer/docs/query/object-fetcher/recursive
+
+❷ https://babyfish-ct.github.io/jimmer/docs/mutation/save-command/input-dto/
+  https://babyfish-ct.github.io/jimmer/docs/object/view/dto-language#92-recursive-association
+---------------------------------------------------*/

example/java/jimmer-sql/src/main/java/org/babyfish/jimmer/sql/example/business/interceptor/input/BaseEntityDraftInterceptor.java

@@ -9,7 +9,7 @@
 import java.time.LocalDateTime;
 
 @Component
-public class BaseEntityDraftInterceptor implements DraftInterceptor<BaseEntityDraft> {
+public class BaseEntityDraftInterceptor implements DraftInterceptor<BaseEntityDraft> { // ❶
 
     /*
      * In this simple example, `BaseEntity` has only two fields: `createdTime` and `modifiedTime`.
@@ -23,12 +23,20 @@ public class BaseEntityDraftInterceptor implements DraftInterceptor<BaseEntityDr
      */
 
     @Override
-    public void beforeSave(BaseEntityDraft draft, boolean isNew) {
-        if (!ImmutableObjects.isLoaded(draft, BaseEntityProps.MODIFIED_TIME)) {
+    public void beforeSave(BaseEntityDraft draft, boolean isNew) { // ❷
+        if (!ImmutableObjects.isLoaded(draft, BaseEntityProps.MODIFIED_TIME)) { // ❸
             draft.setModifiedTime(LocalDateTime.now());
         }
-        if (isNew && !ImmutableObjects.isLoaded(draft, BaseEntityProps.CREATED_TIME)) {
+        if (isNew && !ImmutableObjects.isLoaded(draft, BaseEntityProps.CREATED_TIME)) { // ❹
             draft.setCreatedTime(LocalDateTime.now());
         }
     }
 }
+
+/*----------------Documentation Links----------------
+❶ https://babyfish-ct.github.io/jimmer/docs/mutation/draft-interceptor
+❷ https://babyfish-ct.github.io/jimmer/docs/object/draft
+
+❸ ❹ https://babyfish-ct.github.io/jimmer/docs/object/tool#isloaded
+     https://babyfish-ct.github.io/jimmer/docs/object/dynamic
+---------------------------------------------------*/

example/java/jimmer-sql/src/main/java/org/babyfish/jimmer/sql/example/business/interceptor/input/TenantAwareDraftInterceptor.java

@@ -10,7 +10,7 @@
 import org.springframework.stereotype.Component;
 
 @Component
-public class TenantAwareDraftInterceptor implements DraftInterceptor<TenantAwareDraft> {
+public class TenantAwareDraftInterceptor implements DraftInterceptor<TenantAwareDraft> { //
 
     private final TenantProvider tenantProvider;
 
@@ -25,8 +25,8 @@ public TenantAwareDraftInterceptor(
     }
 
     @Override
-    public void beforeSave(@NotNull TenantAwareDraft draft, boolean isNew) {
-        if (!ImmutableObjects.isLoaded(draft, TenantAwareProps.TENANT)) {
+    public void beforeSave(@NotNull TenantAwareDraft draft, boolean isNew) { // ❷
+        if (!ImmutableObjects.isLoaded(draft, TenantAwareProps.TENANT)) { // ❸
             String tenant = tenantProvider.get();
             if (tenant == null) {
                 tenant = defaultTenant;
@@ -35,3 +35,11 @@ public void beforeSave(@NotNull TenantAwareDraft draft, boolean isNew) {
         }
     }
 }
+
+/*----------------Documentation Links----------------
+❶ https://babyfish-ct.github.io/jimmer/docs/mutation/draft-interceptor
+❷ https://babyfish-ct.github.io/jimmer/docs/object/draft
+
+❸ https://babyfish-ct.github.io/jimmer/docs/object/tool#isloaded
+  https://babyfish-ct.github.io/jimmer/docs/object/dynamic
+---------------------------------------------------*/

example/java/jimmer-sql/src/main/java/org/babyfish/jimmer/sql/example/business/interceptor/output/TenantFilterForCacheMode.java

@@ -33,14 +33,14 @@
 @ConditionalOnProperty("spring.redis.host")
 public class TenantFilterForCacheMode
         extends TenantFilterForNonCacheMode
-        implements CacheableFilter<TenantAwareProps> {
+        implements CacheableFilter<TenantAwareProps> { // ❶
 
     public TenantFilterForCacheMode(TenantProvider tenantProvider) {
         super(tenantProvider);
     }
 
     @Override
-    public SortedMap<String, Object> getParameters() {
+    public SortedMap<String, Object> getParameters() { // ❷
         String tenant = tenantProvider.get();
         if (tenant == null) {
             return null;
@@ -51,7 +51,15 @@ public SortedMap<String, Object> getParameters() {
     }
 
     @Override
-    public boolean isAffectedBy(EntityEvent<?> e) {
+    public boolean isAffectedBy(EntityEvent<?> e) { // ❸
         return e.isChanged(TenantAwareProps.TENANT);
     }
 }
+
+/*----------------Documentation Links----------------
+❶ https://babyfish-ct.github.io/jimmer/docs/cache/multiview-cache/user-filter
+
+❷ https://babyfish-ct.github.io/jimmer/docs/cache/multiview-cache/concept#subkey
+
+❸ https://babyfish-ct.github.io/jimmer/docs/cache/multiview-cache/user-filter#define-cache-friendly-filters
+---------------------------------------------------*/

example/java/jimmer-sql/src/main/java/org/babyfish/jimmer/sql/example/business/interceptor/output/TenantFilterForNonCacheMode.java

@@ -14,7 +14,7 @@
  */
 @ConditionalOnMissingBean(TenantFilterForCacheMode.class)
 @Component
-public class TenantFilterForNonCacheMode implements Filter<TenantAwareProps> {
+public class TenantFilterForNonCacheMode implements Filter<TenantAwareProps> { // ❶
 
     protected final TenantProvider tenantProvider;
 
@@ -30,3 +30,7 @@ public void filter(FilterArgs<TenantAwareProps> args) {
         }
     }
 }
+
+/*----------------Documentation Links----------------
+❶ https://babyfish-ct.github.io/jimmer/docs/query/global-filter/user-filter
+---------------------------------------------------*/