Module java.sql
Package java.sql

Interface Array

所有已知的实现类:
SerialArray
public interface Array
Java编程语言中对SQL类型ARRAY的映射。默认情况下，Array值是对SQL ARRAY值的事务期引用。默认情况下，Array对象在内部使用SQL LOCATOR(array)实现，这意味着Array对象包含对SQL ARRAY值中数据的逻辑指针，而不是包含ARRAY值的数据。

Array接口提供了将SQL ARRAY值的数据作为数组或ResultSet对象带到客户端的方法。如果SQL ARRAY的元素是UDT，则可以进行自定义映射。要创建自定义映射，程序员必须执行两项操作:

  • 创建一个实现SQLData接口的类，用于自定义映射的UDT。
  • 在包含以下内容的类型映射中进行条目
    • UDT的完全限定SQL类型名称
    • 实现SQLData的类的Class对象

如果向方法getArray和getResultSet提供了具有基本类型条目的类型映射，则将使用它包含的映射来映射ARRAY值的元素。如果未提供类型映射，这通常是情况，将默认使用连接的类型映射。如果连接的类型映射或向方法提供的类型映射没有基本类型的条目，则根据标准映射来映射元素。

如果JDBC驱动程序支持数据类型，则Array接口上的所有方法必须完全实现。

自1.2版本起:
1.2

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    free()
    该方法释放Array对象并释放其持有的资源。
    Object
    getArray()
    以Java编程语言中数组的形式检索由此Array对象指定的SQL ARRAY值的内容。
    Object
    getArray(long index, int count)
    以Java编程语言中数组的形式检索由此Array对象指定的SQL ARRAY值的切片，从指定的index开始，包含最多count个连续的SQL数组元素。
    Object
    getArray(long index, int count, Map<String,Class<?>> map)
    以Java编程语言中数组的形式检索由此Array对象指定的SQL ARRAY值的切片，从指定的index开始，包含最多count个连续的SQL数组元素。
    Object
    getArray(Map<String,Class<?>> map)
    检索由此Array对象指定的SQL ARRAY值的内容。
    int
    getBaseType()
    检索由此Array对象指定的数组中元素的JDBC类型。
    String
    getBaseTypeName()
    检索由此Array对象指定的数组中元素的SQL类型名称。
    ResultSet
    getResultSet()
    检索包含由此Array对象指定的SQL ARRAY值的元素的结果集。
    ResultSet
    getResultSet(long index, int count)
    检索包含从索引index开始并包含最多count个连续元素的子数组元素的结果集。
    ResultSet
    getResultSet(long index, int count, Map<String,Class<?>> map)
    检索包含从索引index开始并包含最多count个连续元素的子数组元素的结果集。
    ResultSet
    getResultSet(Map<String,Class<?>> map)
    检索包含由此Array对象指定的SQL ARRAY值的元素的结果集。

  • Method Details

    • getBaseTypeName

      String getBaseTypeName() throws SQLException
      检索由此Array对象指定的数组中元素的SQL类型名称。如果元素是内置类型，则返回元素的数据库特定类型名称。如果元素是用户定义类型（UDT），则此方法返回完全限定的SQL类型名称。
      返回:
      一个String，用于内置基本类型的数据库特定名称；或用于UDT的基本类型的完全限定SQL类型名称
      抛出:
      SQLException - 如果尝试访问类型名称时发生错误
      SQLFeatureNotSupportedException - 如果JDBC驱动程序不支持此方法
      自1.2版本起:
      1.2

    • getBaseType

      int getBaseType() throws SQLException
      检索由此Array对象指定的数组中元素的JDBC类型。
      返回:
      来自类Types的常量，该常量是由此Array对象指定的数组中元素的类型代码
      抛出:
      SQLException - 如果尝试访问基本类型时发生错误
      SQLFeatureNotSupportedException - 如果JDBC驱动程序不支持此方法
      自1.2版本起:
      1.2

    • getArray

      Object getArray() throws SQLException
      以Java编程语言中数组的形式检索由此Array对象指定的SQL ARRAY值的内容。此方法getArray的此版本使用与连接关联的类型映射进行类型映射的自定义。

      注意: 当使用getArray来实现映射到原始数据类型的基本类型时，返回的数组是该原始数据类型的数组还是Object数组是由实现定义的。

      返回:
      一个在Java编程语言中包含由此Array对象指定的SQL ARRAY值的有序元素的数组
      抛出:
      SQLException - 如果尝试访问数组时发生错误
      SQLFeatureNotSupportedException - 如果JDBC驱动程序不支持此方法
      自1.2版本起:
      1.2

    • getArray

      Object getArray(Map<String,Class<?>> map) throws SQLException
      以Java编程语言中数组的形式检索由此Array对象指定的SQL ARRAY值的内容。此方法使用指定的map进行类型映射自定义，除非数组的基本类型与map中的用户定义类型不匹配，在这种情况下，它使用标准映射。此方法getArray的此版本使用给定的类型映射或标准映射；它永远不使用与连接关联的类型映射。

      注意: 当使用getArray来实现映射到原始数据类型的基本类型时，返回的数组是该原始数据类型的数组还是Object数组是由实现定义的。

      参数:
      map - 一个包含SQL类型名称到Java编程语言中类的映射的java.util.Map对象
      返回:
      一个在Java编程语言中包含由此对象指定的SQL数组的有序元素的数组
      抛出:
      SQLException - 如果尝试访问数组时发生错误
      SQLFeatureNotSupportedException - 如果JDBC驱动程序不支持此方法
      自1.2版本起:
      1.2

    • getArray

      Object getArray(long index, int count) throws SQLException
      以Java编程语言中数组的形式检索由此Array对象指定的SQL ARRAY值的切片，从指定的index开始，包含最多count个连续的SQL数组元素。此方法使用与连接关联的类型映射进行类型映射的自定义。

      注意: 当使用getArray来实现映射到原始数据类型的基本类型时，返回的数组是该原始数据类型的数组还是Object数组是由实现定义的。

      参数:
      index - 要检索的第一个元素的数组索引；第一个元素位于索引1处
      count - 要检索的连续SQL数组元素的数量
      返回:
      包含最多count个连续元素的SQL数组的数组，从元素index开始
      抛出:
      SQLException - 如果尝试访问数组时发生错误
      SQLFeatureNotSupportedException - 如果JDBC驱动程序不支持此方法
      自1.2版本起:
      1.2

    • getArray

      Object getArray(long index, int count, Map<String,Class<?>> map) throws SQLException
      以Java编程语言中数组的形式检索由此Array对象指定的SQL ARRAY值的切片，从指定的index开始，包含最多count个连续的SQL数组元素。

      此方法使用指定的map进行类型映射自定义，除非数组的基本类型与map中的用户定义类型不匹配，在这种情况下，它使用标准映射。此方法getArray的此版本使用给定的类型映射或标准映射；它永远不使用与连接关联的类型映射。

      注意: 当使用getArray来实现映射到原始数据类型的基本类型时，返回的数组是该原始数据类型的数组还是Object数组是由实现定义的。

      参数:
      index - 要检索的第一个元素的数组索引；第一个元素的索引为1
      count - 要检索的连续SQL数组元素的数量
      map - 一个包含SQL类型名称和它们在Java编程语言中映射的类的java.util.Map对象
      返回:
      包含由此Array对象指定的SQL ARRAY值的最多count个连续元素的数组，从元素index开始
      抛出:
      SQLException - 如果尝试访问数组时发生错误
      SQLFeatureNotSupportedException - 如果JDBC驱动程序不支持此方法
      自版本:
      1.2

    • getResultSet

      ResultSet getResultSet() throws SQLException
      检索包含由此Array对象指定的SQL ARRAY值的元素的结果集。如果适用，数组的元素将使用连接的类型映射进行映射；否则，将使用标准映射。

      结果集为每个数组元素包含一行，每行有两列。第二列存储元素值；第一列存储该元素的数组索引（第一个数组元素的索引为1）。行按照索引的顺序升序排列。

      返回:
      包含由此Array对象指定的数组中每个元素的一行的ResultSet对象，行按照索引升序排列。
      抛出:
      SQLException - 如果尝试访问数组时发生错误
      SQLFeatureNotSupportedException - 如果JDBC驱动程序不支持此方法
      自版本:
      1.2

    • getResultSet

      ResultSet getResultSet(Map<String,Class<?>> map) throws SQLException
      检索包含由此Array对象指定的SQL ARRAY值的元素的结果集。此方法使用指定的map进行类型映射自定义，除非数组的基本类型与map中的用户定义类型不匹配，在这种情况下将使用标准映射。此版本的方法getResultSet使用给定的类型映射或标准映射；它永远不会使用与连接关联的类型映射。

      结果集为每个数组元素包含一行，每行有两列。第二列存储元素值；第一列存储该元素的数组索引（第一个数组元素的索引为1）。行按照索引的顺序升序排列。

      参数:
      map - 包含SQL用户定义类型到Java编程语言中的类的映射
      返回:
      包含由此Array对象指定的数组中每个元素的一行的ResultSet对象，行按照索引升序排列。
      抛出:
      SQLException - 如果尝试访问数组时发生错误
      SQLFeatureNotSupportedException - 如果JDBC驱动程序不支持此方法
      自版本:
      1.2

    • getResultSet

      ResultSet getResultSet(long index, int count) throws SQLException
      检索从索引index开始并包含最多count个连续元素的子数组的结果集。如果映射中包含基本类型的条目，则此方法使用连接的类型映射来映射数组的元素。否则，将使用标准映射。

      结果集为此对象指定的SQL数组的每个元素包含一行，第一行包含索引为index的元素。结果集最多有count行，按照索引升序排列。每行有两列：第二列存储元素值；第一列存储该元素的数组索引。

      参数:
      index - 要检索的第一个元素的数组索引；第一个元素的索引为1
      count - 要检索的连续SQL数组元素的数量
      返回:
      包含由此Array对象指定的SQL数组中最多count个连续元素的ResultSet对象，从索引index开始。
      抛出:
      SQLException - 如果尝试访问数组时发生错误
      SQLFeatureNotSupportedException - 如果JDBC驱动程序不支持此方法
      自版本:
      1.2

    • getResultSet

      ResultSet getResultSet(long index, int count, Map<String,Class<?>> map) throws SQLException
      检索从索引index开始并包含最多count个连续元素的子数组的结果集。此方法使用指定的map进行类型映射自定义，除非数组的基本类型与map中的用户定义类型不匹配，在这种情况下将使用标准映射。此版本的方法getResultSet使用给定的类型映射或标准映射；它永远不会使用与连接关联的类型映射。

      结果集为此对象指定的SQL数组的每个元素包含一行，第一行包含索引为index的元素。结果集最多有count行，按照索引升序排列。每行有两列：第二列存储元素值；第一列存储该元素的数组索引。

      参数:
      index - 要检索的第一个元素的数组索引；第一个元素的索引为1
      count - 要检索的连续SQL数组元素的数量
      map - 包含SQL类型名称到Java(tm)编程语言中的类的映射的Map对象
      返回:
      包含由此Array对象指定的SQL数组中最多count个连续元素的ResultSet对象，从索引index开始。
      抛出:
      SQLException - 如果尝试访问数组时发生错误
      SQLFeatureNotSupportedException - 如果JDBC驱动程序不支持此方法
      自版本:
      1.2

    • free

      void free() throws SQLException
      该方法释放Array对象并释放其持有的资源。一旦调用free方法，对象将无效。

      在调用free后，任何尝试调用free以外的方法都将导致抛出SQLException。如果多次调用free，则后续调用free将被视为无操作。

      抛出:
      SQLException - 如果释放Array的资源时发生错误
      SQLFeatureNotSupportedException - 如果JDBC驱动程序不支持此方法
      自版本:
      1.6