# mybatis/mybatis-3 architecture

> Architecture diagram of the GitHub repository mybatis/mybatis-3, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mybatis/mybatis-3
- Repository: https://github.com/mybatis/mybatis-3

## Overview

##### Project Type and Purpose
- This is an open‑source Java library/framework (MyBatis SQL Mapper) for mapping Java objects to SQL queries.
- Not a web or full‑stack app, but a reusable core component that sits between user code and the database (via JDBC).

##### Key Layers & Directories
- src/main/java/org/apache/ibatis/annotations → annotation‑driven mapper definitions
- src/main/java/org/apache/ibatis/builder  → builders for configuration and SQL mappings (XML & annotation)
- src/main/java/org/apache/ibatis/binding  → mapper proxy, registry, and invocation logic
- src/main/java/org/apache/ibatis/cache   → caching interfaces, decorators, implementations
- src/main/java/org/apache/ibatis/executor  → core execution layer (SimpleExecutor, BatchExecutor, CachingExecutor)
- src/main/java/org/apache/ibatis/session  → SqlSession, SqlSessionFactory, Configuration classes
- src/main/java/org/apache/ibatis/datasource → DataSource factories (pooled, unpooled, JNDI)
- src/main/java/org/apache/ibatis/type   → type handler registry and handlers for JDBC-to-Java conversions
- Additional modules: io, logging, parsing, scripting, plugin, reflection, transaction, jdbc

##### Main Components
A. User Application
- Calls MyBatis API (SqlSessionFactoryBuilder → SqlSessionFactory → SqlSession).
B. Configuration & Builder
- XMLConfigBuilder & MapperAnnotationBuilder read XML/annotations → build Configuration.
- Configuration holds MappedStatements, TypeAliasRegistry, TypeHandlerRegistry, Environment (DataSource + TransactionFactory).
C. SqlSession Layer
- SqlSessionFactory creates SqlSession.
- SqlSession provides mapper proxies (MapperProxy) and direct query methods.
D. Executor Layer
- Executor (SimpleExecutor / BatchExecutor / ReuseExecutor / CachingExecutor)
- StatementHandler prepares JDBC statements, ParameterHandler populates parameters, ResultSetHandler maps rows.
E. Caching Layer (optional decorator around Executor)
F. Transaction & DataSource
- TransactionFactory creates Transactions (JdbcTransaction or ManagedTransaction).
- DataSourceFactory supplies Connection objects.
G. JDBC & Database
- JDBC Driver
- Underlying relational database

##### Relationships & Data Flow
- 1: User App → calls SqlSessionFactoryBuilder with config file → built Configuration
- 2: Configuration → SqlSessionFactory → SqlSession
- 3: SqlSession → MapperProxy → invokes MappedStatement
- 4: MappedStatement + Executor → StatementHandler → JDBC Connection
- 5: JDBC → Database → ResultSet → ResultHandler → user object
- Cache decorators intercept before/after step 4 to return cached results.
- PluginChain wraps Executor, StatementHandler, ParameterHandler, ResultSetHandler for interception.

##### Architectural Patterns & Principles
- Builder pattern for reading/parsing XML or annotations into Configuration.
- Factory pattern in SqlSessionFactoryBuilder, DataSourceFactory, TransactionFactory.
- Proxy pattern for mapper interfaces (MapperProxy).
- Decorator pattern for caching (CachingExecutor wraps a target Executor).
- Template Method in script runners and executors to handle boilerplate JDBC.
- Separation of concerns: distinct packages for builder, binding, executor, session, transaction, caching, type handling.

##### Extensibility Points
- Plugin/InterceptorChain: intercept core operations (executor.doQuery, parameter mapping, result handling).
- TypeHandlerRegistry: register custom TypeHandler implementations for custom types.
- ObjectFactory & ObjectWrapperFactory for custom instantiation and property mapping.

##### Must‑Haves
- Clear labels for each component/package

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Application"
        UA["User Application"]:::external
    end

    subgraph "MyBatis Core"
        subgraph "Builder & Configuration"
            XCB["XMLConfigBuilder"]:::core
            MAB["MapperAnnotationBuilder"]:::core
            SSFB["SqlSessionFactoryBuilder"]:::api
            SSF["SqlSessionFactory"]:::api
            Cfg["Configuration"]:::core
        end
        subgraph "Session Layer"
            SS["SqlSession"]:::api
            DSS["DefaultSqlSession"]:::api
            MP["MapperProxy"]:::api
        end
        subgraph "Executor & Handlers"
            SubE["SimpleExecutor"]:::exec
            BatE["BatchExecutor"]:::exec
            ReuE["ReuseExecutor"]:::exec
            CachE["CachingExecutor"]:::exec
            SSH["BaseStatementHandler"]:::exec
            PH["ParameterHandler"]:::exec
            RSH["ResultSetHandler"]:::exec
        end
        subgraph "Caching"
            CacheI["Cache"]:::exec
            Lru["LruCache"]:::exec
            Perp["PerpetualCache"]:::exec
        end
        subgraph "Plugin/Interceptor"
            IC["InterceptorChain"]:::core
            Inv["Invocation"]:::core
        end
        subgraph "Type Handling"
            THR["TypeHandlerRegistry"]:::core
            BTH["BaseTypeHandler"]:::core
        end
        subgraph "Parsing & XML"
            XP["XPathParser"]:::core
            XMB["XMLMapperBuilder"]:::core
        end
        subgraph "Reflection & Factory"
            MO["MetaObject"]:::core
            OF["ObjectFactory"]:::core
        end
        subgraph "Logging"
            LF["LogFactory"]:::core
            BJ["BaseJdbcLogger"]:::core
        end
        subgraph "Mapping Models"
            MS["MappedStatement"]:::core
            Env["Environment"]:::core
        end
        subgraph "JDBC Utils"
            SQLu["SQL"]:::core
            SR["ScriptRunner"]:::core
        end
    end

    subgraph "DataSource & Transaction"
        UD["UnpooledDataSource"]:::ds
        PD["PooledDataSource"]:::ds
        JT["JdbcTransaction"]:::ds
        MT["ManagedTransaction"]:::ds
    end

    subgraph "JDBC & Database"
        JDBC["JDBC Driver"]:::external
        DB["Database"]:::external
    end

    UA -->|"calls with config file"| SSFB
    SSFB -->|builds| Cfg
    XCB -->|parses XML into| Cfg
    MAB -->|parses annotations into| Cfg
    Cfg -->|creates| SSF
    SSF -->|opens| SS
    SS -->|uses proxy| MP
    MP -->|invokes| MS
    MS -->|executes via| CachE
    CachE -->|decorates| SubE
    SubE -->|uses| SSH
    SSH -->|prepare stmt| JDBC
    SSH -->|uses| PH
    SSH -->|uses| RSH
    IC -->|wraps| SubE
    IC -->|wraps| SSH
    IC -->|wraps| PH
    IC -->|wraps| RSH
    Cfg -->|includes| THR
    Cfg -->|includes| MS
    Cfg -->|includes| Env
    Env -->|has| UD
    Env -->|has| PD
    Env -->|has| JT
    Env -->|has| MT
    JT -->|gets connection| UD
    SR -->|runs| SQLu
    JDBC -->|connects to| DB
    DB -->|returns results| RSH

    click XCB "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/builder/xml/XMLConfigBuilder.java"
    click MAB "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/builder/annotation/MapperAnnotationBuilder.java"
    click SSFB "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/session/SqlSessionFactoryBuilder.java"
    click SSF "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/session/SqlSessionFactory.java"
    click Cfg "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/session/Configuration.java"
    click SS "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/session/SqlSession.java"
    click DSS "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/session/defaults/DefaultSqlSession.java"
    click MP "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/binding/MapperProxy.java"
    click SubE "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/executor/SimpleExecutor.java"
    click BatE "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/executor/BatchExecutor.java"
    click ReuE "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/executor/ReuseExecutor.java"
    click CachE "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/executor/CachingExecutor.java"
    click SSH "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/executor/statement/BaseStatementHandler.java"
    click PH "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/executor/parameter/ParameterHandler.java"
    click RSH "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/executor/resultset/ResultSetHandler.java"
    click CacheI "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/cache/Cache.java"
    click Lru "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/cache/decorators/LruCache.java"
    click Perp "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/cache/impl/PerpetualCache.java"
    click UD "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/datasource/unpooled/UnpooledDataSource.java"
    click PD "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/datasource/pooled/PooledDataSource.java"
    click JT "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/transaction/jdbc/JdbcTransaction.java"
    click MT "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/transaction/managed/ManagedTransaction.java"
    click SQLu "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/jdbc/SQL.java"
    click SR "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/jdbc/ScriptRunner.java"
    click IC "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/plugin/InterceptorChain.java"
    click Inv "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/plugin/Invocation.java"
    click THR "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/type/TypeHandlerRegistry.java"
    click BTH "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/type/BaseTypeHandler.java"
    click XP "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/parsing/XPathParser.java"
    click XMB "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/builder/xml/XMLMapperBuilder.java"
    click MO "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/reflection/MetaObject.java"
    click OF "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/reflection/factory/ObjectFactory.java"
    click LF "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/logging/LogFactory.java"
    click BJ "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/logging/jdbc/BaseJdbcLogger.java"
    click MS "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/mapping/MappedStatement.java"
    click Env "https://github.com/mybatis/mybatis-3/blob/master/src/main/java/org/apache/ibatis/mapping/Environment.java"

    classDef api fill:#D6EAF8,stroke:#333
    classDef exec fill:#D5F5E3,stroke:#333
    classDef ds fill:#FCF3CF,stroke:#333
    classDef external fill:#F0F0F0,stroke:#333
    classDef core fill:#EBDEF0,stroke:#333
```
