Udpate doc to 0.8.130

babyfish-ct · May 5, 2024 · b9566ac · b9566ac
1 parent 1ab83d2
commit b9566ac
Show file tree

Hide file tree

Showing 14 changed files with 737 additions and 214 deletions.
diff --git a/docs/configuration/in-list-optimization.mdx b/docs/configuration/in-list-optimization.mdx
@@ -0,0 +1,93 @@
+---
+sidebar_position: 15
+title: In List Predicate Optimization
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+:::caution
+This article only explains how to enable the relevant options.
+
+As for what these options are used for, please refer to [Query Chapter/DSL Expression/IN LIST/Optimization](../query/expression#optimization), this article will not repeat it.
+:::
+
+## Enable Padding Optimization
+
+Two ways to enable:
+
+-   If you are using the Jimmer Spring Boot Starter, modify `application.yml` (or `application.properties`) as follows:
+
+    ```sh title="application.yml"
+    jimmer:
+        #highlight-next-line
+        in-list-padding-enabled: true
+    ```
+
+-   If you are not using the Jimmer Spring Boot Starter, you need to call the following API when creating the `sqlClient`:
+
+    <Tabs groupId="language">
+    <TabItem value="java" label="Java">
+
+    ```java
+    JSqlClient sqlClient = JSqlClient
+        .newBuilder()
+        // highlight-next-line
+        .setInListPaddingEnabled(true)
+        // ...omitted other configurations...
+        .build();
+    ```
+
+    </TabItem>
+    <TabItem value="kotlin" label="Kotlin">
+
+    ```kotlin
+    val sqlClient = newKSqlClient {
+        // highlight-next-line
+        setInListPaddingEnabled(true)
+        // ...omitted other configurations...
+    }
+    ```
+
+    </TabItem>
+    </Tabs>
+
+## Enable Any Equality Optimization
+
+Two ways to enable:
+
+-   If you are using the Jimmer Spring Boot Starter, modify `application.yml` (or `application.properties`) as follows:
+
+    ```sh title="application.yml"
+    jimmer:
+        #highlight-next-line
+        in-list-to-any-equality-enabled: true
+    ```
+
+-   If you are not using the Jimmer Spring Boot Starter, you need to call the following API when creating the `sqlClient`:
+
+    <Tabs groupId="language">
+    <TabItem value="java" label="Java">
+
+    ```java
+    JSqlClient sqlClient = JSqlClient
+        .newBuilder()
+        // highlight-next-line
+        .setInListToAnyEqualityEnabled(true)
+        // ...omitted other configurations...
+        .build();
+    ```
+
+    </TabItem>
+    <TabItem value="kotlin" label="Kotlin">
+
+    ```kotlin
+    val sqlClient = newKSqlClient {
+        // highlight-next-line
+        setInListToAnyEqualityEnabled(true)
+        // ...omitted other configurations...
+    }
+    ```
+
+    </TabItem>
+    </Tabs>
diff --git a/docs/mutation/save-command/other.mdx b/docs/mutation/save-command/other.mdx
@@ -148,87 +148,3 @@ The explanation is:
     -   New association between `Book(id=3L)` and `Author(id=3L)`.
 
     -   New association between `Book(id=3L)` and `Author(id=1000L)`.
-
-## AppendOnly Mode  
-
-:::warning
-This is an immature API provided in early deficient documentation to address the inability of initial users to understand why save commands need keys.
-
-It violates the core design philosophy of save commands, leading to severely degraded capabilities, and may be removed in the future. Usage should be avoided.  
-:::
-
-There are two usage methods:
-
--   Set specific association properties to AppendOnly mode
-
-    <Tabs groupId="language">
-    <TabItem value="java" label="Java">
-
-    ```java
-    Book book = ...
-    sqlClient
-        .getEntities()
-        .saveCommand(book)
-        // highlight-next-line
-        .setAppendOnly(BookProps.AUTHORS)
-        .execute();
-    ```
-
-    </TabItem>
-    <TabItem value="kotlin" label="Kotlin">
-
-    ```kotlin
-    val book = ...
-    sqlClient.saveBook(book) {
-        // highlight-next-line
-        setAppendOnly(BookProps.AUTHORS)
-    }
-    ```
-
-    </TabItem>
-    </Tabs>
-
--   Set all association properties to AppendOnly mode
-
-    <Tabs groupId="language">
-    <TabItem value="java" label="Java">
-
-    ```java
-    Book book = ...
-    sqlClient
-        .getEntities()
-        .saveCommand(book)
-        // highlight-next-line
-        .setAppendOnlyAll()
-        .execute();
-    ```
-
-    </TabItem>
-    <TabItem value="kotlin" label="Kotlin">
-
-    ```kotlin
-    val book = ...
-    sqlClient.saveBook(book) {
-        // highlight-next-line
-        setAppendOnlyAll()
-    }
-    ```
-
-    </TabItem>
-    </Tabs>
-
-Regardless of usage, once enabled, the consequences are:
-
--   Idempotency of saving associated objects is lost.
-
-    This config allows associated objects to have neither id nor key properties, resulting in unconditional insertion of associated objects.
-
--   Associated properties lose [dissociation](./dissociation) capability.
-
-    This config will only insert or update the associated objects provided by the user, and will not dissociate other associated objects existing in the database but absent from the data structure to be saved.
-
-:::info
-The author believes this API runs counter to the core philosophy of save commands, and should not be retained.
-
-You are welcome to share your insights. Please see [Discussions](../../resource/discuss).
-:::
diff --git a/docs/object/view/dto-language.mdx b/docs/object/view/dto-language.mdx
@@ -323,6 +323,15 @@ Compared with Output DTO, Input DTO has the following differences:
 
 -   The input DTO can only define savable properties, such as simple properties, ordinary ORM associations, and id-view properties. Unsavable properties such as transient properties, formula properties, computed properties, and remote associations cannot be defined, otherwise it will cause compilation errors.
 
+-   Input DTO provides comprehensive and powerful support for nullable properties.
+
+    :::tip
+    For properties that are allowed to be null in the original entity, how to map them through Input DTO is a complex topic. 
+    Jimmer provides comprehensive and powerful support. 
+    
+    Please refer to [Modification/Save Command/Input DTO/Handle Null Values](../../mutation/save-command/input-dto/null-handling).
+    :::
+
 ### 3.3 specification-specific functionalities
 
 The role of `specification` is similar to `input`, used to decorate input types, but `specification` does not provide the ability to convert between entity objects, but is used as a query parameter to support [super QBE queries](../../query/super_qbe). 
@@ -520,20 +529,13 @@ input UpdateBookInput {
 
 -   When the original property in the entity allows null
 
-    For originally nullable properties in entities, if the corresponding property in the DTO object is null, then when converting the DTO object to the entity object:
-
-    - If the `input` type is not modified by the `dynamic` keyword, the original property in the entity object will be assigned to null.
-
-    - If the `input` type is modified by the `dynamic` keyword, for example:
-
-        ```sh title="BookStroe.dto" 
-        #highlight-next-line
-        dynamic input BookInput {
-            #allScalars(this)?
-        }
-        ```
-
-        The original properties in the entity object will not be assigned.
+    :::tip
+    For properties that are allowed to be null in the original entity, how to map them through Input DTO is a complex topic. 
+    Jimmer provides comprehensive and powerful support. 
+    
+    Due to length limitations, this issue forms a separate article. 
+    Please refer to [Modification/Save Command/Input DTO/Handle Null Values](../../mutation/save-command/input-dto/null-handling).
+    :::
 
 ### 7.2. `!`
 
@@ -1481,3 +1483,11 @@ If a property in the DTO overrides an abstract property in the interface, then i
 
 Apart from this, the DTO language does not perform much validation on interface implementation. If the user makes other mistakes, it will result in generating incorrect Java/Kotlin types, which will be handled by the Java/Kotlin compiler.
 :::
+
+## 12. Related Links
+
+As mentioned earlier, the DTO language has two more powerful features that are not discussed in depth in this article due to length limitations, but have been separated into other documents. Here we emphasize them again:
+
+- [Handling Null Values in Input DTO](../../mutation/save-command/input-dto/null-handling)
+
+- [Specification DTO, Super QBE](../../query/super_qbe)