. This SortedMap must use the default sorting rule without custom Comparator. This is very important. For example, SubKey can only be {\"module\":\"x\",\"tenant\":\"a\"}, not {tenant:\"a\", \"module\":\"x\"} which is different but equivalent. This ensures there is no redundant information internally in multi-view cache. Multi-view cache is only for property cache, i.e. association cache and calculated cache. So association properties and complex calculated properties must specify sub key for their multi-view caches.","s":"SubKey","u":"/jimmer-doc/docs/cache/multiview-cache/concept","h":"#subkey","p":77},{"i":85,"t":"For association properties, the necessity of multi-view cache must be caused by the associated entity being affected by user defined global filters. Supporting multi-view cache by merely implementing the Filter/KFilter interface is not enough. The CacheableFilter/KCacheableFilter interface must be implemented. Java Kotlin CacheableFilter.java package org.babyfish.jimmer.sql.filter; public interface CacheableFilter extends Filter
{ SortedMap getParameters(); ...other code omitted... } KCacheableFilter.kt package org.babyfish.jimmer.sql.kt.filter interface KCacheableFilter : KFilter { fun getParameters(): SortedMap? ...other code omitted... } Users need to implement the getParameters() method to contribute part of the information to sub key. info When multiple CacheableFilter/KCacheableFilter affect the associated entity, the data returned by the getParameters() method of each filter object is merged together as the SubKey.","s":"SubKey of Association Properties","u":"/jimmer-doc/docs/cache/multiview-cache/concept","h":"#subkey-of-association-properties","p":77},{"i":87,"t":"Implementing complex calculated properties requires implementing the TransientResolver/KTransientResolver interface. Java Kotlin TransientResolver.java package org.babyfish.jimmer.sql; import org.babyfish.jimmer.lang.Ref; import java.util.SortedMap; public interface TransientResolver { default Ref> getParameterMapRef() { return Ref.empty(); } ...other code omitted... } KTransientResolver.kt package org.babyfish.jimmer.sql.kt import org.babyfish.jimmer.lang.Ref interface KTransientResolver : TransientResolver { override fun getParameterMapRef(): Ref?>? = Ref.empty() ...other code omitted... } This method returns the Ref which is the wrapper of SortedMap. If Ref itself is null, it means getting sub key is difficult and multi-view cache cannot be applied to the calculated property. info In this case, Jimmer will tell developers why cache is abandoned. Otherwise, the internal value of Ref represents the sub key of the current calculated property. info When invalidating cache, Jimmer will automatically delete invalid cached by key. Cached items of multi-view cache are always deleted as a whole based on Key rather than partially based on Key + SubKey, to maximize the relative simplicity of multi-view cache.","s":"SubKey of Complex Calculated Properties","u":"/jimmer-doc/docs/cache/multiview-cache/concept","h":"#subkey-of-complex-calculated-properties","p":77},{"i":92,"t":"In the User defined Filters documentation, we introduced that custom global filters need to implement the Filter/KFilter interface. However, ordinary filters defined using this interface are not cache-friendly. Taking the Book entity as an example, if a cache-unfriendly global filter is set for it, it will cause all the following filter-sensitive properties Association properties targeting Book, such as BookStore.books, Author.books Calculated properties relying on the above association properties, such as BookStore.avgPrice, BookStore.newestBooks to become uncacheable. Jimmer uses the CacheableFilter/KCacheableFilter interface to define cache-friendly filters: Java Kotlin CacheableFilter.java package org.babyfish.jimmer.sql.filter; import org.babyfish.jimmer.sql.ast.table.Props; import org.babyfish.jimmer.sql.event.EntityEvent; import java.util.SortedMap; public interface CacheableFilter extends Filter
{ SortedMap getParameters(); boolean isAffectedBy(EntityEvent e); } KCacheableFilter.kt package org.babyfish.jimmer.sql.kt.filter import org.babyfish.jimmer.sql.event.EntityEvent import java.util.* interface KCacheableFilter : KFilter { fun getParameters(): SortedMap? fun isAffectedBy(e: EntityEvent<*>): Boolean } This interface inherits from Filter/KFilter and adds two new methods: getParameters: The sub key fragment contributed by this filter for multi-view cache. isAffectedBy: Accepts an event that the filtered entity is modified, and judges whether the filtering fields depended on by the current filter are changed. info An entity type allows being processed by multiple global filters: If any one of them is cache-unfriendly, it will cause all filter-sensitive properties to become uncacheable. Therefore, these global filters must either all be cache-unfriendly Filter/KFilter, or all be cache-friendly CacheableFilter/KCacheableFilter. Mixing them together makes no sense. If such meaningless mixing occurs accidentally, Jimmer will tell why cache is abandoned. When all global filters are cache-friendly, the data returned by the getParameters() method of all CacheableFilter/KCacheableFilter objects is merged together as the SubKey of the multi-view cache. For example, if an entity is processed by two global filters at the same time. One is the filter implied by logical delete, denoted as a; the other one is a user-defined filter, denoted as b. Assume a's getParameters() returns {\"logicalDeleted\":false} b's getParameters() returns {\"tenant\":\"a\"} Then the final SubKey in multi-view cache will be {\"logicalDeleted\":false,\"tenant\":\"a\"}","s":"Basic Concepts","u":"/jimmer-doc/docs/cache/multiview-cache/user-filter","h":"#basic-concepts","p":89},{"i":94,"t":"In the User-defined Filters documentation, we defined a super type TenantAware for entities. Let's review its code again: Java Kotlin TenantAware.java @MappedSuperclass public interface TenantAware { String tenant(); } TenantAware.kt @MappedSuperclass interface TenantAware { val tenant: String } Any entity type that needs to support multiple tenants can inherit TenantAware, such as Book: Java Kotlin Book.java @Entity public interface Book extends TenantAware { ...code omitted... } Book.kt @Entity interface Book : TenantAware { ...code omitted... } Assume there is an object of type TenantProvider in the Spring context. Its Java method get() and Kotlin property tenant are used to extract the tenant from the identity information of the current operator. Define the following filter: Java Kotlin @Component public class TenantFilter implements CacheableFilter { private final TenantProvider tenantProvider; public TenantFilter(TenantProvider tenantProvider) { this.tenantProvider = tenantProvider; } @Override public void filter(FilterArgs args) { String tenant = tenantProvider.get(); if (tenant != null) { args.where(args.getTable().tenant().eq(tenant)); } } @Override public SortedMap getParameters() { String tenant = tenantProvider.get(); if (tenant == null) { return null; } SortedMap map = new TreeMap<>(); map.put(\"tenant\", tenant); return map; } @Override public boolean isAffectedBy(EntityEvent e) { return e.isChanged(TenantAwareProps.TENANT) } } @Component class TenantFilter( private val tenantProvider: TenantProvider ) : KCacheableFilter { override fun filter(args: KFilterArgs) { tenantProvider.tenant?.let { args.apply { where(table.tenant.eq(it)) } } } override fun getParameters(): SortedMap? = tenantProvider.tenant?.let { sortedMapOf(\"tenant\" to it) } override fun isAffectedBy(e: EntityEvent<*>): Boolean = e.isChanged(TenantAware::tenant) }","s":"Define Cache-friendly Filters","u":"/jimmer-doc/docs/cache/multiview-cache/user-filter","h":"#define-cache-friendly-filters","p":89},{"i":97,"t":"Java Kotlin @Bean public CacheFactory cacheFactory( RedisConnectionFactory connectionFactory, ObjectMapper objectMapper ) { return new CacheFactory() { @Override public Cache createObjectCache(@NotNull ImmutableType type) { ...code omitted... } @Override public Cache createAssociatedIdCache(@NotNull ImmutableProp prop) { ...code omitted... } @Override public Cache createAssociatedIdCache(@NotNull ImmutableProp prop) { return createPropCache( prop == BookStoreProps.BOOKS.unwrap() || prop == AuthorProps.BOOKS.unwrap() prop, Duration.ofMinutes(5), Duration.ofHours(5) ); } @Override public Cache createResolverCache(ImmutableProp prop) { return createPropCache( prop == BookStoreProps.AVG_PRICE.unwrap() || prop == BookStoreProps.NEWEST_BOOKS.unwrap() prop, Duration.ofMinutes(1), Duration.ofHours(1) ); } private Cache createPropCache( boolean isMultiviewCache, ImmutableProp prop, Duration caffeineDuration, Duration redisDuration ) { if (isMultiView) { return new ChainCacheBuilder() .add( CaffeineHashBinder .forProp(prop) .maximumSize(128) .duration(caffeineDuration) .build() ) .add( RedisHashBinder .forProp(prop) .redis(connectionFactory) .objectMapper(objectMapper) .duration(redisDuration) .build() ) .build(); } return new ChainCacheBuilder<>() .add( CaffeineValueBinder .forObject(type) .maximumSize(512) .duration(caffeineDuration) .build() ) .add( RedisValueBinder .forProp(prop) .redis(connectionFactory) .objectMapper(objectMapper) .duration(redisDuration) .build() ) .build(); } }; } @Bean fun cacheFactory( connectionFactory: RedisConnectionFactory, objectMapper: ObjectMapper ): KCacheFactory { return object: KCacheFactory { override fun createObjectCache(type: ImmutableType): Cache<*, *>? = ...code omitted... override fun createAssociatedIdCache(prop: ImmutableProp): Cache<*, *>? = ...code omitted... override fun createAssociatedIdListCache(prop: ImmutableProp): Cache<*, List<*>>? = createPropCache( prop === BookStore::books.toImmutableProp() || prop === Author::books.toImmutableProp(), prop, Duration.ofMinutes(1), Duration.ofHours(1) ) override fun createResolverCache(prop: ImmutableProp): Cache<*, *> = createPropCache( prop === BookStore::avgPrice.toImmutableProp() || prop === BookStore::newestBooks.toImmutableProp(), prop, Duration.ofMinutes(1), Duration.ofHours(1) ) private fun createPropCache( isMultiView: Boolean, prop: ImmutableProp, caffeineDuration: Duration, redisDuration: Duration ): Cache { if (isMultiView) { return ChainCacheBuilder() .add( CaffeineHashBinder .forProp(prop) .maximumSize(128) .duration(caffeineDuration) .build() ) .add( RedisHashBinder .forProp(prop) .redis(connectionFactory) .objectMapper(objectMapper) .duration(redisDuration) .build() ) .build(); } ChainCacheBuilder() .add( CaffeineValueBinder .forProp(prop) .maximumSize(512) .duration(caffeineDuration) .build() ) .add( RedisValueBinder .forProp(prop) .redis(connectionFactory) .objectMapper(objectMapper) .duration(redisDuration) .build() ) .build() } } } The RedisHashBinder class in the above code is a very important implementation that utilizes Redis' support for multi-view cache. The underlying storage structure corresponds to Redis Hashes, i.e. nested Hash structures. Cache Style Is Multi-view Abstract API Built-in Impl Cache with self-loading (usually first-level cache technologies like Guava, Caffeine) Single-view LoadingBinder CaffeineValueBinder Multi-view LoadingBinder.Parameterized None Cache without self-loading (usually second-level cache technologies like Redis) Single-view SimpleBinder RedisValueBinder Multi-view SimpleBinder.Parameterized RedisHashBinder RedisHashBinder","s":"Simple Approach","u":"/jimmer-doc/docs/cache/multiview-cache/user-filter","h":"#simple-approach","p":89},{"i":99,"t":"In the above code, the createAssociatedIdListCache method judges the prop parameter to decide whether to build multi-view cache or single-view cache. However, tip For association properties, whether multi-view cache needs to be built can be determined solely by whether the target entity is filtered. Jimmer provides better support for this. Developers only need to replace the super interface CacheFactory/KCacheFactory with the super class AbstractCacheFactory/AbstractKCacheFactory to inherit a member called getFilterState/filterState which can help us determine whether to build multi-view cache. Java Kotlin @Bean public CacheFactory cacheFactory( RedisConnectionFactory connectionFactory, ObjectMapper objectMapper ) { return new AbstractCacheFactory() { @Override public Cache createObjectCache(@NotNull ImmutableType type) { ...code omitted... } @Override public Cache createAssociatedIdCache(@NotNull ImmutableProp prop) { return createPropCache( getFilterState().isAffectedBy(prop.getTargetType()), prop, Duration.ofMinutes(5), Duration.ofHours(5) ); } @Override public Cache createAssociatedIdCache(@NotNull ImmutableProp prop) { return createPropCache( getFilterState().isAffectedBy(prop.getTargetType()), prop, Duration.ofMinutes(5), Duration.ofHours(5) ); } @Override public Cache createResolverCache(ImmutableProp prop) { return createPropCache( prop == BookStoreProps.AVG_PRICE.unwrap() || prop == BookStoreProps.NEWEST_BOOKS.unwrap() prop, Duration.ofSeconds(1), Duration.ofHours(24) ); } private Cache createPropCache( boolean isMultiviewCache, ImmutableProp prop, Duration duration ) { ...code omitted... } }; } @Bean fun cacheFactory( connectionFactory: RedisConnectionFactory, objectMapper: ObjectMapper ): KCacheFactory { return object: AbstractKCacheFactory() { override fun createObjectCache(type: ImmutableType): Cache<*, *>? = ...code omitted... override fun createAssociatedIdCache(prop: ImmutableProp): Cache<*, *>? = createPropCache( filterState.isAffectedBy(prop.targetType), prop, Duration.ofMinutes(5), Duration.ofHours(5) ) override fun createAssociatedIdListCache(prop: ImmutableProp): Cache<*, List<*>>? = createPropCache( filterState.isAffectedBy(prop.targetType), prop, Duration.ofMinutes(5), Duration.ofHours(5) ) override fun createResolverCache(prop: ImmutableProp): Cache<*, *> = createPropCache( prop === BookStore::avgPrice.toImmutableProp() || prop === BookStore::newestBooks.toImmutableProp(), prop, Duration.ofHours(1), Duration.ofHours(24) ) private fun createPropCache( isMultiView: Boolean, prop: ImmutableProp, caffeineDuration: Duration, redisDuration: Duration ): Cache { ...code omitted... } } } info Unfortunately, this method can only simplify the construction of association caches, i.e. simplify the createAssociatedIdCache and createAssociatedIdListCache methods. For calculated properties, since the framework is unaware of the internal logic used by user-defined calculated properties, it cannot simplify them. Users need to decide whether to build multi-view caches based on their own business characteristics.","s":"Better Approach","u":"/jimmer-doc/docs/cache/multiview-cache/user-filter","h":"#better-approach","p":89},{"i":101,"t":"We have defined the getParameters method in TenantFilter. All affected association properties will automatically specify SubKey for their association caches. However, unfortunately, due to the introduction of user-defined calculation rules that the framework cannot understand, developers must manually specify SubKey for the TransientResolver implementation of calculated properties. Java Kotlin BookStoreAvgPriceResolver.java @Component public class BookStoreAvgPriceResolver implements TransientResolver { private final JSqlClient sqlClient; @Override public Ref> getParameterMapRef() { return sqlClient .getFilters() .getTargetParameterMapRef(BookStoreProps.BOOKS); } ...code omitted... } BookStoreAvgPriceResolver.kt @Component class BookStoreAvgPriceResolver( private val sqlClient: KSqlClient ) : KTransientResolver { override fun getParameterMapRef(): Ref?>? { return sqlClient .filters .getTargetParameterMapRef(BookStore::books) } ...code omitted... } Obviously, the calculated property BookStore.avgPrice is actually determined by the association property BookStore.books and changes with it. Therefore, whatever SubKey the association property BookStore.books specifies for the multi-view cache system in the current invocation context, the calculated property BookStore.avgPrice should specify the same one. note BookStore.avgPrice is also affected by Book.price. It changes when Book.price changes. However, Book.price is a non-associative property of the object, so it must be irrelevant to the multi-view cache system. The getParameterMapRef method does not need to consider it here.","s":"SubKey of Calculated Properties","u":"/jimmer-doc/docs/cache/multiview-cache/user-filter","h":"#subkey-of-calculated-properties","p":89},{"i":103,"t":"Now that we have made the association property BookStore.books and the calculated property BookStore.avgPrice support multi-view caching, let's use object fetchers to query them: Java Kotlin BookStoreTable table = Tables.BOOK_STORE_TABLE; List stores = sqlClient .createQuery(table) .select( table.fetch( Fetchers.BOOK_STORE_FETCHER .allScalarFields() .books( ❶ Fetchers.BOOK_FETCHER .allScalarFields() ) .avgPrice() ❷ ) ) .execute(); System.out.println(stores); val stores = sqlClient .createQuery(BookStore::class) { select( table.fetchBy { allScalarFields() books { ❶ allScalarFields() } avgPrice() ❷ } ) } .execute() println(stores)","s":"Usage","u":"/jimmer-doc/docs/cache/multiview-cache/user-filter","h":"#usage","p":89},{"i":105,"t":"Assume the current tenant name is a, the execution process is as follows: First step: Query aggregate root First query the aggregate root object by executing the following SQL: select tb_1_.ID, tb_1_.NAME, tb_1_.WEBSITE from BOOK_STORE tb_1_ Here the query in the code is implemented to get some BookStore objects. Such objects directly queried by the user are called aggregate root objects. Second step: Query BookStore.books in ❶ through association cache The above code will get a series of aggregate root objects. If using the official example data, it will get two aggregate root objects with ID of 1 and 2 for BOOK_STORE. Jimmer first looks up the data from Redis. The keys looked up are BookStore.books-1 and BookStore.books-2. Assume the data for these keys cannot be found in Redis: 127.0.0.1:6379> keys BookStore.books-* (empty array) So the following SQL is executed to complete the associated property BookStore.books: SQL: select, tb_1_.STORE_ID, tb_1_.ID from BOOK tb_1_ where tb_1_.STORE_ID in ( ? /* 1 */, ? /* 2 */ ) and // highlight-next-line tb_1_.TENANT = ? /* a */ order by tb_1_.NAME asc, tb_1_.EDITION desc info The filter condition tb_1_.TENANT = 'a' comes from the user filter TenantFilter. Jimmer will put the query result into Redis. So we can view the data from Redis: 127.0.0.1:6379> keys BookStore.books-* 1) \"BookStore.books-2\" 2) \"BookStore.books-1\" 127.0.0.1:6379> hgetall BookStore.books-1 1) \"{\\\"tenant\\\":\\\"a\\\"}\" 2) \"[5,3,1,9,7]\" 127.0.0.1:6379> hgetall BookStore.books-2 1) \"{\\\"tenant\\\":\\\"a\\\"}\" 2) \"[11]\" info Jimmer uses Redis Hash for multi-perspective cache. So hgetall instead of get is needed. Redis Hash is a nested KV structure: The outer Redis Key, e.g. BookStore.books-1 and BookStore.books-2, is no different from single-perspective cache. The inner Hash Key, also called SubKey in Jimmer, is provided by global filters. Here, {\"tenant\":\"a\"} is provided by TenantProvider, indicating the cached value is not the id set of all associated objects, but the id set of associated objects visible to tenant a. tip Undoubtedly, executing the above Java/Kotlin code again with the same tenant identity before data expiration in Redis, it will directly return associated data from Redis without generating related SQL. Third step: Convert id set to associated objects In the previous step we got the id set of associated objects corresponding to associated property BookStore.books, representing the associated objects visible to tenant a. Now we can use the object cache of Book to convert the Book id set into Book object set. This step is very simple without further discussion. Fourth step: Query BookStore.avgPrice in ❷ through computation cache The above code will get a series of aggregate root objects. If using the official example data, it will get two aggregate root objects with ID of 1 and 2 for BOOK_STORE. Jimmer first looks up the data from Redis. The keys looked up are BookStore.avgPrice-1 and BookStore.avgPrice-2. Assume the data for these keys cannot be found in Redis: 127.0.0.1:6379> keys BookStore.avgPrice-* (empty array) So the following SQL is executed to compute the calculation property: select tb_1_.ID, avg(tb_2_.PRICE) from BOOK_STORE tb_1_ left join BOOK tb_2_ on tb_1_.ID = tb_2_.STORE_ID where tb_1_.ID in ( ? /* 1 */, ? /* 2 */ ) and // highlight-next-line tb_1_.TENANT = ? /* a */ group by tb_1_.ID info The filter condition tb_1_.TENANT = 'a' comes from the user filter TenantFilter. Jimmer will put the query result into Redis. So we can view the data from Redis: 127.0.0.1:6379> keys BookStore.avgPrice-* 1) \"BookStore.avgPrice-2\" 2) \"BookStore.avgPrice-1\" 127.0.0.1:6379> hgetall BookStore.avgPrice-1 1) \"{\\\"tenant\\\":\\\"a\\\"}\" 2) \"53.1\" 127.0.0.1:6379> hgetall BookStore.avgPrice-2 1) \"{\\\"tenant\\\":\\\"a\\\"}\" 2) \"81\" info Jimmer uses Redis Hash for multi-perspective cache. So hgetall instead of get is needed. Redis Hash is a nested KV structure: The outer Redis Key, e.g. BookStore.avgPrice-1 and BookStore.avgPrice-2, is no different from single-perspective cache. The inner Hash Key, also called SubKey in Jimmer, is provided by global filters. Here, {\"tenant\": \"a\"} is provided by TenantProvider, indicating the cached value is not the average price of all associated objects, but the average price of associated objects visible to tenant a. tip Undoubtedly, executing the above Java/Kotlin code again with the same tenant identity before data expiration in Redis, it will directly return associated data from Redis without generating related SQL. Finally, Jimmer concatenates the results of the 4 steps and returns them to the user. [ { \"id\":2, \"name\":\"MANNING\", \"website\":null, \"books\":[ { \"id\":11, \"name\":\"GraphQL in Action\", \"edition\":2, \"price\":81 } ], \"avgPrice\":81 }, { \"id\":1, \"name\":\"O'REILLY\", \"website\":null, \"books\":[ { \"id\":5, \"name\":\"Effective TypeScript\", \"edition\":2, \"price\":69 }, { \"id\":3, ...omitted... }, { \"id\":1, ...omitted... }, { \"id\":9, ...omitted... }, { \"id\":7, ...omitted... } ], \"avgPrice\":53.1 } ]","s":"Execute with one tenant identity","u":"/jimmer-doc/docs/cache/multiview-cache/user-filter","h":"#execute-with-one-tenant-identity","p":89},{"i":107,"t":"The query execution process with tenant a has been discussed. Similarly, we can execute multiple times using different tenant identities to leave cache data in Redis from the following perspectives: tenant = null tenant = \"a\" tenant = \"b\" info For the official example, TenantProvider is implemented based on HTTP request header and has swagger UI support. It's easy to execute three times with three different user identities. Among them, tenant = null corresponds to the unauthorized/logout state in swagger UI. Open redis-cli, we can verify the data in Redis: 127.0.0.1:6379> keys BookStore.books-* 1) \"BookStore.books-2\" 2) \"BookStore.books-1\" 127.0.0.1:6379> hgetall BookStore.books-1 1) \"{\\\"tenant\\\":\\\"b\\\"}\" 2) \"[6,4,2,8]\" 3) \"{\\\"tenant\\\":\\\"a\\\"}\" 4) \"[5,3,1,9,7]\" 5) \"{}\" 6) \"[6,5,4,3,2,1,9,8,7]\" 127.0.0.1:6379> hgetall BookStore.books-2 1) \"{\\\"tenant\\\":\\\"b\\\"}\" 2) \"[12,10]\" 3) \"{\\\"tenant\\\":\\\"a\\\"}\" 4) \"[11]\" 5) \"{}\" 6) \"[12,11,10]\" 127.0.0.1:6379> keys BookStore.avgPrice-* 1) \"BookStore.avgPrice-2\" 2) \"BookStore.avgPrice-1\" 127.0.0.1:6379> hgetall BookStore.avgPrice-1 1) \"{\\\"tenant\\\":\\\"b\\\"}\" 2) \"65.25\" 3) \"{\\\"tenant\\\":\\\"a\\\"}\" 4) \"53.1\" 5) \"{}\" 6) \"58.500000\" 127.0.0.1:6379> hgetall BookStore.avgPrice-2 1) \"{\\\"tenant\\\":\\\"b\\\"}\" 2) \"80\" 3) \"{\\\"tenant\\\":\\\"a\\\"}\" 4) \"81\" 5) \"{}\" 6) \"80.333333\" tip Readers can take a close look at these redis-cli commands and easily find that the data of sub key {\"tenant\":\"a\"} merged with the data of sub key {\"tenant\":\"b\"} is exactly the data of SubKey {}. The data returned to the user in the 3 calls is: tenant=null tenant=a tenant=b [ { \"id\":2, \"name\":\"MANNING\", \"website\":null, \"books\":[ { \"id\":12, \"name\":\"GraphQL in Action\", \"edition\":3, \"price\":80, }, { \"id\":11, ...omitted... }, { \"id\":10, ...omitted... } ], \"avgPrice\":80.333333 }, { \"id\":1, \"name\":\"O'REILLY\", \"website\":null, \"books\":[ { \"id\":6, \"name\":\"Effective TypeScript\", \"edition\":3, \"price\":88 }, { \"id\":5, ...omitted... }, { \"id\":4, ...omitted... }, { \"id\":3, \"name\":\"Learning GraphQL\", \"edition\":3, \"price\":51 }, { \"id\":2, ...omitted... }, { \"id\":1, ...omitted... }, { \"id\":9, \"name\":\"Programming TypeScript\", \"edition\":3, \"price\":48 }, { \"id\":8, ...omitted... }, { \"id\":7, ...omitted... } ], \"avgPrice\":58.5 } ] [ { \"id\":2, \"name\":\"MANNING\", \"website\":null, \"books\":[ { \"id\":11, \"name\":\"GraphQL in Action\", \"edition\":2, \"price\":81 } ], \"avgPrice\":81 }, { \"id\":1, \"name\":\"O'REILLY\", \"website\":null, \"books\":[ { \"id\":5, \"name\":\"Effective TypeScript\", \"edition\":2, \"price\":69 }, { \"id\":3, ...omitted... }, { \"id\":1, ...omitted... }, { \"id\":9, ...omitted... }, { \"id\":7, ...omitted... } ], \"avgPrice\":53.1 } ] [ { \"id\":2, \"name\":\"MANNING\", \"website\":null, \"books\":[ { \"id\":12, \"name\":\"GraphQL in Action\", \"edition\":3, \"price\":80 }, { \"id\":10, ...omitted... } ], \"avgPrice\":80 }, { \"id\":1, \"name\":\"O'REILLY\", \"website\":null, \"books\":[ { \"id\":6, \"name\":\"Effective TypeScript\", \"edition\":3, \"price\":88 }, { \"id\":4, ...omitted... }, { \"id\":2, ...omitted... }, { \"id\":8, ...omitted... } ], \"avgPrice\":65.25 } ]","s":"Execute repeatedly with multiple tenant identities","u":"/jimmer-doc/docs/cache/multiview-cache/user-filter","h":"#execute-repeatedly-with-multiple-tenant-identities","p":89},{"i":109,"t":"Now let's modify the property Book.tenant of the Book object with id 6 from \"b\" to \"a\". Since Book-6 belongs to BookStore-1, it is foreseeable that the multi-view caches corresponding to the properties BookStore.books-1 and BookStore.avgPrice-1 will definitely be invalidated. If BinLog trigger is enabled, modifying the database in any way can lead to Jimmer's cache consistency involvement. For example, directly executing the following SQL in SQL IDE: update BOOK set TENANT = 'a' where ID = 6; If only Transaction trigger is enabled, the database must be modified using Jimmer's API: Java Kotlin sqlClient.save( Immutables.createBook(draft -> { draft.setId(6L); draft.setTenant(\"a\"); }) ); sqlClient.save( Book { id = 6L tenant = \"a\" } ) No matter which way above is used to modify the data, you will see the following log output: Delete data from redis: [Book-6] ❶ Delete data from redis: [Author.books-3] ❷ Delete data from redis: [BookStore.books-1] ❸ Delete data from redis: [BookStore.avgPrice-1] ❹ ❶ Update object cache of modified entity ❷ Any association property targeting Book must be affected, of course including Author.books According to existing database data, the affected Author object id is 3 ❸ Any association property targeting Book must be affected, of course including BookStore.books According to existing database data, the affected BookStore object id is 1 ❹ The calculated cache BookStore.avgPrice of BookStore object with id 1 is also affected. This is the most amazing characteristic. Although the framework is unaware of the calculation rule used by users in calculated properties, in the Calculated Cache documentation, we discussed the following code in the BookStoreAvgPriceResolver class: Java Kotlin @EventListener public void onAssociationChange(AssociationEvent e) { if (sqlClient.getCaches().isAffectedBy(e) && e.isChanged(BookStoreProps.BOOKS) ) { ...code omitted... } } @EventListener fun onAssociationChange(e: AssociationEvent) { if (sqlClient.caches.isAffectedBy(e) && e.isChanged(BookStore::books) ) { ...code omitted... } } If you have forgotten the specific logic of this code, you can review the Calculated Cache documentation. Just focus on the highlighted line. Here, this calculated property cares about changes to the association property BookStore.books. tip Modifying the association field between tables is not the only way to trigger association change events. Modifying the filtered field in associated objects that affects global filters, like TENANT here, can also trigger association change events. This is a very important characteristic of Jimmer's trigger mechanism! It is obvious that ❸ has already sensed the change of association property BookStore.books, so it will further lead to the invalidation of the calculated cache here.","s":"Cache Invalidation","u":"/jimmer-doc/docs/cache/multiview-cache/user-filter","h":"#cache-invalidation","p":89},{"i":112,"t":"To enable cache, you first need to implement the CacheFactory/KCacheFactory interface, which is defined as follows: Java Kotlin CacheFactory.java package org.babyfish.jimmer.sql.cache; import org.babyfish.jimmer.meta.ImmutableProp; import org.babyfish.jimmer.meta.ImmutableType; import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.Nullable; import java.util.List; public interface CacheFactory { @Nullable default Cache createObjectCache(@NotNull ImmutableType type) { return null; } @Nullable default Cache createAssociatedIdCache(@NotNull ImmutableProp prop) { return null; } @Nullable default Cache> createAssociatedIdListCache(@NotNull ImmutableProp prop) { return null; } @Nullable default Cache createResolverCache(@NotNull ImmutableProp prop) { return null; } } KCacheFactory.kt package org.babyfish.jimmer.sql.kt.cache import org.babyfish.jimmer.meta.ImmutableProp import org.babyfish.jimmer.sql.cache.Cache import org.babyfish.jimmer.sql.cache.CacheFactory interface KCacheFactory : CacheFactory { override fun createObjectCache(type: ImmutableType): Cache<*, *>? = null override fun createAssociatedIdCache(prop: ImmutableProp): Cache<*, *>? = null override fun createAssociatedIdListCache(prop: ImmutableProp): Cache<*, List<*>>? = null override fun createResolverCache(prop: ImmutableProp): Cache<*, *>? = null } info For Kotlin, in order to generate better code when overriding createAssociatedIdListCache, please implement the org.babyfish.jimmer.sql.kt.cache.KCacheFactory interface. Otherwise, the return type of the override method generated by the IDE will be Cache<*, MutableList<*>> instead of the expected Cache<*, List<*>>. Jimmer calls this interface to initialize caches for types and properties. Users implement this interface to answer: createObjectCache: Enable object cache The parameter specifies an entity type. If you want to enable object cache for it, create and return the cache; otherwise, return null. Object cache refers to mapping id to entity object. info This entity object is orphaned, without associated properties. One-to-one/many-to-one associations based on foreign keys are an exception, they can hold associated objects with only the id property, because the id of the associated object is actually the foreign key field of the current table. createAssociatedIdCache and createAssociatedIdListCache: Enable association cache Both createAssociatedIdCache and createAssociatedIdListCache are used to enable association cache. The only difference between them is: createAssociatedIdCache: For one-to-one or many-to-one associations. createAssociatedIdListCache: For one-to-many or many-to-many associations. The parameter specifies an association property. If you want to enable association cache for it, create and return the cache; otherwise return null. Association cache refers to mapping id to associated id or associated id collection. createResolverCache: Enable calculated cache The parameter specifies a complex calculated property. If you want to enable calculated cache for it, create and return the cache; otherwise, return null. Computed cache refers to mapping id to calculated result.","s":"CacheFactory Interface","u":"/jimmer-doc/docs/cache/enable-cache","h":"#cachefactory-interface","p":110},{"i":114,"t":"The return type of all methods of the CacheFactory interface is org.babyfish.jimmer.sql.cache.Cache. Users do not need to directly implement Cache, but need to use org.babyfish.jimmer.sql.cache.chain.ChainCacheBuilder to build multi-level caches. In theory, ChainCacheBuilder supports caches of any number of levels. However, in most projects, two levels of cache are sufficient, for example: Java Kotlin return new CacheFactory() { @Override @Nullable public Cache createObjectCache(@NotNull ImmutableType type) { return new ChainCacheBuilder<>() .add( ❶ CaffeineValueBinder .forObject(type) .maximumSize(512) .duration(Duration.ofSeconds(10)) .build() ) .add( ❷ RedisValueBinder .forObject(type) .redis(connectionFactory) .objectMapper(objectMapper) .duration(Duration.ofHours(10)) .build() ) ) .build(); } }; return object: KCacheFactory { override fun createObjectCache(type: ImmutableType): Cache<*, *>? = ChainCacheBuilder() .add( ❶ CaffeineValueBinder .forObject(type) .maximumSize(512) .duration(Duration.ofSeconds(10)) .build() ) .add( ❷ RedisValueBinder .forObject(type) .redis(connectionFactory) .objectMapper(objectMapper) .duration(Duration.ofHours(10)) .build() ) ) .build() } ❶ Indicates first level cache based on Caffeine in-process JVM cache. ❷ Indicates second level cache based on Redis remote cache. As we can see, ChainCacheBuilder uses chain programming style. Calling the add method multiple times can build multi-level caches. The ChainCacheBuilder.add method is defined as follows: public class ChainCacheBuilder { public ChainCacheBuilder add(LoadingBinder binder) { ❶ ...omit code... return this; } public ChainCacheBuilder add(LoadingBinder.Parameterized binder) { ❷ ...omit code... return this; } public ChainCacheBuilder add(SimpleBinder binder) { ❸ ...omit code... return this; } ...omit other code... } ❶ org.babyfish.jimmer.sql.cache.chain.LoadingBinder is an interface. Any cache technology that automatically loads values on first access to a key can be adapted through this interface. Almost all in-process JVM caches have automatic loading capabilities, such as Caffeine or Guava Cache used in the above code. ❷ The code is only used by multi-view caches. Readers can ignore it for now. ❸ org.babyfish.jimmer.sql.cache.chain.SimpleBinder is an interface. Any cache technology without automatic value loading behavior can be adapted through this interface. Almost all remote caches do not have automatic loading capabilities, such as Redis used in the above code. tip Any cache technology can be adapted to the abstract interfaces LoadingBinder or SimpleBinder. Therefore, in Jimmer's multi-level cache architecture, no assumptions or restrictions are made on the choice of cache technology at any level. If using Jimmer's SpringBoot Starter, you can use the following three cache technology adapter classes, as in the code above: Jimmer's built-in adapter classes Implemented Interface Supports Multi-view Cache org.babyfish.jimmer.spring.cache.CaffeineBinder org.babyfish.jimmer.sql.cache.chain.LoadingBinder No org.babyfish.jimmer.spring.cache.RedisValueBinder org.babyfish.jimmer.sql.cache.chain.SimpleBinder No org.babyfish.jimmer.spring.cache.RedisHashBinder org.babyfish.jimmer.sql.cache.chain.SimpleBinder.Parameterized Yes note Multi-view caches will be explained in a subsequent article. Please ignore them for now.","s":"Multi-level Cache Architecture","u":"/jimmer-doc/docs/cache/enable-cache","h":"#multi-level-cache-architecture","p":110},{"i":116,"t":"Now we have introduced the CacheFactory interface and multi-level cache architecture, but there is one last step to enable cache. The last step is to register CacheFactory for Jimmer.","s":"Configuring CacheFactory","u":"/jimmer-doc/docs/cache/enable-cache","h":"#configuring-cachefactory","p":110},{"i":118,"t":"If using SpringBoot Starter, just let CacheFactory be managed by Spring. Java Kotlin @Bean public CacheFactory cacheFactory() { return new CacheFactory() { ...omit code... }; } @Bean fun cacheFactory(): KCacheFactory = object: KCacheFactory { ...omit code... }","s":"SpringBoot Configuration","u":"/jimmer-doc/docs/cache/enable-cache","h":"#springboot-configuration","p":110},{"i":120,"t":"Java Kotlin JSqlClient sqlClient = JSqlClient .newBuilder() .setCacheFactory( new CacheFactory() { ...omit code... } ) ...omit other configuration... .build(); val sqlClient = newKSqlClient { setCacheFactory( object: KCacheFactory { ...omit code... } ) ...omit other configuration... }","s":"Underlying API Configuration","u":"/jimmer-doc/docs/cache/enable-cache","h":"#underlying-api-configuration","p":110},{"i":122,"t":"Earlier we mentioned that if using Jimmer's SpringBoot Starter, you can use the ready-made org.babyfish.jimmer.spring.cache.RedisValueBinder without having to adapt Redis yourself. note RedisHashBinder is related to multi-view caches and will not be discussed in this article. To build RedisValueBinder, you need a RedisOperations. Jimmer's SpringBoot Stater provides the org.babyfish.jimmer.spring.cache.RedisCaches class whose static method RedisCaches.cacheRedisTemplate can quickly build this RedisOperations object. An example of the helper method RedisCaches.cacheRedisTemplate is as follows: Java Kotlin @Bean public CacheFactory cacheFactory( RedisConnectionFactory connectionFactory, ObjectMapper objectMapper ) { return new CacheFactory() { @Override @Nullable public Cache createObjectCache(@NotNull ImmutableType type) { return new ChainCacheBuilder() .add( CaffeineValueBinder .forProp() .maximumSize(1024) .duration(RedisCaches.ofMinutes(24)) .bind() ) .add( RedisValueBinder .forProp(prop) .redis(connectionFactory) .objectMapper(objectMapper) .duration(Duration.ofHours(24)) .build() ) .build(); } @Override @Nullable public Cache createAssociatedIdCache(@NotNull ImmutableProp prop) { return createPropCache( prop, Duration.ofMinutes(10), Duration.ofHours(10) ); } @Override @Nullable public Cache> createAssociatedIdListCache(@NotNull ImmutableProp prop) { return createPropCache( prop, Duration.ofMinutes(5), Duration.ofHours(5), ); } @Override @Nullable public Cache createResolverCache(@NotNull ImmutableProp prop) { return createPropCache( prop, Duration.ofMinutes(5), Duration.ofHours(5) ); } private Cache createPropCache( ImmutableProp prop, Duration caffeineDuration Duration redisDuration ) { return new ChainCacheBuilder() .add( CaffeineValueBinder .forProp(prop) .maximumSize(512) .duration(caffeineDuration) .build() ) .add( RedisValueBinder .forProp(prop) .redis(connectionFactory) .objectMapper(objectMapper) .duration(redisDuration) .build() ) .build(); } }; } @Bean fun cacheFactory( connectionFactory: RedisConnectionFactory, objectMapper: ObjectMapper ): KCacheFactory { return object: KCacheFactory { override fun createObjectCache(type: ImmutableType): Cache<*, *>? = ChainCacheBuilder() .add( CaffeineValueBinder .forObject(type) .maximumSize(1024) .duration(Duration.ofHours(1)) .build() ) .add( RedisValueBinder .forObject(type) .redis(connectionFactory) .objectMapper(objectMapper) .duration(Duration.ofHours(24)) .build() ) .build() override fun createAssociatedIdCache(prop: ImmutableProp): Cache<*, *>? = createPropCache( prop, Duration.ofMinutes(10), Duration.ofHours(10) ) override fun createAssociatedIdListCache(prop: ImmutableProp): Cache<*, List<*>>? = createPropCache( prop, Duration.ofMinutes(5), Duration.ofHours(5) ) override fun createResolverCache(prop: ImmutableProp): Cache<*, *>? = createPropCache( prop, Duration.ofMinutes(5), Duration.ofHours(5) ) private fun createPropCache( type: ImmutableType, caffeineDuration: Duration, redisDuration: Duration ): Cache<*, *> = ChainCacheBuilder() .add( CaffeineValueBinder .forProp(prop) .maximumSize(512) .duration(caffeineDuration) .build() ) .add( RedisValueBinder .forProp(prop) .redis(connectionFactory) .objectMapper(objectMapper) .duration(redisDuration) .build() ) .build() } }","s":"Redis Cache Helper APIs","u":"/jimmer-doc/docs/cache/enable-cache","h":"#redis-cache-helper-apis","p":110},{"i":124,"t":"This section introduces the global configurations supported by Jimmer.","s":"Configuration","u":"/jimmer-doc/docs/configuration/","h":"","p":123},{"i":126,"t":"SqlClient supports two configurations: DefaultBatchSize and DefaultListBatchSize. If not configured, the default values are 128 and 16. These two configurations provide default values for the batchSize in Object Fetcher. Their effects have been described in detail in Object Fetcher, so this article only explains the configuration without repeating the explanation of their effects. There are two ways to set these configurations: Use Spring Boot Starter Don't use Spring Boot Starter","s":"Batch Control","u":"/jimmer-doc/docs/configuration/batch-size","h":"","p":125},{"i":128,"t":"jimmer: default-batch-size: 256 default-list-batch-size: 32","s":"Use Spring Boot Starter","u":"/jimmer-doc/docs/configuration/batch-size","h":"#use-spring-boot-starter","p":125},{"i":130,"t":"Java Kotlin @Bean public JSqlClient sqlClient() { return JSqlClient .newBuilder() .setConnectionManager(...) .setDialect(new H2Dialect()) .setExecutor(...) .addScalarProvider(...) .setDefaultBatchSize(256) .setDefaultListBatchSize(32) .build(); } @Bean fun sqlClient(): KSqlClient = newKSqlClient { setConnectionManager { ... } setDialect(H2Dialect()) setExecutor { ... } addScalarProvider { ... } setDefaultBatchSize(256) setDefaultListBatchSize(32) }","s":"Don't use Spring Boot Starter","u":"/jimmer-doc/docs/configuration/batch-size","h":"#dont-use-spring-boot-starter","p":125},{"i":133,"t":"If using Jimmer to build backend systems, developers have three ways to solve the DTO Explosion Description Where object shapes are restricted Client experience Solution 1 Use Jimmer to build GraphQL services Client side Good Solution 2 Use Jimmer to build REST services, shapes specified by client Client side Bad Solution 3 Use Jimmer to build REST services, shapes enumerated by server Server side Good Let's discuss the three cases separately:","s":"Basic Concepts","u":"/jimmer-doc/docs/client/api","h":"#basic-concepts","p":131},{"i":135,"t":"Use Jimmer to build GraphQL services Server: Develop GraphQL Backend with Jimmer Client: Many client frameworks to choose from. Using my graphql-ts-client can get the ultimate TypeScript experience caution Jimmer itself supports recursive query of self-associated properties, but so far, the GraphQL protocol does not support this feature, which means the feature will be lost.","s":"Solution 1 (GraphQL)","u":"/jimmer-doc/docs/client/api","h":"#solution-1-graphql","p":131},{"i":137,"t":"Use Jimmer to build REST services, shapes specified by client This approach actually gives REST the capabilities of GraphQL. The client passes a string, and the server parses it into a Fetcher via org.babyfish.jimmer.sql.fetcher.compiler.FetcherCompiler Java Kotlin BookController.java @GetMapping(\"/book/{id}\") public Book findBookById( @PathVariable long id, @RequestParam(required = false) String fetcherCode ) { Fetcher fetcher = FetcherCompiler.compile(fetcherCode, Book.class); return bookRepository.findNullable(id, fetcher); } BookController.kt @GetMapping(\"/book/{id}\") fun findBookById( @PathVariable id: Long, @RequestParam(required = false) fetcherCode: String? ): Book? = bookRepository.findNullable( id, FetcherCompiler.compile(fetcherCode, Book::class.java) ) When calling, specify the fetcherCode parameter, for example { id name authors { id firstName lastName } } or { id, name, authors { id, firstName, lastName }} info To learn how to express more complex object fetcher in string code, refer to the toString() method of object fetcher. caution Although this approach can give REST capabilities similar to GraphQL, which is very flexible, it only facilitates server-side writing. The client will get a messy type system, so it is not recommended. If due to some historical constraints, the client uses JavaScript, not TypeScript, and there is no foreseeable hope of any improvement, then consider this usage.","s":"Solution 2 (Not Recommended)","u":"/jimmer-doc/docs/client/api","h":"#solution-2-not-recommended","p":131},{"i":139,"t":"Use Jimmer to build REST services, shapes enumerated by server This usage is more in line with the original intention of the REST protocol, and it is also easier to manage permissions (although the previous two usages are flexible, permission control is very difficult), and it is also the topic to be discussed in this article. info The case discussed here is when the server API returns dynamic entities (recommended), not DTOs. Let's look at a contradiction first Jimmer uses dynamic entities. As long as the root entity types are the same, any data structure shape can be expressed with the same Java/Kotlin type. The client needs to see rich data types. The shapes returned by the same entity type in different HTTP interfaces are different. This contradiction is essentially the difference in awareness of DTO Explosion Server perspective is producer perspective. From the producer's point of view, DTO explosion is a very annoying problem, which means that their own development costs will also increase dramatically. Therefore, Jimmer uses dynamic entities combined with object fetchers to eliminate DTO explosions on the server side. Client perspective is consumer perspective. From the consumer's point of view, DTO explosion is beneficial, each business scenario has an accurate return type, which is very nice to use. (Difficult to implement? What does that have to do with me?) Therefore, Jimmer server can automatically generate client code to (such as TypeScript) restore the DTO explosion eliminated on the server side on the client side. tip The server eliminates DTO explosions, and the client restores DTO explosions. This is the fundamental value of Jimmer's automatic sever-client integration, and it is also the essential difference between Jimmer and any other technology that automatically generates client code. Only by letting the server and client use completely different programming models can both sides get the ultimate development experience at the same time.","s":"Solution 3 (Topic of This Article)","u":"/jimmer-doc/docs/client/api","h":"#solution-3-topic-of-this-article","p":131},{"i":142,"t":"Previously we discussed that using Jimmer to build REST services with shapes enumerated by the server is the topic to be discussed in this article. To use this development approach, you need to use the @org.babyfish.jimmer.client.FetchBy annotation to decorate dynamic entity types in REST API return types, to mark specific shapes of dynamic objects for the client. tip @FetchBy does not simply decorate the return value of the REST API, but is used to decorate type references. Its declaration code is as follows package org.babyfish.jimmer.client; import java.lang.annotation.*; @Documented @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.TYPE_USE) public @interface FetchBy { ...omitted... } Therefore, the return type of the REST API is very flexible. You can use it to decorate Jimmer entity types anywhere (including generic parameters), for example @FetchBy(\"...\") Book List<@FetchBy(\"...\") Book> Page<@FetchBy(\"...\") Book> Tuple2<@FetchBy(\"...\") BookStore, @FetchBy(\"...\") Author> Map> Java Kotlin BookController.java @GetMapping(\"/books\") public Page< @FetchBy(\"SIMPLE_FETCHER\") Book ❶ > findBookById( @RequestParam(defaultValue = \"0\") int pageIndex, @RequestParam(defaultValue = \"5\") int pageSize, @RequestParam(defaultValue = \"name asc, edition desc\") String sortCode ) { return bookRepository.findBooks( PageRequest.of(pageIndex, pageSize, SortUtils.toSort(sortCode)), SIMPLE_FETCHER ❷ ); } @GetMapping(\"book/{id}\") @Nullable public @FetchBy(\"COMPLEX_FETCHER\") Book ❸ findComplexBook( @PathVariable(\"id\") long id ) { return bookRepository.findNullable( id, COMPLEX_FETCHER ❹ ); } private static final Fetcher SIMPLE_FETCHER = ❺ Fetchers.BOOK_FETCHER .allScalarFields() .tenant(false); private static final Fetcher COMPLEX_FETCHER = ❻ Fetchers.BOOK_FETCHER .allScalarFields() .tenant(false) .store( Fetchers.BOOK_STORE_FETCHER .allScalarFields() .avgPrice() ) .authors( Fetchers.AUTHOR_FETCHER .allScalarFields() ); BookController.kt @GetMapping(\"/books\") fun findBooks( @RequestParam(defaultValue = \"0\") pageIndex: Int, @RequestParam(defaultValue = \"5\") pageSize: Int, @RequestParam(defaultValue = \"name asc, edition desc\") sortCode: String ): Page< @FetchBy(\"SIMPLE_FETCHER\") Book ❶ > = bookRepository.findBooks( PageRequest.of(pageIndex, pageSize, SortUtils.toSort(sortCode)), name, storeName, authorName, SIMPLE_FETCHER ❷ ) @GetMapping(\"/book/{id}\") fun findBookById( @PathVariable id: Long, ): @FetchBy(\"COMPLEX_FETCHER\") Book? = ❸ bookRepository.findNullable( id, COMPLEX_FETCHER ❹ ) companion object { private val SIMPLE_FETCHER = ❺ newFetcher(Book::class).by { allScalarFields() tenant(false) } private val COMPLEX_FETCHER = ❻ newFetcher(Book::class).by { allScalarFields() tenant(false) store { allScalarFields() avgPrice() } authors { allScalarFields() } } } ❶ Promise externally that the shape of each Book object in the paged object returned by GET /books is expressed by the static constant SIMPLE_FETCHER ❷ Internal implementation, GET /books uses static constant SIMPLE_FETCHER internally to query data caution ❶ as external commitment and ❷ as internal implementation must be consistent ::: ❸ Promise externally that if GET /book/{id} returns non-null, its shape is expressed by the static constant COMPLEX_FETCHER ❹ Internal implementation, GET /book/{id} uses static constant COMPLEX_FETCHER internally to query data caution ❸ as external commitment and ❹ as internal implementation must be consistent ❺ and ❻, declare object shapes as static constants. With the decoration of @FetchBy, Jimmer understands the specific shape of each object's externally returned data, so it can generate code for the client, including TypeScript. info In this example, the class annotated with @FetchBy and the class declaring object shapes with static constants are the same class. If not, you can use the ownerType parameter of @FetchBy, for example @FetchBy(value = \"COMPLEX_FETCHER\", ownerType = FetcherConstants.class)","s":"Declare @FetchBy","u":"/jimmer-doc/docs/client/api","h":"#declare-fetchby","p":131},{"i":144,"t":"The following configuration can be declared in application.yml or application.properties to download related client code jimmer: ...other configurations omitted... client: ts: path: /ts.zip ❶ java-feign: path: /java-feign.zip ❷ Currently, Jimmer supports generating two types of client code, TypeScript and Java Feign Client code required by Spring Cloud ❶ Can download Web client required TypeScript code through http://localhost:8080/ts.zip ❷ Can download Spring Cloud required Java Feign Client code through http://localhost:8080/java-feign.zip Next we discuss the TypeScript code. Start the service, download http://localhost:8080/ts.zip, decompress it. Let the root directory after decompression be ${ts_root}: Let's take a look at ${ts_root}/model/dto/BookDto.ts first BookDto.ts export type BookDto = { 'BookService/SIMPLE_FETCHER': { readonly id: number, readonly name: string, readonly edition: number, readonly price: number, }, 'BookService/COMPLEX_FETCHER': { readonly id: number, readonly name: string, readonly edition: number, readonly price: number, readonly store?: { readonly id: number, readonly name: string, readonly website?: string, readonly avgPrice: number }, readonly authors: ReadonlyArray<{ readonly id: number, readonly firstName: string, readonly lastName: string, readonly gender: Gender }> } } info It is obvious that the DTO explosion eliminated on the server side is restored on the client side. Let's also take a look at ${ts_root}/services/BookService.ts import type { BookDto } from '../model/dto'; import type { Page } from '../model/static'; export class BookService { async findBooks( options: BookServiceOptions['findBooks'] ): Promise< Page< BookDto['BookService/SIMPLE_FETCHER'] > > { ...code omitted... } async findBookById( options: BookServiceOptions['findBookById'] ): Promise< BookDto['BookService/COMPLEX_FETCHER'] | undefined > { ...code omitted... } ...other code omitted... } export type BookServiceOptions = { 'findBooks': { readonly pageIndex: number, readonly pageSize: number, readonly sortCode: string }, 'findBookById': { readonly id: number } } info It is obvious that the return type of each business scenario is accurately defined.","s":"Generate Client Code","u":"/jimmer-doc/docs/client/api","h":"#generate-client-code","p":131},{"i":146,"t":"Create project First create a typescript based react project yarn create react-app my-web-app --template typescript Automatically generate client code Obviously, it is impossible to require client developers to manually download server code, decompress it, and replace local code every time changes occur on the server side. So we need to write a small script to automatically complete the download, decompression and replacement of the latest TypeScript code. Add folder scripts under project root, and add file generate-api.js under it. This file is executed by nodejs and is tooling code for development, not the code of the client itself. scripts/generate-api.js const http = require('http'); const fs = require('fs'); const fse = require('fs-extra'); const uuid = require('uuid'); const tempDir = require('temp-dir'); const AdmZip = require('adm-zip'); const sourceUrl = \"http://localhost:8080/ts.zip\"; const tmpFilePath = tempDir + \"/\" + uuid.v4() + \".zip\"; const generatePath = \"src/__generated\"; console.log(\"Downloading \" + sourceUrl + \"...\"); const tmpFile = fs.createWriteStream(tmpFilePath); const request = http.get(sourceUrl, (response) => { response.pipe(tmpFile); tmpFile.on(\"finish\", () => { tmpFile.close(); console.log(\"File save success: \", tmpFilePath); // Remove generatePath if it exists if (fs.existsSync(generatePath)) { console.log(\"Removing existing generatePath...\"); fse.removeSync(generatePath); console.log(\"Existing generatePath removed.\"); } // Unzip the file using adm-zip console.log(\"Unzipping the file...\"); const zip = new AdmZip(tmpFilePath); zip.extractAllTo(generatePath, true); console.log(\"File unzipped successfully.\"); // Remove the temporary file console.log(\"Removing temporary file...\"); fs.unlink(tmpFilePath, (err) => { if (err) { console.error(\"Error while removing temporary file:\", err); } else { console.log(\"Temporary file removed.\"); } }); }); }); Here, adm-zip needs to be installed separately yarn add adm-zip --dev Modify project's package.json and add the following code under its \"scripts\" field { ...other code omitted... \"scripts\": { ...other code omitted... \"api\": \"node scripts/generate-api.js\" } ...other code omitted... } So every time the server team notifies that REST API changes have occurred, just execute yarn api simply to refresh the local TypeScript client code caution This method is only suitable when the web team is very small in size. If there are many web developers, it is more recommended to implement secondary development on the CI environment to achieve the following: Each time the server code on a specific branch is committed, the CI environment compiles and starts the service, then downloads the ts code, decompresses it, and commits it to git. Finally, web engineers can simply pull the latest code from git. Create Global API Object The generated TypeScript code has a __generated/Api.ts file that needs to be instantiated into a global variable and configured properly. Under src, create ApiInstance.ts and export the global variable api src/ApiInstance.ts import { Api } from \"../__generated\"; const BASE_URL = \"http://localhost:8080\"; // Export global variable `api` export const api = new Api(async({uri, method, body}) => { const response = await fetch(`${BASE_URL}${uri}`, { body: body !== undefined ? JSON.stringify(body) : undefined, headers: { 'content-type': 'application/json;charset=UTF-8', ...other important HTTP headers, e.g. Authorization... } }); if (response.status !== 200) { throw response.json(); } const text = await response.text(); if (text.length === 0) { return null; } return JSON.parse(text); }); Call REST APIs Now we can call REST APIs based on global variable api. info The following examples are based on use-immer and TanStack/Query. Being proficient in or quickly mastering various remote request libraries is the basic literacy of web front-end engineers, so the details are not elaborated here. Experience api.bookService.findBooks const [options, setOptions] = useImmer< // RequestOf is a TypeScript helper class generated by Jimmer, // used to extract parameter types of any REST API RequestOf< typeof api.bookService.findBooks > >(() => { return { pageIndex: 0, pageSize: 10, sortCode: \"name asc\" }; }); const { isLoading, // If `data` is not `undefined`, its type must be // `Page` data, error, refetch } = useQuery({ queryKey: [\"Books\", options], // The type of `data` is determined here queryFn: () => api.bookService.findBooks(options) }); If request succeeds, the type of data is Page. Where BookDto['BookService/SIMPLE_FETCHER'] is defined as { readonly id: number, readonly name: string, readonly edition: number, readonly price: number, } Experience api.bookService.findBookById In the following code, assume id is the current React primary key parameter const { // If `data` is not `undefined`, its type must be // `BookDto['BookService/COMPLEX_FETCHER']` data, isLoading, error } = useQuery({ queryKey: [\"book/detail\", id], queryFn: () => api.bookService.findBookById({id: id!}), enabled: id !== undefined }); If request succeeds and data is not null, its type is BookDto['BookService/COMPLEX_FETCHER']. This type is defined as: { readonly id: number, readonly name: string, readonly edition: number, readonly price: number, readonly store?: { readonly id: number, readonly name: string, readonly website?: string, readonly avgPrice: number }, readonly authors: ReadonlyArray<{ readonly id: number, readonly firstName: string, readonly lastName: string, readonly gender: Gender }> } tip It can be seen that any REST API call will return strict data type definitions, and these strict type definitions will also affect the React UI template code in tsx files. This will give full play to the advantages of TypeScript, providing good IDE intelligence, and ensuring all problems are discovered at compile time, thus having a good development experience.","s":"Develop Web Client Project","u":"/jimmer-doc/docs/client/api","h":"#develop-web-client-project","p":131},{"i":148,"t":"Although @FetchBy combined with Jimmer's dynamic entities can restore DTO type definitions in client code, one situation still needs to be carefully considered: the returned data type differs greatly from the underlying entity model. For example: Java Kotlin ActiveAuthorInfo.java @lombok.Data public class ActiveAuthorInfo { private Author raw; private List stores; } ActiveAuthorInfo.kt data class ActiveAuthorInfo( val raw: Author, val stores: List ) In this example, ActiveAuthorInfo represents a very active author, containing the original information of the author raw, and the collection of all bookstores selling his/her books. The corresponding HTTP service interface is: Java Kotlin AuthorController.java @GetMapping(\"/authors/mostActive\") public List findMostActiveAuthorInfos( @RequestParam(defaultValue = \"10\") int limit ) { ...omitted... } AuthorController.kt @GetMapping(\"/authors/mostActive\") fun findMostActiveAuthorInfos( @RequestParam(defaultValue = \"10\") limit: Int ): List { ...omitted... } Obviously, this data structure differs greatly from the underlying entity model. In the entity model, there is an association between BookStore and Book, and there is also an association between Book and Author, but there is no association between BookStore and Author. tip In some cases, the data required by the client may contain multiple entity objects that have no direct ORM association, but only a certain business-level correlation. If such business-level correlations are not generic at all, then defining complex calculated properties for entities is not a good choice either. At this point, we can break the stereotypical thinking of the entity object graph and use custom data to represent the return results, just like ActiveAuthorInfo here. However, ActiveAuthorInfo is not a purely custom user data type, it mixes the use of Jimmer entities internally. Let's call it a hybrid type. The @FetchBy annotation can be used to decorate the fields of this hybrid type, for example: Java Kotlin ActiveAuthorInfo.java @lombok.Data public class ActiveAuthorInfo { private @FetchBy(\"AUTHOR_FETCHER\") Author raw; private List<@FetchBy(\"STORE_FETCHER\") BookStore> stores; private static final Fetcher AUTHOR_FETCHER = Fetchers.AUTHOR_FETCHER .firstName() .lastName(); private static final Fetcher STORE_FETCHER = Fetchers.AUTHOR_FETCHER.name(); } ActiveAuthorInfo.kt data class ActiveAuthorInfo( val raw: @FetchBy(\"AUTHOR_FETCHER\") Author, val stores: List<@FetchBy(\"STORE_FETCHER\") BookStore> ) { companion object { private val AUTHOR_FETCHER = newFetcher(Author::class) { firstName() lastName() } private val STORE_FETCHER = new Fetcher(BookStore::class) { name() } } } Finally, the TypeScript related types generated for ActiveAuthorInfo are as follows (for convenience, the code of multiple TypeScript files is mixed here): export interface ActiveAuthorInfo { readonly raw: AuthorDto['ActiveAuthorInfo/AUTHOR_FETCHER']; readonly stores: ReadonlyArray< BookStoreDto['ActiveAuthorInfo/STORE_FETCHER'] >; } export type AuthorDto { 'ActiveAuthorInfo/AUTHOR_FETCHER': { readonly id: number, readonly firstName: string, readonly lastName: string }, ...other DTO types omitted... } export type BookStoreDto { 'ActiveAuthorInfo/STORE_FETCHER': { readonly id: number, readonly name: string }, ...other DTO types omitted... }","s":"Integrate with Custom Data","u":"/jimmer-doc/docs/client/api","h":"#integrate-with-custom-data","p":131},{"i":150,"t":"This configuration is explained in Cache Section/Multiview Cache/Cache Abandoned Reason. Therefore, this article will not repeat the explanation, it just serves as a link reference.","s":"Cache Abandoned Reason","u":"/jimmer-doc/docs/configuration/cache-abandoned","h":"","p":149},{"i":153,"t":"Admittedly, Jimmer's strongly typed SQL DSL can expose problems as much as possible at compile time, and most errors can be prevented before testing. But this is not enough. The strongly typed SQL DSL can only improve the reliability of the entity model -> business code link, but cannot guarantee the reliability of the database structure -> entity model link. There is also a derived problem. If developers get reliable applications in the test environment, how to ensure that the application remains reliable after being transplanted to the production environment? Database validation is a very important feature that is used to verify the consistency between the database structure and the entity model definition. info Validation Rules Verify that table names, column names, sequence names are consistent with definitions in the entity model. Verify that the nullity of columns is consistent with the definitions of properties in the entity model. If a property is decorated with @OneToOne(inputNotNull = true) or @ManyToOne(inputNotNull = true), the nullity of the property itself is ignored. it is considered that the corresponding foreign key in the data cannot be null. For the id property of each entity in the entity model, verify that the database has a primary key constraint that exactly matches. For true foreign keys defined in the entity model (see True and False Foreign Keys), verify that the database has exactly matching foreign key constraints.","s":"Function Introduction","u":"/jimmer-doc/docs/configuration/database-validation","h":"#function-introduction","p":151},{"i":155,"t":"There are two ways to start validation: Use Spring Boot Starter Modify application.yml (or application.properties) jimmer: database-validation-mode: ERROR Use underlying API Java Kotlin JSqlClient sqlClient = JSqlClient .newBuilder() .setDatabaseValidationMode( DatabaseValidationMode.ERROR ) ...Omit other configurations... .build(); val sqlClient = newKSqlClient { setDatabaseValidationMode( DatabaseValidationMode.ERROR ) ...Omit other configurations... } DatabaseValidationMode is an enum type with three values: NONE: Don't validate database structure, this is the default behavior. WARNING: Validate database structure, if the database structure is inconsistent with the entity model definition, it does not prevent the program from running, just prints warning information in the log. ERROR: Validate database structure, if the database structure is inconsistent with the entity model definition, an exception will be thrown to prevent the program from running.","s":"Enable Validation","u":"/jimmer-doc/docs/configuration/database-validation","h":"#enable-validation","p":151},{"i":157,"t":"Entity types must correspond to a table in the database, whether the table name is explicitly configured by the developer via @Table or automatically determined by the naming strategy. Association properties based on join tables must correspond to a real join table in the database, whether the table name is explicitly configured by the developer via @JoinTable or automatically determined by the naming strategy. The ID whose auto growth strategy is SEQUENCE must correspond to a sequence in the database, whether the sequence name is explicitly configured by the developer via @GeneratedValue or automatically determined by the naming strategy . When the program starts, Jimmer needs to query the database metadata to verify whether these tables or sequences exist. And if they exist, whether their internal structures are correct (for tables). However, since database often support multiple sub-databases, and sub-databases can authorize each other, the JDBC connection may see tables with the same name in different database users, such as db1.BOOK, db2.BOOK, and db3.BOOK. This is called table conflict. Of course, Jimmer can extract the database name from the JDBC connection metadata, for example, extract \"db1\" from jdbc:mysql://localhost:3306/db1, and first look for table information in the automatically extracted sub-database for verification. However, this method is not always valid. As long as the specified table cannot be found in the current sub-database, it will look for it in other sub-databases, which may lead to table conflict issues. To solve this problem, the following two methods are available: Specify strict table names or sequence names, for example: Change @Table(name = \"BOOK\") to @Table(name = \"db1.BOOK\"). Change @JoinTable(name = \"BOOK_AUTHOR_MAPPING\") to @JoinTable(name = \"db1.BOOK_AUTHOR_MAPPING\"). Change @GeneratedValue(sequenceName = \"BOOK_ID_SEQ\") to @GeneratedValue(sequenceName = \"db1.BOOK_ID_SEQ\"). Explicitly specify the sub-database name used for validation, which can be divided into two methods: There are two ways to start validation Use Spring Boot Starter Modify application.yml (or application.properties) jimmer: database-validation: mode: ERROR catalog: db1 info jimmer.database-validation-mode and jimmer.database-validation.mode are equivalent Use underlying API Java Kotlin JSqlClient sqlClient = JSqlClient .newBuilder() .setDatabaseValidationMode( DatabaseValidationMode.ERROR ) .setDatabaseValidationCatalog(\"db1\") ...Omit other configurations... .build(); val sqlClient = newKSqlClient { setDatabaseValidationMode( DatabaseValidationMode.ERROR ) setDatabaseValidationCatalog(\"db1\") ...Omit other configurations... } Similarly, schema can also be specified, for example: Direct configuration: @Table(name = \"mydatabase.myschema.BOOK\") Configure in SpringBoot's application.yml file jimmer: database-validation: mode: ERROR catalog: mydatabase schema: myschema Underlying API configuration Java Kotlin JSqlClient sqlClient = JSqlClient .newBuilder() .setDatabaseValidationMode( DatabaseValidationMode.ERROR ) .setDatabaseValidationCatalog(\"mydatabase\") setDatabaseValidationSchema(\"myschema\") ...Omit other configurations... .build(); val sqlClient = newKSqlClient { setDatabaseValidationMode( DatabaseValidationMode.ERROR ) setDatabaseValidationCatalog(\"mydatabase\") setDatabaseValidationSchema(\"myschema\") ...Omit other configurations... }","s":"Resolve Table Conflicts","u":"/jimmer-doc/docs/configuration/database-validation","h":"#resolve-table-conflicts","p":151},{"i":159,"t":"Sometimes developers are developing a new feature that is incomplete and cannot be verified. Developers will naturally not run unfinished features and expect unfinished parts not to verify the database structure. For this, Jimmer provides the annotation @org.babyfish.jimmer.sql.DatabaseValidationIgnore. This annotation has the following two usages: Annotate entity interfaces to indicate that the entire entity does not need to be verified. Annotate entity properties to indicate that specific properties do not need to be verified.","s":"Temporarily ignore partial validation","u":"/jimmer-doc/docs/configuration/database-validation","h":"#temporarily-ignore-partial-validation","p":151},{"i":161,"t":"This configuration is explained in Mapping Section/Base Mapping/Naming Strategy. Therefore, this article will not repeat the explanation, it just serves as a link reference.","s":"Default Naming Strategy","u":"/jimmer-doc/docs/configuration/default-database-stragegy","h":"","p":160},{"i":163,"t":"This configuration is explained in Mapping Section/Advanced Mapping/Enum Mapping/Don't explicitly use @EnumType. Therefore, this article will not repeat the explanation, it just serves as a link reference.","s":"Default Enum Strategy","u":"/jimmer-doc/docs/configuration/default-enum-strategy","h":"","p":162},{"i":165,"t":"Different databases have vastly different SQL support, so Jimmer uses dialect configuration to adapt to different databases.","s":"Dialect","u":"/jimmer-doc/docs/configuration/dialect","h":"","p":164},{"i":167,"t":"If using the Spring Boot Starter provided by Jimmer, there are two ways: Configure application.yml or application.properties jimmer: dialect: org.babyfish.jimmer.sql.dialect.MySqlDialect Provide global dialect Bean Java Kotlin @Bean public Dialect dialect() { return new MySqlDialect(); } @Bean fun dialect(): Dialect = MySqlDialect() info If both methods above are used (not recommended), the second method takes precedence If not using the Spring Boot Starter provided by Jimmer Java Kotlin JSqlClient sqlClient = JSqlClient .newBuilder() .setDialect(new MySqlDialect()) ...Omit other configurations... .build(); val sqlClient = newKSqlClient { setDialect(MySqlDialect()) ...Omit other configurations... }","s":"Set Dialect","u":"/jimmer-doc/docs/configuration/dialect","h":"#set-dialect","p":164},{"i":169,"t":"org.babyfish.jimmer.sql.dialect.DefaultDialect This is the default dialect used by Jimmer when no dialect is specified, so there is no need to specify it explicitly. warning The default configuration can only be used for learning simple demos in the initial stage, and can never be used in actual projects. The following situations will cause exceptions: Operations on Jimmer in the code will generate SQL that depends on specific database products, rather than perfect cross-database SQL When the type of trigger is set to TRANSACTION_ONLY and cache is used, Jimmer will automatically create the JIMMER_TRANS_CACHE_OPERATOR table at startup. DefaultDialect does not support this operation, please refer to Cache Consistency org.babyfish.jimmer.sql.dialect.H2Dialect org.babyfish.jimmer.sql.dialect.MySql5Dialect org.babyfish.jimmer.sql.dialect.MySqlDialect org.babyfish.jimmer.sql.dialect.PostgresDialect org.babyfish.jimmer.sql.dialect.OracleDialect org.babyfish.jimmer.sql.dialect.TiDBDialect org.babyfish.jimmer.sql.dialect.SQLiteDialect Because TiDB is a distributed database that does not support foreign key constraints, true foreign keys are not supported by this dialect. Please refer to True and False Foreign Keys Apart from this, TiDBDialect has no difference with MySqlDialect. For other databases, users can extend dialects by themselves. But the database needs to support multi-column in expressions, such as where (a, b) in ((3, 4), (8, 13)) Or where (a, b) in (select x, y from ...) note Currently, multi-column in expressions are highly dependent features of Jimmer, and Microsoft Sql Server does not support this feature for the time being. So Microsoft Sql Server is not supported for now.","s":"Dialect List","u":"/jimmer-doc/docs/configuration/dialect","h":"#dialect-list","p":164},{"i":172,"t":"In Jimmer, all executable statements and instructions support two execution modes: Execute based on the JDBC connection specified by the user Executed by Jimmer automatically determining based on a JDBC connection Here, take Executable (Java) or KExecutable (Kotlin) interface as an example Java Kotlin Executable.java package org.babyfish.jimmer.sql.ast; import java.sql.Connection; public interface Executable { R execute(); R execute(Connection con); } KExecutable.kt package org.babyfish.jimmer.sql.kt import java.sql.Connection interface KExecutable { fun execute(con: Connection? = null): R } execute(Connection): Execute on the JDBC connection specified by the user. Take query as an example: Java Kotlin BookTable book = Tables.BOOK_TABLE; List books = sqlClient .createQuery(book) .select(book) .execute(con); val books = sqlClient .createQuery(Book::class) { select(table) } .execute(con) info For this usage, no special configuration of SqlClient is required. execute() or execute(null): Determined by Jimmer to execute on a JDBC connection. Take query as an example: Java Kotlin BookTable book = Tables.BOOK_TABLE; List books = sqlClient .createQuery(book) .select(book) .execute(); val books = sqlClient .createQuery(Book::class) { select(table) } .execute() info For this usage, ConnectionManager must be configured for SqlClient. Otherwise it will cause exceptions. Undoubtedly, the 2nd approach is more in line with the requirements of business system development, so it is recommended. So it is strongly recommended to configure ConnectionManager for SqlClient.","s":"Concept","u":"/jimmer-doc/docs/configuration/connection-manager","h":"#concept","p":170},{"i":174,"t":"Java Kotlin javax.sql.DataSource dataSource = ...; JSqlClient sqlClient = JSqlClient .newBuilder() .setConnectionManager( ConnectionManager .simpleConnectionManager(dataSource) ) .build(); val dataSource: javax.sql.DataSource = ... val sqlClient = newKSqlClient { setConnectionManager { dataSource.connection.use { proceed(it) } } } danger This way is only responsible for getting connections from DataSource and has no transaction management mechanism. However, transactions are very important in actual projects. Therefore, except for learning and trying, it is not recommended to use this approach in actual projects.","s":"Simple ConnectionManager","u":"/jimmer-doc/docs/configuration/connection-manager","h":"#simple-connectionmanager","p":170},{"i":176,"t":"This topic has been discussed in detail in Spring Section/Integrate Spring Transaction. This article will not repeat the explanation. tip Letting Jimmer be managed by Spring transaction is the recommended usage.","s":"ConnectionManager managed by Spring transaction","u":"/jimmer-doc/docs/configuration/connection-manager","h":"#connectionmanager-managed-by-spring-transaction","p":170},{"i":178,"t":"This configuration is explained in Mutation Section/Save Command/Enum Mapping/Associated Id Checking. Therefore, this article will not repeat the explanation, it just serves as a link reference.","s":"Associated Id Checking","u":"/jimmer-doc/docs/configuration/id-only-target-checking-level","h":"","p":177},{"i":180,"t":"In the OnDissociate article, we know there are 5 dissociation modes: NONE (default) LAX CHECK SET_NULL DELETE For pseudo foreign key (please refer to Real and Fake Foreign Keys) associative properties, when its dissociation mode is NONE: If the global configuration jimmer.default-dissociation-action-checkable is true (default), it is equivalent to CHECK. If the global configuration jimmer.default-dissociation-action-checkable is false, it is equivalent to NONE.","s":"Default Dissociation Mode","u":"/jimmer-doc/docs/configuration/dissociate-action-checking","h":"","p":179},{"i":182,"t":"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, this article will not repeat it.","s":"In List Predicate Optimization","u":"/jimmer-doc/docs/configuration/in-list-optimization","h":"","p":181},{"i":184,"t":"Two ways to enable: If you are using the Jimmer Spring Boot Starter, modify application.yml (or application.properties) as follows: application.yml jimmer: 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: Java Kotlin JSqlClient sqlClient = JSqlClient .newBuilder() .setInListPaddingEnabled(true) // ...omitted other configurations... .build(); val sqlClient = newKSqlClient { setInListPaddingEnabled(true) // ...omitted other configurations... }","s":"Enable Padding Optimization","u":"/jimmer-doc/docs/configuration/in-list-optimization","h":"#enable-padding-optimization","p":181},{"i":186,"t":"Two ways to enable: If you are using the Jimmer Spring Boot Starter, modify application.yml (or application.properties) as follows: application.yml jimmer: 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: Java Kotlin JSqlClient sqlClient = JSqlClient .newBuilder() .setInListToAnyEqualityEnabled(true) // ...omitted other configurations... .build(); val sqlClient = newKSqlClient { setInListToAnyEqualityEnabled(true) // ...omitted other configurations... }","s":"Enable Any Equality Optimization","u":"/jimmer-doc/docs/configuration/in-list-optimization","h":"#enable-any-equality-optimization","p":181},{"i":188,"t":"This configuration is explained in Spring Section/SpringCloud and Remote Association/Enable Jimmer to Support Microservices. Therefore, this article will not repeat the explanation, it just serves as a link reference.","s":"Microservice","u":"/jimmer-doc/docs/configuration/micro-service","h":"","p":187},{"i":190,"t":"This configuration is explained in Mutation Section/Save Command/Pessimistic Lock. Therefore, this article will not repeat the explanation, it just serves as a link reference.","s":"Pessimistic Lock","u":"/jimmer-doc/docs/configuration/save-command-pessimistic-lock","h":"","p":189},{"i":192,"t":"This part is actually unrelated to ORM. However, since generate client api is provided, this part of the functionality must also be provided to make it a complete solution.","s":"Generate Client Errors","u":"/jimmer-doc/docs/client/error","h":"","p":191},{"i":194,"t":"We need to define special Java/Kotlin business exceptions that can be directly translated into data that the client can understand. How do we define this special type of business exception? There are two extreme choices: Share one business exception class across the entire application, with built-in error codes that the client can understand Define a business exception class for each business error Obviously, both of the above solutions are unsuitable. The first option is too coarse-grained, with globally maintained error codes that are difficult to maintain. The second option is too fine-grained, requiring the definition of too many exception classes. So, Jimmer chooses a compromise: dividing business exceptions into multiple families, with each family using one set of Error Codes. Jimmer uses enums to define exception families, where the enum also serves as the error code for that family, e.g.","s":"Exception Families","u":"/jimmer-doc/docs/client/error","h":"#exception-families","p":191},{"i":196,"t":"Java Kotlin UserInfoErrorCode.java package com.example.business.error; import org.babyfish.jimmer.error.ErrorFamily; @ErrorFamily public enum UserInfoErrorCode { ILLEGAL_USER_NAME, PASSWORD_TOO_SHORT, PASSWORDS_NOT_SAME } UserInfoErrorCode.kt package com.example.business.error import org.babyfish.jimmer.error.ErrorFamily @ErrorFamily enum class UserInfoErrorCode { ILLEGAL_USER_NAME, PASSWORD_TOO_SHORT, PASSWORDS_NOT_SAME } The @org.babyfish.jimmer.error.ErrorFamily annotation indicates that this enum represents a family of business exceptions, and the enum itself serves as the error code for this family. The @ErrorFamily annotation will be processed by Jimmer's precompiler info Here, the precompiler refers to Annotation Processor for Java, and KSP for Kotlin. This part of the code has been discussed in Overview/Get Started/Generate Code, so it won't be repeated here. The precompiler will generate the following exception class based on this enum: info For enums used to declare exception families, you can choose to use ErrorCode or Error as a special suffix. If there is such a special suffix, the exception class name = enum name without the suffix + Exception Otherwise, exception class name = enum name + Exception So here the generated exception name is UserInfoException After compilation by Jimmer, the following exception class will be generated. Java Kotlin UserInfoException.java public abstract class UserInfoException extends CodeBasedException { ❶ private UserInfoException(String message, Throwable cause) { super(message, cause); } @Override public abstract UserInfoErrorCode getCode(); ❷ public static UserInfoException illegalUserName(@NotNull String message) { ❸ return new IllegalUserName( message, null ); } public static UserInfoException illegalUserName( ❹ @NotNull String message, @Nullable Throwable cause ) { return new IllegalUserName( message, cause ); } public static UserInfoException passwordTooShort(@NotNull String message) { ❺ return new PasswordTooShort( message, null ); } public static UserInfoException passwordTooShort( ❻ @NotNull String message, @Nullable Throwable cause ) { return new PasswordTooShort( message, cause ); } public static UserInfoException passwordsNotSame(@NotNull String message) { ❼ return new PasswordsNotSame( message, null ); } public static UserInfoException passwordsNotSame( ❽ @NotNull String message, @Nullable Throwable cause ) { return new PasswordsNotSame( message, cause ); } public static class IllegalUserName extends UserInfoException { public IllegalUserName(String message, Throwable cause) { super(message, cause); } @Override public UserInfoErrorCode getCode() { return UserInfoErrorCode.ILLEGAL_USER_NAME; ❾ } @Override public Map getFields() { return Collections.emptyMap(); } } public static class PasswordTooShort extends UserInfoException { public PasswordTooShort(String message, Throwable cause) { super(message, cause); } @Override public UserInfoErrorCode getCode() { return UserInfoErrorCode.PASSWORD_TOO_SHORT; ❿ } @Override public Map getFields() { return Collections.emptyMap(); } } public static class PasswordsNotSame extends UserInfoException { public PasswordsNotSame(String message, Throwable cause) { super(message, cause); } @Override public UserInfoErrorCode getCode() { return UserInfoErrorCode.PASSWORDS_NOT_SAME; ⓫ } @Override public Map getFields() { return Collections.emptyMap(); } } } UserInfoException.kt public abstract class UserInfoException private constructor( message: String, cause: Throwable? = null, ) : CodeBasedException(message, cause) { ❶ public abstract override val code: UserInfoErrorCode ❷ public companion object { @JvmStatic public fun illegalUserName( ❸❹ message: String, cause: Throwable? = null ): UserInfoException = IllegalUserName( message, cause ) @JvmStatic public fun passwordTooShort( ❺❻ message: String, cause: Throwable? = null ): UserInfoException = PasswordTooShort( message, cause ) @JvmStatic public fun passwordsNotSame( ❼❽ message: String, cause: Throwable? = null ): UserInfoException = PasswordsNotSame( message, cause ) } public class IllegalUserName( message: String, cause: Throwable? = null, ) : UserInfoException(message, cause) { public override val code: UserInfoErrorCode get() = UserInfoErrorCode.ILLEGAL_USER_NAME ❾ public override val fields: Map get() = emptyMap() } public class PasswordTooShort( message: String, cause: Throwable? = null, ) : UserInfoException(message, cause) { public override val code: UserInfoErrorCode get() = UserInfoErrorCode.PASSWORD_TOO_SHORT ❿ public override val fields: Map get() = emptyMap() } public class PasswordsNotSame( message: String, cause: Throwable? = null, ) : UserInfoException(message, cause) { public override val code: UserInfoErrorCode get() = UserInfoErrorCode.PASSWORDS_NOT_SAME ⓫ public override val fields: Map get() = emptyMap() } } ❶ Exceptions based on enum error codes must inherit from org.babyfish.jimmer.error.CodeBasedException ❷ The error code type for this family of exceptions is UserInfoErrorCode ❸❹ Static method to construct exception with error code ILLEGAL_USER_NAME ❺❻ Static method to construct exception with error code PASSWORD_TOO_SHORT ❼❽ Static method to construct exception with error code PASSWORDS_NOT_SAME ❾ Exception class UserInfoException.IllegalUserName has error code ILLEGAL_USER_NAME ❿ Exception class UserInfoException.PasswordTooShort has error code PASSWORD_TOO_SHORT ⓫ Exception class UserInfoException.PasswordsNotSame has error code PASSWORDS_NOT_SAME","s":"Define Exception Families","u":"/jimmer-doc/docs/client/error","h":"#define-exception-families","p":191},{"i":198,"t":"Additional fields can be added to any error code. For example, ILLEGAL_USER_NAME indicates an illegal username, i.e. the username contains illegal characters. We can add the field illegalChars for it. Java Kotlin UserInfoErrorCode.java @ErrorFamily public enum UserInfoErrorCode { @ErrorField(name = \"illegalChars\", type = Character.class, list = true) ILLEGAL_USER_NAME, PASSWORD_TOO_SHORT, PASSWORDS_NOT_SAME } UserInfoErrorCode.kt @ErrorFamily enum class UserInfoErrorCode { @ErrorField(name = \"illegalChars\", type = Char::class, list = true) ILLEGAL_USER_NAME, PASSWORD_TOO_SHORT, PASSWORDS_NOT_SAME } The generated code is as follows: Java Kotlin UserInfoException.java public abstract class UserInfoException extends CodeBasedException { public static UserInfoException illegalUserName( @NotNull String message, @NotNull List illegalChars ) { ...omit code... } public static UserInfoException illegalUserName( @NotNull String message, @Nullable Throwable cause, @NotNull List illegalChars ) { ...omit code... } public static class IllegalUserName extends UserInfoException { @NotNull private final List illegalChars; public IllegalUserName( String message, Throwable cause, @NotNull List illegalChars ) { super(message, cause); this.illegalChars = illegalChars; } @Override public Map getFields() { return Collections.singletonMap(\"illegalChars\", illegalChars); } @NotNull public List getIllegalChars() { return illegalChars; } ...omit other code... } ...omit other code... } UserInfoException.kt public abstract class UserInfoException private constructor( message: String, cause: Throwable? = null, ) : CodeBasedException(message, cause) { ❶ public abstract override val code: UserInfoErrorCode ❷ public companion object { @JvmStatic public fun illegalUserName( message: String, cause: Throwable? = null, illegalChars: List, ): UserInfoException = ...omit code... ...omit other code... } public class IllegalUserName( message: String, cause: Throwable? = null, public val illegalChars: List, ) : UserInfoException(message, cause) { public override val fields: Map get() = mapOf( \"illegalChars\" to illegalChars ) ...omit other code... } }","s":"Add Fields to Error Codes","u":"/jimmer-doc/docs/client/error","h":"#add-fields-to-error-codes","p":191},{"i":201,"t":"Java Kotlin UserController.java package com.example.service; import org.babyfish.jimmer.client.ThrowsAll; @PostMapping(\"/user\") @ThrowsAll(UserInfoErrorCode.class) public void registerUser(@RequestBody RegisterUserInput input) { ...omit code... } UserController.kt package com.example.service import import org.babyfish.jimmer.client.ThrowsAll @PostMapping(\"/user\") @ThrowsAll(UserInfoErrorCode::class) fun registerUser(@RequestBody input: RegisterUserInput) { ...omit code... } info The @org.babyfish.jimmer.client.ThrowsAll annotation allows the REST API to throw all exceptions in the family.","s":"Allow To Throw All Exceptions Of Family","u":"/jimmer-doc/docs/client/error","h":"#allow-to-throw-all-exceptions-of-family","p":191},{"i":203,"t":"Let's locate another business exception family: Java Kotlin PlatformErrorCode.java @ErrorFamily public enum PlatformErrorCode { PERMISSION_DENIED, DATA_IS_FROZEN, SERVICE_IS_SUSPENDED, } PlatformErrorCode.kt @ErrorFamily enum class PlatformErrorCode { PERMISSION_DENIED, DATA_IS_FROZEN, SERVICE_IS_SUSPENDED } To be able to declare that a REST API can only throw some of the exceptions in this family, define the following annotation: Java Kotlin ThrowsPlatformError.java @Documented @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) public @interface ThrowsPlatformError { PlatformErrorCode[] value(); } ThrowsPlatformError.kt @Retention(AnnotationRetention.RUNTIME) @Target(AnnotationTarget.FUNCTION) annotation class ThrowsPlatformError( val value: Array ) This annotation satisfies the following 5 conditions: Retention is configured as RUNTIME, i.e. reflectable at runtime Target is configured as METHOD or FUNCTION (kotlin), can be used to decorate methods Has a property named value The value property is of array type The array element type of value is an enum decorated with @ErrorFamily. tip If an annotation satisfies all the above conditions, it can be used to decorate REST APIs to declare the exceptions that can be thrown. Just like how we use @ThrowsAll. Java Kotlin UserController.java @PostMapping(\"/user\") @ThrowsAll(UserInfoErrorCode.class) @ThrowsPlatformError({PlatformErrorCode.SERVICE_IS_SUSPENDED}) public void registerUser(@RequestBody RegisterUserInput input) { ...omit code... } UserController.kt @PostMapping(\"/user\") @ThrowsAll(UserInfoErrorCode::class) @ThrowsPlatformError([PlatformErrorCode.SERVICE_IS_SUSPENDED]) fun registerUser(@RequestBody input: RegisterUserInput) { ...omit code... }","s":"Allow To Throw Some Exceptions Of Family","u":"/jimmer-doc/docs/client/error","h":"#allow-to-throw-some-exceptions-of-family","p":191},{"i":206,"t":"Java Kotlin UserController.java @PostMapping(\"/user\") @ThrowsAll(UserInfoErrorCode.class) @ThrowsPlatformError({PlatformErrorCode.SERVICE_IS_SUSPENDED}) public void registerUser(@RequestBody RegisterUserInput input) { if (...some condition...) { throw PlatformException.serviceIsSuspended( \"The service is suspended\" ); } ...omit other code... } UserController.kt @PostMapping(\"/user\") @ThrowsAll(UserInfoErrorCode::class) @ThrowsPlatformError([PlatformErrorCode.SERVICE_IS_SUSPENDED]) fun registerUser(@RequestBody input: RegisterUserInput) { if (...some condition...) { throw PlatformException.serviceIsSuspended( \"The service is suspended\" ) } ...omit other code... } caution The kinds of exceptions thrown internally must not exceed those declared externally.","s":"Throw Exceptions","u":"/jimmer-doc/docs/client/error","h":"#throw-exceptions","p":191},{"i":208,"t":"tip As long as Jimmer's Spring Boot Starter is used, no extra work is required. Any exception inherited from CodeBasedException thrown by the service will be automatically translated. The translation result is: { \"family\":\"USER_INFO_ERROR_CODE\", \"code\":\"ILLEGAL_USER_NAME\", \"illegalChars\": [\"&\", \"`\", \"@\"] } To facilitate development and testing, you can configure in application.yml or application.properties: jimmer: error-translator: debug-info-supported: true This configuration will include information useful for locating issues during development and testing in the HTTP response. Since the content is quite long, please click the button below to view the result. View Result warning This configuration is only for assisting development and testing, and must NOT be enabled in production environments! For example, enable this switch in application-dev.yml and application-test.yml, but absolutely do NOT enable it in application-prod.yml.","s":"Write Exception Messages to HTTP Responses","u":"/jimmer-doc/docs/client/error","h":"#write-exception-messages-to-http-responses","p":191},{"i":211,"t":"export type AllErrors = ❶ { readonly family: \"PLATFORM_ERROR_CODE\", ❷ readonly code: \"SERVICE_IS_SUSPENDED\" ❸ } | { readonly family: \"USER_INFO_ERROR_CODE\", readonly code: \"ILLEGAL_USER_NAME\", readonly \"illegalChars\": ReadonlyArray ❹ } | { readonly family: \"USER_INFO_ERROR_CODE\", readonly code: \"PASSWORDS_NOT_SAME\" } | { readonly family: \"USER_INFO_ERROR_CODE\", readonly code: \"PASSWORD_TOO_SHORT\" } | ...omit other code... ; export type ApiErrors = { ❺ \"userController\": { ❻ \"registerUser\": AllErrors & ( ❼ { readonly family: 'USER_INFO_ERROR_CODE', readonly code: 'ILLEGAL_USER_NAME', readonly [key:string]: any } | { readonly family: 'USER_INFO_ERROR_CODE', readonly code: 'PASSWORD_TOO_SHORT', readonly [key:string]: any } | { readonly family: 'USER_INFO_ERROR_CODE', readonly code: 'PASSWORDS_NOT_SAME', readonly [key:string]: any } | { readonly family: 'PLATFORM_ERROR_CODE', readonly code: 'SERVICE_IS_SUSPENDED', readonly [key:string]: any } ), ...omit other code... }, \"bookController\": { ...omit code... }, ...omit other code... }; ❶ AllErrors defines all error types caution Only REST APIs that explicitly declare exceptions that may be thrown via annotations in Java/Kotlin code will be used to generate TypeScript code. For example, in the Java/Kotlin code above, we defined the error codes PlatformError.PERMISSION_DENIED and PlatformErrorCode.DATA_IS_FROZEN, but they have not yet been declared as throwable by any REST API using @ThrowsAll or custom @ThrowsPlatformError. So they will not be defined in AllErrors. ❷ The enum name decorated with @ErrorFamily is the family field in client code, used to identify which family the error belongs to ❸ The enum variable name is the code field in client code, used to identify which specific error it is ❹ The server uses @ErrorField (can repeat) to declare arbitrary additional fields for an error code (only one here), so all additional fields are generated here tip ❶ AllErrors defines all errors, never duplicated. ApiErrors at ❺ refers to errors, may have duplicates. Because different REST APIs may declare throwing the same error code. So additional fields are always declared in AllErrors, not in ApiErrors. This is the fundamental reason AllErrors and ApiErrors are separated. ❺ Errors that each REST API may throw ❻ Errors that userController module may throw ❼ Errors that userController.registerUser API may throw","s":"Generated TypeScript Code","u":"/jimmer-doc/docs/client/error","h":"#generated-typescript-code","p":191},{"i":213,"t":"The above TypeScript code is quite lengthy, and considering some readers may not have TypeScript background knowledge, here are some IDE auto-complete screenshots: Under global type ApiErrors, there are two options: userController and bookController ApiErrors[\"userController\"] has three options: login, logout and registerUser For ApiErrors[\"userController\"][\"registerUser\"], the family field has two options: USER_INFO_ERROR_CODE and PLATFORM_ERROR_CODE Once family is determined as UserInfoErrorCode, the code field has three options: ILLEGAL_USER_NAME, PASSWORD_TOO_SHORT and PASSWORDS_NOT_SAME Once code is determined as ILLEGAL_USER_NAME, the additional illegalChars field can be used","s":"TypeScript IDE Effects","u":"/jimmer-doc/docs/client/error","h":"#typescript-ide-effects","p":191},{"i":215,"t":"In Jimmer, each data source corresponds to a sqlClient object (whose type is JSqlClient or KSqlClient). For the most classic single data source case, one sqlClient object is sufficient. Even the Jimmer Spring Boot Starter can automatically create a single sqlClient object. For multiple data sources, developers need to manually create multiple sqlClient objects. For the Jimmer Spring Boot Starter, the support for multiple data sources falls into two cases: Distributed Transaction Mode Local Transaction Mode","s":"Multiple DataSources","u":"/jimmer-doc/docs/configuration/multi-datasources","h":"","p":214},{"i":217,"t":"Here, distributed transactions refer to using Spring's support for JTA transactions. In this mode, simply create multiple sqlClient objects. Java Kotlin import org.springframework.beans.factory.annotation.Qualifier; import org.babyfish.jimmer.spring.SpringClients; @configuration public class SqlClientConfig { @Bean public JSqlClient sqlClient1( ApplicationContext ctx, @Qualifier(\"ds1\") DataSource dataSource ) { return SqlClients.java(ctx, dataSource, null); } @Bean public JSqlClient sqlClient2( ApplicationContext ctx, @Qualifier(\"ds2\") DataSource dataSource ) { return SqlClients.java(ctx, dataSource, null); } } import org.springframework.beans.factory.annotation.Qualifier import org.babyfish.jimmer.spring.SpringClients @configuration class SqlClientConfig { @Bean public fun sqlClient1( ctx: ApplicationContext, @Qualifier(\"ds1\") dataSource: DataSource ): KSqlClient = SqlClients.kotlin(ctx, dataSource) @Bean public fun sqlClient2( ctx: ApplicationContext, @Qualifier(\"ds2\") dataSource: DataSource ): KSqlClient = SqlClients.kotlin(ctx, dataSource) } Then, developers can freely use any of the sqlClient objects. Even if two data sources are operated within a transaction, the JTA transaction will ensure consistency between them.","s":"Distributed Transaction Mode","u":"/jimmer-doc/docs/configuration/multi-datasources","h":"#distributed-transaction-mode","p":214},{"i":219,"t":"Local transactions are slightly different, let's first look at the code: Java Kotlin import org.springframework.beans.factory.annotation.Qualifier; import org.springframework.transaction.support.PlatformTransactionManager; import org.babyfish.jimmer.spring.SpringClients; import org.babyfish.jimmer.spring.transaction.JimmerTransactionManager; import org.babyfish.jimmer.spring.transaction.TransactionalSqlClients; @configuration public class SqlClientConfig { @Bean public PlatformTransactionManager tm1( ❶ ApplicationContext ctx, @Qualifier(\"ds1\") DataSource dataSource ) { return new JimmerTransactionManager( SqlClients.java(ctx, dataSource, null) ); } @Bean public PlatformTransactionManager tm2( ❷ ApplicationContext ctx, @Qualifier(\"ds2\") DataSource dataSource ) { return new JimmerTransactionManager( SqlClients.java(ctx, dataSource, null) ); } @Bean public JSqlClient sqlClient() { ❸ return TransactionalSqlClients.java(); } } import org.springframework.beans.factory.annotation.Qualifier import org.springframework.transaction.support.PlatformTransactionManager import org.babyfish.jimmer.spring.SpringClients import org.babyfish.jimmer.spring.transaction.JimmerTransactionManager import org.babyfish.jimmer.spring.transaction.TransactionalSqlClients @configuration public class SqlClientConfig { @Bean fun tm1( ctx: ApplicationContext, @Qualifier(\"ds1\") dataSource: DataSource ): PlatformTransactionManager = ❶ JimmerTransactionManager( SqlClients.kotlin(ctx, dataSource, null) ) @Bean fun tm2( ctx: ApplicationContext, @Qualifier(\"ds2\") dataSource: DataSource ): PlatformTransactionManager = ❷ JimmerTransactionManager( SqlClients.kotlin(ctx, dataSource, null) ) @Bean public JSqlClient sqlClient() = ❸ TransactionalSqlClients.kotlin() } ❶ Create the first transaction manager based on the first DataSource, note that: The transaction manager type is org.babyfish.jimmer.spring.transaction.JimmerTransactionManager. Although the internal code creates a sqlClient object, it is not exposed to the Spring context, but is held and hidden by the transaction manager. ❷ Create the second transaction manager based on the second DataSource, same as ❶, no need to repeat. ❸ Create a sqlClient proxy and expose it to the Spring context for developers to inject and use. For any business method that needs to operate Jimmer, the annotation @Transactional(\"tm1\") or @Transactional(\"tm2\") must be used, so that Jimmer can be told which JimmerTransactionManager the current business method is using. Otherwise, using the ❸ sqlClient proxy will result in the following exception: The transactional sql client is used, however, there is no AOP transaction, or the transaction manager is not \"org.babyfish.jimmer.spring.transaction.JimmerTransactionManager\" Once Jimmer understands that the current thread is using one of the transaction managers from ❶ and ❷, the ❸ sqlClient proxy will use the internal sqlClient of the corresponding JimmerTransactionManager from ❶ or ❷ to provide services for the user. That is, in the local transaction mode, although multiple sqlClient objects can be created, the business method must explicitly specify which data source to use through the Spring annotation @Transactional(transactionManagerRef).","s":"Local Transaction Mode","u":"/jimmer-doc/docs/configuration/multi-datasources","h":"#local-transaction-mode","p":214},{"i":221,"t":"This configuration is explained in Mutation Section/Trigger/Set Trigger Type. Therefore, this article will not repeat the explanation, it just serves as a link reference.","s":"Trigger Type","u":"/jimmer-doc/docs/configuration/trigger-type","h":"","p":220},{"i":223,"t":"For ORM, it is important to print generated SQL in logs.","s":"SQL Log","u":"/jimmer-doc/docs/configuration/sql-log","h":"","p":222},{"i":225,"t":"There are two ways to enable SQL logs: When using Spring Boot Starter, there are two ways to configure: Modify application.yml (or application.properties) jimmer: show-sql: true Configure global Bean Java Kotlin @Bean public Executor executor() { return Executor.log(); } @Bean fun executor(): Executor = Executor.log() info If both methods above are used (not recommended), the second method takes precedence. Use underlying API Java Kotlin JSqlClient sqlClient = JSqlClient .newBuilder() .setExecutor(Executor.log()) ...Omit other configurations... .build(); val sqlClient = newKSqlClient { setExecutor(Executor.log()) ...Omit other configurations... } The actual printed logs are as follows: jimmer> sql: select tb_1_.ID, tb_1_.CREATED_TIME, tb_1_.MODIFIED_TIME, tb_1_.NAME, tb_1_.EDITION, tb_1_.PRICE, tb_1_.STORE_ID from BOOK tb_1_ where lower(tb_1_.NAME) like ? order by tb_1_.NAME asc, tb_1_.EDITION desc limit ?, ?, variables: [%graphql%, 0, 10], purpose: QUERY caution If only the SQL log is turned on, the above log will not wrap. The log has three parts: sql: The SQL statement being executed variables: The JDBC parameters associated with sql, which is an array whose length is the same as the number of \"?\" characters in sql. purpose: The reason why the SQL is executed, which is an enum with the following values: QUERY: Query directly executed by developers UPDATE: Operations performed by developers via update statements DELETE: Operations performed by developers via delete statements LOAD: Query executed automatically by Jimmer to get the value of associated properties or calculated properties in object fetcher. EXPORT: The user initiates a query to other microservices, and its object fetcher contains remote associations pointing to the current service. Jimmer automatically exposes the data of this service. MUTATE: Operations specified by developers via save commands EVICT: In some cases, the cache that should be cleared cannot be determined solely based on the event information of Jimmer triggers. Jimmer will automatically execute some queries to accurately determine which caches should be cleared.","s":"Enable SQL Log","u":"/jimmer-doc/docs/configuration/sql-log","h":"#enable-sql-log","p":222},{"i":227,"t":"In the previous example, the SQL log is printed in one line, which is poorly readable. Therefore, the SQL needs to be formatted. There are two implementation methods: When using Spring Boot Starter Modify application.yml (or application.properties) jimmer: show-sql: true pretty-sql: true When using underlying API Java Kotlin JSqlClient sqlClient = JSqlClient .newBuilder() .setExecutor(Executor.log()) .setSqlFormatter(SqlFormatter.PRETTY) ...Omit other configurations... .build(); val sqlClient = newKSqlClient { setExecutor(Executor.log()) setSqlFormatter(SqlFormatter.PRETTY) ...Omit other configurations... } The log output is as follows: Execute SQL===> Purpose: QUERY SQL: select tb_1_.ID, tb_1_.CREATED_TIME, tb_1_.MODIFIED_TIME, tb_1_.NAME, tb_1_.EDITION, tb_1_.PRICE, tb_1_.STORE_ID from BOOK tb_1_ where lower(tb_1_.NAME) like ? /* %graphql% */ ❶ order by tb_1_.NAME asc, tb_1_.EDITION desc limit ? /* 0 */ ❷, ? /* 10 */ ❸ JDBC response status: success Time cost: 8ms <===Execute SQL In this mode: The SQL statement will be automatically formatted, automatically wrapped, and automatically indented. ❶ ❷ ❸ Unlike the previous example, all JDBC parameters are not printed together, but injected into the original SQL as comments. Other information will be printed, such as whether SQL execution is successful, total execution time of SQL. For insert, update, delete operations, the number of affected rows will also be printed.","s":"Pretty SQL","u":"/jimmer-doc/docs/configuration/sql-log","h":"#pretty-sql","p":222},{"i":229,"t":"In the previous examples, the JDBC parameters in the SQL logs were inserted after the JDBC parameter placeholders ? as comment, e.g. ? /* %graphql% */. Perhaps you want the parameters to be inlined into the SQL statement directly, making it look as if no JDBC parameters were used. This way, the SQL statement in the logs can be copied directly into a SQL IDE to execute. There are two ways to achieve this Using Spring Boot Starter: Modify application.yml (or application.properties): jimmer: show-sql: true pretty-sql: true inline-sql-variables: true Using low-level API Java Kotlin JSqlClient sqlClient = JSqlClient .newBuilder() .setExecutor(Executor.log()) .setSqlFormatter(SqlFormatter.INLINE_PRETTY) ...other configs omitted... .build(); val sqlClient = newKSqlClient { setExecutor(Executor.log()) setSqlFormatter(SqlFormatter.INLINE_PRETTY) ...other configs omitted... } The log output is as follows: Execute SQL===> Purpose: QUERY SQL: select tb_1_.ID, tb_1_.CREATED_TIME, tb_1_.MODIFIED_TIME, tb_1_.NAME, tb_1_.EDITION, tb_1_.PRICE, tb_1_.STORE_ID from BOOK tb_1_ where lower(tb_1_.NAME) like '%graphql%' ❶ order by tb_1_.NAME asc, tb_1_.EDITION desc limit 0 ❷, 10 ❸ JDBC response status: success Time cost: 8ms <===Execute SQL In this mode, we can see the parameters at ❶ ❷ ❸ are directly inlined. info This only affects the logs. The actual SQL executed still uses JDBC parameters.","s":"Inline SQL Parameters","u":"/jimmer-doc/docs/configuration/sql-log","h":"#inline-sql-parameters","p":222},{"i":231,"t":"In addition to coding, developers often need to troubleshoot issues. Whether it is a functional error or a performance issue, the developer needs to investigate it. If the SQL log only prints JDBC information centered on SQL, the user cannot associate the SQL log with the application code, which is not conducive to users troubleshooting. Jimmer provides a configuration option that if specified, before executing SQL, it will check the stack trace information of the current thread. However, these stack traces contain too much information, including infrastructure call frames represented by jdk, jdbc driver, jimmer and spring, while the business-related information that developers care about will be overwhelmed in the ocean of information. This configuration type is java.util.Collection allowing developers to specify multiple packages or class prefixes. Jimmer will use them to filter the stack trace information. If a call frame can pass the filter, Jimmer will consider it related to user business and include it in the callback parameter before execution. For SQL log printing, call frames that can pass the filter will appear in the print output to help users troubleshoot issues. There are two implementation methods: When using Spring Boot Starter Modify application.yml (or application.properties) jimmer: show-sql: true pretty-sql: true executor-context-prefixes: - com.example.business When using underlying API Java Kotlin JSqlClient sqlClient = JSqlClient .newBuilder() .setExecutor(Executor.log()) .setSqlFormatter(SqlFormatter.PRETTY) .setExecutorContextPrefixes( Collections.singleton( \"com.example.business\" ) ) ...Omit other configurations... .build(); val sqlClient = newKSqlClient { setExecutor(Executor.log()) setSqlFormatter(SqlFormatter.PRETTY) setExecutorContextPrefixes( listOf( \"com.example.business\" ) ) ...Omit other configurations... } The log output is as follows: Execute SQL===> --- Business related stack trace information --- ❶ com.example.business.BookService.findBooks(BookService.java:55) ❷ Purpose: QUERY SQL: select tb_1_.ID, tb_1_.CREATED_TIME, tb_1_.MODIFIED_TIME, tb_1_.NAME, tb_1_.EDITION, tb_1_.PRICE, tb_1_.STORE_ID from BOOK tb_1_ where lower(tb_1_.NAME) like ? /* %graphql% */ order by tb_1_.NAME asc, tb_1_.EDITION desc limit ? /* 0 */, ? /* 10 */ JDBC response status: success Time cost: 9ms <===Execute SQL At ❶ and ❷, the stack trace information of the thread executing the SQL operation is printed. tip However, a large amount of stack trace information is not blindly printed, only what users care about is printed.","s":"Embed Stack Trace","u":"/jimmer-doc/docs/configuration/sql-log","h":"#embed-stack-trace","p":222},{"i":233,"t":"This section introduces how to quickly create GraphQL services with Jimmer.","s":"GraphQL","u":"/jimmer-doc/docs/graphql/","h":"","p":232},{"i":236,"t":"In the Spring section, we discussed how to implement REST services with Jimmer and automatically generate client code like TypeScript. In addition, Jimmer also supports another development mode to build GraphQL services, which is what this article series will discuss. caution So far, the GraphQL protocol does not support recursive queries for self-associated properties. Therefore, it is not possible to expose functionality like recursive queries in object fetchers through GraphQL. This is a functionality sacrifice that must currently be accepted when using GraphQL. Jimmer's support for GraphQL is based on Spring GraphQL. So the project needs to import both the Jimmer and Spring GraphQL Spring Boot starters, for example: Maven Gradle pom.xml ...other code omitted... org.babyfish.jimmer jimmer-spring-boot-starter ${jimmer.version} org.springframework.boot spring-boot-starter-graphql ${spring.boot.version} ...other dependencies omitted... ...other code omitted... build.gradle dependencies { implementation \"org.babyfish.jimmer:jimmer-spring-boot-starter:${jimmerVersion}\" implementation 'org.springframework.boot:spring-boot-starter-graphql' ...other dependencies omitted... } info If the Jimmer entity types are also defined in the GraphQL project rather than in a separate project, the preprocessor (Annotation Processor for Java, KSP for Kotlin) should also be configured in the build script. This has already been discussed in detail in the Generate Code article and will not be repeated here. Spring GraphQL is a Schema-First rather than Code-First approach. Therefore, developers need to create the file src/main/resources/graphql/schema.graphqls in the project and define the GraphQL schema in it. This file is a requirement of Spring GraphQL. The GraphQL schema content is a standard language that is unrelated to Jimmer, so this article will not explain it. Please refer to the GraphQL Schema in the example.","s":"Concepts","u":"/jimmer-doc/docs/graphql/concept","h":"#concepts","p":234},{"i":238,"t":"caution In the current version, there is a limitation that when providing GraphQL services, simple calculated properties based on SQL should NOT be used.","s":"Notes","u":"/jimmer-doc/docs/graphql/concept","h":"#notes","p":234},{"i":241,"t":"In previous documents, we have introduced how to map enums, and how to use @Serialized to map JSON. However, sometimes neither of these methods can meet our requirements. In this case, we can use ScalarProvider. tip ScalarProvider is the most low-level SPI of Jimmer for custom data types. The Enum Mapping and JSON Mapping we discussed before are actually Jimmer's built-in implementations of ScalarProvider. Multiple ScalarProvider can be registered for SqlClient. Each ScalarProvider tells Jimmer how to handle a custom data type. There are two types of ScalarProvider: Global Define the mapping rules between Java/Kotlin types and database types globally and uniformly. Any entity definition that contains properties of this type will be uniformly handled by the global ScalarProvider. note Global ScalarProvider can only handle non-collection types, such as: classes, interfaces, enums, etc. It cannot handle collection types like: Array, Collection, Map, etc. Property level For a specific entity property, define the mapping rules between Java/Kotlin types and database types. note Property-level ScalarProvider can handle any non-built-in types of Jimmer, including collection types such as: Array, Collection, Map. If the mapped property type is a collection type, the property needs to be annotated with @org.babyfish.jimmer.Scalar. tip The @Serialized annotation discussed in JSON Mapping can annotate both the return type of properties and entity properties. This is because the more low-level ScalarProvider has two types. ScalarProvider is an SPI interface provided by Jimmer, which is defined as follows: ScalarProvider package org.babyfish.jimmer.sql.runtime; import java.util.function.Consumer; public abstract class ScalarProvider { protected ScalarProvider(Class scalarType, Class sqlType) { ❸ ...Omitted code... } protected ScalarProvider() { ❹ ...Omitted code... } public abstract T toScalar(S sqlValue); ❺ public abstract S toSql(T scalarValue); ❻ public Collection getHandledProps() { ❼ return null; } } ❶ Generic parameter T: Data type in Java/Kotlin; ❷ Generic parameter S: Data type in the database; ❸ Constructor that explicitly specifies the types represented by T and S; This constructor is usually used to define ScalarProvider with higher generality and reusability. ❹ Constructor that does not need to explicitly specify the types represented by T and S; It requires derived classes to explicitly specify generic parameters T and S so that Jimmer can automatically analyze the types represented by T and S. Otherwise, an exception will occur. This constructor is usually used to define ScalarProvider corresponding to specific types without requiring generality and reusability. ❺ Method toScalar: Convert non-null data read from the database to Java data; ❻ Method toSql: Convert non-null Java data to data acceptable to the database; ❼ If you want to define a property-level ScalarProvider, one option (there are other options) is to override the getHandledProps method in the derived class;","s":"Basic Concepts","u":"/jimmer-doc/docs/configuration/scala-provider","h":"#basic-concepts","p":239},{"i":243,"t":"For example, the current database does not support the UUID type, which can be handled as follows:","s":"Global ScalarProvider","u":"/jimmer-doc/docs/configuration/scala-provider","h":"#global-scalarprovider","p":239},{"i":245,"t":"Java Kotlin UUIDScalarProvider.java public class UUIDScalarProvider extends AbstractScalarProvider { @Override public UUID toScalar(String sqlValue) { return UUID.fromString(sqlValue); } @Override public String toSql(UUID scalarValue) { return scalarValue.toString(); } } UUIDScalarProvider.kt class UUIDScalarProvider : ScalarProvider { override fun toScalar(sqlValue: String): UUID = UUID.fromString(sqlValue) override fun toSql(scalarValue: UUID): String = scalarValue.toString() }","s":"Define ScalarProvider","u":"/jimmer-doc/docs/configuration/scala-provider","h":"#define-scalarprovider","p":239},{"i":247,"t":"There are two ways for Jimmer to register ScalarProvider: Use Spring Boot Starter Just let the derived classes of ScalarProvider be managed by Spring. There are two options: Modify the above UUIDScalarProvider class and annotate it with spring's @Component Java Kotlin UUIDScalarProvider.java @Component public class UUIDScalarProvider extends AbstractScalarProvider { ...Omitted code... } UUIDScalarProvider.kt @Component class UUIDScalarProvider : ScalarProvider { ...Omitted code... } Use Spring's @Bean method to register the UUIDScalaProvider object to Spring Java Kotlin @Bean public UUIDScalarProvider uuidScalarProvider() { return new UUIDScalarProvider(); } @Bean fun uuidScalarProvider(): UUIDScalarProvider = UnitTestIdGenerator() Use underlying API Java Kotlin @Bean public JSqlClient sqlClient() { return JSqlClient .newBuilder() .addScalarProvider(new UUIDScalarProvider()) ...Omit other configurations... .build(); } @Bean fun sqlClient() : KSqlClient = newKSqlClient { addScalarProvider(UUIDScalarProvider()) ...Omit other configurations... }","s":"Register Scalar Provider","u":"/jimmer-doc/docs/configuration/scala-provider","h":"#register-scalar-provider","p":239},{"i":249,"t":"The only difference between property-level ScalarProvider and global ScalarProvider is that it only applies to specific properties, not all properties. So the most important data conversion methods toScalar and toSql in property-level ScalarProvider have exactly the same user code implementation, only the registration method is different. Therefore, here we assume there is a user-defined type Location and its corresponding ScalarProvider implementation class is LocationScalarProvider. Specific implementation is omitted.","s":"Property level ScalarProvider","u":"/jimmer-doc/docs/configuration/scala-provider","h":"#property-level-scalarprovider","p":239},{"i":251,"t":"Java Kotlin @Bean public JSqlClient sqlClient() { return JSqlClient .newBuilder() .setScalarProvider( FlightProps.SOURCE_LOCATION new LocationScalarProvider() ) .setScalarProvider( FlightProps.TARGET_LOCATION new LocationScalarProvider() ) ...Omit other configurations... .build(); } @Bean fun sqlClient() : KSqlClient = newKSqlClient { setScalarProvider( Flight::sourceLocation LocationScalarProvider() ) setScalarProvider( Flight::targetLocation LocationScalarProvider() ) ...Omit other configurations... } That is, except for the Flight.sourceLocation and Flight.targetLocation properties, LocationScalarProvider does not affect any other properties of type Location.","s":"Non-Spring registration","u":"/jimmer-doc/docs/configuration/scala-provider","h":"#non-spring-registration","p":239},{"i":253,"t":"The above method is intuitive, but it is manually registered. Can Spring's automatic registration method be used to register property-level ScalarProvider? Of course. Just override the getHandledProps method of ScalarProvider, and you can use the method of registering global ScalarProvider to register property-level ScalarProvider. For example: Java Kotlin LocationScalarProvider.java @Component public class LocationScalarProvider extends AbstractScalarProvider { @Override public Collection getHandledProps() { return Arrays.asList( FlightProps.SOURCE_LOCATION, FlightProps.TARGET_LOCATION ); } ...Omit other code... } LocationScalarProvider.kt @Component class LocationScalarProvider : ScalarProvider { override fun getHandledProps(): Collection = listOf( Flight::sourceLocation.toImmutableProp(), Flight::targetLocation.toImmutableProp() ) ...Omit other code... }","s":"Spring registration","u":"/jimmer-doc/docs/configuration/scala-provider","h":"#spring-registration","p":239},{"i":255,"t":"In this section, we introduce how to map a relational database to entity model. For readers with ORM experience (especially JPA), you can skim through quickly. Major differences from JPA: Basic Mapping: Nullability Advanced Mapping: View Properties Calculated Properties Remote Associations Key Key is very important for Save Command OnDissociate For readers without ORM experience, you'll have to read slowly. This process is tedious but required for any ORM. All powerful and cool ORM capabilities are built on top of these mappings. To avoid extended tedium for ORM beginners, a suggestion - initially only read the basic mappings, enough to understand most of the docs. Come back for advanced mappings when needed.","s":"Mapping","u":"/jimmer-doc/docs/mapping/","h":"","p":254},{"i":257,"t":"In this series of articles, we will introduce advanced mappings.","s":"Advanced mapping","u":"/jimmer-doc/docs/mapping/advanced/","h":"","p":256},{"i":259,"t":"In this article, you will learn about Jimmer's calculated properties and annotations: org.babyfish.jimmer.sql.Formula Simple calculated properties, can be Java/Kotlin expressions or SQL expressions org.babyfish.jimmer.sql.Transient Complex calculated properties, with the following features: Not only can simple values be calculated, but associated calculated values can also be calculated. That is, calculated properties can be associated properties Any complex calculation rules can be used, for example, using OLAP systems unrelated to the current relational database for calculation caution Calculated properties should only be defined when a calculated metric belongs to an entity. If a calculated metric does not belong to any entity, it should be designed as a global Service API.","s":"Calculated Properties","u":"/jimmer-doc/docs/mapping/advanced/calculated/","h":"","p":258},{"i":262,"t":"In GraphQL, GraphQLObjects returned by queries are dynamic objects of arbitrary shapes. However, if mutation operations accept object parameters, they must be GraphQLInputs, which are static objects of fixed shapes. See GraphQLInput to learn more. Take the GraphQL declaration file in the example schema.graphqls as an example: type Book implements CommonEntity { ❶ id: Long! name: String! edition: Int! price: BigDecimal! store: BookStore authors: [Author!]! createdTime: LocalDateTime! modifiedTime: LocalDateTime! tenant: String! } input BookInput { ❷ id: Long name: String! edition: Int price: BigDecimal! storeId: Long authorIds: [Long!]! } ...other code omitted... ❶ Types declared with the type keyword are dynamic types used to express arbitrary data structures, used as GraphQL output types ❷ Types declared with the input keyword are static types used to express fixed data structures, used as GraphQL input types","s":"Introduction to GraphQL Input","u":"/jimmer-doc/docs/graphql/mutation","h":"#introduction-to-graphql-input","p":260},{"i":264,"t":"Jimmer Input DTOs are introduced in great detail in Save Command/Input DTO, which will not be repeated here. Jimmer provides two ways to define Input DTOs: Automatically generate Input DTOs using the DTO language Manually define Input DTOs based on MapStruct Using the DTO language can achieve our goal very efficiently, so this article adopts this approach. In the project where the entity is defined, create the directory src/main/dto Under src/main/dto, create subdirectories com/yourcompany/yourproject/model according to the package path where the entities are located Under the directory created in the previous step, create the file Book.dto. The file must have the same name as the entity class and the extension must be dto Edit this file and use the DTO language to define various DTO shapes for the Book entity Book.dto input BookInput { #allScalars(Book) id(store) id(authors) as authorIds } ...other DTO definitions omitted... After compilation, the following Input DTO will be generated automatically: Java Kotlin BookInput.java @GeneratedBy(file = \"/src/main/dto/Book.dto\") public class BookInput implements Input { ❶ @Nullable private Long id; private String name; private int edition; private BigDecimal price; @Nullable private Long storeId; private List authorIds; @Override public Book toEntity() { ❷ ...omitted... } ...other members omitted... } BookInput.kt @GeneratedBy(file = \"/src/main/dto/Book.dto\") data class BookInput( val id: Long? = null, val name: String = \"\", val edition: Int = 0, val price: BigDecimal, val storeId: Long? = null, val authorIds: List = emptyList() ): Input { ❶ override fun toEntity(): Book = ❷ ...omitted... ...other members omitted... } ❶ The BookInput class implements the interface org.babyfish.jimmer.Input, which supports the toEntity method to convert the current Input DTO object to a Jimmer dynamic entity object. ❷ Implements the Input.toEntity method","s":"Define Jimmer Input DTO","u":"/jimmer-doc/docs/graphql/mutation","h":"#define-jimmer-input-dto","p":260},{"i":266,"t":"Java Kotlin BookStoreService.java package com.example.business; import org.springframework.graphql.data.method.annotation.Argument; import org.springframework.graphql.data.method.annotation.MutationMapping; import org.springframework.stereotype.Controller; ...other imports omitted... @Controller public class BookStoreService { private final BookStoreRepository bookStoreRepository; public BookStoreService(BookStoreRepository bookStoreRepository) { this.bookStoreRepository = bookStoreRepository; } @MutationMapping ❶ @Transactional public Book saveBook( @Argument BookInput input ❷ ) { // `save(input)` is shorthand for `save(input.toEntity())` return bookRepository.save(input); ❸ } } BookStoreService.kt package com.example.business import org.springframework.graphql.data.method.annotation.Argument import org.springframework.graphql.data.method.annotation.MutationMapping import org.springframework.stereotype.Controller ...other imports omitted... @Controller class BookStoreService( private val bookStoreRepository: BookStoreRepository ) { @MutationMapping ❶ @Transactional fun saveBook( @Argument input: BookInput ❷ ): Book = // `save(input)` is shorthand for `save(input.toEntity())` bookRepository.save(input) ❸ } ❶ Use annotation @org.springframework.graphql.data.method.annotation.MutationMapping ❷ Use the static Input DTO type BookInput to allow users to pass only data structures of specified shapes to conform to GraphQLInput ❸ Save command to save arbitrary data structures in one line Here bookRepository.save(input) is actually shorthand for bookRepository.save(input.toEntity()). tip No matter how simple or relatively complex the data structure defined by the BookInput type, it can be saved in one line. This is the core value of the save command feature.","s":"Implement GraphQL mutation","u":"/jimmer-doc/docs/graphql/mutation","h":"#implement-graphql-mutation","p":260},{"i":270,"t":"Without Jimmer's support, implementing GraphQL queries requires two types of work: Query aggregate roots This is work that needs to be done when developing any data service, whether it's a GraphQL service, REST service, or even a service using other custom protocols. Developers only need to query and return standalone aggregate root objects without considering their association properties. So this is a relatively simple development task. For Spring GraphQL, just add the @QueryMapping annotation to the query methods in controller classes. Query association properties and calculated properties This is the bulk of the work required to implement GraphQL queries, requiring consideration of all current object associations and batch loading. There is some workload involved. In other words, it is precisely because the server undertakes these responsibilities that using GraphQL feels free, convenient and powerful on the client side. For Spring GraphQL, some schemes are provided for querying association properties, such as @SchemaMapping Batch Loading @BatchMapping When using Jimmer to implement GraphQL queries, developers only need to focus on querying aggregate roots, just ensuring that these aggregate roots have simple scalar fields. This is because tip All association properties and calculated properties of entity objects are automatically mapped to GraphQL fields by Jimmer without any development. caution So far, the GraphQL protocol does not support recursive queries for self-associated properties. Therefore, it is not possible to expose functionality like recursive queries in object fetchers through GraphQL. This is a functionality sacrifice that must currently be accepted when using GraphQL.","s":"Feature Description","u":"/jimmer-doc/docs/graphql/query","h":"#feature-description","p":268},{"i":273,"t":"Java Kotlin BookStoreService.java package com.example.business; import org.springframework.graphql.data.method.annotation.Argument; import org.springframework.graphql.data.method.annotation.QueryMapping; import org.springframework.stereotype.Controller; ...Omit other imports... @Controller public class BookStoreService { private final JSqlClient sqlClient; public BookStoreService(JSqlClient sqlClient) { this.sqlClient = sqlClient; } @QueryMapping public List bookStores( @Argument @Nullable String name ) { BookStoreTable table = Tables.BOOK_STORE_TABLE; return sqlClient .createQuery(table) .where(table.name().ilikeIf(name)) .select(table) .execute(); } } BookStoreService.kt package com.example.business import org.springframework.graphql.data.method.annotation.Argument import org.springframework.graphql.data.method.annotation.QueryMapping import org.springframework.stereotype.Controller ...Omit other imports... @Controller class BookStoreService( private val sqlClient: KSqlClient ) { @QueryMapping fun bookStores( @Argument name: String? ): List = sqlClient .createQuery(BookStore::class) { where(table.name `ilike?` name) select(table) } .execute() } Unlike previous REST services, this example does not use object fetchers, returning the simplest orphan objects (orphan objects contain neither associated properties nor calculated properties). Although we return orphan objects here, if the client's GraphQL request contains associated objects, Jimmer will still automatically load the required associated properties. However, there is a problem with this approach: in non-cache mode, unnecessary properties will also be queried, which has performance issues. We will introduce another approach with optimization capability later.","s":"1. Simplest Implementation","u":"/jimmer-doc/docs/graphql/query","h":"#1-simplest-implementation","p":268},{"i":275,"t":"To avoid querying unnecessary non-associated properties in non-cache mode, Jimmer can create a Fetcher object based on graphql.schema.DataFetchingEnvironment and use this Fetcher to query the database with the object as a parameter. tip In non-cache mode, not querying unnecessary non-associated properties is the essential difference between Jimmer GraphQL and other GraphQL implementations in the Java ecosystem. Java Kotlin BookStoreService.java package com.example.business; import org.springframework.graphql.data.method.annotation.Argument; import graphql.schema.DataFetchingEnvironment; import org.babyfish.jimmer.spring.graphql.DataFetchingEnvironments; import org.springframework.graphql.data.method.annotation.QueryMapping; import org.springframework.stereotype.Controller; ...Omit other imports... @Controller public class BookStoreService { private final JSqlClient sqlClient; public BookStoreService(JSqlClient sqlClient) { this.sqlClient = sqlClient; } @QueryMapping public List bookStores( @Argument @Nullable String name, DataFetchingEnvironment env ) { BookStoreTable table = Tables.BOOK_STORE_TABLE; return sqlClient .createQuery(table) .where(table.name().ilikeIf(name)) .select( table.fetch( DataFetchingEnvironments.createQuery( BookStore.class, env ) ) ) .execute(); } } BookStoreService.kt package com.example.business import org.springframework.graphql.data.method.annotation.Argument import graphql.schema.DataFetchingEnvironment import org.babyfish.jimmer.spring.graphql.toFetcher import org.springframework.graphql.data.method.annotation.QueryMapping import org.springframework.stereotype.Controller ...Omit other imports... @Controller class BookStoreService( private val sqlClient: KSqlClient ) { @QueryMapping fun bookStores( @Argument name: String?, env: DataFetchingEnvironment ): List = sqlClient .createQuery(BookStore::class) { where(table.name `ilike?` name) select( table.fetch( env.toFetcher() ) ) } .execute() }","s":"2. Optimize Performance","u":"/jimmer-doc/docs/graphql/query","h":"#2-optimize-performance","p":268},{"i":277,"t":"In the accompanying example, the GraphQL related projects are: Language Example Java jimmer-examples/java/jimmer-sql-graphql Kotlin jimmer-examples/kotlin/jimmer-sql-graphql-kt Select any project, open and start it. Finally, use the browser to visit http://localhost:8080/graphiql note Be careful, it's /graphiql, not /graphql Execute the request: query { bookStores { id name avgPrice ❶ books { ❷ id name edition price authors { ❸ id firstName fullName gender } } } } ❶ Query calculated property BookStore.avgPrice ❷ Query association property BookStore.books ❸ Query association property Book.authors The return result is: { \"data\":{ \"bookStores\":[ { \"id\":2, \"name\":\"MANNING\", \"avgPrice\":80.333333, \"books\":[ { \"id\":10, \"name\":\"GraphQL in Action\", \"edition\":1, \"price\":80, \"authors\":[ { \"id\":5, \"firstName\":\"Samer\", \"fullName\":\"Samer Buna\", \"gender\":\"MALE\" } ] }, { \"id\":11, ...omitted... }, { \"id\":12, ...omitted... } ] }, { \"id\":1, \"name\":\"O'REILLY\", \"avgPrice\":58.5, \"books\":[ { \"id\":4, \"name\":\"Effective TypeScript\", \"edition\":1, \"price\":73, \"authors\":[ { \"id\":3, \"firstName\":\"Dan\", \"fullName\":\"Dan Vanderkam\", \"gender\":\"MALE\" } ] }, { \"id\":5, ...omitted... }, { \"id\":6, ...omitted... }, { \"id\":1, \"name\":\"Learning GraphQL\", \"edition\":1, \"price\":50, \"authors\":[ { \"id\":2, \"firstName\":\"Alex\", \"fullName\":\"Alex Banks\", \"gender\":\"MALE\" }, { \"id\":1, \"firstName\":\"Eve\", \"fullName\":\"Eve Procello\", \"gender\":\"FEMALE\" } ] }, { \"id\":2, \"name\":\"Learning GraphQL\", \"edition\":2, \"price\":55, \"authors\":[ { \"id\":2, \"firstName\":\"Alex\", \"fullName\":\"Alex Banks\", \"gender\":\"MALE\" }, { \"id\":1, \"firstName\":\"Eve\", \"fullName\":\"Eve Procello\", \"gender\":\"FEMALE\" } ] }, { \"id\":3, \"name\":\"Learning GraphQL\", \"edition\":3, \"price\":51, \"authors\":[ { \"id\":2, \"firstName\":\"Alex\", \"fullName\":\"Alex Banks\", \"gender\":\"MALE\" }, { \"id\":1, \"firstName\":\"Eve\", \"fullName\":\"Eve Procello\", \"gender\":\"FEMALE\" } ] }, { \"id\":7, \"name\":\"Programming TypeScript\", \"edition\":1, \"price\":47.5, \"authors\":[ { \"id\":4, \"firstName\":\"Boris\", \"fullName\":\"Boris Cherny\", \"gender\":\"MALE\" } ] }, { \"id\":8, \"name\":\"Programming TypeScript\", \"edition\":2, \"price\":45, \"authors\":[ { \"id\":4, \"firstName\":\"Boris\", \"fullName\":\"Boris Cherny\", \"gender\":\"MALE\" } ] }, { \"id\":9, \"name\":\"Programming TypeScript\", \"edition\":3, \"price\":48, \"authors\":[ { \"id\":4, \"firstName\":\"Boris\", \"fullName\":\"Boris Cherny\", \"gender\":\"MALE\" } ] } ] } ] } }","s":"Running Effect","u":"/jimmer-doc/docs/graphql/query","h":"#running-effect","p":268},{"i":279,"t":"Jimmer handles enums in two ways: Map to string: A choice with better understandability and traceability, also the default option. Map to integer: A choice with better performance-first. Jimmer provides two annotations for enums: org.babyfish.jimmer.sql.EnumType: Decorate enum types, optional Specify mapping method, map to string or ordinal position to integer org.babyfish.jimmer.sql.EnumItem: Decorate enum items, optional Override the mapped string value or integer value for some enum item","s":"Enum Mapping","u":"/jimmer-doc/docs/mapping/advanced/enum","h":"","p":278},{"i":281,"t":"Java Kotlin Gender.java @EnumType(EnumType.Strategy.NAME) public enum Gender { MALE, FEMALE } Gender.kt @EnumType(EnumType.Strategy.NAME) enum class Gender { MALE, FEMALE } Here, the parameter of @EnumType is specified as \"NAME\", indicating mapping to string. By default, the mapped string values of the two enum items are the same as their names, i.e. \"MALE\" and \"FEMALE\". If you expect the mapped strings to be different from the enum item names, you can decorate the enum items with @EnumItem. Java Kotlin Gender.java @EnumType(EnumType.Strategy.NAME) public enum Gender { @EnumItem(name = \"M\") MALE, @EnumItem(name = \"F\") FEMALE } Gender.kt @EnumType(EnumType.Strategy.NAME) enum class Gender { @EnumItem(name = \"M\") MALE, @EnumItem(name = \"F\") FEMALE }","s":"Map to String","u":"/jimmer-doc/docs/mapping/advanced/enum","h":"#map-to-string","p":278},{"i":283,"t":"Java Kotlin Gender.java @EnumType(EnumType.Strategy.ORDINAL) public enum Gender { MALE, FEMALE } Gender.kt @EnumType(EnumType.Strategy.ORDINAL) enum class Gender { MALE, FEMALE } Here, the parameter of @EnumType is specified as \"ORDINAL\", indicating mapping to integer. By default, the mapped integer values of the two enum items are the same as their ordinal, i.e. 0 and 1. If you expect the mapped integers to be different from the enum items' ordinal, you can decorate the enum items with @EnumItem. Java Kotlin Gender.java @EnumType(EnumType.Strategy.ORDINAL) public enum Gender { @EnumItem(ordinal = 100) MALE, @EnumItem(ordinal = 200) FEMALE } Gender.kt @EnumType(EnumType.Strategy.ORDINAL) enum class Gender { @EnumItem(ordinal = 100) MALE, @EnumItem(ordinal = 200) FEMALE }","s":"Map to Integer","u":"/jimmer-doc/docs/mapping/advanced/enum","h":"#map-to-integer","p":278},{"i":285,"t":"You can also avoid specifying the @EnumType annotation for enum types, that is, not explicitly indicate whether an enum type should be mapped to string or integer. In this case, Jimmer will refer to the default global configuration. info The default value of this global configuration is \"NAME\". If you need \"ORDINAL\", please override the global configuration. Next, we show how to override the global configuration: When using SpringBoot Add configuration item jimmer.default-enum-strategy in application.yml or application.properties and set its value to \"ORDINAL\" When not using SpringBoot Java Kotlin JSqlClient sqlClient = JSqlClient .newBuilder() .setDefaultEnumStrategy(EnumType.Strategy.ORDINAL) ...Omit other configurations... .build(); val sqlClient = newKSqlClient { setDefaultEnumStrategy(EnumType.Strategy.ORDINAL) ...Omit other configurations... }","s":"Do Not Explicitly Use @EnumType","u":"/jimmer-doc/docs/mapping/advanced/enum","h":"#do-not-explicitly-use-enumtype","p":278},{"i":287,"t":"The serialization of a type to JSON and its storage in the database are two independent matters. The content described above focuses on how Jimmer handles enum mapping in the database, which is unrelated to JSON. By default, Jackson converts enums to its name, so when generating the TypeScript Client, Jimmer maps the enum according to its name. Java Kotlin enum Gender { MAN, WOMAN } enum class Gender { MAN, WOMAN } The generated TypeScript code is as follows: export const GenderEnum_CONSTANTS = [ 'MAN', 'WOMAN' ] as const; export type GenderEnum = typeof GenderEnum_CONSTANTS[number]; //usage export type PersonDto = { gender: GenderEnum; } If you want to customize the JSON serialization, you need to use the @JsonValue annotation from Jackson. Java Kotlin enum Gender { MAN, WOMAN; @JsonValue public String getValue() { return name().toLowerCase(); } } enum class Gender { MAN, WOMAN; @JsonValue fun getValue(): String { return name().toLowerCase(); } } When detects the presence of annotations like @JsonValue, Jimmer not knowing how the enum will be converted during JSON serialization, so jimmer will translates the enum type to a string. The generated TypeScript code in this case is as follows: export type PersonDto = { gender: string; }","s":"Work with TypeScript Client and Jackson","u":"/jimmer-doc/docs/mapping/advanced/enum","h":"#work-with-typescript-client-and-jackson","p":278},{"i":290,"t":"Through the content related to Association Mapping, it is not difficult to find that all associations are based on @JoinColumn and @JoinTable (may be omitted). Although Jimmer supports fake foreign keys (foreign keys in the developer's mind but without corresponding foreign key constraints in the database), all the association mappings we have discussed so far are based on 3NF design of relational databases. However, you may be handed over a legacy database containing non-normalized database designs, such as: create table book( id bigint unsigned not null auto_increment primary key, // highlight-next-line author_ids varchar(100), ...Omit other columns... ) engine=innodb; Here, author_ids is a string column whose data is the ids of all Author objects associated with the current Book concatenated together with commas, e.g. 1, 5, 100, 206. Obviously, this is a non-structural design that does not satisfy 3NF of relational databases. note For Postgres that supports array types, using arrays would be a better choice, but for better generality of this example, string concatenation is still used here without utilizing database-specific features.","s":"Non-Structural Design Example","u":"/jimmer-doc/docs/mapping/advanced/join-sql","h":"#non-structural-design-example","p":288},{"i":292,"t":"To support such non-structural designs, Jimmer provides the @org.babyfish.jimmer.sql.JoinSql annotation. info @JoinSql must and can only be used together with @ManyToMany. Next, create an SQL function (MySQL is used as example here): create function concatenation_string_contains( self varchar(100), id bigint ) returns boolean begin if self is null then return false; end if; return self regexp concat('(^|\\\\,)\\\\s*', id, '\\\\s*(\\\\,|$)'); end; This function assumes that the parameter self is in the format of multiple numbers concatenated by commas, and determines whether it contains the parameter id. For example: concatenation_string_contains('100, 200, 300', 200) returns true concatenation_string_contains('100, 200, 300', 201) returns false Now we can map the non-structural many-to-many association: Java Kotlin Book.java @Entity public interface Book { @ManyToMany @JoinSql( \"concatenation_string_contains(\" + \" %alias.author_ids, \" + \" %target_alias.id\" + \")\" ) List authors(); ...Omit other code... } Book.kt @Entity interface Book { @ManyToMany @JoinSql( \"concatenation_string_contains(\" + \" %alias.author_ids, \" + \" %target_alias.id\" + \")\" ) val authors: List ...Omit other code... } The SQL expression used in @JsonSql represents the join condition, where: concatenation_string_contains: The SQL function we defined earlier %alias: A special token defined by Jimmer representing the alias of the current table (book table in this example) %target_alias: A special token defined by Jimmer representing the alias of the target table (author table in this example) caution ORM automatically generates SQL (which is very important for dynamic queries, especially for ORMs like Jimmer that first proposed the Dynamic Join concept), and users cannot interfere with the aliases of tables in the final SQL. So using %alias and %target_alias here is the only way. It is worth mentioning that if you want to define a bidirectional many-to-many association, since Book.authors has already used @JoinSql, the other end Author.books does not need to use @JoinSql again. As before, use mappedBy to indicate that it is the inverse property. Java Kotlin Author.java @Entity public interface Author { @ManyToMany(mappedBy = \"authors\") List books(); ...Omit other code... } Author.kt @Entity interface Author { @ManyToMany(mappedBy = \"authors\") val books: List ...Omit other code... }","s":"Non-Structural Association","u":"/jimmer-doc/docs/mapping/advanced/join-sql","h":"#non-structural-association","p":288},{"i":294,"t":"warning Unless legacy database compatibility is required, do not perform non-structural design and map it with @JoinSql, because non-structural many-to-many associations have many limitations: Cannot be used as Remote Association Cannot participate in Dynamic Join Optimization Cannot use Association Cache Cannot be saved as part of data structure by Save Command. In fact, if the data structure to be saved contains non-structural associations, it will cause exceptions.","s":"Precautions","u":"/jimmer-doc/docs/mapping/advanced/join-sql","h":"#precautions","p":288},{"i":296,"t":"Simple formula properties are properties declared with @org.babyfish.jimmer.sql.Formula. There are two usages: Formula properties based on Java/Kotlin calculation Formula properties based on SQL calculation note Simple formula properties are designed for simple and fast calculations. For complex calculations, use Complex Formula Properties instead. In Define Entity, we defined two fields for Author: firstName and lastName. Next, let's add a new property fullName to Author: fullName = firstName + ' ' + lastName Then we use two different ways, Java/Kotlin-based calculation and SQL-based calculation, to implement Author.fullName.","s":"Formula","u":"/jimmer-doc/docs/mapping/advanced/calculated/formula","h":"","p":295},{"i":299,"t":"Java Kotlin Author.java package com.example.model; import org.babyfish.jimmer.sql.*; @Entity public interface Author { @Formula(dependencies = {\"firstName\", \"lastName\"}) default String fullName() { return firstName() + ' ' + lastName(); } ...Omit other properties... } Author.kt package com.example.model import org.babyfish.jimmer.sql.* @Entity interface Author { @Formula(dependencies = [\"firstName\", \"lastName\"]) val fullName: String get() = \"$firstName $lastName\" ...Omit other properties... } It is easy to see that Java/Kotlin-based simple formula properties have the following characteristics: The property is not abstract (requires default keyword in Java) and directly provides calculation logic implementation. @Formula's dependencies is specified, indicating that this property depends on Author.firstName and Author.lastName. That is, the dynamic entity must ensure the presence of both firstName and lastName properties to calculate fullName. The usage is: Java Kotlin Author author = authorRepository.findNullable( 1L, Fetchers.AUTHOR_FETCHER // Query id (implicit + forced) and fullName .fullName() ); System.out.println(author); val author = authorRepository.findNullable( 1L, newFetcher(Author::class).by { // Query id (implicit + forced) and fullName fullName() } ); println(author) The executed SQL is: select tb_1_.ID, /* highlight-start */ tb_1_.FIRST_NAME, tb_1_.LAST_NAME /* highlight-end */ from AUTHOR as tb_1_ where tb_1_.ID = ? fullName is a formula property without corresponding field in the database, but depends on firstName and lastName. So this SQL queries FIRST_NAME and LAST_NAME to make its dependent properties present. Next, let's see what is printed: {\"id\":1,\"fullName\":\"Eve Procello\"} We can see that after Jackson serialization (the toString method of entity objects is a shortcut for serialization), there is only fullName but no firstName and lastName. This is because the object fetcher causes firstName and lastName to be indirectly fetched due to fetching fullName, but they are not directly fetched. In this case, although the dynamic object has firstName and lastName, they are marked as invisible to Jackson and will not appear in the Jackson serialization result. note If the object fetcher directly fetches firstName and lastName, they will definitely appear in the serialization result. Readers can try it themselves, no need to repeat here.","s":"Depending on simple properties","u":"/jimmer-doc/docs/mapping/advanced/calculated/formula","h":"#depending-on-simple-properties","p":295},{"i":301,"t":"Suppose there is an Embeddable type Java Kotlin NameInfo.java @Embeddable public interface NameInfo { String firstName(); String lastName(); } NameInfo.kt @Embeddable interface NameInfo { val firstName: String val lastName: String } If an entity uses this Embeddable type, then the entity properties can depend on its internal properties, for example Java Kotlin Author.java @Entity public interface Author { NameInfo nameInfo(); @Formula(dependencies = {\"nameInfo.firstName\", \"nameInfo.lastName\"}) // or it can be written as: @Formula(dependencies = \"nameInfo\") default String fullName() { return nameInfo().firstName() + ' ' + nameInfo().lastName(); } ...other properties omitted... } Author.kt @Entity interface Author { val nameInfo: NameInfo @Formula(dependencies = [\"nameInfo.firstName\", \"nameInfo.lastName\"]) // or it can be written as: @Formula(dependencies = [\"nameInfo\"]) ...other properties omitted... val fullName: String get() = \"${nameInfo.firstName} ${nameInfo.lastName}\" } info The usage and execution effect are completely the same as above, no need to repeat.","s":"Depending on embedded object","u":"/jimmer-doc/docs/mapping/advanced/calculated/formula","h":"#depending-on-embedded-object","p":295},{"i":303,"t":"Java Kotlin Book.java @Entity public interface Book { @ManyToMany List authors(); @Formula(dependencies = \"authors\") default int authorCount() { return authors().size(); } @Formula(dependencies = {\"authors.firstName\", \"authors.lastName\"}) default List authorNames() { return authors() .stream() .map(author -> author.firstName() + ' ' + author.lastName()) .collect(Collectors.toList()); } ...other properties omitted... } Book.kt @Entity public interface Book { @ManyToMany val authors: List @Formula(dependencies = \"authors\") val authorCount: Int get() = authors.size @Formula(dependencies = [\"authors.firstName\", \"authors.lastName\"]) val authorNames: List get() = authors.map { \"${it.firstName} ${it.lastName}\" } ...other properties omitted... } Execute the following code Java Kotlin BookTable table = BookTable.$; List books = sqlClient .createQuery(table) .where(table.name().eq(\"Learning GraphQL\")) .orderBy(table.edition().desc()) .select( table.fetch( BookFetcher.$ .name() .edition() .authorCount() .authorNames() ) ) .execute(); val books = sqlClient .createQuery(Book::class) { where(table.name eq \"Learning GraphQL\") orderBy(table.edition().desc()) select( table.fetchBy { name() edition() authorCount() authorNames() } ) } .execute() Execute, generating two SQL statements select tb_1_.ID, tb_1_.NAME, tb_1_.EDITION, from BOOK tb_1_ where tb_1_.NAME = ? /* Learning GraphQL */ order by tb_1_.EDITION desc select tb_2_.BOOK_ID, tb_1_.ID, tb_1_.FIRST_NAME, tb_1_.LAST_NAME from AUTHOR tb_1_ inner join BOOK_AUTHOR_MAPPING tb_2_ on tb_1_.ID = tb_2_.AUTHOR_ID where tb_2_.BOOK_ID in ( ? /* 3 */, ? /* 2 */, ? /* 1 */ ) order by tb_1_.FIRST_NAME asc, tb_1_.LAST_NAME asc The obtained data is as follows [ { \"id\":3, \"name\":\"Learning GraphQL\", \"edition\":3, \"authorCount\":2, \"authorNames\":[\"Alex Banks\",\"Eve Procello\"] }, { \"id\":2, \"name\":\"Learning GraphQL\", \"edition\":2, \"authorCount\":2, \"authorNames\":[\"Alex Banks\",\"Eve Procello\"] }, { \"id\":1, \"name\":\"Learning GraphQL\", \"edition\":1, \"authorCount\":2, \"authorNames\":[\"Alex Banks\",\"Eve Procello\"] } ]","s":"Depending on association properties","u":"/jimmer-doc/docs/mapping/advanced/calculated/formula","h":"#depending-on-association-properties","p":295},{"i":305,"t":"Java Kotlin Author.java package com.example.model; import org.babyfish.jimmer.sql.*; @Entity public interface Author { @Formula(sql = \"concat(%alias.FIRST_NAME, ' ', %alias.LAST_NAME)\") String fullName(); ...Omit other properties... } Author.kt package com.example.model import org.babyfish.jimmer.sql.* @Entity interface Author { @Formula(sql = \"concat(%alias.FIRST_NAME, ' ', %alias.LAST_NAME)\") val fullName: String ...Omit other properties... } It is easy to see that SQL-based simple formula properties have the following characteristics: The property is abstract. @Formula's sql is specified as an SQL expression with a special token %alias Users cannot know the alias of the current table in the final SQL in advance, so Jimmer stipulates here that %alias represents the actual table column name. The usage is: Java Kotlin Author author = authorRepository.findNullable( 1L, Fetchers.AUTHOR_FETCHER // Query id (implicit + forced) and fullName .fullName() ); System.out.println(author); val author = authorRepository.findNullable( 1L, newFetcher(Author::class).by { // Query id (implicit + forced) and fullName fullName() } ); println(author) The generated SQL is: select tb_1_.ID, /* Here, `%alias` in @Formula.sql is replaced with `tb_1_` */ /* highlight-next-line */ concat(tb_1_.FIRST_NAME, ' ', tb_1_.LAST_NAME) from AUTHOR as tb_1_ where tb_1_.ID = ? The final printed result is: {\"id\":1,\"fullName\":\"Eve Procello\"}","s":"2. SQL-based Calculation","u":"/jimmer-doc/docs/mapping/advanced/calculated/formula","h":"#2-sql-based-calculation","p":295},{"i":307,"t":"Compared with Java/Kotlin-based simple formula, SQL-based simple formula has one disadvantage and one advantage: Disadvantage: If the object fetcher fetches firstName, lastName and fullName at the same time, it will cause the final SQL to query three columns: tb_1_.FIRST_NAME, tb_1_.LAST_NAME and concat(tb_1_.FIRST_NAME, ' ', tb_1_.LAST_NAME). Obviously, the returned data contains redundancy and is wasteful. Advantage: Java/Kotlin-based formula properties can only be used as fields to be fetched by object fetchers, and cannot be used by SQL DSL. SQL-based formula properties will be generated into the strongly typed SQL DSL API by the code generator, available for SQL DSL, such as: Java's where(table.fullName().eq(\"Eve Procello\")) or Kotlin's where(table.fullName eq \"Eve Procello\") tip Among all formula properties, only SQL-based simple formula properties can be used by SQL DSL. It is recommended to use databases that support function indexes and use them in combination with function indexes. Therefore, it is recommended to carefully consider whether @Formula formula properties should be based on Java/Kotlin calculation or SQL calculation.","s":"Comparison","u":"/jimmer-doc/docs/mapping/advanced/calculated/formula","h":"#comparison","p":295},{"i":309,"t":"Jimmer supports JSON properties. In Java/Kotlin entity types, such properties can be declared as any type other than java.lang.Object and kotlin.Any. In the database, the information stored in the corresponding column is JSON. info JSON properties are simple properties, not association properties. According to the current implementation, the corresponding column type in Postgres should be jsonb, and the corresponding column type in other databases should be string. Jimmer provides org.babyfish.jimmer.sql.Serialized. There are two ways to use JSON mapping: Global JSON mapping If the property type is a custom class rather than an array, collection, or Map, decorate this class with @Serialized. This way, any properties of the this type in all entities will become JSON properties. Property-level JSON mapping The current property can be decorated with @Serialized. Properties of array, collection, or map types must use property-level mapping; however, global mapping is better for custom types.","s":"JSON Mapping","u":"/jimmer-doc/docs/mapping/advanced/json","h":"","p":308},{"i":311,"t":"First, define a custom class and decorate it with @Serialized: Java Kotlin UserType.java @Serialized public class UserType { ...Omit members, can contain any info... ...As long as Json serialization/deserialization is supported... } UserType.kt @Serialized data class UserType( ...Omit parameters, can contain any info... ...As long as Json serialization/deserialization is supported... ) Then UserType can be used to define properties for any entity: Java Kotlin Book.java @Entity public interface Book { UserType userData(); ...Omit other types... } Book.kt @Entity interface Book { val userData: UserType ...Omit other types... }","s":"Global JSON Mapping","u":"/jimmer-doc/docs/mapping/advanced/json","h":"#global-json-mapping","p":308},{"i":313,"t":"Just decorate the property with @Serialized: Java Kotlin Book.java @Entity public interface Book { @Serialized List> userData1(); @Serialized Map> userData2(); ...Omit other types... } Book.kt @Entity interface Book { @Serialized val userData1: List> @Serialized val userData2: Map> ...Omit other types... }","s":"Property-level JSON Mapping","u":"/jimmer-doc/docs/mapping/advanced/json","h":"#property-level-json-mapping","p":308},{"i":316,"t":"Developers can configure the ObjectMapper for JSON serialization/deserialization of properties decorated with @Serialized. Java Kotlin ObjectMapper mapper1 = ...omitted...; ObjectMapper mapper2 = ...omitted...; ObjectMapper mapper3 = ...omitted...; JSqlClient sqlClient = JSqlClient .newBuilder() .setDefaultSerializedTypeObjectMapper(mapper1) ❶ .setSerializedTypeObjectMapper(MetaConfig.class, mapper2) ❷ .setSerializedTypePropMapper(TopicProps.TAGS, mapper3) ❸ ...Omit other configurations... .build(); val mapper1: ObjectMapper = ...omitted... val mapper2: ObjectMapper = ...omitted... val mapper3: ObjectMapper = ...omitted... val sqlClient = newKSqlClient { setDefaultSerializedTypeObjectMapper(mapper1) ❶ setSerializedTypeObjectMapper(MetaConfig::class, mapper2) ❷ setSerializedTypePropMapper(Topic::tags, mapper3) ❸ ...Omit other configurations... } ❶ Set default ObjectMapper to mapper1 Equivalent to setSerializedTypeObjectMapper(Object.class, mapper1) ❷ For any property whose return type is MetaConfig or its subclass, use mapper2 ❸ Explicitly set ObjectMapper for Topic.tags to mapper3 If the set property is not decorated with @Serialized, an exception will be thrown Configuration precedence: ❸ > ❷ > ❶","s":"Use Low-level API","u":"/jimmer-doc/docs/mapping/advanced/json","h":"#use-low-level-api","p":308},{"i":318,"t":"If using the Spring Boot Starter, the SqlClient is created automatically, but users can change the configuration before SqlClient is created via Customizer/KCustomizer: Java Kotlin @Component public class SerializationCustomizer implements Customizer { @Override public void customize(JSqlClient.Builder builder) { builder .setDefaultSerializedTypeObjectMapper(...omitted...) .setSerializedTypeObjectMapper(MetaConfig.class, ...omitted...) .setSerializedTypePropMapper(TopicProps.TAGS, ...omitted...); } } @Component class SerializationCustomizer : KCustomizer { override fun customize(dsl: KSqlClientDsl) { dsl .setDefaultSerializedTypeObjectMapper(...omitted...) .setSerializedTypeObjectMapper(MetaConfig::class, ...omitted...) .setSerializedTypePropMapper(Topic::tags, ...omitted...); } }","s":"Use Spring Boot Starter","u":"/jimmer-doc/docs/mapping/advanced/json","h":"#use-spring-boot-starter","p":308},{"i":320,"t":"Embedded properties (Composite properties) merge multiple columns in the database into an integral whole, map them to a non-entity custom type, and then use this custom type to declare a property for the entity.","s":"Embedded Properties","u":"/jimmer-doc/docs/mapping/advanced/embedded","h":"","p":319},{"i":323,"t":"First, define a composite type: Java Kotlin FullName.java @Embeddable public interface FullName { String firstName(); String lastName(); } FullName.kt @Embeddable interface FullName { val firstName: String val lastName: String } caution Types defined by @Embeddable are not entity types. They must not declare id properties or association properties, otherwise compilation errors will occur. Then we can use it in another entity: Java Kotlin Author.java @Entity public interface Author { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) long id(); FullName name(); } Author.kt @Entity interface Author { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) val id: Long val name: FullName } info Unlike JPA/Hibernate, when using composite types in entities, @Embedded is not required. In fact, Jimmer does not provide the @Embedded annotation at all. The table structure corresponding to Author is: create table author( id bigint unsigned not null auto_increment primary key, /* highlight-next-line */ first_name varchar(20) not null, /* highlight-next-line */ last_name varchar(20) not null ) engine=innodb;","s":"Basic Usage","u":"/jimmer-doc/docs/mapping/advanced/embedded","h":"#basic-usage","p":319},{"i":325,"t":"org.babyfish.jimmer.sql.PropOverride can be used to override column names of composite type properties: Define composite type Point: Java Kotlin Point.java @Embeddable public interface Point { int x(); int y(); } Point.kt @Embeddable interface Point { val x: Int val y: Int } Define composite type Rect and override column names of Point type: Java Kotlin Rect.java @Embeddable public interface Rect { @PropOverride(prop = \"x\", columnName = \"`LEFT`\") @PropOverride(prop = \"y\", columnName = \"`TOP`\") Point leftTop(); @PropOverride(prop = \"x\", columnName = \"`RIGHT`\") @PropOverride(prop = \"y\", columnName = \"BOTTOM\") Point rightBottom(); } Rect.kt @Embeddable interface Rect { @PropOverride(prop = \"x\", columnName = \"`LEFT`\") @PropOverride(prop = \"y\", columnName = \"`TOP`\") val leftTop: Point @PropOverride(prop = \"x\", columnName = \"`RIGHT`\") @PropOverride(prop = \"y\", columnName = \"BOTTOM\") val rightBottom: Point } Define entity type Transition and override column names of Rect type: Java Kotlin Transition.java @Entity public interface Transition { @Id long id(); int millis(); Rect source(); @PropOverride(prop = \"leftTop.x\", columnName = \"TARGET_LEFT\") @PropOverride(prop = \"leftTop.y\", columnName = \"TARGET_TOP\") @PropOverride(prop = \"rightBottom.x\", columnName = \"TARGET_RIGHT\") @PropOverride(prop = \"rightBottom.y\", columnName = \"TARGET_BOTTOM\") Rect target(); } Transition.kt @Entity interface Transition { @Id val id: Long val millis: Int val source: Rect @PropOverride(prop = \"leftTop.x\", columnName = \"TARGET_LEFT\") @PropOverride(prop = \"leftTop.y\", columnName = \"TARGET_TOP\") @PropOverride(prop = \"rightBottom.x\", columnName = \"TARGET_RIGHT\") @PropOverride(prop = \"rightBottom.y\", columnName = \"TARGET_BOTTOM\") val target: Rect } The table structure corresponding to Transition is: create table transition( id bigint unsigned not null auto_increment primary key, millis int not null, `LEFT` int not null, `TOP` int not null, `RIGHT` int not null, bottom int not null, target_left int not null, target_top int not null, target_right int not null, target_bottom int not null ) engine=innodb;","s":"Override Column Names","u":"/jimmer-doc/docs/mapping/advanced/embedded","h":"#override-column-names","p":319},{"i":327,"t":"warning Using composite types as primary/foreign keys, that is, primary keys and foreign keys are composed of multiple columns, makes the system more complex without much benefit. Therefore, unless compatibility with legacy database design is required, the system should avoid such usage to keep primary/foreign keys simple. Let's first define a composite type: Java Kotlin UniqueId.java @Embeddable public interface UniqueId { @columnName(\"UNIQUE_ID_DAY_NO\") int dayNo(); @columnName(\"UNIQUE_ID_SEQ_NO\") int sequenceNo(); } UniqueId.kt @Embeddable interface UniqueId { @columnName(\"UNIQUE_ID_DAY_NO\") val dayNo: Int @columnName(\"UNIQUE_ID_SEQ_NO\") val sequenceNo: Int }","s":"As Primary/Foreign Keys","u":"/jimmer-doc/docs/mapping/advanced/embedded","h":"#as-primaryforeign-keys","p":319},{"i":329,"t":"Java Kotlin Book.java @Entity public interface Book { @Id UniqueId id(); ...Omit other code... } Book.kt @Entity interface Book { @Id val id: UniqueId ...Omit other code... } Since Book.id does not override column names of UniqueId type using @PropOverride, the column names configured in UniqueId are used. The corresponding DDL is: create table book( unique_id_day_no int not null, unique_id_seq_no int not null, ...Omit other columns... ) engine=innodb; alter table book add constraint pk_book primary key(unique_id_day_no, unique_id_seq_no);","s":"As Primary Key","u":"/jimmer-doc/docs/mapping/advanced/embedded","h":"#as-primary-key","p":319},{"i":331,"t":"Java Kotlin Chapter.java @Entity public interface Chapter { @ManyToOne @JoinColumn( name = \"BOOK_ID_DAY_NO\", referencedColumnName = \"UNIQUE_ID_DAY_NO\" ) @JoinColumn( name = \"BOOK_ID_SEQ_NO\", referencedColumnName = \"UNIQUE_ID_SEQ_NO\" ) Book book(); ...Omit other code... } Chapter.kt @Entity interface Chapter { @ManyToOne @JoinColumn( name = \"BOOK_ID_DAY_NO\", referencedColumnName = \"UNIQUE_ID_DAY_NO\" ) @JoinColumn( name = \"BOOK_ID_SEQ_NO\", referencedColumnName = \"UNIQUE_ID_SEQ_NO\" ) val book: Book ...Omit other code... } caution Different from all the examples we have covered before, here the referencedColumnName of the @JoinColumn annotation is specified. When the foreign key consists of multiple columns, multiple @JoinColumn annotations must be used, where each @JoinColumn must specify referencedColumnName. If the foreign key is real, the corresponding constraint is: alter table chapter add constraint fk_chapter__book foreign key( book_id_day_no, book_id_seq_id ) references book( unique_id_day_no, unique_id_seq_no );","s":"Referenced by @JoinColumn","u":"/jimmer-doc/docs/mapping/advanced/embedded","h":"#referenced-by-joincolumn","p":319},{"i":333,"t":"Java Kotlin Book.java @Entity public interface Book { @Id UniqueId id(); @ManyToMany @JoinTable( joinColumns = { @JoinColumn( name = \"BOOK_ID_DAY_NO\", referencedColumnName = \"UNIQUE_ID_DAY_NO\" ), @JoinColumn( name = \"BOOK_ID_SEQ_NO\", referencedColumnName = \"UNIQUE_ID_SEQ_NO\" ) } ) List authors(); ...Omit other code... } Book.kt @Entity interface Book { @Id val id: UniqueId @ManyToMany @JoinTable( joinColumns = [ JoinColumn( name = \"BOOK_ID_DAY_NO\", referencedColumnName = \"UNIQUE_ID_DAY_NO\" ), JoinColumn( name = \"BOOK_ID_SEQ_NO\", referencedColumnName = \"UNIQUE_ID_SEQ_NO\" ) ] ) val authors: List ...Omit other code... } If the foreign key is real, the DDL of the join table is: create table book_author_mapping( book_id_day_no int not null, book_id_seq_id int not null, author_id bigint not null ) engine=innodb; alter table book_author_mapping add constraint pk_book_author_mapping primary key( book_id_day_no, book_id_seq_id, author_id ); alter table book_author_mapping add constraint fk_book_author_mapping__book foreign key( book_id_day_no, book_id_seq_id ) references book( unique_id_day_no, unique_id_seq_no ); alter table book_author_mapping add constraint fk_book_author_mapping__author foreign key(author_id) references author(id);","s":"Referenced by @JoinTable","u":"/jimmer-doc/docs/mapping/advanced/embedded","h":"#referenced-by-jointable","p":319},{"i":335,"t":"Logical deletion, also known as soft deletion, means data is not actually deleted. Instead, data is hidden to give the illusion of deletion. This leaves room for recovering from accidental operations.","s":"Logical Deletion","u":"/jimmer-doc/docs/mapping/advanced/logical-deleted/","h":"","p":334},{"i":338,"t":"info @org.babyfish.jimmer.sql.Key is used together with Save Command in mutation section. Initially, people used business fields directly as the primary key of tables. This is the most straightforward and easy to use approach, but it has the following problems: Unstable primary key Since the primary key itself is a business field, it can be modified, which leads to an unstable primary key. Although the foreign keys that reference it in the database can use on update cascade to keep consistency, an unstable primary key will cause many problems for systems outside the database, such as caches. Even if a unified solution to the primary key instability problem can be abstracted at the technical level, it is not recommended, because it makes the system difficult to understand. High cost of multi-table joins Since the primary key itself is a business field, its type is likely to be a relatively long string type rather than a numeric type, and it may even be a composite primary key composed of multiple columns, which leads to high cost of multi-table joins. To solve the above problems, people learned to use data without business meaning as the primary key, such as Auto numbering by database Sequence value by database UUID Snowflake ID To enable idempotent saves for save commands, Jimmer introduces two concepts: Id and Key @Id: Primary key @Key: Business primary key If Id itself is a business attribute (not recommended), no need to specify Key, because Id itself already represents the uniqueness constraint at the business level. If Id has no business meaning (recommended), then Key represents what the uniqueness constraint is at the business level. See the following example: Java Kotlin @Entity public interface TreeNode { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) long id(); @Key String name(); @Key @ManyToOne @Nullable TreeNode parent(); @OneToMany(mappedBy = \"parent\") List childNodes(); } @Entity interface TreeNode { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) val id: Long @Key val name: String @Key @ManyToOne val parent: TreeNode? @OneToMany(mappedBy = \"parent\") val childNodes: List } Here, the Id of the TreeNode entity uses auto numbering and has no business meaning. Therefore, to better match save commands, key is specified here, consisting of two properties: name and parent. The corresponding DDL is: create table TREE_NODE( ID bigint not null, NAME varchar(20) not null, PARENT_ID bigint ); alter table TREE_NODE add constraint PK_TREE_NODE primary key(ID); alter table TREE_NODE add constraint UQ_TREE_NODE /* highlight-next-line */ unique(NAME, PARENT_ID); The name and parent properties of the entity type decorated with @Key correspond to the UNIQUE constraint (or UNIQUE INDEX) composed of the NAME and PARENT_ID columns in the database. This uniqueness constraint can be analogized to file systems. File systems allow directories or files with the same name, but do not allow the same name if the parent directory is specified. info Through this example, we see: Key can consist of multiple properties Foreign keys can be part of Key Let's take another look at another example where the properties that make up Key are all properties based on foreign keys: Java Kotlin @Entity public interface OrderItem { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) long id(); @Key @ManyToOne Order order(); @Key @ManyToOne Product product(); int quantity(); // Snapshot of `product.price` BigDecimal unitPrice(); } @Entity interface OrderItem { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) val id: Long @Key @ManyToOne val order: Order @Key @ManyToOne val product: Product val quantity: Int // Snapshot of `product.price` val unitPrice: BigDecimal } This article only introduces the configuration of Key. For how to use it further, please refer to Save Command.","s":"Concept","u":"/jimmer-doc/docs/mapping/advanced/key","h":"#concept","p":336},{"i":340,"t":"Jimmer supports logical deletion, which hides deleted data instead of actually deleting it. The unique constraint defined by @Key is only for non-hidden data, not all data in the table, so unique constraint cannot be simply defined by the columns of @key. When the logical deletion flag is datetime Java Kotlin Book.java @Entity public interface Book { @Key String name(); @LogicalDeleted(\"now\") @Nullable LocalDateTime deletedTime(); ...other code omitted... } Book.kt @Entity interface Book { @Key val name: String @LogicalDeleted(\"now\") val deletedTime: LocalDateTime? ...other code omitted... } In this case, combine the columns corresponding to @Key (for this example, NAME) and the logical deletion flag column (for this example, DELETED_TIME) to define the uniqueness constraint, e.g.: alter table BOOK add constraint UQ_BOOK unique(NAME, DELETED_TIME); When the logical deletion flag is other type Java Kotlin Book.java @Entity public interface Book { @Key String name(); @LogicalDeleted(\"true\") boolean deleted(); ...other code omitted... } Book.kt @Entity interface Book { @Key val name: String @LogicalDeleted(\"true\") val deleted: Boolean ...other code omitted... } In this case, combining the @Key columns and the logical deletion flag column is no longer a viable approach. Using a conditional unique index is the only option. caution Unfortunately, not all databases support conditional indexes, and the syntax for creating conditional index varies between databases. Here, PostgresSQL is used as an example: create unique index BOOK_KEY_INDEX on BOOK(NAME) // highlight-next-line where DELETED = false;","s":"Multi-version support","u":"/jimmer-doc/docs/mapping/advanced/key","h":"#multi-version-support","p":336},{"i":342,"t":"Configuration specified by the annotation @Key is called static configuration. Sometimes, different businesses may have different requirements for @Key. Therefore, @Key configurations can be dynamically overridden at runtime. Java Kotlin sqlClient .getEntities() .saveCommand(book) .setKeyProps(BookProps.NAME, BookProps.EDITION) .execute(); sqlClient.save(book) { .setKeyProps(Book::name, Book::edition) }","s":"Dynamic Overrides","u":"/jimmer-doc/docs/mapping/advanced/key","h":"#dynamic-overrides","p":336},{"i":344,"t":"To enable logical deletion support for an entity, add a flag property annotated with org.babyfish.jimmer.sql.LogicalDeleted to indicate whether the data is normal or already deleted. Once a logical deletion property is configured for an entity: By default, when developers call APIs to delete an entity object, Jimmer will NOT actually delete the data with SQL delete statements. Instead, it will use update statements to set the logical deletion property of the entity to \"already deleted\". Other cases: Even if an entity has a logical deletion property, Jimmer also provides APIs for developers to forcibly truly delete objects by passing additional parameters. By default, all SQL queries against the entity will be automatically appended with a where logicalDeleteFlag <> already deleted condition to create the illusion that some data has been deleted. info This doc only covers the mapping configuration of the logical deletion flag field. For how to use the logical deletion functionality, see Global Filters / Logical Deletion.","s":"Entity Table","u":"/jimmer-doc/docs/mapping/advanced/logical-deleted/entity","h":"","p":343},{"i":346,"t":"The logical deletion flag property can be one of the following types: boolean: must be non-null int: must be non-null enum: must be non-null long/Long：either null or non-null UUID: either null or non-null date: must be nullable Type Code Deleted State Initialized State boolean Java Kotlin @LogicalDeleted(\"true\") boolean deleted(); @LogicalDeleted(\"true\") val deleted: Boolean true false Java Kotlin @LogicalDeleted(\"false\") val active: Boolean; @LogicalDeleted(\"false\") val active: Boolean false true int Java Kotlin @Default(\"0\") @LogicalDeleted(\"1\") int state(); @Default(\"0\") @LogicalDeleted(\"1\") val state: Int 1 0 Enum Java Kotlin @Default(\"INITIALIZED\") @LogicalDeleted(\"DELETED\") State state(); @Default(\"INITIALIZED\") @LogicalDeleted(\"DELETED\") val state: State DELETED INITIALIZED ✩ long Java Kotlin @LogicalDeleted long deletedMillis(); @LogicalDeleted val deletedMillis: Long Current milliseconds 0L ✩ Nullable Long Java Kotlin @LogicalDeleted Long deletedMillis(); @LogicalDeleted val deletedMillis: Long? Current milliseconds null ✩ UUID Java Kotlin @LogicalDeleted UUID deletedData(); @LogicalDeleted val deletedData: UUID Random UUID UUID with all bytes as 0 ✩ Nullable UUID Java Kotlin @Nullable @LogicalDeleted UUID deletedData(); @LogicalDeleted val deletedData: UUID? Random UUID null Nullable LocalDateTime ✩ Java Kotlin @Nullable @LogicalDeleted(\"now\") UUID deletedTime(); @LogicalDeleted(\"now\") val deletedTime: LocalDateTime? Current time null Java Kotlin @Nullable @LogicalDeleted(\"null\") UUID createdTime(); @LogicalDeleted(\"null\") val createdTime: LocalDateTime? null Current time Where ✩ in the first or second column indicates that the current configuration method supports multi-version data to be discussed in the next section. info Supporting logical deletion but not considering multi-version data issues is a less mature consideration. Therefore, it is recommended to use the logical deletion configuration that supports multi-version data. Current milliseconds, the default behavior is System.currentMillis(), which is the behavior of the default org.babyfish.jimmer.sql.meta.LogicalDeletedLongGenerator. If this behavior is unsatisfactory, a custom class can be implemented that implements the LogicalDeletedValueGenerator interface, and configured with: @LogicalDeleted(generatedType = YourGenerator.class) @LogicalDeleted(generatedRef = YourGenerator.class), where generatorRef indicates the name of the object in the IOC container management framework Random UUID, the default behavior is UUID.randomUUID(), which is the behavior of the default org.babyfish.jimmer.sql.meta.LogicalDeletedUUIDGenerator. If this behavior is unsatisfactory, a custom class can be implemented that implements the LogicalDeletedValueGenerator interface, and configured with: @LogicalDeleted(generatedType = YourGenerator.class) @LogicalDeleted(generatedRef = YourGenerator.class), where generatorRef indicates the name of the object in the IOC container management framework","s":"Usage","u":"/jimmer-doc/docs/mapping/advanced/logical-deleted/entity","h":"#usage","p":343},{"i":348,"t":"Logical deletion does not actually delete data, it only hides the data. This means that data appears in multiple versions. This issue is also described in Key / Multi-version Support. Take the example of long type logical deletion that supports multiple versions Java Kotlin @Entity public interface Book { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) long id(); @Key String name(); @Key int edition(); @LogicalDeleted long deletedMillis(); BigDecimal price(); @ManyToOne BookStore store(); } @Entity interface Book { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) val id: Long @Key val name: String @Key val edition: String @LogicalDeleted val deletedMillis: Long val price: BigDecimal @ManyToOne val store: BookStore } Although the Key of the Book object is name and edition, because the deletedMillis property is the logical deletion flag, the non-primary key UNIQUE constraint at the database level should be: alter table BOOK add constraint uq_key_BOOK unique(NAME, EDITION, DELETED_MILLIS); If the table input is as follows: ID NAME EDITION PRICE STORE_ID DELETED_MILLIS 1027 SQL in Action 1 49.99 23 0 1026 SQL in Action 1 55.99 22 1708796420956 1025 SQL in Action 1 47.99 23 1708234681901 3131 SQL in Action 2 59.99 23 0 3130 SQL in Action 2 53.99 22 1708722582793 3129 SQL in Action 2 58.99 23 1708664484823 There are 4 associated data records hidden, leaving only two valid data records: ID NAME EDITION PRICE STORE_ID DELETED_MILLIS 1027 SQL in Action 1 49.99 23 0 3131 SQL in Action 2 59.99 23 0","s":"Multi-Version Data","u":"/jimmer-doc/docs/mapping/advanced/logical-deleted/entity","h":"#multi-version-data","p":343},{"i":350,"t":"If an entity is logically deleted, what effect does it have on associations based on middle tables (using the @JoinTable annotation)? If the middle table also supports logical deletion, that is, the logicalDeletedFilter of the @JoinTable annotation is specified, the middle table records related to the logically deleted entity will also be logically deleted. In [the next document] (./join-table), we will discuss in detail the logical deletion of middle tables. If the deletedWhenEndpointIsLogicallyDeleted of the @JoinTable annotation is set to true, the middle table records related to the logically deleted entity will be physically deleted. If neither of the above two conditions is met, the middle table records related to the logically deleted entity will not be processed at all.","s":"Effects on Middle Tables","u":"/jimmer-doc/docs/mapping/advanced/logical-deleted/entity","h":"#effects-on-middle-tables","p":343},{"i":353,"t":"org.babyfish.jimmer.sql.MappedSuperclass is used to provide abstract super types that can be inherited by entities. The super type itself is not an entity, but can be inherited by multiple entity types to avoid duplicate declaration of the same properties in multiple entities. Let's look at an example. First define the super type: Java Kotlin BaseEntity.java @MappedSuperclass public interface BaseEntity { LocalDateTime createdTime(); @ManyToOne User createdBy(); LocalDateTime modifiedTime(); @ManyToOne User modifiedBy(); } BaseEntity.kt @MappedSuperclass interface BaseEntity { val createdTime: LocalDateTime @ManyToOne val createdBy: User val modifiedTime: LocalDateTime @ManyToOne val modifiedBy: User } Other entities can inherit it: BookStore Java Kotlin BookStore.java @Entity public interface BookStore extends BaseEntity { ...Omit other code... } BookStore.kt @Entity interface BookStore : BaseEntity { ...Omit other code... } Book Java Kotlin Book.java @Entity public interface Book extends BaseEntity { ...Omit other code... } Book.kt @Entity interface Book : BaseEntity { ...Omit other code... } Author Java Kotlin Author.java @Entity public interface Author extends BaseEntity { ...Omit other code... } Author.kt @Entity interface Author : BaseEntity { ...Omit other code... }","s":"Basic Usage","u":"/jimmer-doc/docs/mapping/advanced/mapped-super-class","h":"#basic-usage","p":351},{"i":355,"t":"Types decorated with MappedSuperclass support multiple inheritance. Other types can inherit from multiple MappedSuperclass super types. Add a new abstract interface TenantAware to be inherited by all multi-tenant entities: Java Kotlin TenantAware.java @MappedSuperclass public interface TenantAware { String tenant(); } TenantAware.kt interface TenantAware { val tenant: String } Java Kotlin Book.java @Entity public interface Book extends BaseEntity, TenantAware { ...Omit other code... } Book.kt @Entity interface Book : BaseEntity, TenantAware { ...Omit other code... } Modify Book to inherit not only BaseEntity but also TenantAware. tip The role of @MapperSuperclass is not just to reduce duplicate code, it can also cooperate with two other functions: Global Filters Interceptors When used in cooperation with them, multiple inheritance can provide good flexibility.","s":"Multiple Inheritance","u":"/jimmer-doc/docs/mapping/advanced/mapped-super-class","h":"#multiple-inheritance","p":351},{"i":358,"t":"@org.babyfish.jimmer.sql.OnDissociate is used together with Modification/Save Command and Modification/Delete Command Modification/Save Command Existing data structure in database Data structure expected to be saved by user +-BookStore(id=2) | +-----Book(id=10) | +-----Book(id=11) | \\-----Book(id=12) +-BookStore(id=2) | +-----Book(id=10) | | | | | \\-----Book(id=9) This means: The association between BookStore-2 and Book-10 remains unchanged The association between BookStore-2 and Book-9 needs to be created BookStore-2 needs to be disassociated from Book-11 and Book-12. Modification/Delete Command This is easy to understand. Child objects need to be disassociated before deleting the parent object. @OnDissociate can only be used on foreign key based many-to-one associations, for example: Java Kotlin Book.java @Entity public interface Book { @Null @ManyToOne @OnDissociate(DissociateAction.SET_NULL) BookStore store(); ... } Book.kt @Entity interface Book { @ManyToOne @OnDissociate(DissociateAction.SET_NULL) val store: BookStore? ... } info Although disassociation of child objects is caused by a one-to-many association (or inverse one-to-one) (that is, the parent object abandons some child objects. The one-to-many association here is BookStore.books), the disassociation mode is configured for the inverse many-to-one association (here Book.store). This design is to maintain similarity with configuring cascade properties of foreign keys in database DDLs. For Jimmer, a one-to-many association must be bidirectional, so the many-to-one association that is the mirror image of a known one-to-many association is always known. So there is no problem with this design.","s":"Concepts","u":"/jimmer-doc/docs/mapping/advanced/on-dissociate","h":"#concepts","p":356},{"i":360,"t":"The parameter of the OnDissociate annotation in the above code is called the dissociation mode: There are 5 modes for dissociating child objects Name Description NONE (default) Depend on the global configuration jimmer.default-dissociate-action-checking. If jimmer.default-dissociate-action-checking is true (default) or the foreign key underlying the current association is real (there is a corresponding foreign key constraint in the database, please refer to Real and Fake Foreign Keys), it is treated as CHECK. If jimmer.default-dissociate-action-checking is false and the foreign key underlying the current association is fake (there is no corresponding foreign key constraint in the database, please refer to Real and Fake Foreign Keys), it is treated as LAX. LAX This option is only valid for pseudo foreign keys (please refer to Real and Fake Foreign Keys), otherwise it will be ignored, the same as CHECK. Dissociation operations are supported even if there are child objects. Even if the parent object is deleted (dissociation mode is also adopted by delete commands), dangling pseudo foreign keys of child objects are allowed (even if pseudo foreign keys are left dangling, the query system can still work normally). CHECK If there are child objects, disassociation is not supported, the operation is prevented by throwing an exception. SET_NULL Set the foreign key of the disassociated child object to null. The prerequisite is that the many-to-one associated property of the child object is nullable; otherwise, attempting this configuration will lead to an exception. DELETE Delete the disassociated child objects. This article only introduces the configuration of OnDissociate. For how to use it further, please refer to Save Command/Dissociation Operations and Delete Commands.","s":"Dissociation Modes","u":"/jimmer-doc/docs/mapping/advanced/on-dissociate","h":"#dissociation-modes","p":356},{"i":362,"t":"Configuration specified by the annotation @OnDissociate is called static configuration. Sometimes, different businesses may have different requirements for dissociation operations. Therefore, dissociation configurations can be dynamically overridden at runtime. Modification/Save Command Java Kotlin sqlClient .getEntities() .saveCommand(book) .setDissociateAction(BookProps.STORE, DissociateAction.SET_NULL) .execute(); sqlClient.save(book) { .setDissociateAction(Book::store, DissociateAction.SET_NULL) } Modification/Delete Command Java Kotlin DeleteResult result = sqlClient .getEntities() .deleteCommand(BookStore.class, 1L) .configure(it -> it .setDissociateAction( BookProps.STORE, DissociateAction.SET_NULL ) ) .execute(); val result = sqlClient .entities .delete(BookStore::class, 1L) { setDissociateAction( Book::store, DissociateAction.SET_NULL ) }","s":"Dynamic Overrides","u":"/jimmer-doc/docs/mapping/advanced/on-dissociate","h":"#dynamic-overrides","p":356},{"i":364,"t":"caution Remote association is a product of combining Jimmer with microservice architecture. It will be introduced in detail in Spring Cloud and Remote Association. The purpose of this article is not to systematically explain remote associations, just to introduce the mapping configuration required for remote associations.","s":"Remote Association","u":"/jimmer-doc/docs/mapping/advanced/remote","h":"","p":363},{"i":366,"t":"The @Entity annotation has an optional parameter microServiceName whose default value is \"\". Association properties involve two entity types. Since associations must point from the source to the target (self association properties are special, the source and target overlap): If the microServiceName of the source entity and target entity of the association property are equal, then this association is a local association (All entities in the examples before this article use the default microServiceName, so they are local associations). If the microServiceName of the source entity and target entity of the association property are not equal, then this association is a remote association. For example: Owning side (required): Book.authors Java Kotlin Book.java @Entity(microServiceName = \"book-service\") public interface Book { @ManyToMany List authors(); ...Omit other code... } Book.kt @Entity(microServiceName = \"book-service\") interface Book { @ManyToMany val authors: List ...Omit other code... } Inverse side (optional): Author.authors Java Kotlin Author.java @Entity(microServiceName = \"author-service\") public interface Author { @ManyToMany(mappedBy = \"authors\") List books(); ...Omit other code... } Author.kt @Entity(microServiceName = \"author-service\") interface Author { @ManyToMany(mappedBy = \"authors\") val books: List ...Omit other code... } Here, the microservice name of Book is book-service, and the microservice name of Author is author-service. The two are not equal, so Book.authors and Author.books are remote associations.","s":"@Entity","u":"/jimmer-doc/docs/mapping/advanced/remote","h":"#entity","p":363},{"i":368,"t":"As a super type, MappedSuperclass has two usages: Can contain association properties, but must belong to the same microservice Java Kotlin BookServiceCommonEntity.java @MappedSuperclass(microServiceName = \"book-service\") public interface BookServiceCommonEntity { LocalDateTime createdTime(); @ManyToOne User createdBy(); LocalDateTime modifiedTime(); @ManyToOne User modifiedBy(); } BookServiceCommonEntity.kt @MappedSuperclass(microServiceName = \"book-service\") interface BookServiceCommonEntity { val createdTime: LocalDateTime @ManyToOne val createdBy: User val modifiedTime: LocalDateTime @ManyToOne val modifiedBy: User } Here BookServiceCommonEntity contains association properties createdBy and modifiedBy, but only Entity or other MappedSuperclass belonging to the microservice \"book-service\" can inherit it. Can span any microservices, but must not contain association properties Java Kotlin CommonEntity.java @MappedSuperclass(acrossMicroServices = true) public interface CommonEntity { LocalDateTime createdTime(); LocalDateTime modifiedTime(); } CommonEntity.kt @MappedSuperclass(acrossMicroServices = true) interface CommonEntity { val createdTime: LocalDateTime val modifiedTime: LocalDateTime } Here CommonEntity can span any microservices. Any Entity or other MappedSuperclass under any microservice can inherit it, but it itself does not contain any association properties.","s":"@MappedSuperclass","u":"/jimmer-doc/docs/mapping/advanced/remote","h":"#mappedsuperclass","p":363},{"i":370,"t":"View properties do not maintain their own data, they are just another representation of another attribute (called original attribute) of their owning entity type. View properties and original properties share the same underlying data, the only difference is that the returned data format is different from the original attribute. In this article, you will learn about these annotations: org.babyfish.jimmer.sql.IdView org.babyfish.jimmer.sql.ManyToManyView","s":"View Properties","u":"/jimmer-doc/docs/mapping/advanced/view/","h":"","p":369},{"i":372,"t":"To enable logical deletion for the middle table, the property needs to be specified for the org.babyfish.jimmer.sql.JoinTable annotation to indicate whether the data is normal or has been deleted. Once a logical deletion attribute is configured for the middle table, when any entity on either end is logically deleted, all related middle table records will be logically deleted. All JOIN operations for the current association will be automatically added with the condition and logical deletion flag <> already deleted to give the illusion that some associations have been deleted.","s":"Join Table","u":"/jimmer-doc/docs/mapping/advanced/logical-deleted/join-table","h":"","p":371},{"i":374,"t":"The logical deletion flag attribute can be one of the following types: boolean: must be non-null int: must be non-null enum: must be non-null long/Long: can be null or non-null UUID: must be non-null Date: must be nullable Type Code Deleted State Initialized State boolean Java Kotlin @ManyToMany @JoinTable( ...Omit other arguments..., logicalDeletedFilter = @JoinTable.LogicalDeletedFilter( columnName = \"DELETED\", type = boolean.class, value = \"true\" ) ) List authors(); @ManyToMany @JoinTable( ...Omit other arguments..., logicalDeletedFilter = JoinTable.LogicalDeletedFilter( columnName = \"DELETED\", type = boolean.class, value = \"true\" ) ) val authors: List true false Java Kotlin @ManyToMany @JoinTable( ...Omit other arguments..., logicalDeletedFilter = @JoinTable.LogicalDeletedFilter( columnName = \"ACTIVE\", type = boolean.class, value = \"false\" ) ) List authors(); @ManyToMany @JoinTable( ...Omit other arguments..., logicalDeletedFilter = JoinTable.LogicalDeletedFilter( columnName = \"ACTIVE\", type = boolean.class, value = \"false\" ) ) val authors: List false true int Java Kotlin @ManyToMany @JoinTable( ...Omit other arguments..., logicalDeletedFilter = @JoinTable.LogicalDeletedFilter( columnName = \"STATE\", type = int.class, value = \"1\", initializedValue = \"0\" ) ) List authors(); @ManyToMany @JoinTable( ...Omit other arguments..., logicalDeletedFilter = JoinTable.LogicalDeletedFilter( columnName = \"STATE\", type = int.class, value = \"1\", initializedValue = \"0\" ) ) val authors: List 1 0 Enum Java Kotlin @ManyToMany @JoinTable( ...Omit other arguments..., logicalDeletedFilter = @JoinTable.LogicalDeletedFilter( columnName = \"STATE\", type = State.class, value = \"DELETED\", initializedValue = \"INITIALIZED\" ) ) List authors(); @ManyToMany @JoinTable( ...Omit other arguments..., logicalDeletedFilter = JoinTable.LogicalDeletedFilter( columnName = \"STATE\", type = State.class, value = \"DELETED\", initializedValue = \"INITIALIZED\" ) ) val authors: List DELETED INITIALIZED ✩ long Java Kotlin @ManyToMany @JoinTable( ...Omit other arguments..., logicalDeletedFilter = @JoinTable.LogicalDeletedFilter( columnName = \"DELETED_MILLIS\", type = long.class ) ) List authors(); @ManyToMany @JoinTable( ...Omit other arguments..., logicalDeletedFilter = JoinTable.LogicalDeletedFilter( columnName = \"DELETED_MILLIS\", type = long.class ) ) val authors: List Current milliseconds 0L ✩ Nullable Long Java Kotlin @ManyToMany @JoinTable( ...Omit other arguments..., logicalDeletedFilter = @JoinTable.LogicalDeletedFilter( columnName = \"DELETED_MILLIS\", type = Long.class, nullable = true ) ) List authors(); @ManyToMany @JoinTable( ...Omit other arguments..., logicalDeletedFilter = JoinTable.LogicalDeletedFilter( columnName = \"DELETED_MILLIS\", type = Long.class, nullable = true ) ) val authors: List Current milliseconds null ✩ UUID Java Kotlin @ManyToMany @JoinTable( ...Omit other arguments..., logicalDeletedFilter = @JoinTable.LogicalDeletedFilter( columnName = \"DELETED_DATA\", type = UUID.class ) ) List authors(); @ManyToMany @JoinTable( ...Omit other arguments..., logicalDeletedFilter = @JoinTable.LogicalDeletedFilter( columnName = \"DELETED_DATA\", type = UUID.class ) ) val authors: List Random UUID UUID with all bytes as 0 ✩ Nullable UUID Java Kotlin @ManyToMany @JoinTable( ...Omit other arguments..., logicalDeletedFilter = @JoinTable.LogicalDeletedFilter( columnName = \"DELETED_DATA\", type = UUID.class, nullable = true ) ) List authors(); @ManyToMany @JoinTable( ...Omit other arguments..., logicalDeletedFilter = JoinTable.LogicalDeletedFilter( columnName = \"DELETED_DATA\", type = UUID.class, nullable = true ) ) val authors: List Random UUID null Nullable LocalDateTime ✩ Java Kotlin @ManyToMany @JoinTable( ...Omit other arguments..., logicalDeletedFilter = @JoinTable.LogicalDeletedFilter( columnName = \"DELETED_TIME\", type = LocalDateTime.class, nullable = true, value = \"now\" ) ) List authors(); @ManyToMany @JoinTable( ...Omit other arguments..., logicalDeletedFilter = JoinTable.LogicalDeletedFilter( columnName = \"DELETED_TIME\", type = LocalDateTime.class, nullable = true, value = \"now\" ) ) val authors: List Current Time null Java Kotlin @ManyToMany @JoinTable( ...Omit other arguments..., logicalDeletedFilter = @JoinTable.LogicalDeletedFilter( columnName = \"CREATED_TIME\", type = LocalDateTime.class, nullable = true, value = \"null\" ) ) List authors(); @ManyToMany @JoinTable( ...Omit other arguments..., logicalDeletedFilter = JoinTable.LogicalDeletedFilter( columnName = \"CREATED_TIME\", type = LocalDateTime.class, nullable = true, value = \"null\" ) ) val authors: List null Current Time Where ✩ in the first or second column indicates that the current configuration method supports multi-version data to be discussed in the next section. info Supporting logical deletion without considering multi-version data issues is less mature. Therefore, it is recommended to use the logical deletion configuration that supports multi-version data. Current milliseconds, the default behavior is System.currentMillis(), which is the behavior of the default org.babyfish.jimmer.sql.meta.LogicalDeletedLongGenerator. If this behavior is unsatisfactory, a custom class can be implemented that implements the LogicalDeletedValueGenerator interface, and configured with: @JoinTable.LogicalDeletedFilter(generatedType = YourGenerator.class) @JoinTable.LogicalDeletedFilter(generatedRef = YourGenerator.class), where generatorRef indicates the name of the object in the IOC container management framework Random UUID, the default behavior is UUID.randomUUID(), which is the behavior of the default org.babyfish.jimmer.sql.meta.LogicalDeletedUUIDGenerator. If this behavior is unsatisfactory, a custom class can be implemented that implements the LogicalDeletedValueGenerator interface, and configured with: @JoinTable.LogicalDeletedFilter(generatedType = YourGenerator.class) @JoinTable.LogicalDeletedFilter(generatedRef = YourGenerator.class), where generatorRef indicates the name of the object in the IOC container management framework","s":"Usage","u":"/jimmer-doc/docs/mapping/advanced/logical-deleted/join-table","h":"#usage","p":371},{"i":376,"t":"Logical deletion does not actually delete data, it only hides it. This means that data appears in multiple versions. Take the configuration that supports multi-version data as an example: Java Kotlin @ManyToMany @JoinTable( name = \"BOOK_AUTHOR_MAPPING\", joinColumnName = \"BOOK_ID\", inverseJoinColumnName = \"AUTHOR_ID\", logicalDeletedFilter = @JoinTable.LogicalDeletedFilter( columnName = \"DELETED_MILLIS\", type = long.class ) ) List authors(); @ManyToMany @JoinTable( name = \"BOOK_AUTHOR_MAPPING\", joinColumnName = \"BOOK_ID\", inverseJoinColumnName = \"AUTHOR_ID\",| logicalDeletedFilter = @JoinTable.LogicalDeletedFilter( columnName = \"DELETED_MILLIS\", type = long.class ) ) val authors: List For example, the BOOK_AUTHOR_MAPPING table has three columns, all as part of the primary key alter table BOOK_AUTHOR_MAPPING add pk_BOOK_AUTHOR_MAPPING primary key( BOOK_ID, AUTHOR_ID, DELETED_MILLIS ); If the table input is as follows: BOOK_ID AUTHOR_ID DELETED_MILLIS 97 23 0 97 23 1708796420956 97 23 1708234681901 249 11 0 249 11 1708722582793 249 11 1708664484823 There are 4 associated data records hidden, leaving only two valid data records: BOOK_ID AUTHOR_ID DELETED_MILLIS 97 23 0 249 11 0","s":"Multi-Version Data","u":"/jimmer-doc/docs/mapping/advanced/logical-deleted/join-table","h":"#multi-version-data","p":371},{"i":379,"t":"In Basic Mapping/Associative Mapping, we learned about the classic associative mappings in ORM, including one-to-one, many-to-one, one-to-many and many-to-many. However, there is one scenario that makes the choice of mapping mode very tangled. To show this scenario, let's start with a familiar scenario.","s":"Limitations of classic ORM associations","u":"/jimmer-doc/docs/mapping/advanced/view/many-to-many-view","h":"#limitations-of-classic-orm-associations","p":377},{"i":381,"t":"Let's look at a piece of DDL create table book( ...omit... )engine=innodb;; create table author( ...omit... ) engine=innodb; /* highlight-next-line */ create table book_author_mapping( book_id bigint unsigned not null, author_id bigint unsigned not null ) engine=innodb; alter table book_author_mapping add constraint pk_book_author_mapping primary key(book_id, author_id) ; alter table book_author_mapping add constraint fk_book_author_mapping__book foreign key(book_id) references book(id) on delete cascade ; alter table book_author_mapping add constraint fk_book_author_mapping__author foreign key(author_id) references author(id) on delete cascade ; In this piece of DDL, book_author_mapping table is very special, it only has two foreign keys, one pointing to book table, and one pointing to author table. This kind of subtable with only two foreign keys is used to express the many-to-many association between two parent tables. ORM's many-to-many mapping will hide the intermediate table, that is, the intermediate table does not correspond to a Java/Kotlin entity type. Therefore, the intermediate table does not need an independent primary key, but directly uses the two foreign keys as a combined primary key. info In addition to the two associative foreign keys, the intermediate table must not have any other fields, which is a limitation of many-to-many associations in ORM. The corresponding many-to-many association in ORM is as follows: Owning side: Book.authors Java Kotlin Book.java @Entity public interface Book { @ManyToMany List authors(); ...other code omitted... } Book.kt @Entity interface Book { @ManyToMany val authors: List ...other code omitted... } Inverse side (optional): Author.books Java Kotlin Author.java @Entity public interface Author { @ManyToMany(mappedBy = \"authors\") List books(); ...other code omitted... } Author.kt @Entity interface Author { @ManyToMany(mappedBy = \"authors\") val books: List ...other code omitted... }","s":"Undisputed many-to-many association","u":"/jimmer-doc/docs/mapping/advanced/view/many-to-many-view","h":"#undisputed-many-to-many-association","p":377},{"i":383,"t":"Let's look at the second scenario, first, look at a piece of DDL create table order_( ...omit... ) engine=innodb; create table product( ...omit... ) engine=innodb; /* highlight-next-line */ create table order_item( id bigint unsigned not null auto_increment primary key, order_id bigint unsigned not null, product_id bigint unsigned not null, /* highlight-next-line */ quantity int not null, /* highlight-next-line */ unit_price numeric(10, 2) not null ) engine=innodb; alter table order_item add constraint business_key_order_item unique(order_id, product_id) ; alter table order_item add constraint fk_order_item__order foreign key(order_id) references order_(id) ; alter table order_item add constraint fk_order_item__product foreign key(product_id) references product(id) ; This is a classic order - order item - product association. Among them, order-item looks a bit like the intermediate table of many-to-many, because it has two foreign keys: order_id pointing to the order_ table and product_id pointing to the product table. However, order-item is not an intermediate table, because it has other business fields, quantity representing quantity of goods, and unit_price representing a snapshot of the price of goods at the time of order. Fortunately, for the classic order - order item - product association, it is more intuitive to think of order_item as an independent entity, with two many-to-one associations pointing to order_ and product respectively; Rather than viewing order-item as a join table and thinking there is a many-to-many relationship between order_ and product. It is precisely because order_item is regarded as an independent entity that order_item uses an independent primary key. We can map these three tables in ORM using two many-to-one associations OrderItem.order and OrderItem.product Java Kotlin OrderItem.java @Entity public interface OrderItem { @ManyToOne Order order(); @ManyToOne Product product(); int quantity(); BigDecimal unitPrice(); ...other code omitted... } OrderItem.kt @Entity interface OrderItem { @ManyToOne val order: Order @ManyToOne val product: Product val quantity: Int val unitPrice: BigDecimal ...other code omitted... } Order.items In such systems, it is often necessary to get the detail list according to the order, so we define a one-to-many property Order.items as a mirror of OrderItem.order. Java Kotlin Order.java @Entity @Table(name = \"ORDER_\") public interface Order { @OneToMany(mappedBy = \"order\") List items(); ...other code omitted... } Order.kt @Entity @Table(name = \"ORDER_\") interface Order { @OneToMany(mappedBy = \"order\") val items: List ...other code omitted... } Do not provide Product.items In such systems, it is rarely necessary to get the detail list based on the product (if starting the analysis from the product side, it is usually a complex query rather than a simple association), so a one-way OrderItem.product association is sufficient. So there is no need to show the code for the Product entity.","s":"Undisputed double many-to-one association","u":"/jimmer-doc/docs/mapping/advanced/view/many-to-many-view","h":"#undisputed-double-many-to-one-association","p":377},{"i":385,"t":"In the previous text, we showed two business scenarios Scenario 1: The intermediate table book_author_mapping is very clean, with only two foreign key fields, and is naturally mapped to a many-to-many association Scenario 2: order_item looks like an intermediate table but is not an intermediate table, because in addition to the two foreign keys it also needs to have other business fields. Fortunately, people will choose to treat OrderItem as an independent entity and use two many-to-one associations to string the three entity types together. Next, let's look at scenario 3, first look at the DDL: create table student( ...omit... )engine=innodb;; create table course( ...omit... ) engine=innodb; /* highlight-next-line */ create table learning_link ( id bigint unsigned not null auto_increment primary key, student_id bigint unsigned not null, course_id bigint unsigned not null, /* highlight-next-line */ score int ) engine=innodb; alter table learning_link add constraint pk_student_course_mapping primary key(student_id, course_id) ; alter table learning_link add constraint fk_student_course_mapping__student foreign key(student_id) references student(id) on delete cascade ; alter table learning_link add constraint fk_student_course_mapping__course foreign key(course_id) references course(id) on delete cascade ; This piece of DDL represents the elective course system in schools. There is a many-to-many relationship between students and elective courses. For students, it is of course very important to know which courses they have chosen For schools, it is also very important to know which students have chosen each course, because teacher resources and teaching venues need to be arranged based on this information That is, for the student entity and the course entity, associating with each other and querying each other is an important and high frequency operation. Therefore, abstracting bidirectional many-to-many associations between student and course is a very good choice. Unfortunately, the elective relationship table learning_link has a score field that can be null, null indicating that the exam has not yet taken place, non-null indicating the score after the exam. Because of the existence of this field, the intermediate table is no longer clean, and cannot be simply mapped to the classic ORM many-to-many association. That is, this is not a simple scenario 1. Of course, we can handle this problem using the method of scenario 2, treating learning_link as an independent entity, and using two many-to-one associations to string the three entity types together. However, for a large part of the upper layer business, what they really care about is only the mutual association between student and course, and they don't care about the score field of the learning_link table. (That is, the non-foreign key business field learning_link.score of the intermediate table is far less important than the relevant fields in scenario 2). In this case, scenario 2's solution will bring a higher cognitive burden, and scenario 1's way of thinking is obviously simpler. info This scenario is actually the most tangled scenario in classic ORM, which cannot be simply mapped to many-to-many associations, while hoping that some upper layer business can adopt the many-to-many mentality to simplify the problem. @ManyToManyView is a powerful tool designed for such scenarios.","s":"The controversial, tangled scenario","u":"/jimmer-doc/docs/mapping/advanced/view/many-to-many-view","h":"#the-controversial-tangled-scenario","p":377},{"i":387,"t":"For the discussed scenario 3 above, Jimmer gave a two-step solution. Basic association mapping: First, treat learning_link as an independent entity according to scenario 2, and provide two many-to-one associations pointing to student and course respectively; Conversely, student and course also use one-to-many associations to reference learning_link. That is, use two bidirectional one-to-many associations to string the three entity types together. Use @ManyToManyView: Then, on the basis of the first step, use @ManyToManyView to quickly simulate the effect of scenario 1.","s":"Getting Started with ManyToManyView","u":"/jimmer-doc/docs/mapping/advanced/view/many-to-many-view","h":"#getting-started-with-manytomanyview","p":377},{"i":389,"t":"LearningLink.student and LearningLink.course Java Kotlin LearningLink.java @Entity public interface LearningLink { @ManyToOne Student student(); ① @ManyToOne Course course(); ② Integer score(); ...other code omitted... } LearningLink.kt @Entity interface LearningLink { @ManyToOne val student: Student ① @ManyToOne val course: Course ② val score: Int? ...other code omitted... } Where ① and ② will be referenced by subsequent code Student.learningLinks Java Kotlin Student.java @Entity public interface Student { @OneToMany(mappedBy = \"student\") List learningLinks(); ③ ...other code omitted... } Student.kt @Entity interface Student { @OneToMany(mappedBy = \"student\") val learningLinks: List ③ ...other code omitted... } Where ③ will be referenced by subsequent code Course.learningLinks Java Kotlin Course.java @Entity public interface Course { @OneToMany(mappedBy = \"course\") List learningLinks(); ④ ...other code omitted... } Course.kt @Entity interface Course { @OneToMany(mappedBy = \"course\") val learningLinks: List ④ ...other code omitted... } Where ④ will be referenced by subsequent code","s":"Basic relationship mapping","u":"/jimmer-doc/docs/mapping/advanced/view/many-to-many-view","h":"#basic-relationship-mapping","p":377},{"i":391,"t":"Simulate many-to-many association: Student.courses Java Kotlin Student.java @Entity public interface Student { @ManyToManyView( prop = \"learningLinks\", ❶ -> ③ deeperProp = \"course\" ❷ -> ② ) List courses(); // The one-to-many association `learningLinks` // has been declared in step 1 @OneToMany(mappedBy = \"student\") List learningLinks(); ③ ...other code omitted... } Student.kt @Entity interface Student { @ManyToManyView( prop = \"learningLinks\", ❶ -> ③ deeperProp = \"course\" ❷ -> ② ) val courses: List // The one-to-many association `learningLinks` // has been declared in step 1 @OneToMany(mappedBy = \"student\") val learningLinks: List ③ ...other code omitted... } The current property Student.courses can be obtained in two steps: ❶ prop = \"learningLinks\" First, get all LearningLink objects through another property of the current entity Student.learningLinks ③ ❷ deeperProp = \"course\" For each LearningLink object obtained in the previous step, Course can be further obtained through the LearningLink.course property ② tip Since the LearningLink entity has only one many-to-one association pointing to the Course entity, there is no ambiguity, so deeperProp = \"course\" can be omitted here Simulate many-to-many association: Course.students Java Kotlin Course.java @Entity public interface Course { @ManyToManyView( prop = \"learningLinks\", ❶ -> ④ deeperProp = \"student\" ❷ -> ① ) List students(); // The one-to-many association `learningLinks` has been declared in step 1 @OneToMany(mappedBy = \"course\") List learningLinks(); ④ ...other code omitted... } Course.kt @Entity interface Course { @ManyToManyView( prop = \"learningLinks\", ❶ -> ④ deeperProp = \"student\" ❷ -> ① ) val students: List // The one-to-many association `learningLinks` has been declared in step 1 @OneToMany(mappedBy = \"course\") val learningLinks: List ④ ...other code omitted... } The current property Course.students can be obtained in two steps: ❶ prop = \"learningLinks\" First, get all LearningLink objects through another property of the current entity Course.learningLinks ④ ❷ deeperProp = \"student\" For each LearningLink object obtained in the previous step, Student can be further obtained through the LearningLink.student property ① tip Since the LearningLink entity has only one many-to-one association pointing to the Student entity, there is no ambiguity, so deeperProp = \"student\" can be omitted here","s":"Using @ManyToManyView","u":"/jimmer-doc/docs/mapping/advanced/view/many-to-many-view","h":"#using-manytomanyview","p":377},{"i":393,"t":"The property declared by @ManyToManyView does not maintain its own data, it is only a view of the original property, which proxies and wraps the collection returned by the original property. Take the Java example in this article Student side as an example (the Course side is the same). Original association property: List learningLinks(); View association property: List courses(); You can understand the ManyToManyView view property with this pseudocode: @Override public List courses() { return new ListProxy<>( this.learningLinks(), LearningLink::course ); } The view association property returns a proxy collection that wraps the collection of the original property and transforms the elements of the original collection. It is obvious that the two are essentially the same and share the same data. When constructing entity objects, only the original property can be set, not the view property. This is different from @IdView. For @IdView, both the original property and the view property can be set. Whether it is the original property or the view property, the preprocessor will generate code to match them, so both can be used in object fetchers and strongly typed SQL DSL.","s":"The essence of @ManyToManyView","u":"/jimmer-doc/docs/mapping/advanced/view/many-to-many-view","h":"#the-essence-of-manytomanyview","p":377},{"i":395,"t":"In this series of articles, we will introduce base mappings.","s":"Base mapping","u":"/jimmer-doc/docs/mapping/base/","h":"","p":394},{"i":397,"t":"Here, you will learn about the most important capability of ORM: entity relationship mapping. You will learn about these annotations: org.babyfish.jimmer.sql.OneToOne org.babyfish.jimmer.sql.ManyToOne org.babyfish.jimmer.sql.OneToMany org.babyfish.jimmer.sql.ManyToMany org.babyfish.jimmer.sql.JoinColumn org.babyfish.jimmer.sql.JoinTable caution For associations, the type of the basic properties in the entity type should be the associated object, not the associated Id. If you want to define associated Id properties, please First complete the association mapping according to this chapter Then add associated Id properties according to IdView","s":"Association Mapping","u":"/jimmer-doc/docs/mapping/base/association/","h":"","p":396},{"i":399,"t":"This chapter introduces how to use the @org.babyfish.jimmer.sql.ManyToMany annotation to declare many-to-many association properties. Many-to-many supports bidirectional association. For bidirectional associations, one side must be the owning side, and the other side must be the inverse side. Owning side (required): The actual mapping between the database and association properties to implement unidirectional many-to-many association. Inverse side (optional): If a unidirectional association already exists, the inverse side can be configured as a mirror of the owning side to form a bidirectional association. Let's assume there are two entity types Book and Author, and establish a bidirectional many-to-many association between them. info Different from JPA/Hibernate, the owning side and inverse side can be chosen arbitrarily. Both can be used to persist associations. The example in this article chooses: Owning side (required): Book.authors Inverse side (optional): Author.books","s":"Many To Many","u":"/jimmer-doc/docs/mapping/base/association/many-to-many","h":"","p":398},{"i":401,"t":"Java Kotlin Book.java @Entity public interface Book { @ManyToMany List authors(); ...Omit other code... } Book.kt @Entity interface Book { @ManyToMany val authors: List ...Omit other code... } Many-to-many associations must be implemented based on a join table, even if the @JoinTable annotation is not used in the above code, it is actually equivalent to using the annotation. If no properties are specified for @JoinTable, and even @JoinTable itself is omitted (like the previous code), Jimmer will deduce the column names corresponding to the authors property based on the naming strategy. If the default naming strategy is not overridden by the user, the deduced join table information is: Join table name: BOOK_AUTHOR_MAPPING Join table foreign key column pointing to current entity: BOOK_ID Join table foreign key column pointing to associated entity: AUTHOR_ID So the previous code is equivalent to: Java Kotlin Book.java @Entity public interface Book { @ManyToMany @JoinTable( name = \"BOOK_AUTHOR_MAPPING\", joinColumnName = \"BOOK_ID\", inverseJoinColumnName = \"AUTHOR_ID\" ) List authors(); ...Omit other code... } Book.kt @Entity interface Book { @ManyToMany @JoinTable( name = \"BOOK_AUTHOR_MAPPING\", joinColumnName = \"BOOK_ID\", inverseJoinColumnName = \"AUTHOR_ID\" ) val authors: List ...Omit other code... } The join table BOOK_AUTHOR_MAPPING is defined as: create table BOOK_AUTHOR_MAPPING( BOOK_ID bigint not null, AUTHOR_ID bigint not null ); alter table AUTHOR_MAPPING add constraint PK_AUTHOR_MAPPING primary(BOOK_ID, AUTHOR_ID); // If foreign key pointing to current entity is real, // create foreign key constraint alter table BOOK_AUTHOR_MAPPING add constraint FK_BOOK_AUTHOR_MAPPING__BOOK foreign key(BOOK_ID) references BOOK(ID); // If foreign key pointing to associated entity is real, // create foreign key constraint alter table BOOK_AUTHOR_MAPPING add constraint FK_BOOK_AUTHOR_MAPPING__AUTHOR foreign key(AUTHOR_ID) references AUTHOR(ID); The join table has only two foreign keys, both non-null. The join table maintains the association by inserting and deleting data, never storing null data itself. The join table has no corresponding ORM entity and does not need an independent primary key. The two foreign keys combined can serve as the primary key. caution Note The @ManyToMany association property must be non-null. If an object requires fetching its many-to-many association properties, then for the current object that has no corresponding associated object, the value of this property is a collection of length 0 rather than null.","s":"Owning Side","u":"/jimmer-doc/docs/mapping/base/association/many-to-many","h":"#owning-side","p":398},{"i":403,"t":"The configuration of the inverse side is very simple, just specify that Author.books is the mirror of Book.authors. In the following code: Left: The owning side discussed in the previous section Right: The inverse side association Author.books introduced in this section, which is the mirror of Book.authors Here, @ManyToMany(mappedBy = \"store\") indicates that the current property Authors.books is the mirror of Book.authors. Java Kotlin Book.java @Entity public interface Book { @ManyToMany @JoinTable( name = \"BOOK_AUTHOR_MAPPING\", joinColumnName = \"BOOK_ID\", inverseJoinColumnName = \"AUTHOR_ID\" ) List authors(); ...Omit other code... } Book.kt @Entity interface Book { @ManyToMany @JoinTable( name = \"BOOK_AUTHOR_MAPPING\", joinColumnName = \"BOOK_ID\", inverseJoinColumnName = \"AUTHOR_ID\" ) val authors: List ...Omit other code... } Java Kotlin Author.java @Entity public interface Author { // `mappedBy` indicates `Author.books` // is the mirror of `Book.authors` @ManyToMany(mappedBy = \"authors\") List books(); ...Omit other code... } Author.kt @Entity interface Author { // `mappedBy` indicates `Author.books` // is the mirror of `Book.authors` @ManyToMany(mappedBy = \"authors\") val books: List ...Omit other code... } caution Note: Once the mappedBy property of @ManyToMany is specified, @JoinTable must not be used. Like the @ManyToMany association property on the owning side, the @ManyToMany association on the inverse side must also be non-null for the same reason.","s":"Inverse Side","u":"/jimmer-doc/docs/mapping/base/association/many-to-many","h":"#inverse-side","p":398},{"i":405,"t":"For the many-to-many association discussed in this article, no business fields other than the two foreign keys can be defined on the join table. If you want to define more other business fields in the join table of the many-to-many association, please refer to ManyToManyView.","s":"If business fields need to be added to the join table","u":"/jimmer-doc/docs/mapping/base/association/many-to-many","h":"#if-business-fields-need-to-be-added-to-the-join-table","p":398},{"i":407,"t":"This chapter introduces how to use the @org.babyfish.jimmer.sql.ManyToOne annotation to declare many-to-one association properties. There are two ways to implement many-to-one associations: based on foreign key and based on join table.","s":"Many To One","u":"/jimmer-doc/docs/mapping/base/association/many-to-one","h":"","p":406},{"i":409,"t":"Java Kotlin Book.java @Entity public interface Book { @ManyToOne BookStore store(); ...Omit other code... } Book.kt @Entity interface Book { @ManyToOne val store: BookStore ...Omit other code... } Here @JoinColumn is not used together to explicitly specify the foreign key column name. Jimmer will deduce the column name corresponding to the store property based on the naming strategy. If the default naming strategy is not overridden by the user, the foreign key column name of the store property is STORE_ID. So the previous code is equivalent to: Java Kotlin Book.java @Entity public interface Book { @ManyToOne @JoinColumn(name = \"STORE_ID\") BookStore store(); ...Omit other code... } Book.kt @Entity interface Book { @ManyToOne @JoinColumn(name = \"STORE_ID\") val store: BookStore ...Omit other code... } The foreign key can be real or fake. Fake foreign keys are discussed in subsequent documents. Here we assume the foreign key is real, so the corresponding constraint in the database is: // If foreign key pointing to associated entity is real, // create foreign key constraint alter table BOOK add constraint FK_BOOK__BOOK_STORE /* highlight-next-line */ foreign key(STORE_ID) references BOOK_STORE(ID);","s":"1. Based on Foreign Key","u":"/jimmer-doc/docs/mapping/base/association/many-to-one","h":"#1-based-on-foreign-key","p":406},{"i":411,"t":"Java Kotlin Book.java @Entity public interface Book { @Nullable @ManyToOne @JoinTable BookStore store(); ... } Book.kt @Entity interface Book { @Nullable @ManyToOne @JoinTable val store: BookStore? ... } Here, no properties are specified for @JoinTable. Jimmer will deduce the column names corresponding to the store property based on the naming strategy. If the default naming strategy is not overridden by the user, the deduced join table information is: Join table name: BOOK_BOOK_STORE_MAPPING Join table foreign key column pointing to current entity: BOOK_ID Join table foreign key column pointing to associated entity: STORE_ID So the previous code is equivalent to: Java Kotlin Book.java @Entity public interface Book { @Null @ManyToOne @JoinTable( name = \"BOOK_BOOK_STORE_MAPPING\", joinColumnName = \"BOOK_ID\", inverseJoinColumnName = \"STORE_ID\" ) BookStore store(); ... } Book.kt @Entity interface Book { @ManyToOne @JoinTable( name = \"BOOK_BOOK_STORE_MAPPING\", joinColumnName = \"BOOK_ID\", inverseJoinColumnName = \"STORE_ID\" ) val store: BookStore? ... } The join table BOOK_BOOK_STORE_MAPPING is defined as: create table BOOK_BOOK_STORE_MAPPING( BOOK_ID bigint not null, STORE_ID bigint not null ); alter table BOOK_STORE_MAPPING add constraint PK_BOOK_STORE_MAPPING primary(BOOK_ID, STORE_ID); // If foreign key pointing to current entity is real, // create foreign key constraint alter table BOOK_BOOK_STORE_MAPPING add constraint FK_BOOK_BOOK_STORE_MAPPING__BOOK foreign key(BOOK_ID) references BOOK(ID); // If foreign key pointing to associated entity is real, // create foreign key constraint alter table BOOK_BOOK_STORE_MAPPING add constraint FK_BOOK_BOOK_STORE_MAPPING__STORE foreign key(STORE_ID) references BOOK_STORE(ID); // This constraint is very important. // Otherwise this join table expresses a many-to-many association // rather than a many-to-one association alter table BOOK_BOOK_STORE_MAPPING add constraint UQ_BOOK_BOOK_STORE_MAPPING__BOOK_ID unique(BOOK_ID); The join table has only two foreign keys, both non-null. The join table maintains the association by inserting and deleting data, never storing null data itself. The join table has no corresponding ORM entity and does not need an independent primary key. The two foreign keys combined can serve as the primary key. By default, the join table represents a many-to-many association. To degrade it to a many-to-one association, a unique constraint must be specified for the foreign key BOOK_ID pointing to the current entity. caution Unless for compatibility with existing database design, many-to-one associations are recommended to use foreign keys directly instead of join tables. Once a many-to-one association is mapped using a join table, the Jimmer association property must be nullable, because the database cannot guarantee that any entity must have corresponding data in the join table.","s":"2. Based on Join Table","u":"/jimmer-doc/docs/mapping/base/association/many-to-one","h":"#2-based-on-join-table","p":406},{"i":413,"t":"Unlike JPA, Jimmer does not support unidirectional one-to-many associations. One-to-many associations can only exist as mirrors of many-to-one associations. That is, one-to-many associations necessarily imply bidirectional associations. In the following code: Left: Book.store discussed in Many To One Right: BookStore.books to be discussed in this article, which is the mirror of Book.store Java Kotlin Book.java @Entity public interface Book { @ManyToOne @JoinColumn(name = \"STORE_ID\") BookStore store(); ...Omit other code... } Book.kt @Entity interface Book { @ManyToOne @JoinColumn(name = \"STORE_ID\") val store: BookStore ...Omit other code... } Java Kotlin BookStore.java @Entity public interface BookStore { // `mappedBy` indicates `BookStore.books` // is the mirror of `Book.store` @OneToMany(mappedBy = \"store\") @Nullable List books(); ...Omit other code... } BookStore.kt @Entity interface BookStore { // `mappedBy` indicates `BookStore.books` // is the mirror of `Book.store` @OneToMany(mappedBy = \"store\") val books: List? ...Omit other code... } caution @OneToMany associations are merely mirrors of @ManyToOne associations. @JoinColumn and @JoinTable must not be used. The @OneToMany association property must be non-null. If the parent object is queried and its one-to-many association property needs to be fetched, then for the parent object that has no corresponding child objects, the value of this property is a collection of length 0 rather than null.","s":"One To Many","u":"/jimmer-doc/docs/mapping/base/association/one-to-many","h":"","p":412},{"i":415,"t":"This chapter introduces how to use the @org.babyfish.jimmer.sql.OneToOne annotation to declare one-to-one association properties. One-to-one supports bidirectional association. For bidirectional associations, one side must be the owning side and the other side must be the inverse side: Owning side (required): The actual mapping between the database and association properties to implement unidirectional one-to-one association. Inverse side (optional): If a unidirectional association already exists, the inverse side can be configured as a mirror of the owning side to form a bidirectional association. Let's assume there are two entity types Customer and Address, and establish a bidirectional one-to-one association between them. info Unlike JPA/Hibernate, the owning side and inverse side can be chosen arbitrarily. Both can be used to persist associations. The example in this article chooses: Owning side (required): Customer.address Inverse side (optional): Address.customer","s":"One To One","u":"/jimmer-doc/docs/mapping/base/association/one-to-one","h":"","p":414},{"i":417,"t":"There are two ways to implement a one-to-one association: based on foreign key and based on join table.","s":"Owning Side","u":"/jimmer-doc/docs/mapping/base/association/one-to-one","h":"#owning-side","p":414},{"i":419,"t":"Java Kotlin Customer.java @Entity public interface Customer { @OneToOne Address address(); ...Omit other code... } Customer.kt @Entity interface Customer { @OneToOne val address: Address ...Omit other code... } Here @JoinColumn is not used together to explicitly specify the foreign key column name. Jimmer will deduce the column name corresponding to the address property based on the naming strategy. If the default naming strategy is not overridden by the user, the foreign key column name of the address property is ADDRESS_ID. So the previous code is equivalent to: Therefore, the above code is equivalent to the following: Java Kotlin Customer.java @Entity public interface Customer { @OneToOne @JoinColumn(name = \"ADDRESS_ID\") Address address(); ...Omit other code... } Customer.kt @Entity interface Customer { @OneToOne @JoinColumn(name = \"ADDRESS_ID\") val address: Address ...Omit other code... } The foreign key can be real or fake. Fake foreign keys are discussed in subsequent documents. Here we assume the foreign key is real, so the corresponding constraint in the database is: // If foreign key pointing to associated entity is real, create foreign key constraint alter table CUSTOMER add constraint FK_CUSTOMER__ADDRESS /* highlight-next-line */ foreign key(ADDRESS_ID) references ADDRESS(ID);","s":"1. Based on Foreign Key","u":"/jimmer-doc/docs/mapping/base/association/one-to-one","h":"#1-based-on-foreign-key","p":414},{"i":421,"t":"Java Kotlin Customer.java @Entity public interface Customer { @Nullable @OneToOne @JoinTable Address address(); ... } Customer.kt @Entity interface Customer { @OneToOne @JoinTable val address: Address? ... } Here, no properties are specified for @JoinTable. Jimmer will deduce the column names corresponding to the address property based on the naming strategy. If the default naming strategy is not overridden by the user, the deduced join table information is: Join table name: CUSTOMER_ADDRESS_MAPPING Join table foreign key column pointing to current entity: CUSTOMER_ID Join table foreign key column pointing to associated entity: ADDRESS_ID So the previous code is equivalent to: Java Kotlin Customer.java @Entity public interface Customer { @Nullable @OneToOne @JoinTable( name = \"CUSTOMER_ADDRESS_MAPPING\", joinColumnName = \"CUSTOMER_ID\", inverseJoinColumnName = \"ADDRESS_ID\" ) Address address(); ... } Customer.kt @Entity interface Customer { @OneToOne @JoinTable( name = \"CUSTOMER_ADDRESS_MAPPING\", joinColumnName = \"CUSTOMER_ID\", inverseJoinColumnName = \"ADDRESS_ID\" ) val address: Address? ... } The join table CUSTOMER_ADDRESS_MAPPING is defined as follows: create table CUSTOMER_ADDRESS_MAPPING( CUSTOMER_ID bigint not null, ADDRESS_ID bigint not null ); alter table ADDRESS_MAPPING add constraint PK_ADDRESS_MAPPING primary(CUSTOMER_ID, ADDRESS_ID); // If foreign key pointing to current entity is real, // create foreign key constraint alter table CUSTOMER_ADDRESS_MAPPING add constraint FK_CUSTOMER_ADDRESS_MAPPING__CUSTOMER foreign key(CUSTOMER_ID) references CUSTOMER(ID); // If foreign key pointing to associated entity is real, // create foreign key constraint alter table CUSTOMER_ADDRESS_MAPPING add constraint FK_CUSTOMER_ADDRESS_MAPPING__ADDRESS foreign key(ADDRESS_ID) references ADDRESS(ID); // These two constraints are very important. // Otherwise this join table expresses a many-to-many association // rather than a one-to-one association alter table CUSTOMER_ADDRESS_MAPPING add constraint UQ_CUSTOMER_ADDRESS_MAPPING__CUSTOMER_ID unique(CUSTOMER_ID); alter table CUSTOMER_ADDRESS_MAPPING add constraint UQ_CUSTOMER_ADDRESS_MAPPING__ADDRESS_ID unique(ADDRESS_ID); The join table has only two foreign keys, both non-null. The join table maintains the association by inserting and deleting data, never storing null data itself. The join table has no corresponding ORM entity and does not need an independent primary key. The two foreign keys combined can serve as the primary key. By default, the join table represents a many-to-many association. To degrade it to a one-to-one association, a unique constraint must be specified for each foreign key of the join table. caution Unless for compatibility with existing database design, one-to-one associations are recommended to directly use foreign keys instead of join tables. Once a one-to-one association is mapped using a join table, the Jimmer association property must be nullable, because the database cannot guarantee that any entity must have corresponding data in the join table.","s":"2. Based on Join Table","u":"/jimmer-doc/docs/mapping/base/association/one-to-one","h":"#2-based-on-join-table","p":414},{"i":423,"t":"The configuration of the inverse side is very simple: just specify that Address.customer is the mirror of Customer.address. In the following code: Left: The owning side discussed in the previous section Right: The inverse side association Address.customer introduced in this section, which is the mirror of Customer.address Here, @OneToOne(mappedBy = \"address\") indicates that the current property Address.customer is the mirror of Customer.address. Java Kotlin Customer.java @Entity public interface Customer { @OneToOne @JoinColumn(name = \"ADDRESS_ID\") Address address(); ...Omit other code... } Customer.kt @Entity interface Customer { @OneToOne @JoinColumn(name = \"ADDRESS_ID\") val address: Address ...Omit other code... } Java Kotlin Address.java @Entity public interface Address { // `mappedBy` indicates `Address.customer` // is the mirror of `Customer.address` @OneToOne(mappedBy = \"address\") @Nullable Customer customer(); ...Omit other code... } Address.kt @Entity interface Address { // `mappedBy` indicates `Address.customer` // is the mirror of `Customer.address` @OneToOne(mappedBy = \"address\") val customer: Customer? ...Omit other code... } caution Once the mappedBy property of @OneToOne is specified, annotations like @JoinColumn and @JoinTable must not be used. The one-to-one association property as the inverse side must be nullable.","s":"Inverse Side","u":"/jimmer-doc/docs/mapping/base/association/one-to-one","h":"#inverse-side","p":414},{"i":426,"t":"Before introducing IdView, we need to first introduce a concept: short associations. Before introducing short associations, let's first look at a normal association Java Kotlin Book book = bookRepository.findNullable( 1L, Fetchers.BOOK_FETCHER .allScalarFields() .store( Fetchers.BOOK_STORE_FETCHER .allScalarFields() ) .authors( Fetchers.AUTHOR_FETCHER .firstName() .lastName() ) ); System.out.println(book); val book = bookRepository.findNullable( 1L, newFetcher(Book::class).by { allScalarFields() store { allScalarFields() } authors { firstName() lastName() } } ); System.out.println(book); In this code: Fetches associated BookStore object via store association property of Book, expecting to get all non-associative properties of associated object Fetches associated Author objects via authors association property of Book, expecting id (implicit + mandatory), firstName and lastName of associated objects The output is: { \"id\":1, \"name\":\"Learning GraphQL\", \"edition\":1, \"price\":45, \"store\":{ \"id\":1, \"name\":\"O'REILLY\", \"website\":null }, \"authors\":[ { \"id\":2, \"firstName\":\"Alex\", \"lastName\":\"Banks\" }, { \"id\":1, \"firstName\":\"Eve\", \"lastName\":\"Procello\" } ] } Here, associated objects BookStore and Author on aggregate root Book have properties other than id, with relatively complete information. More importantly, non-id properties of course also include associated properties, so this data structure can be nested multiple levels or even recursive. This kind of association can also be called a \"long association\". info However, not all cases require such a deep data structure. In actual projects, sometimes only a very simple UI is needed, like below: Book Form Name Name Edition Edition Price Price Store O'REILLY Authors Authors Eve Procello, Alex Banks Authors Submit In this UI: Book.store is a many-to-one association, rendered as a dropdown selector Book.authors is a many-to-many association, rendered as a multiple dropdown selector Of course, if there are too many options, a dropdown list is no longer a reasonable design. In this case, improve it to a popup dialog with pagination. But these UI details are unimportant and irrelevant to the current topic. It is obvious that at this point, the user only cares about the id of the associated object, and has no interest in other properties of the associated object. That is, we want the associated object to only have the id property To allow aggregate roots to be associated with some objects that only have id, we can improve the code. Java Kotlin Book book = bookRepository.findNullable( 1L, Fetchers.BOOK_FETCHER .allScalarFields() .store() // no args means id only .authors() // no args means id only ); System.out.println(book); val book = bookRepository.findNullable( 1L, newFetcher(Book::class).by { allScalarFields() store() // no args means id only authors() // no args means id only } ); System.out.println(book); This time, we get a data structure like this: { \"id\":1, \"name\":\"Learning GraphQL\", \"edition\":1, \"price\":45, \"store\":{ // Only has id property \"id\":1 }, \"authors\":[ { // Only has id property \"id\":1 }, { // Only has id property \"id\":2 } ] } note In Hibernate, this kind of object with only id property is called a proxy object. However, associated objects with only id are not as simple as just the id of the association. Let's look at the same data expressed with associated ids instead of associated objects: { \"id\":1, \"name\":\"Learning GraphQL\", \"edition\":1, \"price\":45, \"storeId\": 1, \"authorIds\":[1, 2] } It is obvious that for short association use cases, associated ids or their collections are simpler than associated objects or their collections with only id.","s":"Basic Concepts: Short Associations","u":"/jimmer-doc/docs/mapping/advanced/view/id-view","h":"#basic-concepts-short-associations","p":424},{"i":428,"t":"Name Name Edition Edition Price Price Store O'REILLY Authors Authors Eve Procello, Alex Banks Authors Submit","s":"Book Form","u":"/jimmer-doc/docs/mapping/advanced/view/id-view","h":"","p":424},{"i":430,"t":"ADO.NET EF Core is Microsoft's ORM. Let's look at its design: https://learn.microsoft.com/en-us/ef/core/modeling/relationships?tabs=fluent-api%2Cfluent-api-simple-key%2Csimple-key public class Post { public int PostId { get; set; } public string Title { get; set; } public string Content { get; set; } public int BlogId { get; set; } public Blog Blog { get; set; } } It's easy to see that: Associated object: public Blog Blog { get; set; } Associated id: public int BlogId { get; set; } They coexist. Jimmer learns from this design of ADO.NET EF Core and provides the @IdView property.","s":"Microsoft's Solution","u":"/jimmer-doc/docs/mapping/advanced/view/id-view","h":"#microsofts-solution","p":424},{"i":433,"t":"IdView properties are declared with @org.babyfish.jimmer.sql.IdView: Java Kotlin Book.java package com.example.model; import org.babyfish.jimmer.sql.*; import org.jetbrains.annotations.Nullable; @Entity public interface Book { ...other properties omitted... @ManyToOne @Nullable BookStore store(); @ManyToMany @JoinTable( name = \"BOOK_AUTHOR_MAPPING\", joinColumnName = \"BOOK_ID\", inverseJoinColumnName = \"AUTHOR_id\" ) List authors(); @IdView // View of store id Long storeId(); // View of all author ids in authors collection @IdView(\"authors\") List authorIds(); } Book.kt package com.example.model import org.babyfish.jimmer.sql.* @Entity interface Book { ...other properties omitted... @ManyToOne val store: BookStore? @ManyToMany @JoinTable( name = \"BOOK_AUTHOR_MAPPING\", joinColumnName = \"BOOK_ID\", inverseJoinColumnName = \"AUTHOR_id\" ) val authors: List @IdView // View of store id val storeId: Long? // View of all author ids in authors collection @IdView(\"authors\") val authorIds: List } Where: Book.storeId: View of the id of associated Book.store object. Since storeId itself ends with Id, the parameter of @IdView annotation can be omitted. Jimmer infers the original association property to be Book.store. Nullability of original association property and IdView property must be consistent. In this example, Book.store property can be null, i.e. annotated with @Nullable in Java, or returns BookStore? in Kotlin. Therefore, Book.storeId must also be nullable, i.e. returns Long instead of long in Java, or returns Long? instead of Long in Kotlin. Otherwise it would cause compile error. Book.authorIds: View of ids of all Author objects in associated Book.authors collection. authorIds itself does not end with Id, so the parameter of @IdView annotation must be specified to explicitly indicate its original association is Book.authors. This is required in this case due to irregular noun pluralization in English.","s":"Declaring View Properties","u":"/jimmer-doc/docs/mapping/advanced/view/id-view","h":"#declaring-view-properties","p":424},{"i":435,"t":"The emphasis on the word \"view\" above is intentional. IdView properties do not have their own data, they are just views of original association properties. info IdView properties and original association properties are linked. Setting one necessarily affects the other. Setting view property affects original property: Java Kotlin // Set view property Book book = Immutables.createBook(draft -> { draft.setStoreId(10L); draft.setAuthorIds(Arrays.asList(100L, 101L)); }); // Print original property System.out.println(\"Store: \" + book.store()); System.out.println(\"Authors:\" + book.authors()); // Set view property val book = Book { storeId = 10L authorIds = listOf(100L, 101L) } // Print original property println(\"Store: $book.store}\") println(\"Authors: ${book.authors}\") Prints: Store: {\"id\":10} Authors: [{\"id\":100},{\"id\":101}] Setting original property affects view property: Java Kotlin // Set original property Book book = Immutables.createBook(draft -> { draft.applyStore(store -> { store.setId(10L).storeName(\"TURING\") }); draft.addIntoAuthors(author -> { author.setId(101L); author.setFirstName(\"Fabrice\"); author.setLastName(\"Marguerie\"); }); draft.addIntoAuthors(author -> { author.setId(101L); author.setFirstName(\"Steve\"); author.setLastName(\"Eichert\"); }); }); // Print view property System.out.println(\"StoreId: \" + book.storeId()); System.out.println(\"AuthorIds:\" + book.authorIds()); // Set original property val book = Book { store { id = 10L name = \"TURING\" } authors().addBy { id = 100L; firstName = \"Fabrice\" lastName = \"Marguerie\" } authors().addBy { id = 101L firstName = \"Steve\" lastName = \"Eichert\" } } // Print view property println(\"Store: $book.storeId}\") println(\"Authors: ${book.authorIds}\") Prints: StoreId: 10 AuthorIds: [100, 101] tip This shows that view properties and original properties are highly unified. Jimmer is still a ORM framework that is core-associated-object-oriented. View properties are just syntactic sugar. Except for the impact on ObjectFetcher to be explained below, view properties do not affect ORM and core logic at all.","s":"Essence of View Properties","u":"/jimmer-doc/docs/mapping/advanced/view/id-view","h":"#essence-of-view-properties","p":424},{"i":437,"t":"Java Kotlin Book book = bookRepository.findNullable( 1L, Fetchers.BOOK_FETCHER .allScalarFields() .storeId() .authorIds() ); System.out.println(book); val book = bookRepository.findNullable( 1L, newFetcher(Book::class).by { allScalarFields() storeId() authorIds() } ); System.out.println(book); Prints: { \"id\":1, \"name\":\"Learning GraphQL\", \"edition\":1, \"price\":45, \"storeId\": 1, \"authorIds\":[1, 2] } tip For Jimmer dynamic entities, original association properties and view properties are absolutely consistent. Either both can be accessed, or both are missing. Whether choosing to fetch the original association property or choosing to fetch the IdView view property does not affect the underlying execution logic of Jimmer, including the ultimately generated SQL. The only difference brought by different choices is that the Jackson visibility flag of original association properties and view properties are different. That is, properties fetched directly will be serialized by Jackson, while properties not fetched directly will be ignored. Here is the English translation of the file, with the code indentation preserved:","s":"Fetching IdView Properties","u":"/jimmer-doc/docs/mapping/advanced/view/id-view","h":"#fetching-idview-properties","p":424},{"i":439,"t":"caution Without the assistance of DTOs, hope that the entity itself can express associated ids, is the only scenario where it is appropriate to use @IdView. Other features make no assumptions about whether an association property has a corresponding @IdView property. Using associated IDs in the SQL DSL Even if an entity's one-to-one or many-to-one association property does not have a corresponding @IdView property, you can still use associated id expressions in the SQL DSL, for example: Java Kotlin where(table.storeId().eq(2L)); where(table.storeId eq 2L) Of course, if you are not satisfied with the auto-generated name for the associated id (e.g., storeId here), you can provide an @IdView property to change its name. Using associated ids in the DTO language The DTO language does not require @IdView properties at all. Even if an entity's associated property already has a corresponding @IdView property, it is not recommended to use it in the DTO language, as this is a fragile assumption. Once that @IdView property is removed, the DTO code cannot be correctly compiled until it is synchronized with the change. The DTO language should directly use the association properties, for example: export yourpackage.Book -> package yourpackage.dto input BookInput { allScalarFields() id(store) // as storeId id(authors) as authorIds } specification BookSpecification { like/i(name) associatedIdIn(store) as storeIds associatedIdNotIn(store) as excludedStoreIds }","s":"Do Not Abuse","u":"/jimmer-doc/docs/mapping/advanced/view/id-view","h":"#do-not-abuse","p":424},{"i":442,"t":"The @Entity annotation is used to decorate immutable interfaces to represent ORM entities. Java Kotlin Book.java @Entity public interface Book { ...Omit other code... } Book.kt @Entity interface Book { ...Omit other code... } info Why are entity types interfaces instead of classes? Jimmer entities have dynamic shapes and immutability, which are not simple POJOs with intricate internal workings that cannot be accomplished manually or with lombok assistance. So Jimmer lets developers write interfaces that are implemented at compile time by preprocessors (AnnotationProcessor for Java, KSP for Kotlin).","s":"@Entity","u":"/jimmer-doc/docs/mapping/base/basic","h":"#entity","p":440},{"i":444,"t":"The @Table annotation specifies the table name for the entity. If @Table annotation is not used, e.g. Java Kotlin BookStore.java @Entity public interface BookStore { ...Omit other code... } BookStore.kt @Entity interface BookStore { ...Omit other code... } Jimmer will deduce the table name corresponding to the BookStore interface based on the naming strategy. If the default naming strategy is not overridden by the user, the table name for interface BookStore is BOOK_STORE. So the previous code is equivalent to: Java Kotlin BookStore.java @Entity @Table(name = \"BOOK_STORE\") public interface BookStore { ...Omit other code... } BookStore.kt @Entity @Table(name = \"BOOK_STORE\") interface BookStore { ...Omit other code... }","s":"@Table","u":"/jimmer-doc/docs/mapping/base/basic","h":"#table","p":440},{"i":446,"t":"The @Column annotation specifies the database column for ordinary non-associative properties. If @Column annotation is not used, e.g. Java Kotlin Author.java @Entity public interface BookStore { String firstName(); ...Omit other code... } Author.kt @Entity interface Author { val firstName: String ...Omit other code... } Jimmer will deduce the column name corresponding to the firstName property based on the naming strategy. If the default naming strategy is not overridden by the user, the column name for property firstName is FIRST_NAME. So the previous code is equivalent to: Java Kotlin Author.java @Entity public interface BookStore { @Column(name = \"FIRST_NAME\") String firstName(); ...Omit other code... } Author.kt @Entity interface Author { @Column(name = \"FIRST_NAME\") val firstName: String ...Omit other code... } caution @Column is only used to explicitly specify column names for non-associative properties. For foreign key column names of many-to-one or one-to-one association properties, they must be specified through @JoinColumn. See Association Mapping for more.","s":"@Column","u":"/jimmer-doc/docs/mapping/base/basic","h":"#column","p":440},{"i":448,"t":"Declare a property as the id property, as follows Java Kotlin Book.java @Entity public interface Book { @Id long id(); } Book.kt @Entity interface Book { @Id val id: Long } caution The id field must be non-null (for Java, long is used here instead of Long) Unlike JPA, which encourages declaring the id as a nullable type, Jimmer does not use this method to express not specifying the id during data insertion. The dynamism of Jimmer objects themselves can easily express this problem. See Nullity for details.","s":"@Id","u":"/jimmer-doc/docs/mapping/base/basic","h":"#id","p":440},{"i":450,"t":"In the previous example, the primary key property decorated with @Id is a business field that must be specified when inserting data. However, more often, we expect that the primary key property itself has no business meaning, so that it can be unspecified when inserting data and automatically generated instead. The automatic id generation strategies are: Database autoincrement Database sequence UUID Snowflake ID @GeneratedValue works with @Id to specify auto growth strategy for Id.","s":"@GeneratedValue","u":"/jimmer-doc/docs/mapping/base/basic","h":"#generatedvalue","p":440},{"i":452,"t":"Java Kotlin Book.java @Entity public interface Book { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) long id(); } Book.kt @Entity interface Book { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) val id: Long }","s":"Database autoincrement","u":"/jimmer-doc/docs/mapping/base/basic","h":"#database-autoincrement","p":440},{"i":454,"t":"Java Kotlin Book.java @Entity public interface Book { @Id @GeneratedValue(strategy = GenerationType.SEQUENCE) long id(); } Book.kt @Entity interface Book { @Id @GeneratedValue(strategy = GenerationType.SEQUENCE) val id: Long } Here, the sequence name in the database is not specified through the sequenceName of @GeneratorValue. Jimmer will deduce the sequence name based on the naming strategy. If the default naming strategy is not overridden by the user, the sequence name here is BOOK_ID_SEQ. So the previous code is equivalent to: Java Kotlin Book.java @Entity public interface Book { @Id @GeneratedValue( strategy = GenerationType.SEQUENCE, sequenceName = \"BOOK_ID_SEQ\" ) long id(); } Book.kt @Entity interface Book { @Id @GeneratedValue( strategy = GenerationType.SEQUENCE, sequenceName = \"BOOK_ID_SEQ\" ) val id: Long }","s":"Database sequence","u":"/jimmer-doc/docs/mapping/base/basic","h":"#database-sequence","p":440},{"i":456,"t":"Setting the generatorType property of @GeneratedValue to org.babyfish.jimmer.sql.meta.UUIDIdGenerator can be used to randomly generate UUIDs Java Kotlin Book.java @Entity public interface Book { @Id @GeneratedValue(generatorType = UUIDIdGenerator.class) UUID id(); } Book.kt @Entity interface Book { @Id @GeneratedValue(generatorType = UUIDIdGenerator::class) val id: UUID }","s":"UUID","u":"/jimmer-doc/docs/mapping/base/basic","h":"#uuid","p":440},{"i":458,"t":"When the above Id growth strategies cannot meet the requirements, a custom Id generation strategy can be defined. Jimmer provides an UserIdGenerator interface UserIdGenerator.java package org.babyfish.jimmer.sql.meta; public interface UserIdGenerator extends IdGenerator { T generate(Class entityType); } Users can implement this interface to implement any Id generation algorithm, including snowflake ID. MyGenerator.java package com.mycompany.myproject.common; public class MyIdGenerator implements UserIdGenerator { @Override public Long generate(Class entityType) { return ...Omit custom id generation logic... } } Java Kotlin Book.java @Entity public interface Book { @Id @GeneratedValue(generateType = MyIdGenerator.class) Long id(); } Book.kt @Entity interface Book { @Id @GeneratedValue(generateType = MyIdGenerator::class) val id: Long } caution The user-implemented Id generation class MyIdGenerator itself does not have generic parameters, but generic parameters must be specified for the super interface UserIdGenerator. The type of the decorated Id property must be consistent with this generic parameter, otherwise an exception will be thrown.","s":"Custom IdGenerator","u":"/jimmer-doc/docs/mapping/base/basic","h":"#custom-idgenerator","p":440},{"i":461,"t":"Jimmer supports join table filters, with two usage scenarios:","s":"Two Scenarios","u":"/jimmer-doc/docs/mapping/advanced/join-table-filter","h":"#two-scenarios","p":459},{"i":463,"t":"Java Kotlin @Entity public interface Shop { @Id long id(); String name(); @ManyToMany @JoinTable( name = \"SHOP_CUSTOMER_MAPPING\", joinColumnName = \"SHOP_ID\", inverseJoinColumnName = \"CUSTOMER_ID\", readonly = true ) List