cdata-cli-java

技能：CData CLI — Java / JDBC 构建

cdata-cli 技能的构建阶段配套工具。cdata-cli 使用 JDBC 驱动进行探索 （连接、探索架构、验证 SQL）；此技能会在你开始使用同一款 CData JDBC Driver 编写 JVM 应用代码时接手。

这是构建技能中衔接最顺畅的一项：应用所需的 JDBC jar 正是 cdata-cli 在探索阶段 已下载并激活的 jar。在那里验证过的一切——表、列、SQL——都可以通过 JDBC 原样运行。

---

语言 / 驱动版本

语言	CData 版本	入口点
Java（也包括 Kotlin、Scala 和其他 JVM 语言）	CData JDBC Driver	驱动类 cdata.jdbc.<source>.<Source>Driver；URL jdbc:<source>:<connection-string>

<source> 是驱动名称的小写形式（例如 salesforce），<Source> 是其首字母大写的形式 （例如 Salesforce）：jar 为 cdata.jdbc.salesforce.jar，类为 cdata.jdbc.salesforce.SalesforceDriver，URL 前缀为 jdbc:salesforce:。

---

前提条件：先完成探索

如果本次会话中尚未使用 cdata-cli，请停止并先调用它。 此技能仅涵盖构建阶段——继续操作前，必须通过 cdata-cli 完成连接设置、架构探索和 SQL 验证。

此技能假设你已使用 cdata-cli 确认源能够连接，并验证了应用将要运行的表、列和 SQL。由于 CLI 基于 Java，并通过 JDBC 运行，因此这是所有构建技能中衔接最顺畅的一种——通常有两项工作已经替你完成：

• jar 已下载——cdatacli drivers download 已将 cdata.jdbc.<source>.jar 放入 ./lib/（或者你知道已安装产品的路径）。
• jar 很可能已获得许可——如果探索阶段运行了 cdatacli drivers activate， drivers list 会显示 "activated": true，同一个 jar 已可供应用使用。

如果探索阶段创建了 OAuth 连接，请记下其 OAuthSettingsLocation——应用的 JDBC URL 可以指向同一个缓存令牌文件，从而跳过重新身份验证（参见 连接）。

---

步骤 1：获取驱动 jar

优先使用探索阶段已有的 jar；否则选择以下替代方案之一。

A. 重用 CLI jar（最简单）。 这是完全相同的驱动，且已位于本地：

./lib/cdata.jdbc.<source>.jar        # where cdatacli drivers download put it

B. 已安装产品的路径（如果已安装 JDBC 驱动产品）：

C:\Program Files\CData\CData JDBC Driver for <Source> <Year>\lib\cdata.jdbc.<datasource>.jar   # Windows
/Applications/CData/CData JDBC Driver for <Source> <Year>/lib/cdata.jdbc.<datasource>.jar       # macOS

C. 使用 CData JDBC Maven 仓库中的 Maven/Gradle 依赖。 坐标遵循 CLI 目录 URL——仓库基址为 https://maven.cdata.com/p/jdbc/，groupId 为 cdata，artifactId 为 <source>-jdbc。请通过 cdatacli drivers search --driver <source> 确认准确的 artifactId/版本：

// Gradle (Kotlin DSL) — verify coordinates against `cdatacli drivers search` output
repositories { maven { url = uri("https://maven.cdata.com/p/jdbc/") } }
dependencies { implementation("cdata:salesforce-jdbc:26.0.9666") }

<repository><id>cdata</id><url>https://maven.cdata.com/p/jdbc/</url></repository>
<dependency>
  <groupId>cdata</groupId><artifactId>salesforce-jdbc</artifactId><version>26.0.9666</version>
</dependency>

如果构建无法解析远程仓库，请改为将本地 jar 安装到构建中（Gradle implementation(files("libs/cdata.jdbc.<source>.jar"))，或 Maven mvn install:install-file）。

---

步骤 2：许可

JDBC 驱动按机器授权，与 ADO.NET/ODBC/Python 版本分开。如果探索阶段已激活你要使用的 jar，应用无需再做任何操作。

如需激活：

• 通过 CLI（试用许可可安全地在会话中使用；购买的密钥属于机密——请在 AI 会话之外运行）：

  cdatacli drivers activate <Driver> --name "First Last" --email [email protected] --trial
  cdatacli drivers activate <Driver> --name "First Last" --email [email protected] --key XXXXX
  

• **通过 jar：**双击以启动 GUI 向导，或以非交互方式运行： java -jar cdata.jdbc.<source>.jar --name "First Last" --email [email protected] --key XXXXX。

驱动会在 jar 旁查找许可证（cdata.jdbc.<source>.lic），或在用户的 CData 文件夹中查找 （~/.CData/cdata.jdbc.<source>.lic，即 Windows 上的 %USERPROFILE%\.CData\）。请将 .lic 文件与要分发的 jar 放在一起，或确保 运行时用户的 ~/.CData/ 中包含该文件。

---

步骤 3：将其添加到类路径

操作系统说明： Windows（PowerShell/cmd）上的类路径分隔符是 ;，macOS/Linux 上是 :。 相对路径以当前目录为基准解析——切换到源文件夹，或使用 绝对路径。

javac -cp "cdata.jdbc.<source>.jar" App.java
java  -cp ".:cdata.jdbc.<source>.jar" App        # macOS/Linux — Windows: ".;cdata.jdbc.<source>.jar"

使用 Maven/Gradle 时，步骤 1 中的依赖会自动将其添加到类路径。现代 JDBC（4.0+）会通过 ServiceLoader 自动注册驱动，因此不需要 Class.forName(...)——只需将 jar 添加到类路径即可。

---

步骤 4：连接（JDBC）

JDBC 对象实现了 AutoCloseable，因此请使用 try-with-resources：

import java.sql.*;

String url = "jdbc:salesforce:AuthScheme=OAuth;InitiateOAuth=GETANDREFRESH;UseSandbox=true;"
           + "OAuthSettingsLocation=C:\\...\\OAuthSettings-sbx.txt";

try (Connection conn = DriverManager.getConnection(url);
     PreparedStatement ps = conn.prepareStatement(
         "SELECT Id, Name FROM Account WHERE Name LIKE ?")) {
    ps.setString(1, "%Acme%");                  // ? positional params
    try (ResultSet rs = ps.executeQuery()) {
        while (rs.next()) System.out.println(rs.getString("Name"));
    }
}

• JDBC URL 为 jdbc:<source>:，后接你通过 cdatacli 验证过的、以 ; 分隔的相同连接属性。
• ? 位置参数（setString/setObject）；执行 INSERT/UPDATE/DELETE 时使用 executeUpdate()。
• 使用 ServiceLoader 时无需显式注册驱动；如果非标准类加载器未能找到驱动，请使用 Class.forName("cdata.jdbc.<source>.<Source>Driver") 注册。

连接字符串与身份验证（复用发现结果，勿将密钥写入代码）

根据配置构建 URL，不要硬编码。对于 OAuth 源，将 OAuthSettingsLocation 指向发现流程已填充的令牌文件，以便应用静默刷新。对于没有内置 OAuth 应用的源（例如 Gmail），即使只是刷新令牌，也需要用户自己的 OAuthClientId/OAuthClientSecret——从环境变量读取这些值，切勿提交到版本库。

---

步骤 5：端到端示例（Java）

import java.sql.*;
import java.util.*;

public class Accounts {
    private static final String URL =
        "jdbc:salesforce:AuthScheme=OAuth;InitiateOAuth=GETANDREFRESH;UseSandbox=true;"
      + "OAuthSettingsLocation=C:\\...\\OAuthSettings-sbx.txt";

    static List<String> list(String search, int limit) throws SQLException {
        String sql = "SELECT Id, Name FROM Account"
                   + (search == null ? "" : " WHERE Name LIKE ?")
                   + " ORDER BY Name LIMIT " + limit;
        try (Connection c = DriverManager.getConnection(URL);
             PreparedStatement ps = c.prepareStatement(sql)) {
            if (search != null) ps.setString(1, "%" + search + "%");
            try (ResultSet rs = ps.executeQuery()) {
                List<String> out = new ArrayList<>();
                while (rs.next()) out.add(rs.getString("Name"));
                return out;
            }
        }
    }

    static void create(String name, String industry) throws SQLException {
        try (Connection c = DriverManager.getConnection(URL);
             PreparedStatement ps = c.prepareStatement(
                 "INSERT INTO Account (Name, Industry) VALUES (?, ?)")) {
            ps.setString(1, name);
            ps.setString(2, industry);
            ps.executeUpdate();
        }
    }
}

---

故障排除

错误	原因 / 解决方法
No suitable driver found for jdbc:<source>:...	jar 不在类路径中（或 URL 前缀错误）。将 cdata.jdbc.<source>.jar 添加到类路径 / 依赖项中；确认 URL 以 jdbc:<source>: 开头。
Could not find a valid license	jar 尚未在此计算机上激活——通过 cdatacli drivers activate 或 jar 向导（步骤 2）激活。.lic 必须放在 jar 旁边或 ~/.CData/ 中。
ClassNotFoundException: cdata.jdbc.<source>.<Source>Driver	仅在手动注册时适用——jar 不在类路径中，或类名拼写错误（<Source> 是大小写格式正确的驱动名称）。
'OAuthClientId' and 'OAuthClientSecret' are needed to initiate OAuth	此源没有内置 OAuth 应用；将客户端 ID/密钥（来自环境变量）添加到 JDBC URL 中，并确保与缓存刷新令牌的应用一致。