Package org.kiwiproject.jdbc

Class KiwiJdbc

java.lang.Object
org.kiwiproject.jdbc.KiwiJdbc
public final class KiwiJdbc extends Object
JDBC utilities.

  • Method Details

    • nextOrThrow

      public static void nextOrThrow(ResultSet rs) throws SQLException
      Attempt to call ResultSet.next() on the given ResultSet, and throw an IllegalStateException if the result set was not advanced.
      Parameters:
      rs - the ResultSet
      Throws:
      SQLException - if a database access error occurs or this method is called on a closed result set (copied from ResultSet.next())
      IllegalStateException - if the result set was not advanced

    • nextOrThrow

      public static void nextOrThrow(ResultSet rs, String message) throws SQLException
      Attempt to call ResultSet.next() on the given ResultSet, and throw an IllegalStateException if the result set was not advanced.
      Parameters:
      rs - the ResultSet
      message - the error message in case the result set cannot be advanced
      Throws:
      SQLException - if a database access error occurs or this method is called on a closed result set (copied from ResultSet.next())
      IllegalStateException - if the result set was not advanced

    • nextOrThrow

      public static void nextOrThrow(ResultSet rs, String messageTemplate, Object... args) throws SQLException
      Attempt to call ResultSet.next() on the given ResultSet, and throw an IllegalStateException if the result set was not advanced.
      Parameters:
      rs - the ResultSet
      messageTemplate - the error message template in case the result set cannot be advanced, according to how KiwiStrings.format(String, Object...) handles placeholders
      args - the arguments to be substituted into the message template
      Throws:
      SQLException - if a database access error occurs or this method is called on a closed result set (copied from ResultSet.next())
      IllegalStateException - if the result set was not advanced

    • epochMillisFromTimestamp

      public static long epochMillisFromTimestamp(ResultSet rs, String columnName) throws SQLException
      Convert the timestamp column given by columnName in the ResultSet to milliseconds from the epoch.
      Parameters:
      rs - the ResultSet
      columnName - the timestamp column name
      Returns:
      epoch milliseconds
      Throws:
      SQLException - if there is a database problem
      IllegalArgumentException - if the timestamp returned from the ResultSet is null
      See Also:

    • epochMillisFromTimestamp

      public static long epochMillisFromTimestamp(Timestamp timestamp)
      Convert the given Timestamp to milliseconds from the epoch.
      Parameters:
      timestamp - the timestamp to convert
      Returns:
      epoch milliseconds
      Throws:
      IllegalArgumentException - if timestamp is null
      See Also:

    • dateFromTimestamp

      public static @Nullable Date dateFromTimestamp(ResultSet rs, String columnName) throws SQLException
      Returns a Date from the specified Timestamp column in the given ResultSet.
      Parameters:
      rs - the ResultSet
      columnName - the timestamp column name
      Returns:
      the converted Date or null if the column was NULL
      Throws:
      SQLException - if there is a database problem

    • dateFromTimestamp

      public static @Nullable Date dateFromTimestamp(Timestamp timestamp)
      Returns a Date from the given Timestamp.
      Parameters:
      timestamp - the timestamp to convert
      Returns:
      a Date or null if the timestamp is null

    • instantFromTimestamp

      public static @Nullable Instant instantFromTimestamp(ResultSet rs, String columnName) throws SQLException
      Returns a Instant from the specified Timestamp column in the given ResultSet.
      Parameters:
      rs - the ResultSet
      columnName - the timestamp column name
      Returns:
      the converted Instant or null if the column was NULL
      Throws:
      SQLException - if there is a database problem

    • instantFromTimestamp

      public static @Nullable Instant instantFromTimestamp(Timestamp timestamp)
      Returns an Instant from the given Timestamp.
      Parameters:
      timestamp - the timestamp to convert
      Returns:
      an Instant or null if the timestamp is null

    • localDateTimeFromTimestamp

      public static @Nullable LocalDateTime localDateTimeFromTimestamp(ResultSet rs, String columnName) throws SQLException
      Returns a LocalDateTime from the specified Timestamp column in the given ResultSet.
      Parameters:
      rs - the ResultSet
      columnName - the timestamp column name
      Returns:
      the converted LocalDateTime or null if the column was NULL
      Throws:
      SQLException - if there is a database problem

    • localDateTimeFromTimestamp

      public static @Nullable LocalDateTime localDateTimeFromTimestamp(Timestamp timestamp)
      Returns a LocalDateTime from the given Timestamp.
      Parameters:
      timestamp - the timestamp to convert
      Returns:
      a LocalDateTime or null if the timestamp is null

    • localDateFromDateOrNull

      public static @Nullable LocalDate localDateFromDateOrNull(ResultSet rs, String columnName) throws SQLException
      Returns a LocalDate from the specified Date column in the given ResultSet.
      Parameters:
      rs - the ResultSet
      columnName - the date column name
      Returns:
      the converted LocalDate or null if the column was NULL
      Throws:
      SQLException - if there is any error getting the date value from the database

    • localDateFromDateOrNull

      public static @Nullable LocalDate localDateFromDateOrNull(@Nullable Date date)
      Returns a LocalDateTime from the given Date.
      Parameters:
      date - the date to convert
      Returns:
      the converted LocalDate or null if the date is null

    • utcZonedDateTimeFromTimestamp

      public static @Nullable ZonedDateTime utcZonedDateTimeFromTimestamp(ResultSet rs, String columnName) throws SQLException
      Returns a ZonedDateTime in UTC from the specified column in the ResultSet.
      Parameters:
      rs - the ResultSet
      columnName - the timestamp column name
      Returns:
      a UTC ZonedDateTime or null if the column was NULL
      Throws:
      SQLException - if there is a database problem

    • zonedDateTimeFromTimestamp

      public static @Nullable ZonedDateTime zonedDateTimeFromTimestamp(ResultSet rs, String columnName, ZoneId zoneId) throws SQLException
      Returns a ZonedDateTime in the specified time zone from the specified column in the ResultSet.
      Parameters:
      rs - the ResultSet
      columnName - the timestamp column name
      zoneId - the time zone ID
      Returns:
      a ZonedDateTime in the specified zone, or null if the column was NULL
      Throws:
      SQLException - if there is a database problem

    • utcZonedDateTimeFromTimestamp

      public static @Nullable ZonedDateTime utcZonedDateTimeFromTimestamp(Timestamp timestamp)
      Returns a ZonedDateTime in UTC from the specified Timestamp.
      Parameters:
      timestamp - the timestamp to convert
      Returns:
      a UTC ZonedDateTime or null if the timestamp is null

    • utcZonedDateTimeFromEpochMilli

      public static ZonedDateTime utcZonedDateTimeFromEpochMilli(long epochMilli)
      Returns a ZonedDateTime in UTC from the given number of milliseconds since the epoch.

      Note that this method will always have zero as the nano-of-second.

      Parameters:
      epochMilli - number of milliseconds since the epoch
      Returns:
      a UTC ZonedDateTime

    • zonedDateTimeFromTimestamp

      public static @Nullable ZonedDateTime zonedDateTimeFromTimestamp(Timestamp timestamp, ZoneId zoneId)
      Returns a ZonedDateTime in the specified time zone from the given Timestamp.
      Parameters:
      timestamp - the timestamp to convert
      zoneId - the time zone ID
      Returns:
      a ZonedDateTime in the specified zone, or null if the timestamp is null

    • timestampFromInstant

      public static @Nullable Timestamp timestampFromInstant(Instant instant)
      Returns a Timestamp from the given Instant.
      Parameters:
      instant - the Instant to convert
      Returns:
      a Timestamp or null if the instant is null

    • timestampFromZonedDateTime

      public static @Nullable Timestamp timestampFromZonedDateTime(ZonedDateTime zonedDateTime)
      Returns a Timestamp from the given ZonedDateTime.
      Parameters:
      zonedDateTime - the ZonedDateTime to convert
      Returns:
      a Timestamp or null if the zonedDateTime is null

    • longValueOrNull

      public static @Nullable Long longValueOrNull(ResultSet rs, String columnName) throws SQLException
      Simplifies the JDBC silliness whereby getting a long value that is actually null returns zero, and you have to check if the last value was actually null using the ResultSet.wasNull() method.
      Parameters:
      rs - the ResultSet
      columnName - the column name
      Returns:
      a Long or null
      Throws:
      SQLException - if there is a database problem

    • intValueOrNull

      public static @Nullable Integer intValueOrNull(ResultSet rs, String columnName) throws SQLException
      Simplifies the JDBC silliness whereby getting an int value that is actually null returns zero, and you have to check if the last value was actually null using the ResultSet.wasNull() method.
      Parameters:
      rs - the ResultSet
      columnName - the column name
      Returns:
      an Integer or null
      Throws:
      SQLException - if there is a database problem

    • doubleValueOrNull

      public static @Nullable Double doubleValueOrNull(ResultSet rs, String columnName) throws SQLException
      Simplifies the JDBC silliness whereby getting a double value that is actually null returns zero, and you have to check if the last value was actually null using the ResultSet.wasNull() method.
      Parameters:
      rs - the ResultSet
      columnName - the column name
      Returns:
      a Double or null
      Throws:
      SQLException - if there is a database problem

    • enumValueOrNull

      public static <T extends Enum<T>> @Nullable T enumValueOrNull(ResultSet rs, String columnName, Class<T> enumType) throws SQLException
      Returns an enum constant of the given type from the specified column in the result set.
      Type Parameters:
      T - the enum type parameter
      Parameters:
      rs - the ResultSet
      columnName - the column name
      enumType - the enum class
      Returns:
      an enum constant of type enumType or null if the database value was NULL
      Throws:
      SQLException - if there is a database problem
      IllegalArgumentException - if the value from the ResultSet is an invalid enum constant
      See Also:

    • enumValueOrEmpty

      public static <T extends Enum<T>> Optional<T> enumValueOrEmpty(ResultSet rs, String columnName, Class<T> enumType) throws SQLException
      Returns an enum constant of the given type from the specified column in the result set.
      Type Parameters:
      T - the enum type parameter
      Parameters:
      rs - the ResultSet
      columnName - the column name
      enumType - the enum class
      Returns:
      an enum constant of type enumType or an empty Optional if the database value was NULL
      Throws:
      SQLException - if there is a database problem
      IllegalArgumentException - if the value from the ResultSet is an invalid enum constant
      See Also:

    • booleanFromLong

      public static boolean booleanFromLong(ResultSet rs, String columnName) throws SQLException
      Converts a long value in the specified column to a boolean. The database value must be zero, one or NULL.
      Parameters:
      rs - the ResultSet
      columnName - the column name
      Returns:
      true if the database value is one, or false if it is zero or NULL
      Throws:
      IllegalArgumentException - if the value in the column is not zero, one, or NULL
      SQLException - if there is any error getting the value from the database
      See Also:

    • booleanFromLong

      public static boolean booleanFromLong(ResultSet rs, String columnName, KiwiPrimitives.BooleanConversionOption option) throws SQLException
      Converts a long value in the specified column to a boolean using the given KiwiPrimitives.BooleanConversionOption.
      Parameters:
      rs - the ResultSet
      columnName - the column name
      option - how to convert the long value into a boolean
      Returns:
      the converted value, determined using the conversion option
      Throws:
      SQLException - if there is any error getting the value from the database

    • booleanFromInt

      public static boolean booleanFromInt(ResultSet rs, String columnName) throws SQLException
      Converts an int value in the specified column to a boolean. The database value must be zero, one or NULL.
      Parameters:
      rs - the ResultSet
      columnName - the column name
      Returns:
      true if the database value is one, or false if it is zero or NULL
      Throws:
      IllegalArgumentException - if the value in the column is not zero, one, or NULL
      SQLException - if there is any error getting the value from the database
      See Also:

    • booleanFromInt

      public static boolean booleanFromInt(ResultSet rs, String columnName, KiwiPrimitives.BooleanConversionOption option) throws SQLException
      Converts an int value in the specified column to a boolean using the given KiwiPrimitives.BooleanConversionOption.
      Parameters:
      rs - the ResultSet
      columnName - the column name
      option - how to convert the int value into a boolean
      Returns:
      the converted value, determined using the conversion option
      Throws:
      SQLException - if there is any error getting the value from the database

    • stringOrNullIfBlank

      public static @Nullable String stringOrNullIfBlank(ResultSet rs, String columnName) throws SQLException
      Returns a String from the specified column in the ResultSet. When the database value is NULL or contains only whitespace, returns null.
      Parameters:
      rs - the ResultSet
      columnName - the date column name
      Returns:
      the String value, or null if the column was blank or NULL
      Throws:
      SQLException - if there is any error getting the value from the database
      See Also:

    • trimmedStringOrNullIfBlank

      public static @Nullable String trimmedStringOrNullIfBlank(ResultSet rs, String columnName) throws SQLException
      Returns a String from the specified column in the ResultSet, trimming leading and trailing whitespace. When the database value is NULL or contains only whitespace, returns null.
      Parameters:
      rs - the ResultSet
      columnName - the date column name
      Returns:
      the String with leading and trailing whitespace removed, or null if the column was blank or NULL
      Throws:
      SQLException - if there is any error getting the value from the database
      See Also:

    • stringOrNullIfBlank

      public static @Nullable String stringOrNullIfBlank(ResultSet rs, String columnName, KiwiJdbc.StringTrimOption option) throws SQLException
      Returns a String from the specified column in the ResultSet using the given KiwiJdbc.StringTrimOption. When the database value is NULL or contains only whitespace, returns null.
      Parameters:
      rs - the ResultSet
      columnName - the date column name
      option - how to handle leading and trailing whitespace
      Returns:
      the String with the specified trim option applied, or null if the column was blank or NULL
      Throws:
      SQLException - if there is any error getting the value from the database
      See Also:

    • nullSafeSetTimestamp

      public static void nullSafeSetTimestamp(PreparedStatement ps, int parameterIndex, Timestamp value) throws SQLException
      Sets the Timestamp value in a null-safe manner by using the PreparedStatement.setNull(int, int) method for null values. Uses Types.TIMESTAMP as the SQL type.
      Parameters:
      ps - the PreparedStatement to set the value on
      parameterIndex - the positional index of the value in the SQL statement
      value - the value to set, or null
      Throws:
      SQLException - if there is a database problem

    • nullSafeSetTimestamp

      public static void nullSafeSetTimestamp(PreparedStatement ps, int parameterIndex, Timestamp value, int type) throws SQLException
      Sets the Timestamp value in a null-safe manner by using the PreparedStatement.setNull(int, int) method for null values. Specify the exact SQL timestamp type using one of the values in Types.
      Parameters:
      ps - the PreparedStatement to set the value on
      parameterIndex - the positional index of the value in the SQL statement
      value - the value to set, or null
      type - the SQL type to use when setting a null value
      Throws:
      SQLException - if there is a database problem
      See Also:

    • nullSafeSetDateAsTimestamp

      public static void nullSafeSetDateAsTimestamp(PreparedStatement ps, int parameterIndex, Date value) throws SQLException
      Sets the Date value in a null-safe manner by using the PreparedStatement.setNull(int, int) method for null values. Uses Types.TIMESTAMP as the SQL type.
      Parameters:
      ps - the PreparedStatement to set the value on
      parameterIndex - the positional index of the value in the SQL statement
      value - the value to set, or null
      Throws:
      SQLException - if there is a database problem

    • nullSafeSetDateAsTimestamp

      public static void nullSafeSetDateAsTimestamp(PreparedStatement ps, int parameterIndex, Date value, int type) throws SQLException
      Sets the Date value in a null-safe manner by using the PreparedStatement.setNull(int, int) method for null values. Specify the exact SQL timestamp type using one of the values in Types.
      Parameters:
      ps - the PreparedStatement to set the value on
      parameterIndex - the positional index of the value in the SQL statement
      value - the value to set, or null
      type - the SQL type to use when setting a null value
      Throws:
      SQLException - if there is a database problem
      See Also:

    • nullSafeSetInt

      public static void nullSafeSetInt(PreparedStatement ps, int parameterIndex, Integer value) throws SQLException
      Sets the Integer value in a null-safe manner by using the PreparedStatement.setNull(int, int) method for null values. Uses Types.INTEGER as the SQL type.
      Parameters:
      ps - the PreparedStatement to set the value on
      parameterIndex - the positional index of the value in the SQL statement
      value - the value to set, or null
      Throws:
      SQLException - if there is a database problem

    • nullSafeSetInt

      public static void nullSafeSetInt(PreparedStatement ps, int parameterIndex, Integer value, int type) throws SQLException
      Sets the Integer value in a null-safe manner by using the PreparedStatement.setNull(int, int) method for null values. Specify the exact SQL int type using one of the values in Types.
      Parameters:
      ps - the PreparedStatement to set the value on
      parameterIndex - the positional index of the value in the SQL statement
      value - the value to set, or null
      type - the SQL type to use when setting a null value
      Throws:
      SQLException - if there is a database problem
      See Also:

    • nullSafeSetLong

      public static void nullSafeSetLong(PreparedStatement ps, int parameterIndex, Long value) throws SQLException
      Sets the Long value in a null-safe manner by using the PreparedStatement.setNull(int, int) method for null values. Uses Types.BIGINT as the SQL type.
      Parameters:
      ps - the PreparedStatement to set the value on
      parameterIndex - the positional index of the value in the SQL statement
      value - the value to set, or null
      Throws:
      SQLException - if there is a database problem

    • nullSafeSetLong

      public static void nullSafeSetLong(PreparedStatement ps, int parameterIndex, Long value, int type) throws SQLException
      Sets the Long value in a null-safe manner by using the PreparedStatement.setNull(int, int) method for null values. Specify the exact SQL long type using one of the values in Types.
      Parameters:
      ps - the PreparedStatement to set the value on
      parameterIndex - the positional index of the value in the SQL statement
      value - the value to set, or null
      type - the SQL type to use when setting a null value
      Throws:
      SQLException - if there is a database problem
      See Also:

    • nullSafeSetDouble

      public static void nullSafeSetDouble(PreparedStatement ps, int parameterIndex, Double value) throws SQLException
      Sets the Double value in a null-safe manner by using the PreparedStatement.setNull(int, int) method for null values. Uses Types.DOUBLE as the SQL type.
      Parameters:
      ps - the PreparedStatement to set the value on
      parameterIndex - the positional index of the value in the SQL statement
      value - the value to set, or null
      Throws:
      SQLException - if there is a database problem

    • nullSafeSetDouble

      public static void nullSafeSetDouble(PreparedStatement ps, int parameterIndex, Double value, int type) throws SQLException
      Sets the Double value in a null-safe manner by using the PreparedStatement.setNull(int, int) method for null values. Specify the exact SQL double type using one of the values in Types.
      Parameters:
      ps - the PreparedStatement to set the value on
      parameterIndex - the positional index of the value in the SQL statement
      value - the value to set, or null
      type - the SQL type to use when setting a null value
      Throws:
      SQLException - if there is a database problem
      See Also:

    • nullSafeSetString

      public static void nullSafeSetString(PreparedStatement ps, int parameterIndex, String value) throws SQLException
      Sets the String value in a null-safe manner by using the PreparedStatement.setNull(int, int) method for null values. Uses Types.VARCHAR as the SQL type.
      Parameters:
      ps - the PreparedStatement to set the value on
      parameterIndex - the positional index of the value in the SQL statement
      value - the value to set, or null
      Throws:
      SQLException - if there is a database problem

    • nullSafeSetString

      public static void nullSafeSetString(PreparedStatement ps, int parameterIndex, String value, int type) throws SQLException
      Sets the String value in a null-safe manner by using the PreparedStatement.setNull(int, int) method for null values. Specify the exact SQL string type using one of the values in Types.
      Parameters:
      ps - the PreparedStatement to set the value on
      parameterIndex - the positional index of the value in the SQL statement
      value - the value to set, or null
      type - the SQL type as an int, see SQLType
      Throws:
      SQLException - if there is a database problem
      See Also: