Top Description Fields Constructors Methods
org.postgresql.jdbc

public Class PgArray

extends Object
implements Array
Class Inheritance
All Implemented Interfaces
java.sql.Array
Static Imports
org.postgresql.util.internal.Nullness.castNonNull

Array is used collect one column of query result data.

Read a field of type Array into either a natively-typed Java array object or a ResultSet. Accessor methods provide the ability to capture array slices.

Other than the constructor all methods are direct implementations of those specified for java.sql.Array. Please refer to the javadoc for java.sql.Array for detailed descriptions of the functionality and parameters of the methods of this class.

See Also
ResultSet#getArray

Field Summary

Modifier and TypeField and Description
protected @Nullable ArrayDecoding.PgArrayList
arrayList

Value of field as PgArrayList.

protected @Nullable BaseConnection
connection

A database connection.

protected @Nullable byte[]
protected @Nullable String
fieldString

Field value as String.

private final ResourceLock
private final int
oid

The OID of this field.

Constructor Summary

AccessConstructor and Description
private
PgArray(BaseConnection connection, int oid)

public
PgArray(BaseConnection
a database connection
connection
,
int
the oid of the array datatype
oid
,
@Nullable String
the array data in string form
fieldString
)

Create a new Array.

public
PgArray(BaseConnection
a database connection
connection
,
int
the oid of the array datatype
oid
,
@Nullable byte[]
the array data in byte form
fieldBytes
)

Create a new Array.

Method Summary

Modifier and TypeMethod and Description
private Object
buildArray(ArrayDecoding.PgArrayList
list to be converted into array
input
,
int index, int count)

Convert ArrayList to array.

private ArrayDecoding.PgArrayList
buildArrayList(String fieldString)

Build ArrayList from field's string input.

private int
calcRemainingDataLength(byte[] fieldBytes, int[] dims, int pos, int elementOid, int thisDimension)

public static void
public void
free()

Implements java.sql.Array.free.

This method frees the Array object and releases the resources that it holds.

public Object
getArray()

Implements java.sql.Array.getArray.

Retrieves the contents of the SQL ARRAY value designated by this Array object in the form of an array in the Java programming language.

public Object
getArray(long
the array index of the first element to retrieve; the first element is at index 1
index
,
int
the number of successive SQL array elements to retrieve
count
)

Implements java.sql.Array.getArray.

Retrieves a slice of the SQL ARRAY value designated by this Array object, beginning with the specified index and containing up to count successive elements of the SQL array.

public Object
getArray(Map<String, Class<?>>
a java.util.Map object that contains mappings of SQL type names to classes in the Java programming language
map
)

Implements java.sql.Array.getArray.

Retrieves the contents of the SQL ARRAY value designated by this Array object.

public Object
getArray(long
the array index of the first element to retrieve; the first element is at index 1
index
,
int
the number of successive SQL array elements to retrieve
count
,
@Nullable Map<String, Class<?>>
a java.util.Map object that contains SQL type names and the classes in the Java programming language to which they are mapped
map
)

Implements java.sql.Array.getArray.

Retrieves a slice of the SQL ARRAY value designated by this Array object, beginning with the specified index and containing up to count successive elements of the SQL array.

public Object
public @Nullable Object
getArrayImpl(long index, int count, @Nullable Map<String, Class<?>> map)

public int
getBaseType()

Implements java.sql.Array.getBaseType.

Retrieves the JDBC type of the elements in the array designated by this Array object.

public String
getBaseTypeName()

Implements java.sql.Array.getBaseTypeName.

Retrieves the SQL type name of the elements in the array designated by this Array object.

private BaseConnection
public ResultSet
getResultSet()

Implements java.sql.Array.getResultSet.

Retrieves a result set that contains the elements of the SQL ARRAY value designated by this Array object.

public ResultSet
getResultSet(long
the array index of the first element to retrieve; the first element is at index 1
index
,
int
the number of successive SQL array elements to retrieve
count
)

Implements java.sql.Array.getResultSet.

Retrieves a result set holding the elements of the subarray that starts at index index and contains up to count successive elements.

public ResultSet
getResultSet(@Nullable Map<String, Class<?>>
contains the mapping of SQL user-defined types to classes in the Java programming language
map
)

Implements java.sql.Array.getResultSet.

Retrieves a result set that contains the elements of the SQL ARRAY value designated by this Array object.

public ResultSet
getResultSet(long
the array index of the first element to retrieve; the first element is at index 1
index
,
int
the number of successive SQL array elements to retrieve
count
,
@Nullable Map<String, Class<?>>
the Map object that contains the mapping of SQL type names to classes in the Java(tm) programming language
map
)

Implements java.sql.Array.getResultSet.

Retrieves a result set holding the elements of the subarray that starts at index index and contains up to count successive elements.

public ResultSet
public ResultSet
getResultSetImpl(long index, int count, @Nullable Map<String, Class<?>> map)

public boolean
private Object
readBinaryArray(byte[] fieldBytes, int index, int count)

private ResultSet
readBinaryResultSet(byte[] fieldBytes, int index, int count)

private int
storeValues(byte[] fieldBytes, List<Tuple> rows, Field[] fields, int elementOid, final int[] dims, int pos, final int thisDimension, int index)

public @Nullable byte[]
public @Nullable String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.

private String
toString(ArrayDecoding.PgArrayList list)

Convert array list to PG String representation (e.g. {0,1,2}).

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

arrayListback to summary
protected @Nullable ArrayDecoding.PgArrayList arrayList

Value of field as PgArrayList. Will be initialized only once within buildArrayList(String).

connectionback to summary
protected @Nullable BaseConnection connection

A database connection.

fieldBytesback to summary
protected @Nullable byte[] fieldBytes
fieldStringback to summary
protected @Nullable String fieldString

Field value as String.

lockback to summary
private final ResourceLock lock
oidback to summary
private final int oid

The OID of this field.

Constructor Detail

PgArrayback to summary
private PgArray(BaseConnection connection, int oid) throws SQLException
PgArrayback to summary
public PgArray(BaseConnection connection, int oid, @Nullable String fieldString) throws SQLException

Create a new Array.

Parameters
connection:BaseConnection

a database connection

oid:int

the oid of the array datatype

fieldString:@Nullable String

the array data in string form

Exceptions
SQLException:
if something wrong happens
PgArrayback to summary
public PgArray(BaseConnection connection, int oid, @Nullable byte[] fieldBytes) throws SQLException

Create a new Array.

Parameters
connection:BaseConnection

a database connection

oid:int

the oid of the array datatype

fieldBytes:@Nullable byte[]

the array data in byte form

Exceptions
SQLException:
if something wrong happens

Method Detail

buildArrayback to summary
private Object buildArray(ArrayDecoding.PgArrayList input, int index, int count) throws SQLException

Convert ArrayList to array.

Parameters
input:ArrayDecoding.PgArrayList

list to be converted into array

buildArrayListback to summary
private ArrayDecoding.PgArrayList buildArrayList(String fieldString) throws SQLException

Build ArrayList from field's string input. As a result of this method arrayList is build. Method can be called many times in order to make sure that array list is ready to use, however arrayList will be set only once during first call.

calcRemainingDataLengthback to summary
private int calcRemainingDataLength(byte[] fieldBytes, int[] dims, int pos, int elementOid, int thisDimension)
escapeArrayElementback to summary
public static void escapeArrayElement(StringBuilder b, String s)
freeback to summary
public void free() throws SQLException

Implements java.sql.Array.free.

Doc from java.sql.Array.free.

This method frees the Array object and releases the resources that it holds. The object is invalid once the free method is called.

After free has been called, any attempt to invoke a method other than free will result in a SQLException being thrown. If free is called multiple times, the subsequent calls to free are treated as a no-op.

Annotations
@Override
Exceptions
SQLException:
if an error occurs releasing the Array's resources
getArrayback to summary
public Object getArray() throws SQLException

Implements java.sql.Array.getArray.

Doc from java.sql.Array.getArray.

Retrieves the contents of the SQL ARRAY value designated by this Array object in the form of an array in the Java programming language. This version of the method getArray uses the type map associated with the connection for customizations of the type mappings.

Note

When getArray is used to materialize a base type that maps to a primitive data type, then it is implementation-defined whether the array returned is an array of that primitive data type or an array of Object.

Returns:Object

an array in the Java programming language that contains the ordered elements of the SQL ARRAY value designated by this Array object

Annotations
@Override
@SuppressWarnings:return
Exceptions
SQLException:
if an error occurs while attempting to access the array
getArrayback to summary
public Object getArray(long index, int count) throws SQLException

Implements java.sql.Array.getArray.

Doc from java.sql.Array.getArray.

Retrieves a slice of the SQL ARRAY value designated by this Array object, beginning with the specified index and containing up to count successive elements of the SQL array. This method uses the type map associated with the connection for customizations of the type mappings.

Note

When getArray is used to materialize a base type that maps to a primitive data type, then it is implementation-defined whether the array returned is an array of that primitive data type or an array of Object.

Parameters
index:long

the array index of the first element to retrieve; the first element is at index 1

count:int

the number of successive SQL array elements to retrieve

Returns:Object

an array containing up to count consecutive elements of the SQL array, beginning with element index

Annotations
@Override
@SuppressWarnings:return
Exceptions
SQLException:
if an error occurs while attempting to access the array
getArrayback to summary
public Object getArray(Map<String, Class<?>> map) throws SQLException

Implements java.sql.Array.getArray.

Doc from java.sql.Array.getArray.

Retrieves the contents of the SQL ARRAY value designated by this Array object. This method uses the specified map for type map customizations unless the base type of the array does not match a user-defined type in map, in which case it uses the standard mapping. This version of the method getArray uses either the given type map or the standard mapping; it never uses the type map associated with the connection.

Note

When getArray is used to materialize a base type that maps to a primitive data type, then it is implementation-defined whether the array returned is an array of that primitive data type or an array of Object.

Parameters
map:Map<String, Class<?>>

a java.util.Map object that contains mappings of SQL type names to classes in the Java programming language

Returns:Object

an array in the Java programming language that contains the ordered elements of the SQL array designated by this object

Annotations
@Override
@SuppressWarnings:return
Exceptions
SQLException:
if an error occurs while attempting to access the array
getArrayback to summary
public Object getArray(long index, int count, @Nullable Map<String, Class<?>> map) throws SQLException

Implements java.sql.Array.getArray.

Doc from java.sql.Array.getArray.

Retrieves a slice of the SQL ARRAY value designated by this Array object, beginning with the specified index and containing up to count successive elements of the SQL array.

This method uses the specified map for type map customizations unless the base type of the array does not match a user-defined type in map, in which case it uses the standard mapping. This version of the method getArray uses either the given type map or the standard mapping; it never uses the type map associated with the connection.

Note

When getArray is used to materialize a base type that maps to a primitive data type, then it is implementation-defined whether the array returned is an array of that primitive data type or an array of Object.

Parameters
index:long

the array index of the first element to retrieve; the first element is at index 1

count:int

the number of successive SQL array elements to retrieve

map:@Nullable Map<String, Class<?>>

a java.util.Map object that contains SQL type names and the classes in the Java programming language to which they are mapped

Returns:Object

an array containing up to count consecutive elements of the SQL ARRAY value designated by this Array object, beginning with element index

Annotations
@Override
@SuppressWarnings:return
Exceptions
SQLException:
if an error occurs while attempting to access the array
getArrayImplback to summary
public Object getArrayImpl(Map<String, Class<?>> map) throws SQLException
Annotations
@SuppressWarnings:return
getArrayImplback to summary
public @Nullable Object getArrayImpl(long index, int count, @Nullable Map<String, Class<?>> map) throws SQLException
getBaseTypeback to summary
public int getBaseType() throws SQLException

Implements java.sql.Array.getBaseType.

Doc from java.sql.Array.getBaseType.

Retrieves the JDBC type of the elements in the array designated by this Array object.

Returns:int

a constant from the class java.sql.Types that is the type code for the elements in the array designated by this Array object

Annotations
@Override
Exceptions
SQLException:
if an error occurs while attempting to access the base type
getBaseTypeNameback to summary
public String getBaseTypeName() throws SQLException

Implements java.sql.Array.getBaseTypeName.

Doc from java.sql.Array.getBaseTypeName.

Retrieves the SQL type name of the elements in the array designated by this Array object. If the elements are a built-in type, it returns the database-specific type name of the elements. If the elements are a user-defined type (UDT), this method returns the fully-qualified SQL type name.

Returns:String

a String that is the database-specific name for a built-in base type; or the fully-qualified SQL type name for a base type that is a UDT

Annotations
@Override
Exceptions
SQLException:
if an error occurs while attempting to access the type name
getConnectionback to summary
private BaseConnection getConnection()
getResultSetback to summary
public ResultSet getResultSet() throws SQLException

Implements java.sql.Array.getResultSet.

Doc from java.sql.Array.getResultSet.

Retrieves a result set that contains the elements of the SQL ARRAY value designated by this Array object. If appropriate, the elements of the array are mapped using the connection's type map; otherwise, the standard mapping is used.

The result set contains one row for each array element, with two columns in each row. The second column stores the element value; the first column stores the index into the array for that element (with the first array element being at index 1). The rows are in ascending order corresponding to the order of the indices.

Returns:ResultSet

a ResultSet object containing one row for each of the elements in the array designated by this Array object, with the rows in ascending order based on the indices.

Annotations
@Override
Exceptions
SQLException:
if an error occurs while attempting to access the array
getResultSetback to summary
public ResultSet getResultSet(long index, int count) throws SQLException

Implements java.sql.Array.getResultSet.

Doc from java.sql.Array.getResultSet.

Retrieves a result set holding the elements of the subarray that starts at index index and contains up to count successive elements. This method uses the connection's type map to map the elements of the array if the map contains an entry for the base type. Otherwise, the standard mapping is used.

The result set has one row for each element of the SQL array designated by this object, with the first row containing the element at index index. The result set has up to count rows in ascending order based on the indices. Each row has two columns: The second column stores the element value; the first column stores the index into the array for that element.

Parameters
index:long

the array index of the first element to retrieve; the first element is at index 1

count:int

the number of successive SQL array elements to retrieve

Returns:ResultSet

a ResultSet object containing up to count consecutive elements of the SQL array designated by this Array object, starting at index index.

Annotations
@Override
Exceptions
SQLException:
if an error occurs while attempting to access the array
getResultSetback to summary
public ResultSet getResultSet(@Nullable Map<String, Class<?>> map) throws SQLException

Implements java.sql.Array.getResultSet.

Doc from java.sql.Array.getResultSet.

Retrieves a result set that contains the elements of the SQL ARRAY value designated by this Array object. This method uses the specified map for type map customizations unless the base type of the array does not match a user-defined type in map, in which case it uses the standard mapping. This version of the method getResultSet uses either the given type map or the standard mapping; it never uses the type map associated with the connection.

The result set contains one row for each array element, with two columns in each row. The second column stores the element value; the first column stores the index into the array for that element (with the first array element being at index 1). The rows are in ascending order corresponding to the order of the indices.

Parameters
map:@Nullable Map<String, Class<?>>

contains the mapping of SQL user-defined types to classes in the Java programming language

Returns:ResultSet

a ResultSet object containing one row for each of the elements in the array designated by this Array object, with the rows in ascending order based on the indices.

Annotations
@Override
Exceptions
SQLException:
if an error occurs while attempting to access the array
getResultSetback to summary
public ResultSet getResultSet(long index, int count, @Nullable Map<String, Class<?>> map) throws SQLException

Implements java.sql.Array.getResultSet.

Doc from java.sql.Array.getResultSet.

Retrieves a result set holding the elements of the subarray that starts at index index and contains up to count successive elements. This method uses the specified map for type map customizations unless the base type of the array does not match a user-defined type in map, in which case it uses the standard mapping. This version of the method getResultSet uses either the given type map or the standard mapping; it never uses the type map associated with the connection.

The result set has one row for each element of the SQL array designated by this object, with the first row containing the element at index index. The result set has up to count rows in ascending order based on the indices. Each row has two columns: The second column stores the element value; the first column stores the index into the array for that element.

Parameters
index:long

the array index of the first element to retrieve; the first element is at index 1

count:int

the number of successive SQL array elements to retrieve

map:@Nullable Map<String, Class<?>>

the Map object that contains the mapping of SQL type names to classes in the Java(tm) programming language

Returns:ResultSet

a ResultSet object containing up to count consecutive elements of the SQL array designated by this Array object, starting at index index.

Annotations
@Override
Exceptions
SQLException:
if an error occurs while attempting to access the array
getResultSetImplback to summary
public ResultSet getResultSetImpl(@Nullable Map<String, Class<?>> map) throws SQLException
getResultSetImplback to summary
public ResultSet getResultSetImpl(long index, int count, @Nullable Map<String, Class<?>> map) throws SQLException
isBinaryback to summary
public boolean isBinary()
readBinaryArrayback to summary
private Object readBinaryArray(byte[] fieldBytes, int index, int count) throws SQLException
readBinaryResultSetback to summary
private ResultSet readBinaryResultSet(byte[] fieldBytes, int index, int count) throws SQLException
storeValuesback to summary
private int storeValues(byte[] fieldBytes, List<Tuple> rows, Field[] fields, int elementOid, final int[] dims, int pos, final int thisDimension, int index) throws SQLException
toBytesback to summary
public @Nullable byte[] toBytes()
toStringback to summary
public @Nullable String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object. Satisfying this method's contract implies a non-null result must be returned.

Returns:@Nullable String

a string representation of the object

Annotations
@Override
@SuppressWarnings:nullness
toStringback to summary
private String toString(ArrayDecoding.PgArrayList list) throws SQLException

Convert array list to PG String representation (e.g. {0,1,2}).