Array

本章节描述在JDBC驱动使用java.sql.Array类型时，Oracle与GaussDB的差异。

表1 构造方法参考
构造方式	Oracle数据库	GaussDB数据库	接口差异
1. ArrayDescriptor的静态构造方法构造ArrayDescriptor对象； 2. 通过ArrayDescriptor构造Array对象。	String typeName = "XXX"; Connection conn = getConnection(); Object[] elements = null; ArrayDescriptor desc = ArrayDescriptor.createDescriptor(typeName, conn); Array array = new ARRAY(desc, conn, elements);	String typeName = "xxx"; Connection conn = getConnection(); Object[] elements = null; ArrayDescriptor desc = ArrayDescriptor.getDescriptor(typeName, conn); Array array = new GaussArray(desc, elements);	构造ArrayDescriptor的静态方法名不一致，Oracle的方法名为createDescriptor，GaussDB的方法名为getDescriptor。 Array的构造方法名定义不一致，Oracle为ARRAY(ArrayDescriptor, Connection, Object)，GaussDB为GaussArray(ArrayDescriptor, Object)。变量说明： typeName为类型名称，且大小写敏感，通常Oracle的类型名大写，GaussDB的类型名小写。 conn为对应数据库的连接对象。 elements为对应类型的元素数据。

对于上述表格中未列举出的构造方式，GaussDB暂不支持。
若元素类型为字符类型，构造传入的字符串长度大于元素类型定义的长度，Oracle会在绑定入参时报错；
若数组类型为varray类型时，若元素个数大于varray类型的长度上限，Oracle会在绑定入参时报错；

GaussDB在构造或者绑定入参时不会对类型修饰符进行校验，在数据库接收Array对象并执行SQL时，由数据库决定是否报错。

表2 接口参考
方法名	返回值类型	throws	GaussDB数据库
getBaseTypeName()	String	SQLException	支持
getBaseType()	int	SQLException	支持
getArray()	Object	SQLException	支持
getArray(java.util.Map<String,Class<?>> map)	Object	SQLException	不支持
getArray(long index, int count)	Object	SQLException	支持
getArray(long index, int count, java.util.Map<String,Class<?>> map)	Object	SQLException	不支持
getResultSet()	ResultSet	SQLException	不支持
getResultSet(java.util.Map<String,Class<?>> map)	ResultSet	SQLException	不支持
getResultSet(long index, int count)	ResultSet	SQLException	不支持
getResultSet (long index, int count, java.util.Map<String,Class<?>> map)	ResultSet	SQLException	不支持
free()	void	SQLException	不支持

表3 getArray()接口详细差异
元素数据库类型	getArray接口实际返回值类型（Oracle）	getArray接口实际返回值类型（GaussDB）
CHAR	java.lang.String[]	java.lang.String[]
VARCHAR/VARCHAR2	java.lang.String[]	java.lang.String[]
NCHAR	java.lang.String[]	java.lang.String[]
NVARCHAR2	java.lang.String[]	java.lang.String[]
NUMBER	java.math.BigDecimal[]	java.math.BigDecimal[]
NUMERIC	java.math.BigDecimal[]	java.math.BigDecimal[]
DECIMAL	java.math.BigDecimal[]	java.math.BigDecimal[]
INTEGER	java.math.BigDecimal[]	java.lang.Integer[]
SMALLINT	java.math.BigDecimal[]	java.lang.Short[]
DOUBLE PRECISION	java.math.BigDecimal[]	java.lang.Double[]
FLOAT	java.math.BigDecimal[]	java.lang.Double[]
REAL	java.math.BigDecimal[]	java.lang.Float[]
BINARY_DOUBLE	java.lang.Double[]	java.lang.Double[]
BINARY_INTEGER	java.math.BigDecimal[]	java.lang.Integer[]
BOOLEAN	java.math.BigDecimal[]	java.lang.Boolean[]
TIMESTAMP	java.sql.Timestamp[]	java.sql.Timestamp[]
TIMESTAMP WITH TIME ZONE	java.time.OffsetDateTime[]	java.sql.Timestamp[]
BLOB	oracle.sql.BLOB[]	java.sql.Blob[]
CLOB	oracle.sql.CLOB[]	java.sql.Clob[]
集合类型/数组类型	java.lang.Object[]	java.sql.Array[]
RECORD类型	java.lang.Object[]	java.sql.Struct[]

对于上述表格中未列举出的类型，GaussDB暂不支持。
getArray(long index, int count)接口返回值差异也参考上述表格。
getArray接口(long index, int count)，参数index的差异如下：
- Oracle支持范围为[1, Long.MAX_VALUE]；Gauss支持范围为[1, Integer.MAX_VALUE]。
- Oracle在index > Integer.MAX_VALUE时index会被截断；Gauss在index > Integer.MAX_VALUE时报错。

表4 getBaseType()接口详细差异
元素数据库类型	getBaseType接口返回值（Oracle）	getBaseType接口返回值（GaussDB）
CHAR	java.sql.Types.CHAR	java.sql.Types.CHAR
VARCHAR/VARCHAR2	java.sql.Types.VARCHAR	java.sql.Types.VARCHAR
NCHAR	java.sql.Types.NCHAR	java.sql.Types.CHAR
NVARCHAR2	java.sql.Types.NVARCHAR	java.sql.Types.VARCHAR
NUMBER	java.sql.Types.NUMERIC	java.sql.Types.NUMERIC
NUMERIC	java.sql.Types.DECIMAL	java.sql.Types.NUMERIC
DECIMAL	java.sql.Types.DECIMAL	java.sql.Types.NUMERIC
INTEGER	java.sql.Types.NUMERIC	java.sql.Types.INTEGER
SMALLINT	java.sql.Types.NUMERIC	java.sql.Types.SMALLINT
DOUBLE PRECISION	java.sql.Types.FLOAT	java.sql.Types.DOUBLE
FLOAT	java.sql.Types.FLOAT	java.sql.Types.DOUBLE
REAL	java.sql.Types.FLOAT	java.sql.Types.REAL
BINARY_DOUBLE	oracle.jdbc.OracleTypes.BINARY_DOUBLE	java.sql.Types.DOUBLE
BINARY_INTEGER	java.sql.Types.NUMERIC	java.sql.Types.INTEGER
BOOLEAN	java.sql.Types.NUMERIC	java.sql.Types.BIT
TIMESTAMP	java.sql.Types.TIMESTAMP	java.sql.Types.TIMESTAMP
TIMESTAMP WITH TIME ZONE	oracle.jdbc.OracleTypes.TIMESTAMPTZ	java.sql.Types.TIMESTAMP
BLOB	java.sql.Types.BLOB	java.sql.Types.BLOB
CLOB	java.sql.Types.CLOB	java.sql.Types.CLOB
集合类型/数组类型	java.sql.Types.ARRAY	java.sql.Types.ARRAY
RECORD类型	java.sql.Types.STRUCT	java.sql.Types.STRUCT

对于上述表格中未列举出的类型，GaussDB暂不支持。

表5 getBaseTypeName()接口详细差异
元素数据库类型	getBaseTypeName接口返回值（Oracle）	getBaseTypeName接口返回值（GaussDB）
CHAR	"CHAR"	"bpchar"
VARCHAR/VARCHAR2	"VARCHAR"	"varchar"
NCHAR	"NCHAR"	"bpchar"
NVARCHAR2	"NVARCHAR"	"nvarchar2"
NUMBER	"NUMBER"	"numeric"
NUMERIC	"DECIMAL"	"numeric"
DECIMAL	"DECIMAL"	"numeric"
INTEGER	"NUMBER"	"int4"
SMALLINT	"NUMBER"	"int2"
DOUBLE PRECISION	"FLOAT"	"float8"
FLOAT	"FLOAT"	"float8"
REAL	"FLOAT"	"float4"
BINARY_DOUBLE	"BINARY_DOUBLE"	"float8"
BINARY_INTEGER	"NUMBER"	"int4"
BOOLEAN	"NUMBER"	"bool"
TIMESTAMP	"TIMESTAMP"	"timestamp"
TIMESTAMP WITH TIME ZONE	"TIMESTAMP WITH TIME ZONE"	"timestamptz"
BLOB	"BLOB"	"blob"
CLOB	"CLOB"	"clob"
集合类型/数组类型	见说明部分	见说明部分
RECORD类型	见说明部分	见说明部分

对于上述表格中未列举出的类型，GaussDB暂不支持。
元素为集合类型、数组类型或record类型，且元素类型是package里定义的类型时，getBaseTypeName返回规则如下：
- OJDBC11返回schemaName.packageName.typeName。
- OJDBC8一般返回schemaName.packageName.typeName，在类型名满足以下条件返回"schemaName"."packageName.typeName"：
  schemaName/packageName/typeName中有任意名称不符合首字符为字母，其他字符为字母、数字或下划线。
- GaussDB一般返回schemaName.packageName.typeName，在类型名满足以下条件返回"schemaName"."packageName"."typeName"：
  schemaName/packageName/typeName中有任意名称不符合首字符为字母或下划线，其他字符为字母、数字或下划线。
元素为集合类型、数组类型或record类型，且元素类型是schema下定义的类型时（非package里定义的类型），getBaseTypeName返回规则如下：
- OJDBC11返回schemaName.typeName。
- OJDBC8一般返回schemaName.typeName，在类型名满足以下条件返回"schemaName"."typeName"：
  schemaName/typeName中有任意名称不符合首字符为字母，其他字符为字母、数字或下划线。
- GaussDB一般返回schemaName.typeName，在类型名满足以下条件返回"schemaName"."typeName"：
  schemaName/typeName中有任意名称不符合首字符为字母或下划线，其他字符为字母、数字或下划线。
若元素类型在创建时不做特殊处理，Oracle的getBaseTypeName接口通常返回的是大写的类型名称，GaussDB的getBaseTypeName接口通常返回的是小写的类型名称。

表6 Array构造接口详细差异
元素数据库类型	元素入参支持的Java类型列表（Oracle OJDBC8）	元素入参支持的Java类型列表（GaussDB）	差异说明
CHAR	任意Java类型	Byte、Short、Integer、Long、BigInteger、BigDecimal、Float、Double、Character、Boolean、java.sql.Date、java.sql.Time、java.sql.Timestamp、PGClob	元素入参支持的类型差异见表格。
VARCHAR/VARCHAR2	任意Java类型	Byte、Short、Integer、Long、BigInteger、BigDecimal、Float、Double、Character、Boolean、java.sql.Date、java.sql.Time、java.sql.Timestamp、PGClob	元素入参支持的类型差异见表格。
NCHAR	任意Java类型	Byte、Short、Integer、Long、BigInteger、BigDecimal、Float、Double、Character、Boolean、java.sql.Date、java.sql.Time、java.sql.Timestamp、PGClob	元素入参支持的类型差异见表格。
NVARCHAR2	任意Java类型	Byte、Short、Integer、Long、BigInteger、BigDecimal、Float、Double、Character、Boolean、java.sql.Date、java.sql.Time、java.sql.Timestamp、PGClob	元素入参支持的类型差异见表格。
NUMBER	Byte、Short、Integer、Long、Float、Double、Boolean、BigDecimal、BigInteger、String、oracle.sql.NUMBER	Byte、Short、Integer、Long、Float、Double、Boolean、BigDecimal、BigInteger、String	元素入参支持的类型差异见表格。当入参为Float、Double、BigDecimal、String且小数点部分为0时，Oracle会舍去小数部分；GaussDB会保留小数部分。
NUMERIC	Byte、Short、Integer、Long、Float、Double、Boolean、BigDecimal、BigInteger、String、oracle.sql.NUMBER	Byte、Short、Integer、Long、Float、Double、Boolean、BigDecimal、BigInteger、String	元素入参支持的类型差异见表格。当入参为Float、Double、BigDecimal、String且小数点部分为0时，Oracle会舍去小数部分；GaussDB会保留小数部分。
DECIMAL	Byte、Short、Integer、Long、Float、Double、Boolean、BigDecimal、BigInteger、String、oracle.sql.NUMBER	Byte、Short、Integer、Long、Float、Double、Boolean、BigDecimal、BigInteger、String	元素入参支持的类型差异见表格。当入参为Float、Double、BigDecimal、String且小数点部分为0时，Oracle会舍去小数部分；GaussDB会保留小数部分。
INTEGER	Byte、Short、Integer、Long、Float、Double、Boolean、BigDecimal、BigInteger、String、oracle.sql.NUMBER	Byte、Short、Integer、Long、Float、Double、Boolean、BigDecimal、BigInteger、String	元素入参支持的类型差异见表格。目标类型不一致，参考getArray接口详细差异。当入参超过Integer范围时GaussDB会报错。
SMALLINT	Byte、Short、Integer、Long、Float、Double、Boolean、BigDecimal、BigInteger、String、oracle.sql.NUMBER	Byte、Short、Integer、Long、Float、Double、Boolean、BigDecimal、BigInteger、String	元素入参支持的类型差异见表格。目标类型不一致，参考getArray接口详细差异。当入参超过Short范围时GaussDB会报错。
DOUBLE PRECISION	Byte、Short、Integer、Long、Float、Double、Boolean、BigDecimal、BigInteger、String、oracle.sql.NUMBER	Byte、Short、Integer、Long、Float、Double、Boolean、BigDecimal、BigInteger、String	元素入参支持的类型差异见表格。目标类型不一致，参考getArray接口详细差异。更高精度的类型转Double可能会出现精度丢失的情况。
FLOAT	Byte、Short、Integer、Long、Float、Double、Boolean、BigDecimal、BigInteger、String、oracle.sql.NUMBER	Byte、Short、Integer、Long、Float、Double、Boolean、BigDecimal、BigInteger、String	元素入参支持的类型差异见表格。目标类型不一致，参考getArray接口详细差异。更高精度的类型转Double可能会出现精度丢失的情况。
REAL	Byte、Short、Integer、Long、Float、Double、Boolean、BigDecimal、BigInteger、String、oracle.sql.NUMBER	Byte、Short、Integer、Long、Float、Double、Boolean、BigDecimal、BigInteger、String	元素入参支持的类型差异见表格。目标类型不一致，参考getArray接口详细差异。更高精度的类型转Float可能会出现精度丢失的情况。
BINARY_DOUBLE	Double、oracle.sql.BINARY_DOUBLE	Byte、Short、Integer、Long、Float、Double、Boolean、BigDecimal、BigInteger、String	元素入参支持的类型差异见表格。目标类型不一致，参考getArray接口详细差异。更高精度的类型转Double可能会出现精度丢失的情况。
BINARY_INTEGER	Byte、Short、Integer、Long、Float、Double、Boolean、BigDecimal、BigInteger、AtomicInteger、AutomicLong、DoubleAccumulator、DoubleAddr、LongAccumulator、LondAdder、Striped64、String、oracle.sql.NUMBER	Byte、Short、Integer、Long、Float、Double、Boolean、BigDecimal、BigInteger、String	元素入参支持的类型差异见表格。 OJDBC11元素入参支持的类型：Byte、Short、Integer、Long、Float、Double、Boolean、BigDecimal、BigInteger、String、oracle.sql.NUMBER 目标类型不一致，参考getArray接口详细差异。当传入数值超过Integer范围时：GaussDB会报错 Oracle OJDBC8会进行截断处理。
BOOLEAN	Byte、Short、Integer、Long、Float、Double、Boolean、BigDecimal、BigInteger、AtomicInteger、AutomicLong、DoubleAccumulator、DoubleAddr、LongAccumulator、LondAdder、Striped64、String、oracle.sql.NUMBER	Byte、Short、Integer、Long、Float、Double、Boolean、BigDecimal、BigInteger、String	元素入参支持的类型差异见表格。 OJDBC8元素入参支持的类型：Byte、Short、Integer、Long、Float、Double、Boolean、BigDecimal、BigInteger、String、oracle.sql.NUMBER 目标类型不一致，参考getArray接口详细差异。 GaussDB目标类型为Boolean类型，仅支持1、0、"true"、"false"等输入。
TIMESTAMP	byte[]、java.sql.Date、Calendar、java.util.Date、LocalDate、LocalDateTime、LocalTime、OffsetDateTime、OffsetTime、String、java.sql.Time、java.sql.Timestamp、oracle.sql.DATE、oracle.sql.TIMESTAMP、oracle.sql.TIMESTAMPTZ、oracle.sql.TIMESTAMPLTZ、ZonedDateTime	java.util.Date、java.sql.Date、java.sql.Time、java.sql.Timestamp、LocalDateTime、String	元素入参支持的类型差异见表格。
TIMESTAMP WITH TIME ZONE	java.sql.Date、Calendar、java.util.Date、LocalDate、LocalDateTime、LocalTime、OffsetDateTime、OffsetTime、String、java.sql.Time、java.sql.Timestamp、oracle.sql.DATE、oracle.sql.TIMESTAMP、oracle.sql.TIMESTAMPTZ、oracle.sql.TIMESTAMPLTZ、ZonedDateTime	java.util.Date、java.sql.Date、java.sql.Time、java.sql.Timestamp、LocalDateTime、String	元素入参支持的类型差异见表格。目标类型不一致，参考getArray接口详细差异。
BLOB	oracle.sql.BLOB、oracle.jdbc.driver.OracleBlob	PGBlob	元素入参支持的类型差异见表格。
CLOB	oracle.sql.CLOB、oracle.jdbc.driver.OracleClob、InputStream、Reader	PGClob	元素入参支持的类型差异见表格。
集合类型/数组类型	ARRAY、Object	GaussArray、Object	元素入参支持的类型差异见表格。 Oracle：当元素入参为ARRAY时，ARRAY的类型与元素类型不一致时不会报错。 GaussDB：当元素入参为GaussArray时，GaussArray的类型与元素类型不一致时会报错。当元素入参为Object时，参考Array构造接口差异。
RECORD类型	STRUCT、Object[]	GaussStruct、Object[]	元素入参支持的类型差异见表格。 Oracle：当元素入参为STRUCT时，STRUCT的类型与元素类型不一致时不会报错。 GaussDB：当元素入参为GaussStruct时，GaussStruct的类型与元素类型不一致时会报错。当元素入参为Object[]时，参考Struct构造接口差异。