Standard Examples

Through the previous chapters:

• We learned about the three core functionalities of Jimmer and got a basic impression of it.

• We also went through a simple project to understand the basics of using Jimmer, including how to use its Annotation Processor (Java) / KSP (Kotlin).

However, for a comprehensive solution, having rich examples is better. Jimmer provides a series standard examples:

tip

Combining the accompanying examples is the most efficient way to get familiar with Jimmer.

Prerequisites

Like JOOQ, JPA2.0 Criteria, QueryDSL, MyBatis-Flex, Fluent-MyBatis and other types of strong-typed SQL DSL implementations, Jimmer needs to generate more source code based on user code.

• For Java, it is annotation processor
• For Kotlin, it is ksp

When a user opens the accompanying examples in an IDE (such as IntelliJ) for the first time, some classes that should have been automatically generated will be missing.

info

Don't panic, click the run button and all errors will disappear automatically.

Example Introduction

The accompanying examples of Jimmer are very helpful for quickly mastering Jimmer.

The root directory of all examples: https://github.com/babyfish-ct/jimmer-examples

This project provides 5 examples, each with Java and Kotlin versions, for a total of 10 projects.

Java	Kotlin	Description	How to Run	Importance
java/jimmer-core	java/jimmer-core-kt	ORM-unrelated example demonstrating immer-style immutable objects	Run main method	★★★★
java/jimmer-sql	java/jimmer-sql-kt	Use Jimmer to quickly build REST services. This example demonstrates most of Jimmer's capabilities and is the most important and fundamental example.	Run main method Visit swagger page: http://localhost:8080/ui Download client TypeScript code: http://localhost:8080/ts.zip	★★★★★
java/jimmer-sql-graphql	java/jimmer-sql-graphql-kt	Use Jimmer to quickly build GraphQL services	Run main method Visit GraphiQL page: http://localhost:8080/graphiql	★★
java/jimmer-cloud	java/jimmer-cloud-kt	Microservice project based on Spring Cloud, demonstrating Jimmer's remote associations	Start the registry center by running the main method of the registry-center subproject Start all microservices by running the main method in store-service, book-service and author-service Wait about half a minute to ensure the registry center correctly identifies all microservices to avoid exceptions in subsequent swagger calls where some remote services cannot be recognized. Visit the swagger-ui of any of the following microservices store-service: http://localhost:7001/ui book-service: http://localhost:7002/ui author-service: http://localhost:7003/ui note After starting all projects locally, if there is a communication failure between the microservices and it persists after waiting for some time, please visit http://localhost:7000 to open the eureka registration center, add the hostnames of the various registered services to your local hosts file.	★
java/save-command	kotlin/save-command-kt	Dedicated example for save commands	Run all unit tests	★★★

tip

When getting started, the most important examples are jimmer-sql and jimmer-sql-kt. Open either of them according to your language preference:

• Java

  jimmer-examples/java/jimmer-sql

• Kotlin

  jimmer-examples/kotlin/jimmer-sql-kt

Non-Cache Mode

Non-cache mode is the default running mode for all examples. No external environment needs to be installed for them to run directly.

If an example depends on a database, it will use the H2 in-memory database in non-cache mode, and automatically create the database at startup.

As you can see, non-cache mode is very simple and ideal for quickly getting familiar with the examples.

Cache Mode

As introduced above, there are 10 accompanying examples, 4 of which can demonstrate Jimmer's caching and cache consistency.

• java/jimmer-sql and kotlin/jimmer-sql-kt

• java/jimmer-sql-graphql and kotlin/jimmer-sql-graphql-kt

By default, caching is not used, and they run on embedded in-memory databases with automatic database initialization. This ensures no external environment installation is required. Just click the run button to demonstrate.

You can also start them in cache mode by running the program with the spring-boot profile maxwell or debezium.

These two spring profiles utilize the CDC push capabilities of maxwell or debezium to achieve

, so external environments need to be installed.

tip

In fact, relying on CDC push services like maxwell or debezium is not the only way to achieve

. Even without the help of any external technology, Jimmer can also achieve this capability.

• Jimmer's own capability to capture data changes is called Transaction Trigger

• Pushing database changes to Jimmer via external CDC technology is called BinLog Trigger

Please refer to Trigger Classification.

BinLog Trigger has better performance and universality (even if the database is changed through other means that bypass Jimmer, such as directly modifying the data using a SQL IDE, it can also be intercepted), so it is the recommended solution.

Therefore, although Transaction Trigger can achieve

without relying on any special external environment, the official examples still use BinLog Trigger to synchronize the cache, as this is the more recommended approach.

So we need to set up CDC services like maxwell or debezium to push database changes to Jimmer.

Enabling cache mode requires building an external environment.

1. First, you need to install docker on your local machine.

2. Install the external environment

   The accompanying examples support two external environments. Feel free to choose either one to experience

Maxwell + MySQL

Although Maxwell only supports MySQL, it is the simplest of all database change push technologies. So it has demonstrational value.

Open the command line, enter the local directory corresponding to jimmer-examples/env-with-cache/maxwell, and execute

bash ./install.sh 

After installation, docker host port usage is enabled as follows

Container Name	Port	Description
maxwell-demo-zookeeper	4000	Support Kafka, users do not use directly
maxwell-demo-kafka	4100	The exposed address is localhost, that is, assuming the docker host is your local machine. If you want to use a remote server as the docker host, you need to modify the kafka installation command in install.sh and modify the spring-boot configuration file in the examples
maxwell-demo-kafdrop	4101	A Kafka GUI tool, visit http://localhost:4101 with a browser
maxwell-demo-mysql	4200	Database service in this mode
maxwell-demo-maxwell	NA	Background service that pushes MySQL changes to Kafka
maxwell-demo-redis	4400	Caching service in this mode

Debezium + Postgres

Debezium supports many databases and has good versatility. The example uses it to support change propagation for Postgres.

info

Postgres is a great open source database. If your project is brand new without any historical baggage, consider trying Postgres. This is why Jimmer's examples use Debezium to support Postgres.

Open the command line, enter the local directory corresponding to jimmer-examples/env-with-cache/debezium, and execute

bash ./install.sh

After installation, docker host port usage is enabled as follows

Container Name	Port	Description
debezium-demo-zookeeper	5000	Support Kafka, users do not use directly
debezium-demo-kafka	5100	The exposed address is localhost, that is, assuming the docker host is your local machine. If you want to use a remote server as the docker host, you need to modify the kafka installation command in install.sh and modify the spring-boot configuration file in the examples
debezium-demo-kafdrop	5101	A Kafka GUI tool, visit http://localhost:5101 with a browser
debezium-demo-postgres	5200	Database service in this mode
debezium-demo-connect	5300	Responsible for pushing Postgres changes to Kafka using kafka-connector. You can verify whether the pg-connector named debezium-connector is successfully installed by visiting http://localhost:5300/connectors
debezium-demo-redis	5400	Caching service in this mode

Notes

caution

If both the Maxwell + MySQL and Debezium + Postgres external environments are installed, some containers may fail to start due to insufficient memory.

For example, on my Mac, the default memory allocated to docker is 2GB. Installing and starting all of the above containers, plus a few other unrelated containers, led to insufficient memory. The problem was resolved after setting to 3GB.