Persistence (HANA) 技能用于在 Cloud Foundry 上为 Java 应用配置 HANA Cloud 数据库连接，属于 btp-neo-java-app-migration 迁移流程中的持久化环节。
【用途】 将 Neo 环境中的 javax.sql.DataSource JNDI 资源引用，替换为 Cloud Foundry 的 HANA schema 绑定，使用 SAP Java Buildpack 提供的 TomcatDataSourceFactory。
【触发检测】 满足以下任一模式时适用：
- web.xml 中存在 resource-ref，例如 res-ref-name 为 jdbc/DefaultDB、res-type 为 javax.sql.DataSource；
- Java 源码中存在 import javax.sql.DataSource 与 import javax.annotation.Resource 并使用 @Resource(name = "jdbc/DefaultDB")，或通过 JNDI 查找 java:comp/env/jdbc/DefaultDB。
【前置条件】
- 工作目录必须位于由 jakarta-java25-migration 或 neo-to-cf-migration-orchestrator 创建的 -cf-migration 应用副本中；若当前目录不以 -cf-migration 结尾，需先切换。
- 必须先调用 sdk-replacement 技能（用于设置 SAP Cloud SDK），这是本技能的必需前置。
- 子账户中需有可用的 HANA Cloud 实例。
【转换步骤】 Step 0：检测现有 JSON 约定。扫描 pom.xml 与 Java 源码中使用的 JSON 库（如 fasterxml.jackson、com.google.code.gson、org.json、jakarta.json），规则为复用已存在的库；若未发现则默认使用 jakarta.json（JSON-P），其已在 cf-tomcat-bom 中，无需额外依赖。 Step 1：从 web.xml 移除 resource-ref。 Step 2：创建 src/main/webapp/META-INF/context.xml，定义 JNDI DataSource，其中 factory 为 com.sap.xs.jdbc.datasource.tomcat.TomcatDataSourceFactory，service 为 ${service_name_for_DefaultDB}（运行时通过 JBP_CONFIG_RESOURCE_CONFIGURATION 环境变量替换）。 Step 3：创建 resource_configuration.yml（位于 src/main/webapp/META-INF/sap_java_buildpack/config/），内容为 tomcat/webapps/ROOT/META-INF/context.xml 下映射 service_name_for_DefaultDB 为 ${app-name}-hana（需替换为 mtad.yaml 中实际 HANA 服务实例名）。 Step 4：更新 MTA 描述文件 mtad.yaml，加入 HANA schema 资源与配置。模块使用 java.tomcat 类型、buildpack 为 sap_java_buildpack_jakarta，属性中含 JBP_CONFIG_RESOURCE_CONFIGURATION（必须以 YAML 列表格式书写）。资源类型为 com.sap.xs.hana-schema。资料特别强调：不要在 com.sap.xs.hana-schema 资源下添加 service: hana 或 service-plan: hdi-shared，这两个键属于通用的 org.cloudfoundry.managed-service 类型，错误添加会导致部署被拒（CF-UnprocessableEntity(10008)）。 Step 5：Java 代码无需修改，通过 JNDI 查找 DataSource 的方式继续可用（示例包含建表与查询）。 Step 6：使用 @Resource 注解的方式同样继续可用。
【配置文件与目录结构】 应用后目录应包含：src/main/webapp/META-INF/context.xml、src/main/webapp/META-INF/sap_java_buildpack/config/resource_configuration.yml，以及移除 resource-ref 后的 web.xml。CF 服务为 ${app-name}-hana，类型 com.sap.xs.hana-schema。
【创建 HANA Cloud 实例】 若尚无 HANA Cloud 实例，可选：方式一通过 BTP Cockpit（进入子账户、Service Marketplace、查找 SAP HANA Cloud、创建实例、创建 schema 服务键）；方式二通过 CF CLI（cf marketplace -s hana 查看可用计划；cf create-service hana schema ${app-name}-hana）。
【验证】
- 校验目录结构；2. 构建与部署（mvn clean package、cf deploy . -f）；3. 校验服务绑定（cf services、cf env）；4. 测试数据库连通性（curl 应用 URL）；5. 查看日志（cf logs 过滤 datasource/hana/jdbc）。
【常见问题】 包括 "Cannot create JDBC driver"（HANA JDBC 驱动不可用，需使用 sap_java_buildpack_jakarta）、部署时 "Service not found"（HANA schema 服务不存在）、连接被拒（实例未运行或 IP 白名单）、"Invalid object name" SQL 错误（schema 或表名问题）、JBP_CONFIG_RESOURCE_CONFIGURATION 不生效（YAML 语法或路径错误）。
【使用 JPA（可选）】 若应用使用 JPA，可更新 persistence.xml，使用 non-jta-data-source 指向 java:comp/env/jdbc/DefaultDB，版本为 3.0。
【后续步骤】 完成本技能后可继续其他适用技能：document-management-sdm（文档存储）、keystore-credstore（凭证存储）。
【限制】 资料未提供具体的收费、价格、性能指标或平台覆盖范围等信息。