io.rdbc.japi.Row Maven / Gradle / Ivy
/*
* Copyright 2016 rdbc contributors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package io.rdbc.japi;
import io.rdbc.japi.exceptions.ConversionException;
import java.math.BigDecimal;
import java.time.Instant;
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.LocalTime;
import java.util.Optional;
import java.util.UUID;
/**
* Represents a row of a result returned by a database engine.
*
* This class defines a set of methods that can be used to get values from the
* row either by a column name or by a column index. Each method has a version
* returning an {@link Optional} to allow null-safe handling of SQL
* {@code NULL} values.
*/
public interface Row {
/**
* Returns an object of type {@code T} from column with a given index.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
T getCol(int idx, Class cls) throws ConversionException;
/**
* Returns an object of type {@code T} from column with a given index.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getColOpt(int idx, Class cls) throws ConversionException;
/**
* Returns an object of type {@code T} from column with a given name.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
T getCol(String name, Class cls) throws ConversionException;
/**
* Returns an object of type {@code T} from column with a given name.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getColOpt(String name, Class cls) throws ConversionException;
/**
* Returns a {@code String} from column with a given name.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
String getStr(String name) throws ConversionException;
/**
* Returns a {@code String} from column with a given name.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getStrOpt(String name) throws ConversionException;
/**
* Returns a {@code String} from column with a given index.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
String getStr(int idx) throws ConversionException;
/**
* Returns a {@code String} from column with a given index.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getStrOpt(int idx) throws ConversionException;
/**
* Returns a boolean value from column with a given name.
*
*
* - A single {@code 'T'}, {@code 'Y'} or {@code '1'} character values or {@code 1} numeric value are
* considered {@code true}.
* - A single {@code 'F'}, {@code 'N'} or {@code '0'} character values or {@code 0} numeric value are
* considered {@code false}.
*
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
Boolean getBool(String name) throws ConversionException;
/**
* Returns a boolean value from column with a given name.
*
*
* - A single {@code 'T'}, {@code 'Y'} or {@code '1'} character values or {@code 1} numeric value are
* considered {@code true}.
* - A single {@code 'F'}, {@code 'N'} or {@code '0'} character values or {@code 0} numeric value are
* considered {@code false}.
*
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getBoolOpt(String name) throws ConversionException;
/**
* Returns a boolean value from column with a given index.
*
*
* - A single {@code 'T'}, {@code 'Y'} or {@code '1'} character values or {@code 1} numeric value are
* considered {@code true}.
* - A single {@code 'F'}, {@code 'N'} or {@code '0'} character values or {@code 0} numeric value are
* considered {@code false}.
*
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
Boolean getBool(int idx) throws ConversionException;
/**
* Returns a boolean value from column with a given index.
*
*
* - A single {@code 'T'}, {@code 'Y'} or {@code '1'} character values or {@code 1} numeric value are
* considered {@code true}.
* - A single {@code 'F'}, {@code 'N'} or {@code '0'} character values or {@code 0} numeric value are
* considered {@code false}.
*
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getBoolOpt(int idx) throws ConversionException;
/**
* Returns a character from column with a given name.
*
* Varchar types with a single character are convertible to a {@code Char}.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
Character getChar(String name) throws ConversionException;
/**
* Returns a character from column with a given name.
*
* Varchar types with a single character are convertible to a {@code Char}.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getCharOpt(String name) throws ConversionException;
/**
* Returns a character from column with a given index.
*
* Varchar types with a single character are convertible to a {@code Char}.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
Character getChar(int idx) throws ConversionException;
/**
* Returns a character from column with a given index.
*
* Varchar types with a single character are convertible to a {@code Char}.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getCharOpt(int idx) throws ConversionException;
/**
* Returns a {@code Short} from column with a given name.
*
* All numeric types can be converted to {@code Short}, but some conversions may
* involve rounding or truncation.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
Short getShort(String name) throws ConversionException;
/**
* Returns a {@code Short} from column with a given name.
*
* All numeric types can be converted to {@code Short}, but some conversions may
* involve rounding or truncation.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getShortOpt(String name) throws ConversionException;
/**
* Returns a {@code Short} from column with a given index.
*
* All numeric types can be converted to {@code Short}, but some conversions may
* involve rounding or truncation.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
Short getShort(int idx) throws ConversionException;
/**
* Returns a {@code Short} from column with a given index.
*
* All numeric types can be converted to {@code Short}, but some conversions may
* involve rounding or truncation.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getShortOpt(int idx) throws ConversionException;
/**
* Returns an {@code int} from column with a given name.
*
* All numeric types can be converted to {@code int}, but some conversions may
* involve rounding or truncation.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
Integer getInt(String name) throws ConversionException;
/**
* Returns an {@code int} from column with a given name.
*
* All numeric types can be converted to {@code int}, but some conversions may
* involve rounding or truncation.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getIntOpt(String name) throws ConversionException;
/**
* Returns an {@code int} from column with a given index.
*
* All numeric types can be converted to {@code int}, but some conversions may
* involve rounding or truncation.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Integer getInt(int idx) throws ConversionException;
/**
* Returns an {@code int} from column with a given index.
*
* All numeric types can be converted to {@code int}, but some conversions may
* involve rounding or truncation.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getIntOpt(int idx) throws ConversionException;
/**
* Returns a {@code Long} from column with a given name.
*
* All numeric types can be converted to {@code Long}, but some conversions may
* involve rounding or truncation.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
Long getLong(String name) throws ConversionException;
/**
* Returns a {@code Long} from column with a given name.
*
* All numeric types can be converted to {@code Long}, but some conversions may
* involve rounding or truncation.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getLongOpt(String name) throws ConversionException;
/**
* Returns a {@code Long} from column with a given index.
*
* All numeric types can be converted to {@code Long}, but some conversions may
* involve rounding or truncation.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
Long getLong(int idx) throws ConversionException;
/**
* Returns a {@code Long} from column with a given index.
*
* All numeric types can be converted to {@code Long}, but some conversions may
* involve rounding or truncation.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getLongOpt(int idx) throws ConversionException;
/**
* Returns a {@link BigDecimal} from column with a given name.
*
* All numeric types can be converted to {@link BigDecimal}, note however that
* NaN value is not representable by a {@link BigDecimal}. If you expect values
* to be NaN use {@code numeric} method instead.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
BigDecimal getBigDecimal(String name) throws ConversionException;
/**
* Returns a {@link BigDecimal} from column with a given name.
*
* All numeric types can be converted to {@link BigDecimal}, note however that
* NaN value is not representable by a {@link BigDecimal}. If you expect values
* to be NaN use {@code numeric} method instead.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getBigDecimalOpt(String name) throws ConversionException;
/**
* Returns a {@link BigDecimal} from column with a given index.
*
* All numeric types can be converted to {@link BigDecimal}, note however that
* NaN value is not representable by a {@link BigDecimal}. If you expect values
* to be NaN use {@code numeric} method instead.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
BigDecimal getBigDecimal(int idx) throws ConversionException;
/**
* Returns a {@link BigDecimal} from column with a given index.
*
* All numeric types can be converted to {@link BigDecimal}, note however that
* NaN value is not representable by a {@link BigDecimal}. If you expect values
* to be NaN use {@code numeric} method instead.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getBigDecimalOpt(int idx) throws ConversionException;
/**
* Returns a {@link SqlNumeric} from column with a given name.
*
* All numeric types can be converted to {@link SqlNumeric}.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
SqlNumeric getNumeric(String name) throws ConversionException;
/**
* Returns a {@link SqlNumeric} from column with a given name.
*
* All numeric types can be converted to {@link SqlNumeric}.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getNumericOpt(String name) throws ConversionException;
/**
* Returns a {@link SqlNumeric} from column with a given index.
*
* All numeric types can be converted to {@link SqlNumeric}.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
SqlNumeric getNumeric(int idx) throws ConversionException;
/**
* Returns a {@link SqlNumeric} from column with a given index.
*
* All numeric types can be converted to {@link SqlNumeric}.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getNumericOpt(int idx) throws ConversionException;
/**
* Returns a {@code Double} from column with a given name.
*
* All numeric types can be converted to {@code Double}, but some conversions
* may involve rounding or truncation.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
Double getDouble(String name) throws ConversionException;
/**
* Returns a {@code Double} from column with a given name.
*
* All numeric types can be converted to {@code Double}, but some conversions may
* involve rounding or truncation.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getDoubleOpt(String name) throws ConversionException;
/**
* Returns a {@code Double} from column with a given index.
*
* All numeric types can be converted to {@code Double}, but some conversions
* may involve rounding or truncation.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
Double getDouble(int idx) throws ConversionException;
/**
* Returns a {@code Double} from column with a given index.
*
* All numeric types can be converted to {@code Double}, but some conversions may
* involve rounding or truncation.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getDoubleOpt(int idx) throws ConversionException;
/**
* Returns a {@code Float} from column with a given name.
*
* All numeric types can be converted to {@code Float}, but some conversions may
* involve rounding or truncation.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
Float getFloat(String name) throws ConversionException;
/**
* Returns a {@code Float} from column with a given name.
*
* All numeric types can be converted to {@code Float}, but some conversions may
* involve rounding or truncation.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getFloatOpt(String name) throws ConversionException;
/**
* Returns a {@code Float} from column with a given index.
*
* All numeric types can be converted to {@code Float}, but some conversions may
* involve rounding or truncation.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
Float getFloat(int idx) throws ConversionException;
/**
* Returns a {@code Float} from column with a given index.
*
* All numeric types can be converted to {@code Float}, but some conversions may
* involve rounding or truncation.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getFloatOpt(int idx) throws ConversionException;
/**
* Returns an {@code Instant} from column with a given name.
*
* Note that regular timestamp values are not convertible to an {@code Instant}
* because timestamp values do not hold a time zone information.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
Instant getInstant(String name) throws ConversionException;
/**
* Returns an {@code Instant} from column with a given name.
*
* Note that regular timestamp values are not convertible to an {@code Instant}
* because timestamp values do not hold a time zone information.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getInstantOpt(String name) throws ConversionException;
/**
* Returns an {@code Instant} from column with a given index.
*
* Note that regular timestamp values are not convertible to an {@code Instant}
* because timestamp values do not hold a time zone information.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
Instant getInstant(int idx) throws ConversionException;
/**
* Returns an {@code Instant} from column with a given index.
*
* Note that regular timestamp values are not convertible to an {@code Instant}
* because timestamp values do not hold a time zone information.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getInstantOpt(int idx) throws ConversionException;
/**
* Returns a {@code LocalDateTime} from column with a given name.
*
* For SQL date type that does not hold a time, {@code LocalDateTime} at start
* of day is returned.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
LocalDateTime getLocalDateTime(String name) throws ConversionException;
/**
* Returns a {@code LocalDateTime} from column with a given name.
*
* For SQL date type that does not hold a time, {@code LocalDateTime} at start
* of day is returned.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getLocalDateTimeOpt(String name) throws ConversionException;
/**
* Returns a {@code LocalDateTime} from column with a given index.
*
* For SQL date type that does not hold a time, {@code LocalDateTime} at start
* of day is returned.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
LocalDateTime getLocalDateTime(int idx) throws ConversionException;
/**
* Returns a {@code LocalDateTime} from column with a given index.
*
* For SQL date type that does not hold a time, {@code LocalDateTime} at start
* of day is returned.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getLocalDateTimeOpt(int idx) throws ConversionException;
/**
* Returns a {@code LocalDate} from column with a given name.
*
* SQL types that represent a date with a time are convertible to
* {@code LocalDate} - a time part is truncated.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
LocalDate getLocalDate(String name) throws ConversionException;
/**
* Returns a {@code LocalDate} from column with a given name.
*
* SQL types that represent a date with a time are convertible to
* {@code LocalDate} - a time part is truncated.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getLocalDateOpt(String name) throws ConversionException;
/**
* Returns a {@code LocalDate} from column with a given index.
*
* SQL types that represent a date with a time are convertible to
* {@code LocalDate} - a time part is truncated.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
LocalDate getLocalDate(int idx) throws ConversionException;
/**
* Returns a {@code LocalDate} from column with a given index.
*
* SQL types that represent a date with a time are convertible to
* {@code LocalDate} - a time part is truncated.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getLocalDateOpt(int idx) throws ConversionException;
/**
* Returns a {@code LocalDate} from column with a given name.
*
* SQL types that represent a date with a time are convertible to
* {@code LocalTime} - a date part is truncated.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
LocalTime getLocalTime(String name) throws ConversionException;
/**
* Returns a {@code LocalDate} from column with a given name.
*
* SQL types that represent a date with a time are convertible to
* {@code LocalTime} - a date part is truncated.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getLocalTimeOpt(String name) throws ConversionException;
/**
* Returns a {@code LocalDate} from column with a given index.
*
* SQL types that represent a date with a time are convertible to
* {@code LocalTime} - a date part is truncated.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
LocalTime getLocalTime(int idx) throws ConversionException;
/**
* Returns a {@code LocalDate} from column with a given index.
*
* SQL types that represent a date with a time are convertible to
* {@code LocalTime} - a date part is truncated.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getLocalTimeOpt(int idx) throws ConversionException;
/**
* Returns a byte array from column with a given name.
*
* Note that this method cannot be used to fetch raw value of any type from
* the database, it should be used only to fetch binary data.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
byte[] getBytes(String name) throws ConversionException;
/**
* Returns a byte array from column with a given name.
*
* Note that this method cannot be used to fetch raw value of any type from
* the database, it should be used
* only to fetch binary data.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getBytesOpt(String name) throws ConversionException;
/**
* Returns a byte array from column with a given index.
*
* Note that this method cannot be used to fetch raw value of any type from
* the database, it should be used only to fetch binary data.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
byte[] getBytes(int idx) throws ConversionException;
/**
* Returns a byte array from column with a given index.
*
* Note that this method cannot be used to fetch raw value of any type from
* the database, it should be used
* only to fetch binary data.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getBytesOpt(int idx) throws ConversionException;
/**
* Returns an {@code UUID} from column with a given name.
*
* A string type with a standard UUID representation as defined by
* {@code UUID.fromString} is convertible to UUID.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
UUID getUuid(String name) throws ConversionException;
/**
* Returns an {@code UUID} from column with a given name.
*
* A string type with a standard UUID representation as defined by
* {@code UUID.fromString} is convertible to UUID.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getUuidOpt(String name) throws ConversionException;
/**
* Returns an {@code UUID} from column with a given index.
*
* A string type with a standard UUID representation as defined by
* {@code UUID.fromString} is convertible to UUID.
*
* For SQL {@code NULL} values, {@link ConversionException} is thrown. For null-safety consider using
* corresponding {@code *Opt} method.
*/
UUID getUuid(int idx) throws ConversionException;
/**
* Returns an {@code UUID} from column with a given index.
*
* A string type with a standard UUID representation as defined by
* {@code UUID.fromString} is convertible to UUID.
*
* For SQL {@code NULL} values an empty {@link Optional} is returned.
*/
Optional getUuidOpt(int idx) throws ConversionException;
}