快速开始

本节将展示通过 Java API 连接、使用及操作单节点 DolphinDB 服务器的完整操作。通过阅读，您将了解到如何使用 Java API 连接 DolphinDB 并与之交互、以及如何操作数据库表。

使用前准备

Java 基础知识

在学习使用 Java API 前，建议您先了解 Java 的相关知识。您可以查阅 Java 官方文档或者 Java SE 文档，了解有关 Java 的更多信息和教程。

搭建 DolphinDB 服务器

在 DolphinDB 官网下载 DolphinDB 服务器，并参考 DolphinDB 部署指南启动 DolphinDB 服务。

建立连接

DBConnection（数据库连接）可以实现客户端与服务器之间的信息交互。DolphinDB Java API 通过 DBConnection 在 DolphinDB 服务器上执行脚本和函数，同时实现双向的数据传递。

DBConnection 连接及使用示例

在如下示例代码中，先创建一个 DBConnection，然后使用指定的 IP 和端口号，以 Guest 身份连接到 DolphinDB 服务器。最后展示一个简单的计算示例，执行 ”1+1” 的脚本，得到返回值 2。

public class TestDBConnection {
    // host
    private static final String HOST = "localhost"; 
    // port
    private static final int PORT = 8848; 

    DBConnection dbConnection = new DBConnection();

    @Test
    public void testDBConnectAndRun() throws IOException {
        dbConnection.connect(HOST, PORT);
        Entity entity = dbConnection.run("x = 1+1; x;");
        dbConnection.close();
        
        System.out.println(entity.getString());
    }
}

执行结果：

Connect to localhost:8848.
2

注意，部分函数需要使用管理员权限或者有该函数执行权限的用户才能执行，如 getFunctionViews() 等；同时一些函数在非管理员或无权限下执行将返回空结果，如 getDFSDatabases() 等。关于更多用户权限问题，可以参考文档用户权限管理。

下例代码将以 USER = "admin" PASSWORD = "123456"的管理员身份建立连接并登录，同时执行一个获取所有函数视图的脚本。

public class TestDBConnection {
    // hostName
    private static final String HOST = "localhost"; 
    // port
    private static final int PORT = 8848; 
    // userId
    private static final String USER = "admin"; 
    // password
    private static final String PASSWORD = "123456"; 

    DBConnection dbConnection = new DBConnection();

    @Test
    public void testAdminUserConnectAndRun() throws IOException {
        dbConnection.connect(HOST, PORT, USER, PASSWORD);
        Entity entity = dbConnection.run("getFunctionViews()");
        System.out.println(entity.getString());
    }
}

执行结果：

name    body                                                   
------- -------------------------------------------------------------
CONCAT1 def CONCAT1(X, Y){
  return string(X) + string(Y)
}    
instr   def instr(string1, string2, start_position = NULL, n...
nvl2    def nvl2(col, result1, result2){
  return iif(! isNu...

如果以非管理员身份或无权限执行需要有权限的脚本，代码示例如下：

public class TestDBConnection {
    // hostName
    private static final String HOST = "YourHost"; 
    // port
    private static final int PORT = "YourPort"; 

    DBConnection dbConnection = new DBConnection();

    @Test
    public void testGuestConnectAndRun() throws IOException {
        dbConnection.connect(HOST, PORT);
        Entity entity = dbConnection.run("getFunctionViews()");
        System.out.println(entity.getString());
    }
}

则将得到执行结果：

java.io.IOException: 192.168.0.68:8848 Server response: 'getFunctionViews() => Only administrators can use function getFunctionViews.' script: 'getFunctionViews()'

注意：

建立连接前，须先启动 DolphinDB 服务器。
若当前 DBConnection 不再使用，建议立即调用 close() 关闭会话。否则可能出现因连接数过多，导致其它连接无法连接服务器的情况。