Package com.google.cloud.spanner

Interface StructReader

All Known Subinterfaces:
AsyncResultSet, PartitionedQueryResultSet, ProtobufResultSet, ResultSet
All Known Implementing Classes:
AbstractStructReader, ForwardingAsyncResultSet, ForwardingResultSet, ForwardingStructReader, Struct
public interface StructReader
A base interface for reading the fields of a STRUCT. The Cloud Spanner yields StructReader instances as one of the subclasses ResultSet or Struct, most commonly as the result of a read or query operation. At any point in time, a StructReader provides access to a single tuple of data comprising multiple typed columns. Each column may have a NULL or non-NULL value; in both cases, columns always have a type.

Column values are accessed using the getTypeName() methods; a set of methods exists for each Java type that a column may be read as, and depending on the type of the column, only a subset of those methods will be appropriate. For example, getString(int) and getString(String) exist for reading columns of type Type.string(); attempting to call those methods for columns of other types will result in an IllegalStateException. The getTypeName() methods should only be called for non-NULL values, otherwise a NullPointerException is raised; isNull(int)/isNull(String) can be used to test for NULL-ness if necessary.

All methods for accessing a column have overloads that accept an int column index and a String column name. Column indices are zero-based. The column name overloads will fail with IllegalArgumentException if the column name does not appear exactly once in this instance's getType(). The int overloads are typically more efficient than their String counterparts.

StructReader itself does not define whether the implementing type is mutable or immutable. For example, ResultSet is a mutable implementation of StructReader, where the StructReader methods provide access to the row that the result set is currently positioned over and ResultSet.next() changes that view to the next row, whereas Struct is an immutable implementation of StructReader.

  • Method Details

    • getType

      Type getType()
      Returns:
      the type of the underlying data. This will always be a STRUCT type, with fields corresponding to the data's columns. For the result of a read or query, this will always match the columns passed to the read() call or named in the query text, in order.

    • getColumnCount

      int getColumnCount()
      Returns:
      the number of columns in the underlying data. This includes any columns with NULL values.

    • getColumnIndex

      int getColumnIndex(String columnName)
      Parameters:
      columnName - name of the column
      Returns:
      the index of the column named columnName.
      Throws:
      IllegalArgumentException - if there is not exactly one element of type().structFields() with Type.StructField.getName() equal to columnName

    • getColumnType

      Type getColumnType(int columnIndex)
      Parameters:
      columnIndex - index of the column
      Returns:
      the type of a column.

    • getColumnType

      Type getColumnType(String columnName)
      Parameters:
      columnName - name of the column
      Returns:
      the type of a column.

    • isNull

      boolean isNull(int columnIndex)
      Parameters:
      columnIndex - index of the column
      Returns:
      true if a column contains a NULL value.

    • isNull

      boolean isNull(String columnName)
      Parameters:
      columnName - name of the column
      Returns:
      true if a column contains a NULL value.

    • getBoolean

      boolean getBoolean(int columnIndex)
      Parameters:
      columnIndex - index of the column
      Returns:
      the value of a non-NULL column with type Type.bool().

    • getBoolean

      boolean getBoolean(String columnName)
      Parameters:
      columnName - name of the column
      Returns:
      the value of a non-NULL column with type Type.bool().

    • getLong

      long getLong(int columnIndex)
      Parameters:
      columnIndex - index of the column
      Returns:
      the value of a non-NULL column with type Type.int64().

    • getLong

      long getLong(String columnName)
      Parameters:
      columnName - name of the column
      Returns:
      the value of a non-NULL column with type Type.int64().

    • getFloat

      default float getFloat(int columnIndex)
      Parameters:
      columnIndex - index of the column
      Returns:
      the value of a non-NULL column with type Type.float32().

    • getFloat

      default float getFloat(String columnName)
      Parameters:
      columnName - name of the column
      Returns:
      the value of a non-NULL column with type Type.float32().

    • getDouble

      double getDouble(int columnIndex)
      Parameters:
      columnIndex - index of the column
      Returns:
      the value of a non-NULL column with type Type.float64().

    • getDouble

      double getDouble(String columnName)
      Parameters:
      columnName - name of the column
      Returns:
      the value of a non-NULL column with type Type.float64().

    • getBigDecimal

      BigDecimal getBigDecimal(int columnIndex)
      Parameters:
      columnIndex - index of the column
      Returns:
      the value of a non-NULL column with type Type.numeric().

    • getBigDecimal

      BigDecimal getBigDecimal(String columnName)
      Parameters:
      columnName - name of the column
      Returns:
      the value of a non-NULL column with type Type.numeric().

    • getString

      String getString(int columnIndex)
      Parameters:
      columnIndex - index of the column
      Returns:
      the value of a non-NULL column with type Type.string().

    • getString

      String getString(String columnName)
      Parameters:
      columnName - name of the column
      Returns:
      the value of a non-NULL column with type Type.string().

    • getJson

      default String getJson(int columnIndex)
      Parameters:
      columnIndex - index of the column
      Returns:
      the value of a non-NULL column with type Type.json().

    • getJson

      default String getJson(String columnName)
      Parameters:
      columnName - name of the column
      Returns:
      the value of a non-NULL column with type Type.json().

    • getPgJsonb

      default String getPgJsonb(int columnIndex)
      Parameters:
      columnIndex - index of the column
      Returns:
      the value of a non-NULL column with type Type.pgJsonb().

    • getPgJsonb

      default String getPgJsonb(String columnName)
      Parameters:
      columnName - name of the column
      Returns:
      the value of a non-NULL column with type Type.pgJsonb().

    • getProtoMessage

      default <T extends com.google.protobuf.AbstractMessage> T getProtoMessage(int columnIndex, T message)
      To get the proto message of generic type T from Struct.
      Parameters:
      columnIndex - Index of the column.
      message - Proto message object. Message can't be null as it's internally used to find the type of proto. Use @code{MyProtoClass.getDefaultInstance()}. @see getDefaultInstance()
      Returns:
      The value of a non-NULL column with type Type.proto(String) ()}.

    • getProtoMessage

      default <T extends com.google.protobuf.AbstractMessage> T getProtoMessage(String columnName, T message)
      To get the proto message of type T from Struct.
      Parameters:
      columnName - Name of the column.
      message - Proto message object. Message can't be null as it's internally used to find the type of proto. Use @code{MyProtoClass.getDefaultInstance()}. @see getDefaultInstance()
      Returns:
      The value of a non-NULL column with type Type.proto(String) ()}.

    • getProtoEnum

      default <T extends com.google.protobuf.ProtocolMessageEnum> T getProtoEnum(int columnIndex, Function<Integer,com.google.protobuf.ProtocolMessageEnum> method)
      To get the proto enum of type T from Struct.
      Parameters:
      columnIndex - Index of the column.
      method - A function that takes enum integer constant as argument and returns the enum. Use method @code{forNumber} from generated enum class (eg: MyProtoEnum::forNumber). @see forNumber
      Returns:
      The value of a non-NULL column with type Type.protoEnum(String) ()}.

    • getProtoEnum

      default <T extends com.google.protobuf.ProtocolMessageEnum> T getProtoEnum(String columnName, Function<Integer,com.google.protobuf.ProtocolMessageEnum> method)
      To get the proto enum of type T from Struct.
      Parameters:
      columnName - Name of the column.
      method - A function that takes enum integer constant as argument and returns the enum. Use method @code{forNumber} from generated enum class (eg: MyProtoEnum::forNumber). @see forNumber
      Returns:
      The value of a non-NULL column with type Type.protoEnum(String) ()}.

    • getBytes

      com.google.cloud.ByteArray getBytes(int columnIndex)
      Parameters:
      columnIndex - index of the column
      Returns:
      the value of a non-NULL column with type Type.bytes().

    • getBytes

      com.google.cloud.ByteArray getBytes(String columnName)
      Parameters:
      columnName - name of the column
      Returns:
      the value of a non-NULL column with type Type.bytes().

    • getTimestamp

      com.google.cloud.Timestamp getTimestamp(int columnIndex)
      Parameters:
      columnIndex - index of the column
      Returns:
      the value of a non-NULL column with type Type.timestamp().

    • getTimestamp

      com.google.cloud.Timestamp getTimestamp(String columnName)
      Parameters:
      columnName - name of the column
      Returns:
      the value of a non-NULL column with type Type.timestamp().

    • getDate

      com.google.cloud.Date getDate(int columnIndex)
      Parameters:
      columnIndex - index of the column
      Returns:
      the value of a non-NULL column with type Type.date().

    • getDate

      com.google.cloud.Date getDate(String columnName)
      Parameters:
      columnName - name of the column
      Returns:
      the value of a non-NULL column with type Type.date().

    • getValue

      default Value getValue(int columnIndex)
      Parameters:
      columnIndex - index of the column
      Returns:
      the value of a nullable column as a Value.

    • getValue

      default Value getValue(String columnName)
      Parameters:
      columnName - name of the column
      Returns:
      the value of a nullable column as a Value.

    • getBooleanArray

      boolean[] getBooleanArray(int columnIndex)
      Parameters:
      columnIndex - index of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.bool()).
      Throws:
      NullPointerException - if any element of the array value is NULL. If the array may contain NULL values, use getBooleanList(int) instead.

    • getBooleanArray

      boolean[] getBooleanArray(String columnName)
      Parameters:
      columnName - name of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.bool()).
      Throws:
      NullPointerException - if any element of the array value is NULL. If the array may contain NULL values, use getBooleanList(String) instead.

    • getBooleanList

      List<Boolean> getBooleanList(int columnIndex)
      Parameters:
      columnIndex - index of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.bool()). The list returned by this method is lazily constructed. Create a copy of it if you intend to access each element in the list multiple times.

    • getBooleanList

      List<Boolean> getBooleanList(String columnName)
      Parameters:
      columnName - name of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.bool()). The list returned by this method is lazily constructed. Create a copy of it if you intend to access each element in the list multiple times.

    • getLongArray

      long[] getLongArray(int columnIndex)
      Parameters:
      columnIndex - index of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.int64()).
      Throws:
      NullPointerException - if any element of the array value is NULL. If the array may contain NULL values, use getLongList(int) instead.

    • getLongArray

      long[] getLongArray(String columnName)
      Parameters:
      columnName - name of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.int64()).
      Throws:
      NullPointerException - if any element of the array value is NULL. If the array may contain NULL values, use getLongList(String) instead.

    • getLongList

      List<Long> getLongList(int columnIndex)
      Parameters:
      columnIndex - index of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.int64()). The list returned by this method is lazily constructed. Create a copy of it if you intend to access each element in the list multiple times.

    • getLongList

      List<Long> getLongList(String columnName)
      Parameters:
      columnName -
      Returns:
      the value of a non-NULL column with type Type.array(Type.int64()). The list returned by this method is lazily constructed. Create a copy of it if you intend to access each element in the list multiple times.

    • getFloatArray

      default float[] getFloatArray(int columnIndex)
      Parameters:
      columnIndex - index of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.float32()).
      Throws:
      NullPointerException - if any element of the array value is NULL. If the array may contain NULL values, use getFloatList(int) instead.

    • getFloatArray

      default float[] getFloatArray(String columnName)
      Parameters:
      columnName - name of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.float32()).
      Throws:
      NullPointerException - if any element of the array value is NULL. If the array may contain NULL values, use getFloatList(String) instead.

    • getFloatList

      default List<Float> getFloatList(int columnIndex)
      Parameters:
      columnIndex - index of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.float32()) The list returned by this method is lazily constructed. Create a copy of it if you intend to access each element in the list multiple times.

    • getFloatList

      List<Float> getFloatList(String columnName)
      Parameters:
      columnName - name of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.float32()) The list returned by this method is lazily constructed. Create a copy of it if you intend to access each element in the list multiple times.

    • getDoubleArray

      double[] getDoubleArray(int columnIndex)
      Parameters:
      columnIndex - index of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.float64()).
      Throws:
      NullPointerException - if any element of the array value is NULL. If the array may contain NULL values, use getDoubleList(int) instead.

    • getDoubleArray

      double[] getDoubleArray(String columnName)
      Parameters:
      columnName - name of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.float64()).
      Throws:
      NullPointerException - if any element of the array value is NULL. If the array may contain NULL values, use getDoubleList(String) instead.

    • getDoubleList

      List<Double> getDoubleList(int columnIndex)
      Parameters:
      columnIndex - index of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.float64()) The list returned by this method is lazily constructed. Create a copy of it if you intend to access each element in the list multiple times.

    • getDoubleList

      List<Double> getDoubleList(String columnName)
      Parameters:
      columnName - name of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.float64()) The list returned by this method is lazily constructed. Create a copy of it if you intend to access each element in the list multiple times.

    • getBigDecimalList

      List<BigDecimal> getBigDecimalList(int columnIndex)
      Parameters:
      columnIndex - index of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.numeric()) The list returned by this method is lazily constructed. Create a copy of it if you intend to access each element in the list multiple times.

    • getBigDecimalList

      List<BigDecimal> getBigDecimalList(String columnName)
      Parameters:
      columnName - name of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.numeric()) The list returned by this method is lazily constructed. Create a copy of it if you intend to access each element in the list multiple times.

    • getStringList

      List<String> getStringList(int columnIndex)
      Parameters:
      columnIndex - index of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.string()). The list returned by this method is lazily constructed. Create a copy of it if you intend to access each element in the list multiple times.

    • getStringList

      List<String> getStringList(String columnName)
      Parameters:
      columnName - name of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.string()). The list returned by this method is lazily constructed. Create a copy of it if you intend to access each element in the list multiple times.

    • getJsonList

      default List<String> getJsonList(int columnIndex)
      Parameters:
      columnIndex - index of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.json()). The list returned by this method is lazily constructed. Create a copy of it if you intend to access each element in the list multiple times.

    • getJsonList

      default List<String> getJsonList(String columnName)
      Parameters:
      columnName - name of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.json()). The list returned by this method is lazily constructed. Create a copy of it if you intend to access each element in the list multiple times.

    • getPgJsonbList

      default List<String> getPgJsonbList(int columnIndex)
      Parameters:
      columnIndex - index of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.pgJsonb()) The list returned by this method is lazily constructed. Create a copy of it if you intend to access each element in the list multiple times.

    • getPgJsonbList

      default List<String> getPgJsonbList(String columnName)
      Parameters:
      columnName - name of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.pgJsonb()) The list returned by this method is lazily constructed. Create a copy of it if you intend to access each element in the list multiple times.

    • getProtoMessageList

      default <T extends com.google.protobuf.AbstractMessage> List<T> getProtoMessageList(int columnIndex, T message)
      To get the proto message of generic type T from Struct.
      Parameters:
      columnIndex - Index of the column.
      message - Proto message object. Message can't be null as it's internally used to find the type of proto. Use @code{MyProtoClass.getDefaultInstance()}. @see getDefaultInstance()
      Returns:
      The value of a non-NULL column with type Type.array(Type.proto(String)).

    • getProtoMessageList

      default <T extends com.google.protobuf.AbstractMessage> List<T> getProtoMessageList(String columnName, T message)
      To get the proto message of type T from Struct.
      Parameters:
      columnName - Name of the column.
      message - Proto message object. Message can't be null as it's internally used to find the type of proto. Use @code{MyProtoClass.getDefaultInstance()}. @see getDefaultInstance()
      Returns:
      The value of a non-NULL column with type Type.array(Type.proto(String)).

    • getProtoEnumList

      default <T extends com.google.protobuf.ProtocolMessageEnum> List<T> getProtoEnumList(int columnIndex, Function<Integer,com.google.protobuf.ProtocolMessageEnum> method)
      To get the proto enum of type T from Struct.
      Parameters:
      columnIndex - Index of the column.
      method - A function that takes enum integer constant as argument and returns the enum. Use method @code{forNumber} from generated enum class (eg: MyProtoEnum::forNumber). @see forNumber
      Returns:
      The value of a non-NULL column with type Type.array(Type.protoEnum(String)).

    • getProtoEnumList

      default <T extends com.google.protobuf.ProtocolMessageEnum> List<T> getProtoEnumList(String columnName, Function<Integer,com.google.protobuf.ProtocolMessageEnum> method)
      To get the proto enum list of type T from Struct.
      Parameters:
      columnName - Name of the column.
      method - A function that takes enum integer constant as argument and returns the enum. Use method @code{forNumber} from generated enum class (eg: MyProtoEnum::forNumber). @see forNumber
      Returns:
      The value of a non-NULL column with type Type.array(Type.protoEnum(String)).

    • getBytesList

      List<com.google.cloud.ByteArray> getBytesList(int columnIndex)
      Parameters:
      columnIndex - index of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.bytes()). The list returned by this method is lazily constructed. Create a copy of it if you intend to access each element in the list multiple times.

    • getBytesList

      List<com.google.cloud.ByteArray> getBytesList(String columnName)
      Parameters:
      columnName - name of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.bytes()). The list returned by this method is lazily constructed. Create a copy of it if you intend to access each element in the list multiple times.

    • getTimestampList

      List<com.google.cloud.Timestamp> getTimestampList(int columnIndex)
      Parameters:
      columnIndex - index of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.timestamp()) The list returned by this method is lazily constructed. Create a copy of it if you intend to access each element in the list multiple times.

    • getTimestampList

      List<com.google.cloud.Timestamp> getTimestampList(String columnName)
      Parameters:
      columnName - name of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.timestamp()) The list returned by this method is lazily constructed. Create a copy of it if you intend to access each element in the list multiple times.

    • getDateList

      List<com.google.cloud.Date> getDateList(int columnIndex)
      Parameters:
      columnIndex - index of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.date()). The list returned by this method is lazily constructed. Create a copy of it if you intend to access each element in the list multiple times.

    • getDateList

      List<com.google.cloud.Date> getDateList(String columnName)
      Parameters:
      columnName - name of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.date()). The list returned by this method is lazily constructed. Create a copy of it if you intend to access each element in the list multiple times.

    • getStructList

      List<Struct> getStructList(int columnIndex)
      Parameters:
      columnIndex - index of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.struct(...)) The list returned by this method is lazily constructed. Create a copy of it if you intend to access each element in the list multiple times.

    • getStructList

      List<Struct> getStructList(String columnName)
      Parameters:
      columnName - name of the column
      Returns:
      the value of a non-NULL column with type Type.array(Type.struct(...)) The list returned by this method is lazily constructed. Create a copy of it if you intend to access each element in the list multiple times.