OceanBase Connector/J 连接 OceanBase 数据库示例程序

本文将介绍如何使用 OceanBase Connector/J 和 OceanBase 数据库构建一个应用程序，实现创建表、插入数据和查询数据等基本操作。

点击下载 java-oceanbase-jdbc 示例工程 OceanBase Connector/J 连接 OceanBase 数据库示例程序（Oracle 模式）

前提条件

• 您已安装 OceanBase 数据库。

• 您已安装 JDK 1.8 和 Maven。

• 您已安装 Eclipse。

  说明

  本文档运行代码使用的工具是 Eclipse IDE for Java Developers 2022-03 版本，您也可以根据个人喜好选择适合自己的工具运行的示例代码。

操作步骤

1. 将 java-oceanbase-jdbc 项目导入到 Eclipse 中。
2. 获取 OceanBase 数据库 URL。
3. 修改 java-oceanbase-jdbc 项目中的数据库连接信息。
4. 运行 java-oceanbase-jdbc 项目。

步骤一：将 java-oceanbase-jdbc 项目导入到 Eclipse 中

1. 打开 Eclipse，选择 File 菜单中的 Import 选项。

   

2. 在弹出的导入窗口中，选择 Maven > Existing Maven Projects，并点击 Next。

   

3. 在下一个页面中，点击 Browse 按钮，选择 Maven 项目的根目录，然后点击 Finish。

   

4. Eclipse 将会自动识别项目中的 pom.xml 文件，并在 Package Explorer 中显示所有的 Maven 项目。在 Eclipse 的左侧面板中，可以看到Package Explorer 的图标。如果没有显示，可以选择 Window 菜单，然后选择 Show View > Package Explorer。

   说明

   当使用 Eclipse 导入 Maven 项目时，Eclipse 会自动检测项目中的 pom.xml 文件，并根据文件中描述的依赖关系自动下载所需的依赖库，并将它们添加到项目中。

   

5. 查看项目情况。

   

步骤二：获取 OceanBase 数据库 URL

1. 联系 OceanBase 数据库部署人员或者管理员获取相应的数据库连接串。

   示例如下：

   obclient -hxxx.xxx.xxx.xxx -P2883 -usys@oracel001#cluster_name -p******
   

   更多连接串的信息，请参见 通过 OBClient 连接 OceanBase 租户。

2. 根据 OceanBase 数据库连接串信息填写下面 URL 的对应信息。

   连接 OceanBase 数据库 Oracle 模式 URL 示例如下：

   jdbc:oceanbase://$host:$port/$schema_name?user=$user_name&password=$password
   

   参数说明：

   • $host：提供 OceanBase 数据库连接 IP。ODP 连接方式使用的是一个 ODP 地址；直连方式使用的是 OBServer 节点的 IP 地址。
   • $port：提供 OceanBase 数据库连接端口。ODP 连接的方式默认是 2883，在部署 ODP 时可自定义；直连方式默认是 2881，在部署 OceanBase 数据库时可自定义。
   • $schema_name：需要访问的 Schema 名称。
   • $user_name：提供租户的连接账户。ODP 连接的方式格式：用户名@租户名#集群名 或者 集群名:租户名:用户名；直连方式格式：用户名@租户名。
   • $password：提供账户密码。

   更多 URL 参数说明信息，请参见 数据库 URL。

步骤三：修改 java-oceanbase-jdbc 项目中的数据库连接信息

根据 步骤二：获取 OceanBase 数据库 URL 中的信息修改 InsertAndSelectExample.java 文件中的数据库连接信息。

示例如下：

• OBServer 节点的 IP 地址为 10.10.10.1。
• 访问端口使用的是 2881。
• 需要访问的 Schema 名称为 sys。
• 租户的连接账户是 sys@oracle001。oracle001 是在 OceanBase 数据库中创建的一个 Oracle 模式的用户租户，sys 是租户 oracle001 的用户名称。
• 密码是 ******。

示例代码如下：

String url = "jdbc:oceanbase://10.10.10.1:2881/sys";
String user = "sys@oracle001";
String password = "******";

步骤四：运行 java-oceanbase-jdbc 项目

1. 可以在 Package Explorer 中查看项目结构。

   

2. 找到项目中的 Main 类，右键单击该类，选择 Run As > Run Configurations... 打开 Run Configurations 页面。

   

3. 在 Run Configurations 页面，在 Java Application > New_configuration 页面的 Main class 中选择 com.oceanbase.example.InsertAndSelectExample 项目。

   

4. 通过 Eclipse 的控制台来查看项目的日志信息和输出结果。

   

项目代码介绍

点击 java-oceanbase-jdbc 下载项目代码，是一个名称为 java-oceanbase-jdbc.zip 的压缩包。

解压后，得到一个名为 java-oceanbase-jdbc 的文件夹。目录结构如下所示：

.
|-- README-CN.md
|-- README.md
|-- pom.xml
|-- run.sh
`-- src
    `-- main
        `-- java
            `-- com
                `-- oceanbase
                    `-- example
                        |-- InsertAndSelectExample.java
                        `-- OceanBaseClientTest.java

文件说明：

• README-CN.md：该文件是项目的说明文档，主要面向中文用户。
• README.md：该文件也是项目的说明文档，但是采用英文编写，主要面向英文用户。
• pom.xml：该文件是 Maven 项目的配置文件，定义了项目的依赖项、插件和构建规则等信息。
• run.sh：该文件是一个 Shell 脚本，主要用于自动编译和运行Java应用程序。
• src：该目录包含了项目的源代码和资源文件，是项目的主要目录。
• main：该目录是一个 Java 源码目录，包含了项目的主要代码。
• java：该目录是 Java 源码的根目录。
• com：该目录是 Java 包的根目录。
• oceanbase：该目录是 com 包下的子包，表示该项目是与 OceanBase 数据库相关的。
• example：该目录是 oceanbase 包下的子包，表示该项目是一个示例程序，用于演示如何使用 OceanBase JDBC 驱动程序连接和操作 OceanBase 数据库。
• InsertAndSelectExample.java：该文件是示例程序的一部分，包含了一个示例类 InsertAndSelectExample，用于演示如何插入和查询数据。
• OceanBaseClientTest.java：该文件也是示例程序的一部分，包含了一个示例类 OceanBaseClientTest，用于演示如何连接数据库、执行 SQL 语句和查询数据等操作。

pom.xml 代码介绍

pom.xml 文件是 Maven 项目的配置文件，定义了项目的依赖项、插件和构建规则等信息。Maven 是一个 Java 项目管理工具，可以自动下载依赖项、编译和打包项目等操作。

本文 pom.xml 文件的代码主要包括以下几个部分：

1. 文件声明语句。

   声明本文件是一个 XML 文件，使用的 XML 版本是 1.0，字符编码方式是 UTF-8。

   代码如下：

   <?xml version="1.0" encoding="UTF-8"?>
   

2. 配置 POM 的命名空间和 POM 模型版本。

   1. 通过 xmlns 指定 POM 的命名空间为 http://maven.apache.org/POM/4.0.0。
   2. 通过 xmlns:xsi 指定 XML 命名空间 http://www.w3.org/2001/XMLSchema-instance。
   3. 通过 xsi:schemaLocation 指定 POM 的命名空间为 http://maven.apache.org/POM/4.0.0 和 POM 的 XSD 文件的位置为 http://maven.apache.org/xsd/maven-4.0.0.xsd。
   4. 通过 <modelVersion> 元素指定了该 POM 文件使用的 POM 模型版本为 4.0.0。

   代码如下：

   <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
    <!-- 其他配置 -->
   </project>
   

3. 基本信息配置。

   1. 通过 <groupId> 指定项目标识为 com.oceanbase.example。
   2. 通过 <artifactId> 指定项目依赖为 oceanbase-client。
   3. 通过 <version> 项目的版本号为 1.0-SNAPSHOT。
   4. 通过 <name> 设置项目的名称为 ob-example-oceanbase-client。

   代码如下：

   <groupId>com.oceanbase.example</groupId>
   <artifactId>oceanbase-client</artifactId>
   <version>1.0-SNAPSHOT</version>
   
   <name>ob-example-oceanbase-client</name>
   

4. 通过 <properties> 定义项目源文件的属性。

   1. 通过 <project.build.sourceEncoding> 指定项目源文件的编码为 UTF-8。
   2. 通过 <maven.compiler.source> 指定 Maven 编译器使用的 Java 源代码版本为 1.8。
   3. 通过 <maven.compiler.target> 指定 Maven 编译器生成的 Java 字节码版本为 1.8。
   4. 通过 <exec.mainClass> 指定项目中的一个示例程序 com.oceanbase.example.InsertAndSelectExample。

   代码如下：

   <properties>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     <maven.compiler.source>1.8</maven.compiler.source>
     <maven.compiler.target>1.8</maven.compiler.target>
     <exec.mainClass>com.oceanbase.example.InsertAndSelectExample</exec.mainClass>
   </properties>
   

5. 通过 <dependencies> 定义项目所依赖组件。

   说明

   本部分代码定义项目所依赖组件是 OceanBase Connector/J 的 V2.4.2 版本，如果需要了解其他版本的信息，请参见 OceanBase JDBC 驱动程序

   1. 通过 <dependency> 定义一个依赖项。
   2. 通过 <groupId> 指定依赖项所属的组织为 com.oceanbase。
   3. 通过 <artifactId> 指定依赖项的名称为 oceanbase-client。
   4. 通过 <version> 指定依赖项的版本号为 2.4.2。

   代码如下：

     <dependencies>
       <dependency>
         <groupId>com.oceanbase</groupId>
         <artifactId>oceanbase-client</artifactId>
         <version>2.4.2</version>
       </dependency>
     </dependencies>
   

InsertAndSelectExample.java 代码介绍

InsertAndSelectExample.java 文件是示例程序的一部分，包含了一个示例类 InsertAndSelectExample，用于演示如何插入和查询数据。

本文 InsertAndSelectExample.java 文件的代码主要包括以下几个部分：

1. 定义包和导入 java.sql 的接口。

   声明当前文件所属的包名为 com.oceanbase.example。

   引入 java.sql 包中的以下接口和类：

   • Connection 接口：表示与数据库的连接。
   • DriverManager 类：它提供了一组静态方法，用于管理 JDBC 驱动程序的注册和获取数据库连接。其中，最常用的方法是 getConnection()，用于创建一个与数据库的连接。
   • PreparedStatement 接口：表示预编译的 SQL 语句。
   • ResultSet 接口：表示查询结果集。
   • SQLException 异常类：表示在使用 JDBC 连接数据库时发生的各种异常情况，例如：连接失败、执行 SQL 命令失败等。
   • Statement 接口：表示数据库中的一条语句。

   代码如下：

   package com.oceanbase.example;
   
   import java.sql.Connection;
   import java.sql.DriverManager;
   import java.sql.PreparedStatement;
   import java.sql.ResultSet;
   import java.sql.SQLException;
   import java.sql.Statement;
   

2. 定义类名和 main 方法。

   定义类名为 InsertAndSelectExample，需要与文件名保持一致。

   main 方法定义为 public static void，表示是一个公共静态方法，它接受一个字符串数组 args 作为参数。使用 throws ClassNotFoundException, SQLException 表示该方法可能会抛出 ClassNotFoundException 和 SQLException 异常，需要在方法调用处进行处理。

   代码如下：

   public class InsertAndSelectExample {
   
       public static void main(String[] args) throws ClassNotFoundException, SQLException {
           // to do:
           // 3.connect to your database
           // 4.create a table
           // 5.insert records
           // 6.fetch all records
           // 7.release all resources
       }
   }
   

3. 连接数据库和获取数据库连接对象。

   定义连接 OceanBase 数据库所需的 URL 字符串和额外的连接属性，其中：

   • jdbc:oceanbase：表示使用 OceanBase 的 JDBC 驱动程序连接数据库。
   • host:port：表示 OceanBase 数据库的 IP 地址和端口号。
   • opt1=val1&opt2=val2...：额外的连接属性，即 URL 参数。更多 URL 额外的连接属性说明信息，请参见 数据库 URL。
   • schema_name：表示连接的 Schema 名。
   • String user = "user_name"：定义了登录数据库所需的用户名。
   • String password = "******"：定义了登录数据库所需的密码。

   获取数据库连接对象：

   • 通过调用 Class 的 forName 方法，加载指定类名为 com.oceanbase.jdbc.Driver 的驱动程序类。
   • 通过 DriverManager 类中的 getConnection 方法获取 Connection 对象 conn。

   代码如下：

   String url = "jdbc:oceanbase://host:port/schema_name?[opt1=val1&opt2=val2...]";
   String user = "user_name";
   String password = "******";
   Class.forName("com.oceanbase.jdbc.Driver");
   Connection conn = DriverManager.getConnection(url, user, password);
   

4. 创建表。

   创建一个名为 person 的表，其中包含 name 和 age 两个字段，如果该表已经存在，则先删除再创建。具体步骤如下：

   1. 创建了一个名为 stmt 的 Statement 对象，用于向数据库发送 SQL 语句。
   2. 通过调用 stmt 对象的 execute 方法，并传入 SQL 语句drop table person 用来删除名为 person 的表。由于不能确定 person 表是否已经存在，所以使用 try-catch 结构捕获了异常，以免在删除不存在的表时程序崩溃。
   3. 再次通过调用 stmt 对象的 execute 方法，并传入 SQL 语句create table person (name varchar(50), age int) 创建名为 person 的表，其中包含两个字段 name 和 age，name 字段类型为 varchar(50)，age 字段类型为 int。

   代码如下：

   Statement stmt = conn.createStatement();
       try {stmt.execute("drop table person");} 
       catch (Exception ignore) {}
           stmt.execute("create table person (name varchar(50), age int)");
   

5. 向表中插入数据。

   使用了 PreparedStatement 接口来向数据库中的 person 表中插入两条数据。具体步骤如下：

   1. 创建了一个名为 ps 的 PreparedStatement 对象，用于执行 SQL 语句。SQL 语句是 insert into person values(?, ?)，其中 ? 是占位符，表示需要填入具体的值。
   2. 调用 setString() 方法，将第一个占位符（即第一个问号）设置为 Adam。
   3. 调用了 setInt() 方法，将第二个占位符（即第二个问号）设置为 28。
   4. 执行了更新操作，将数据插入到数据库中。
   5. 再次调用了 setString() 方法，将第一个占位符设置为 "Eve"。
   6. 再次调用了 setInt() 方法，将第二个占位符设置为 26。
   7. 再次执行了更新操作，将第二条数据插入到数据库中。

   代码如下：

   PreparedStatement ps = conn.prepareStatement("insert into person values(?, ?)");
       ps.setString(1, "Adam");
       ps.setInt(2, 28);
       ps.executeUpdate();
       ps.setString(1, "Eve");
       ps.setInt(2, 26);
       ps.executeUpdate();
   

6. 获取所有记录。

   从 person 表中查询所有数据，并将结果输出到控制台上。具体步骤如下：

   1. 创建了一个名为 ps 的 PreparedStatement 对象，用于执行 SQL 语句。SQL 语句是 select * from person，表示查询 person 表中的所有数据。通过 setFetchDirection() 方法将结果集的游标设置为向前移动，并通过 setConcurrency() 方法将结果集设置为只读。
   2. 执行了查询操作，将查询结果保存在 ResultSet 对象中，ResultSet 对象命名为 rs。
   3. 使用 while 循环遍历 ResultSet 对象，通过 rs.next() 方法移动游标到下一行数据，如果还有数据就返回 true。 在循环内部，使用 rs.getString(1) 方法获取第一列的值（即 person 表中的 name），使用 rs.getInt(2) 获取第二列的值（即 age），并将这些值输出到控制台中，格式为 name is age years old.。
   4. 循环结束后，关闭了 ResultSet 和 PreparedStatement 对象。

   代码如下：

   ps = conn.prepareStatement("select * from person", ResultSet.TYPE_FORWARD_ONLY, ResultSet.CONCUR_READ_ONLY);
   ResultSet rs = ps.executeQuery();
   while (rs.next()) {
       System.out.println(rs.getString(1) + " is " + rs.getInt(2) + " years old.");
       }
   

7. 释放数据库资源。

   关闭 PreparedStatement、Statement 和 Connection 对象，释放与之相关的数据库资源，从而避免资源消耗和性能问题。

   代码如下：

   ps.close();
   stmt.close();
   conn.close();
   

完整的代码展示

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.oceanbase.example</groupId>
  <artifactId>oceanbase-client</artifactId>
  <version>1.0-SNAPSHOT</version>

  <name>ob-example-oceanbase-client</name>

  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
    <exec.mainClass>com.oceanbase.example.InsertAndSelectExample</exec.mainClass>
  </properties>

  <dependencies>
    <dependency>
      <groupId>com.oceanbase</groupId>
      <artifactId>oceanbase-client</artifactId>
      <version>2.4.2</version>
    </dependency>
  </dependencies>

</project>

package com.oceanbase.example;

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;

public class InsertAndSelectExample {

    public static void main(String[] args) throws ClassNotFoundException, SQLException {

        String url = "jdbc:oceanbase://host:port/schema_name?[opt1=val1&opt2=val2...]";
        String user = "user_name";
        String password = "******";
        Class.forName("com.oceanbase.jdbc.Driver");
        Connection conn = DriverManager.getConnection(url, user, password);

        Statement stmt = conn.createStatement();
        try {
            stmt.execute("drop table person");
        } catch (Exception ignore) {
        }
        stmt.execute("create table person (name varchar2(50), age int)");

        PreparedStatement ps = conn.prepareStatement("insert into person values(?, ?)");
        ps.setString(1, "Adam");
        ps.setInt(2, 28);
        ps.executeUpdate();
        ps.setString(1, "Eve");
        ps.setInt(2, 26);
        ps.executeUpdate();

        ps = conn.prepareStatement("select * from person", ResultSet.TYPE_FORWARD_ONLY, ResultSet.CONCUR_READ_ONLY);
        ResultSet rs = ps.executeQuery();
        while (rs.next()) {
            System.out.println(rs.getString(1) + " is " + rs.getInt(2) + " years old.");
        }

        ps.close();
        stmt.close();
        conn.close();
    }

}

相关文档

更多 OceanBase Connector/J 的信息，请参见 OceanBase JDBC 驱动程序