Module storm.foundation
Package st.orm

Interface IntegrityViolation

All Known Implementing Classes:
IntegrityViolation.Check, IntegrityViolation.ForeignKey, IntegrityViolation.Length, IntegrityViolation.NotNull, IntegrityViolation.NumericRange, IntegrityViolation.Referenced, IntegrityViolation.Unique
public sealed interface IntegrityViolation permits IntegrityViolation.Unique, IntegrityViolation.ForeignKey, IntegrityViolation.Referenced, IntegrityViolation.NotNull, IntegrityViolation.Check, IntegrityViolation.Length, IntegrityViolation.NumericRange
A value that breaks a rule of its table: a duplicate under a unique key, a reference to a row that does not exist, a null in a column that refuses it, a value a check constraint rejects, or a value too large for its column. Each kind of rule is a record of its own, carrying what its kind can report, so a caller matches on the type.

Integrity is meant in the sense of the data conforming to its schema. It spans what SQL calls an integrity constraint violation, SQL state class 23, and a value too large for its column, which SQL files under data exceptions, class 22: both are a value the table refuses, and a caller handles them as one. Each record names the SQL state the standard assigns to its kind; a database may report the violation under a code of its own, which its dialect recognises, and the driver's exception stays the cause of the IntegrityViolationException for a caller that needs the code as reported.

A violation is reported in terms of the entity: the fields it resolves to as metamodel keys, and, where the database reported them, the name of the constraint and the table. The database reports one violation per failed write; the checks of validate report every violation of an entity, each with the limit the value exceeded. A field is set only when the error or the check identifies the column; a violation whose column the database does not name has no fields.

Since:
1.16
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static final record 
    IntegrityViolation.Check
    A value a check constraint rejects.
    static final record 
    IntegrityViolation.ForeignKey
    A foreign key that references a row that does not exist.
    static final record 
    IntegrityViolation.Length
    A string longer than its column.
    static final record 
    IntegrityViolation.NotNull
    A null in a column that does not accept one.
    static final record 
    IntegrityViolation.NumericRange
    A number with more digits before the decimal point than its column holds.
    static final record 
    IntegrityViolation.Referenced
    A row that other rows still reference through a foreign key, so it cannot be removed, or have its key changed.
    static final record 
    IntegrityViolation.Unique
    A value, or a combination of values, that another row already holds under a unique key or the primary key.

  • Method Summary

    Modifier and Type
    Method
    Description
    default @Nullable String
    constraint()
    Returns the name of the violated constraint, as the database reported it.
    default List<Metamodel<?,?>>
    fields()
    Returns the fields the violation resolves to.
    default boolean
    on(Metamodel<?,?> field)
    Returns whether the violation resolves to the given field.
    @Nullable String
    table()
    Returns the table the violated constraint belongs to.
    @Nullable Class<? extends Data>
    type()
    Returns the entity type of the write that was refused.

  • Method Details

    • constraint

      default @Nullable String constraint()
      Returns the name of the violated constraint, as the database reported it. null for a violation the database did not report, such as one of validate, for a database that names no constraint for the kind, and for a kind that has no named constraint: a null, a value too long or a value out of range.
      Returns:
      the constraint name, or null.

    • table

      @Nullable String table()
      Returns the table the violated constraint belongs to. For a IntegrityViolation.Referenced violation this is the table that holds the referencing rows.
      Returns:
      the table name, or null when it is not known.

    • type

      @Nullable Class<? extends Data> type()
      Returns the entity type of the write that was refused. For a IntegrityViolation.Referenced violation this is the type of the removed row.
      Returns:
      the entity type, or null when the write names none.

    • fields

      default List<Metamodel<?,?>> fields()
      Returns the fields the violation resolves to. A violation of a compound key resolves to each of its fields. Empty when the database does not say which column, which the fields of the entity cannot be inferred from, and for a kind that names none: a row still referenced, whose referencing rows name no field of the removed row, and a check constraint.
      Returns:
      the fields, as metamodel keys.

    • on

      default boolean on(Metamodel<?,?> field)
      Returns whether the violation resolves to the given field.
      Parameters:
      field - the field to test for.
      Returns:
      true if the field is among the violation's fields.