0
# MyBatis-Flex Core
1

2
MyBatis-Flex is an elegant enhancement framework for MyBatis that provides type-safe query building, active record patterns, and comprehensive ORM capabilities. It supports 40+ database types and offers multiple programming paradigms including Repository pattern, Active Record, and Service Layer abstractions.
3

4
## Package Information
5

6
- **Package Name**: mybatis-flex-core
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Group ID**: com.mybatis-flex
10
- **Artifact ID**: mybatis-flex-core
11
- **Installation**: 
12
  ```xml
13
  <dependency>
14
      <groupId>com.mybatis-flex</groupId>
15
      <artifactId>mybatis-flex-core</artifactId>
16
      <version>1.10.8</version>
17
  </dependency>
18
  ```
19

20
## Core Imports
21

22
```java
23
import com.mybatisflex.core.MybatisFlexBootstrap;
24
import com.mybatisflex.core.BaseMapper;
25
import com.mybatisflex.core.query.QueryWrapper;
26
import com.mybatisflex.core.activerecord.Model;
27
import com.mybatisflex.core.service.IService;
28
import com.mybatisflex.core.row.Db;
29
import com.mybatisflex.core.FlexGlobalConfig;
30
```
31

32
## Basic Usage
33

34
```java
35
// 1. Bootstrap MyBatis-Flex
36
MybatisFlexBootstrap bootstrap = MybatisFlexBootstrap.getInstance()
37
    .setDataSource(dataSource)
38
    .addMapper(UserMapper.class)
39
    .start();
40

41
// 2. Get mapper instance
42
UserMapper userMapper = bootstrap.getMapper(UserMapper.class);
43

44
// 3. Basic CRUD operations
45
User user = new User("Alice", 25);
46
userMapper.insert(user);
47

48
// 4. Query building
49
List<User> adults = userMapper.selectListByQuery(
50
    QueryWrapper.create()
51
        .select()
52
        .from(User.class)
53
        .where(USER.AGE.ge(18))
54
);
55

56
// 5. Active Record pattern
57
User activeUser = new User();
58
activeUser.setName("Bob");
59
activeUser.setAge(30);
60
activeUser.save();
61

62
// 6. Row-based operations (no entities)
63
Db.insert("users", Row.ofMap(Map.of("name", "Charlie", "age", 28)));
64
```
65

66
## Architecture
67

68
MyBatis-Flex is built around several key components:
69

70
- **Bootstrap System**: `MybatisFlexBootstrap` for framework initialization and configuration
71
- **Repository Pattern**: `BaseMapper<T>` interface providing universal CRUD operations
72
- **Query Builder**: `QueryWrapper` for type-safe, fluent SQL generation
73
- **Active Record**: `Model<T>` base class for entity-centric operations
74
- **Service Layer**: `IService<T>` interface for business logic abstraction
75
- **Row Operations**: `Db` utility class for entity-free database operations
76
- **Multi-Database Support**: Dialect system supporting 40+ database types
77
- **Type Safety**: Comprehensive generic type system with lambda expression support
78

79
## Capabilities
80

81
### Bootstrap and Configuration
82

83
Framework initialization, global configuration, and multi-datasource setup. Essential for getting MyBatis-Flex running in any Java application.
84

85
```java { .api }
86
public class MybatisFlexBootstrap {
87
    public static MybatisFlexBootstrap getInstance();
88
    public MybatisFlexBootstrap setDataSource(DataSource dataSource);
89
    public MybatisFlexBootstrap addDataSource(String key, DataSource dataSource);
90
    public MybatisFlexBootstrap addMapper(Class<?> mapperClass);
91
    public MybatisFlexBootstrap start();
92
    public <T> T getMapper(Class<T> mapperClass);
93
}
94

95
public class FlexGlobalConfig {
96
    public static FlexGlobalConfig getDefaultConfig();
97
    public static void setConfig(String configId, FlexGlobalConfig config, boolean isDefault);
98
}
99
```
100

101
[Bootstrap and Configuration](./bootstrap-config.md)
102

103
### Universal CRUD Operations
104

105
Comprehensive CRUD interface that eliminates the need for custom mapper methods. Supports batch operations, relationship loading, and advanced querying.
106

107
```java { .api }
108
public interface BaseMapper<T> {
109
    // Insert operations
110
    int insert(T entity);
111
    int insertSelective(T entity);
112
    int insertBatch(Collection<T> entities);
113
    int insertOrUpdate(T entity);
114
    
115
    // Select operations
116
    T selectOneById(Serializable id);
117
    List<T> selectListByQuery(QueryWrapper queryWrapper);
118
    long selectCountByQuery(QueryWrapper queryWrapper);
119
    Page<T> paginate(Page<T> page, QueryWrapper queryWrapper);
120
    
121
    // Update operations
122
    int update(T entity);
123
    int updateByQuery(T entity, QueryWrapper queryWrapper);
124
    
125
    // Delete operations
126
    int deleteById(Serializable id);
127
    int deleteBatchByIds(Collection<? extends Serializable> ids);
128
    int deleteByQuery(QueryWrapper queryWrapper);
129
}
130
```
131

132
[Universal CRUD Operations](./crud-operations.md)
133

134
### Query Builder System
135

136
Type-safe, fluent query building with comprehensive SQL support. Includes support for complex joins, subqueries, CTEs, and all major SQL operations.
137

138
```java { .api }
139
public class QueryWrapper {
140
    public static QueryWrapper create();
141
    public QueryWrapper select(QueryColumn... queryColumns);
142
    public QueryWrapper from(Class<?>... entityClasses);
143
    public QueryWrapper where(QueryCondition queryCondition);
144
    public QueryWrapper leftJoin(Class<?> entityClass);
145
    public QueryWrapper orderBy(QueryColumn... queryColumns);
146
    public QueryWrapper groupBy(QueryColumn... queryColumns);
147
    public QueryWrapper limit(Number rows);
148
}
149

150
public class QueryColumn {
151
    public static QueryColumn create(String columnName);
152
    public QueryCondition eq(Object value);
153
    public QueryCondition ge(Object value);
154
    public QueryCondition in(Object... values);
155
}
156
```
157

158
[Query Builder System](./query-builder.md)
159

160
### Active Record Pattern
161

162
Entity-centric operations where domain objects handle their own persistence. Provides a clean, object-oriented approach to database operations.
163

164
```java { .api }
165
public abstract class Model<T extends Model<T>> {
166
    public boolean save();
167
    public boolean update();
168
    public boolean update(boolean ignoreNulls);
169
    public boolean remove();
170
    public Optional<Boolean> saveOpt();
171
    public Optional<Boolean> updateOpt();
172
    public Optional<Boolean> removeOpt();
173
}
174
```
175

176
[Active Record Pattern](./active-record.md)
177

178
### Fluent Update Operations
179

180
Type-safe, chainable update operations that provide a clean alternative to traditional entity updates. Supports conditional field setting, complex WHERE conditions, and direct SQL execution.
181

182
```java { .api }
183
public class UpdateChain<T> {
184
    public static <T> UpdateChain<T> of(Class<T> entityClass);
185
    public static <T> UpdateChain<T> of(BaseMapper<T> mapper);
186
    public UpdateChain<T> set(String column, Object value);
187
    public UpdateChain<T> set(QueryColumn column, Object value);
188
    public <R> UpdateChain<T> set(LambdaGetter<R> getter, Object value);
189
    public UpdateChain<T> where(QueryCondition condition);
190
    public UpdateChain<T> and(QueryCondition condition);
191
    public UpdateChain<T> or(QueryCondition condition);
192
    public boolean update();
193
}
194
```
195

196
[Fluent Update Operations](./update-chain.md)
197

198
### Service Layer Interface
199

200
Business logic abstraction with enhanced CRUD operations, batch processing, and query chaining. Perfect for service-oriented architectures.
201

202
```java { .api }
203
public interface IService<T> {
204
    boolean save(T entity);
205
    boolean saveBatch(Collection<T> entities);
206
    boolean saveOrUpdate(T entity);
207
    boolean removeById(Serializable id);
208
    boolean update(T entity);
209
    T getById(Serializable id);
210
    List<T> list(QueryWrapper queryWrapper);
211
    Page<T> page(Page<T> page, QueryWrapper queryWrapper);
212
    long count(QueryWrapper queryWrapper);
213
}
214
```
215

216
[Service Layer Interface](./service-layer.md)
217

218
### Row-Based Database Operations
219

220
Direct database operations without entity classes. Ideal for dynamic queries, reporting, and working with unknown table structures.
221

222
```java { .api }
223
public class Db {
224
    public static int insert(String tableName, Row row);
225
    public static int insertBySql(String sql, Object... args);
226
    public static List<Row> selectBySql(String sql, Object... args);
227
    public static int updateBySql(String sql, Object... args);
228
    public static int deleteBySql(String sql, Object... args);
229
}
230

231
public class Row {
232
    public static Row ofMap(Map<String, Object> map);
233
    public Row set(String column, Object value);
234
    public Object get(String column);
235
}
236
```
237

238
[Row-Based Operations](./row-operations.md)
239

240
### Multi-Database Support
241

242
Comprehensive database dialect system supporting 40+ database types including MySQL, PostgreSQL, Oracle, SQL Server, and specialized databases.
243

244
```java { .api }
245
public enum DbType {
246
    MYSQL, POSTGRESQL, ORACLE, SQL_SERVER, DB2,
247
    CLICKHOUSE, H2, SQLITE, DERBY, FIREBIRD,
248
    DM, KINGBASE, GBASE, OSCAR, HANA, REDSHIFT;
249
}
250

251
public interface IDialect {
252
    String forSelectByQuery(QueryWrapper queryWrapper);
253
    String forPaginateQuery(QueryWrapper queryWrapper, long offset, long rows);
254
    String wrap(String keyword);
255
}
256
```
257

258
[Multi-Database Support](./database-support.md)
259

260
### Pagination Support
261

262
Comprehensive pagination with performance optimizations, count query optimization, and type conversion support.
263

264
```java { .api }
265
public class Page<T> {
266
    public Page(int pageNumber, int pageSize);
267
    public Page(int pageNumber, int pageSize, boolean optimizeCountQuery);
268
    
269
    public List<T> getRecords();
270
    public long getTotalRow();
271
    public int getTotalPage();
272
    public int getPageNumber();
273
    public int getPageSize();
274
    public <R> Page<R> convert(Function<T, R> mapper);
275
}
276
```
277

278
[Pagination Support](./pagination.md)
279

280
## Types
281

282
```java { .api }
283
// Core query types
284
public class QueryCondition {
285
    public QueryCondition and(QueryCondition condition);
286
    public QueryCondition or(QueryCondition condition);
287
    public QueryCondition not();
288
}
289

290
public class QueryColumn {
291
    public static QueryColumn create(String columnName);
292
    public QueryColumn as(String alias);
293
    public QueryCondition eq(Object value);
294
    public QueryCondition ge(Object value);
295
    public QueryCondition in(Object... values);
296
    public QueryCondition like(String pattern);
297
    public QueryCondition isNull();
298
    public QueryCondition between(Object start, Object end);
299
}
300

301
public class QueryTable {
302
    public static QueryTable create(String tableName);
303
    public static QueryTable create(Class<?> entityClass);
304
    public QueryTable as(String alias);
305
}
306

307
// Update operations
308
public class UpdateChain<T> {
309
    public static <T> UpdateChain<T> of(Class<T> entityClass);
310
    public static <T> UpdateChain<T> of(BaseMapper<T> mapper);
311
    public UpdateChain<T> set(String column, Object value);
312
    public UpdateChain<T> where(QueryCondition condition);
313
    public boolean update();
314
}
315

316
// Pagination types
317
public class Page<T> {
318
    public Page(int pageNumber, int pageSize);
319
    public Page(int pageNumber, int pageSize, boolean optimizeCountQuery);
320
    public List<T> getRecords();
321
    public long getTotalRow();
322
    public int getTotalPage();
323
    public int getPageNumber();
324
    public int getPageSize();
325
    public <R> Page<R> convert(Function<T, R> mapper);
326
}
327

328
// Row operations
329
public class Row extends LinkedHashMap<String, Object> {
330
    public static Row ofMap(Map<String, Object> map);
331
    public Row set(String column, Object value);
332
    public <T> T get(String column);
333
    public Object get(String column);
334
}
335

336
public class RowKey {
337
    public static RowKey of(String... columns);
338
    public static RowKey of(QueryColumn... columns);
339
}
340

341
// Functional interfaces
342
@FunctionalInterface
343
public interface LambdaGetter<T> extends Serializable, Function<T, Object> {
344
}
345

346
// Cursor for streaming results
347
public interface Cursor<T> extends Closeable, Iterable<T> {
348
    boolean isOpen();
349
    boolean isConsumed();
350
    int getCurrentIndex();
351
}
352

353
// Field query builder for relationship loading
354
public interface FieldQueryBuilder {
355
    FieldQueryBuilder with(String fieldName);
356
    FieldQueryBuilder with(LambdaGetter<?>... fieldGetters);
357
}
358

359
// Configuration types
360
public class FlexGlobalConfig {
361
    public DbType getDbType();
362
    public void setDbType(DbType dbType);
363
    public KeyConfig getKeyConfig();
364
    public void setKeyConfig(KeyConfig keyConfig);
365
    public boolean isLogicDeleteColumn(String column);
366
    public void setLogicDeleteColumn(String column);
367
}
368

369
public class KeyConfig {
370
    public KeyType getKeyType();
371
    public void setKeyType(KeyType keyType);
372
    public String getValue();
373
    public void setValue(String value);
374
}
375

376
// Enums
377
public enum DbType {
378
    MYSQL, POSTGRESQL, ORACLE, SQL_SERVER, DB2,
379
    CLICKHOUSE, H2, SQLITE, DERBY, FIREBIRD,
380
    DM, KINGBASE, GBASE, OSCAR, HANA, REDSHIFT;
381
}
382

383
public enum KeyType {
384
    None, Auto, Generator, Sequence;
385
}
386

387
// Transaction support
388
public enum Propagation {
389
    REQUIRED,
390
    REQUIRES_NEW,
391
    NESTED,
392
    NOT_SUPPORTED,
393
    NEVER,
394
    SUPPORTS,
395
    MANDATORY;
396
}
397

398
// Batch processing
399
@FunctionalInterface
400
public interface BatchArgsSetter<T> {
401
    void setArgs(PreparedStatement ps, T item, int index) throws SQLException;
402
}
403
```