JavaTM Platform
Standard Ed. 6

javax.sql.rowset.serial
类 SerialArray

java.lang.Object
  继承者 javax.sql.rowset.serial.SerialArray
所有已实现的接口:
Serializable, Cloneable, Array

public class SerialArray
     
extends Object
implements Array, Serializable, Cloneable

序列化的 Array 对象,它是 SQL ARRAY 值在 Java 编程语言中的映射关系。

SerialArray 类提供一个根据 Array 对象创建 SerialArray 实例的构造方法,提供获取基本类型及其 SQL 名称的各种方法,以及复制全部或部分 SerialArray 对象的各种方法。

注:要让此类正常运行,到数据源的连接必须可用,这样在需要时才能实现 SQL Array 对象(将其所有元素置于客户端服务器)。在这种情况下,指向数据源中数据的逻辑指针(如定位符)当前不受支持。

另请参见:
序列化表格

构造方法摘要
SerialArray(Array array)
          根据给定 Array 对象构造新的 SerialArray 对象。
SerialArray(Array array, Map<String,Class<?>> map)
          根据给定 Array 对象构造新的 SerialArray 对象,当数组元素是 SQL UDT 时对每个元素的自定义映射关系使用给定的类型映射表。
 
方法摘要
 void free()
          此方法释放 Array 对象及其占有的资源。
 Object getArray()
          返回一个新数组,它是此 SerialArray 对象的副本。
 Object getArray(long index, int count)
          返回一个新数组,它是部分此 SerialArray 对象的副本,从给定索引处的元素开始,包含给定的连续元素数。
 Object getArray(long index, int count, Map<String,Class<?>> map)
          返回一个新数组,它是部分此 SerialArray 对象的副本,从给定索引处的元素开始,包含给定的连续元素数。
 Object getArray(Map<String,Class<?>> map)
          返回一个新数组,它是此 SerialArray 对象的副本,当元素为 SQL UDT 时对每个自定义映射关系的元素使用给定类型映射表。
 int getBaseType()
          获取此 SerialArray 对象中 SQL 类型的元素。
 String getBaseTypeName()
          获取此 SerialArray 对象元素特定于 DBMS 的类型名称。
 ResultSet getResultSet()
          获取 ResultSet 对象,该对象包含由此 SerialArray 对象所表示的所有 ARRAY 值中的元素。
 ResultSet getResultSet(long index, int count)
          获取保存子数组元素的 ResultSet 对象,该子数组从 index 索引处开始,包含 count 个连续元素。
 ResultSet getResultSet(long index, int count, Map<String,Class<?>> map)
          获取包含此 SerialArray 对象中元素的子数组的 ResultSet 对象,该子数组从 index 索引处开始,包含 count 个连续元素。
 ResultSet getResultSet(Map<String,Class<?>> map)
          获取 ResultSet 对象,该对象包含由此 SerialArray 对象所表示的所有 SQL ARRAY 值的元素。
 
从类 java.lang.Object 继承的方法
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

构造方法详细信息

SerialArray

public SerialArray(Array array,
                   Map<String,Class<?>> map)
            throws SerialException,
                   SQLException
根据给定 Array 对象构造新的 SerialArray 对象,当数组元素是 SQL UDT 时对每个元素的自定义映射关系使用给定的类型映射表。

如果数组元素为 UDT 并且给定类型映射表具有针对该 UDT 的条目,则此方法执行自定义映射。自定义映射是递归的,这意味着,如果 SQL 结构类型的元素是 SQL 结构类型,而它本身又具有 SQL 结构类型的元素,则根据给定类型映射表映射每个具有自定义映射关系的结构类型。

SerialArray 对象包含的元素与用来构建它的 Array 对象相同,基本类型为 SQL 类型 STRUCTARRAYBLOBCLOBDATALINKJAVA_OBJECT 时除外。在这种情况下,新 SerialArray 对象中的每个元素都是适当的序列化形式,即 SerialStructSerialArraySerialBlobSerialClobSerialDatalinkSerialJavaObject 对象。

注:(1) 用来创建 SerialArray 对象的 Array 对象在被传递给构造方法之前,必须已经在客户端实现了 SQL ARRAY 值的数据。否则,新 SerialArray 对象将不包含任何数据。

注:(2) 如果 Array 包含 java.sql.Types.JAVA_OBJECT 类型,则调用 SerialJavaObject 构造方法,其中会执行检查以确保此对象可序列化。

注:(3) 提供给此构造方法的 Array 对象对于任何 Array.getArray() 方法都不能返回 nullSerialArray 无法序列化 null 数组值。

参数:
array - 要序列化的 Array 对象
map - java.util.Map 对象,其中每个条目都包含:1) 给出 UDT(SQL 结构类型或 distinct 类型)完全限定名的 String 对象 2) 用于定义 UDT 映射方式的 SQLData 实现的 Class 对象。 map 参数对 BlobClobDATALINKJAVA_OBJECT 类型没有任何影响。
抛出:
SerialException - 如果在序列化 Array 对象时出错
SQLException - 如果发生数据库访问错误或者 arraymap 值为 null

SerialArray

public SerialArray(Array array)
            throws SerialException,
                   SQLException
根据给定 Array 对象构造新的 SerialArray 对象。

此构造方法不执行自定义映射。如果数组的基本类型为 SQL 结构类型并且需要自定义映射,则应该使用 SerialArray(Array array, Map map) 构造方法。

SerialArray 对象包含的元素与其据以构建的 Array 对象相同,基本类型为 SQL 类型 BLOBCLOBDATALINKJAVA_OBJECT 时除外。在这种情况下,新 SerialArray 对象中的每个元素都是适当的序列化形式,即 SerialBlobSerialClobSerialDatalinkSerialJavaObject 对象。

注:(1) 用来创建 SerialArray 对象的 Array 对象在被传递给构造方法之前,必须已经在客户端实现了 SQL ARRAY 值的数据。否则,新 SerialArray 对象将不包含任何数据。

注:(2) 提供给此构造方法的 Array 对象对于任何 Array.getArray() 方法都不能返回 nullSerialArray 无法序列化 null 数组值。

参数:
array - 要序列化的 Array 对象
抛出:
SerialException - 如果在序列化 Array 对象时出错
SQLException - 如果发生数据库访问错误或者 array 参数为 null
方法详细信息

free

public void free()
          throws SQLException
此方法释放 Array 对象及其占有的资源。调用 free 方法后,该对象将无效。

如果多次调用了 free,则对 free 的后续调用都被视为无操作 (no-op)。

指定者:
接口 Array 中的 free
抛出:
SQLException - 如果释放 Array 的资源时发生错误
SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法
从以下版本开始:
1.6

getArray

public Object getArray()
                throws SerialException
返回一个新数组,它是此 SerialArray 对象的副本。

指定者:
接口 Array 中的 getArray
返回:
Java 编程语言中此 SerialArray 对象 Object 形式的副本
抛出:
SerialException - 如果在获取此 SerialArray 对象的副本时出错

getArray

public Object getArray(Map<String,Class<?>> map)
                throws SerialException
返回一个新数组,它是此 SerialArray 对象的副本,当元素为 SQL UDT 时对每个自定义映射关系的元素使用给定类型映射表。

如果数组元素为 UDT 并且给定类型映射表具有针对该 UDT 的条目,则此方法执行自定义映射。自定义映射是递归的,这意味着,如果 SQL 结构类型的元素是 SQL 结构类型,而它本身又具有 SQL 结构类型的元素,则根据给定类型映射表映射每个具有自定义映射关系的结构类型。

指定者:
接口 Array 中的 getArray
参数:
map - java.util.Map 对象,其中每个条目包含:1) 给出 UDT 完全限定名的 String 对象 2) 用于定义 UDT 映射方式的 SQLData 实现的 Class 对象
返回:
Java 编程语言中此 SerialArray 对象 Object 形式的副本
抛出:
SerialException - 如果发生错误

getArray

public Object getArray(long index,
                       int count)
                throws SerialException
返回一个新数组,它是部分此 SerialArray 对象的副本,从给定索引处的元素开始,包含给定的连续元素数。

指定者:
接口 Array 中的 getArray
参数:
index - 此 SerialArray 对象中要复制的第一个元素的索引;第一个元素的索引为 0
count - 要复制的连续元素数,从给定索引处开始
返回:
Java 编程语言中此 SerialArray 对象指定元素的 Object 形式的副本
抛出:
SerialException - 如果发生错误

getArray

public Object getArray(long index,
                       int count,
                       Map<String,Class<?>> map)
                throws SerialException
返回一个新数组,它是部分此 SerialArray 对象的副本,从给定索引处的元素开始,包含给定的连续元素数。

如果数组元素为 UDT 并且给定类型映射表具有针对该 UDT 的条目,则此方法执行自定义映射。自定义映射是递归的,这意味着,如果 SQL 结构类型的元素是 SQL 结构类型,而它本身又具有 SQL 结构类型的元素,则根据给定类型映射表映射每个具有自定义映射关系的结构类型。

指定者:
接口 Array 中的 getArray
参数:
index - 此 SerialArray 对象中要复制的第一个元素的索引;数组中第一个元素的索引为 0
count - 要复制的连续元素数,从给定的索引处开始
map - java.util.Map 对象,该对象中的每个条目包含:1) 给出 UDT 完全限定名的 String 对象 2) 用于定义 UDT 映射方式的 SQLData 实现的 Class 对象
返回:
Java 编程语言中此 SerialArray 对象指定元素 Object 形式的副本
抛出:
SerialException - 如果发生错误

getBaseType

public int getBaseType()
                throws SerialException
获取此 SerialArray 对象中 SQL 类型的元素。返回的 intjava.sql.Types 类中的一个常量。

指定者:
接口 Array 中的 getBaseType
返回:
java.sql.Types 中的一个常量,指示此 SerialArray 对象中 SQL 类型的元素
抛出:
SerialException - 如果发生错误

getBaseTypeName

public String getBaseTypeName()
                       throws SerialException
获取此 SerialArray 对象元素特定于 DBMS 的类型名称。

指定者:
接口 Array 中的 getBaseTypeName
返回:
DBMS 用于此 SerialArray 对象基本类型的 SQL 类型名称
抛出:
SerialException - 如果发生错误

getResultSet

public ResultSet getResultSet(long index,
                              int count)
                       throws SerialException
获取保存子数组元素的 ResultSet 对象,该子数组从 index 索引处开始,包含 count 个连续元素。此方法使用连接的类型映射表来映射数组的元素,如果该映射表包含一个对应于基本类型的项。否则使用标准映射关系。

指定者:
接口 Array 中的 getResultSet
参数:
index - 此 SerialArray 对象中要复制的第一个元素的索引;数组中第一个元素的索引为 0
count - 要复制的连续元素数,从给定索引处开始
返回:
包含此 SerialArray 对象中指定元素的 ResultSet 对象,每个元素一个单独行
抛出:
SerialException - (该异常依次抛出 UnsupportedOperationException)如果调用此方法

getResultSet

public ResultSet getResultSet(Map<String,Class<?>> map)
                       throws SerialException
获取 ResultSet 对象,该对象包含由此 SerialArray 对象所表示的所有 SQL ARRAY 值的元素。此方法使用指定的 map 进行类型映射自定义,除非数组的基本类型与 map 中用户定义类型 (UDT) 不匹配,这种情况下使用标准映射关系。这一 getResultSet 方法使用给定类型映射表或标准映射关系;它绝不会使用与连接关联的类型映射表。

指定者:
接口 Array 中的 getResultSet
参数:
map - java.util.Map 对象,其中每个条目包含:1) 给出 UDT 完全限定名的 String 对象 2) 用于定义 UDT 映射方式的 SQLData 实现的 Class 对象
返回:
包含此 SerialArray 对象中所有元素的 ResultSet 对象,第个元素一个单独行
抛出:
SerialException - (该异常依次抛出 UnsupportedOperationException)如果调用此方法

getResultSet

public ResultSet getResultSet()
                       throws SerialException
获取 ResultSet 对象,该对象包含由此 SerialArray 对象所表示的所有 ARRAY 值中的元素。如果合适,则使用该连接的类型映射表来映射数组的元素;否则使用标准映射关系。

指定者:
接口 Array 中的 getResultSet
返回:
包含此 SerialArray 对象中所有元素的 ResultSet 对象,每个元素一个单独行
抛出:
SerialException - (该异常依次抛出 UnsupportedOperationException)如果调用此方法

getResultSet

public ResultSet getResultSet(long index,
                              int count,
                              Map<String,Class<?>> map)
                       throws SerialException
获取包含此 SerialArray 对象中元素的子数组的 ResultSet 对象,该子数组从 index 索引处开始,包含 count 个连续元素。此方法使用指定的 map 进行类型映射自定义,除非数组的基本类型与 map 中用户定义类型 (UDT) 不匹配,这种情况下使用标准映射关系。这一 getResultSet 方法使用给定类型映射表或标准映射关系;它绝不会使用与连接关联的类型映射表。

指定者:
接口 Array 中的 getResultSet
参数:
index - 此 SerialArray 对象中要复制的第一个元素的索引;数组中第一个元素的索引为 0
count - 要复制的连续元素数,从给定的索引处开始
map - java.util.Map 对象,该对象中的每个条目包含:1) 给出 UDT 完全限定名的 String 对象 2) 用于定义 UDT 映射方式的 SQLData 实现的 Class 对象
返回:
包含此 SerialArray 对象中指定元素的 ResultSet 对象,每个元素一个单独行
抛出:
SerialException - (该异常依次抛出 UnsupportedOperationException)如果调用此方法

JavaTM Platform
Standard Ed. 6

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策