Hibernate 6.1.7升级：SingletonEhCacheRegionFactory不可用问题咨询

一、核心变化说明 #

Hibernate 6.x重构了缓存提供体系，原内置的EhCache 2.x集成被移除，改为通过**JCache(JSR-107)**规范集成EhCache 3.x，需同步调整依赖、自定义工厂类和配置文件。

二、具体适配步骤 #

1. 更新依赖

添加适配Hibernate 6.1.7的EhCache集成依赖（以Maven为例）：

<dependency>
    <groupId>org.hibernate.orm</groupId>
    <artifactId>hibernate-ehcache</artifactId>
    <version>6.1.7.FINAL</version>
</dependency>
<!-- 若上述依赖未自动引入，手动添加EhCache 3.x核心依赖 -->
<dependency>
    <groupId>org.ehcache</groupId>
    <artifactId>ehcache</artifactId>
    <version>3.10.8</version> <!-- 选择兼容的3.x版本即可 -->
</dependency>

2. 重构自定义缓存工厂类

原org.hibernate.cache.ehcache.SingletonEhCacheRegionFactory已被移除，需改为继承org.hibernate.cache.jcache.JCacheRegionFactory，并适配新的start方法签名：

import org.hibernate.cache.jcache.JCacheRegionFactory;
import org.hibernate.engine.spi.SessionFactoryImplementor;
import org.hibernate.cache.CacheException;
import java.util.Map;

public class AppJCacheRegionFactory extends JCacheRegionFactory {

    @Override
    public void start(SessionFactoryImplementor sessionFactory, Map<String, Object> config) throws CacheException {
        // 保留原有的init_actions初始化逻辑
        super.start(sessionFactory, config);
    }
}

3. 调整persistence.xml配置

替换旧的缓存工厂配置，并适配JCache规范的EhCache配置：

<persistence-unit name="db" transaction-type="JTA">
    <provider>org.hibernate.jpa.HibernatePersistenceProvider</provider>
    <jta-data-source>app.jdbc.APPDS</jta-data-source>
    <properties>
        <property name="jboss.as.jpa.providerModule" value="org.hibernate:main"/>
        <!-- 替换为自定义的JCache工厂类，或直接使用org.hibernate.cache.jcache.JCacheRegionFactory -->
        <property name="hibernate.cache.region.factory_class"
                  value="com.app.AppJCacheRegionFactory"/>
        <property name="hibernate.connection.release_mode" value="after_transaction"/>
        <property name="hibernate.cache.use_second_level_cache" value="true"/>
        <property name="hibernate.cache.use_query_cache" value="true"/>
        <property name="hibernate.jdbc.batch_size" value="30"/>
        <!-- 替换原net.sf.ehcache.cacheManagerName，指定EhCache 3缓存管理器名称 -->
        <property name="hibernate.jcache.cache_manager_name" value="app-cache"/>
        <!-- 可选：指定EhCache 3配置文件路径 -->
        <property name="hibernate.jcache.cache_manager_configuration_resource_path" value="/ehcache.xml"/>
        <property name="hibernate.integration.envers.enabled" value="false"/>
        <property name="hibernate.cache.region_prefix" value=""/>
    </properties>
</persistence-unit>

4. 升级EhCache配置文件

若原使用EhCache 2.x的ehcache.xml，需升级为EhCache 3.x格式，示例结构：

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns="http://www.ehcache.org/v3"
        xsi:schemaLocation="http://www.ehcache.org/v3 http://www.ehcache.org/schema/ehcache-core-3.0.xsd">

    <!-- 定义缓存管理器名称，与配置中的app-cache对应 -->
    <cache-manager name="app-cache">
        <!-- 定义默认缓存模板 -->
        <cache-template name="default">
            <heap unit="entries">1000</heap>
            <expiry>
                <ttl unit="minutes">30</ttl>
            </expiry>
        </cache-template>
        <!-- 配置实体类对应的二级缓存区域 -->
        <cache alias="com.app.entity.YourEntity" uses-template="default"/>
        <!-- 配置查询缓存区域 -->
        <cache alias="org.hibernate.cache.internal.StandardQueryCache" uses-template="default"/>
    </cache-manager>
</config>

三、注意事项 #

• 若项目已迁移到Jakarta EE，需确保JPA注解使用jakarta.persistence包下的@Cacheable，而非旧的javax.persistence。
• 原start方法中的自定义逻辑若涉及旧EhCache API调用，需替换为EhCache 3的JCache兼容API，确保初始化逻辑正常运行。

内容的提问来源于stack exchange，提问作者Raushan