Class SignInRecordStore

java.lang.Object
com.iizix.server.user.SignInRecordStore

public final class SignInRecordStore extends Object
The sign-in records: where and when every sign-in happened (CC-SIGNIN-RECORDS-AND-SECURITY-LOG, order 556; SN-4 of the v5.1 sign-in plan, the owner's rulings DV-4, DV-6, DV-7, SN-D-15). One row per completed sign-in and re-sign-in of a user on a device in an application: the time (UTC), the device's time zone, the client address, the place the server's region location provider (IP2Location) knows for the address, and the device's own location when the client could give one without asking its user - rounded to about a kilometer (two decimals), so that the table is a security record and not a tracking log (SN-D-15).

The table IZS.SIGNIN_RECORDS is created here when it is absent (ensureSchema()), as DeviceTokenStore creates its own: createBaseTables.sql runs on a database without tables only. The members of a hub share the database; a table another server created at the same moment is used as found. Where the table cannot be created the store is unavailable: nothing is written and nothing is read, and the sign-in is not affected - a record is written AFTER the sign-in, by SignInRecorder, never in its path.

Rows are deleted with the user (the foreign key cascades) and by the daily purge (purge(int)) after $signIn.signInRecordDays days, 90 by default (DV-6). The SQL is SQL-92 and runs unchanged on Derby, PostgreSQL and MySQL. Thread-safe: every method takes its own connection. The clock is injected, so that the tests drive time.

Author:
Christopher Mindus
  • Field Details

    • BROWSER_DEVICE

      public static final String BROWSER_DEVICE
      The device identifier of a Browser the server has not given one of its own: what EnvProps.getDeviceUUID() answers for every Browser.
      See Also:
    • SOURCE_CORDOVA

      public static final String SOURCE_CORDOVA
      The sources of a device location, as stored.
      See Also:
    • SOURCE_BROWSER

      public static final String SOURCE_BROWSER
      The sources of a device location, as stored.
      See Also:
    • SOURCE_IP

      public static final String SOURCE_IP
      The sources of a device location, as stored.
      See Also:
    • SOURCE_NONE

      public static final String SOURCE_NONE
      The sources of a device location, as stored.
      See Also:
  • Constructor Details

    • SignInRecordStore

      public SignInRecordStore(ConnectionSource connections)
      Constructs the store on the system clock.
      Parameters:
      connections - The connection source, in the server DBUtilities::getPooledConnection.
    • SignInRecordStore

      public SignInRecordStore(ConnectionSource connections, LongSupplier clock)
      Constructs the store on a clock.
      Parameters:
      connections - The connection source.
      clock - The clock: epoch milliseconds.
  • Method Details

    • ensureSchema

      public boolean ensureSchema() throws SQLException
      Creates the table when it is absent. Another server on the same database may do so at the same moment: a table it created first is used as found.
      Returns:
      true if the table was created here, false if it existed or another server made it.
      Throws:
      SQLException - For SQL errors: the table is absent and cannot be created.
    • round

      public static double round(double degrees)
      Rounds a coordinate to two decimals, about a kilometer (SN-D-15).
      Parameters:
      degrees - The coordinate, possibly NaN.
      Returns:
      The rounded coordinate, NaN for NaN.
    • write

      Writes a record. The caller's texts are cut to their columns; the coordinates are rounded (round(double)). The row identifier is made here when the record's is zero.
      Parameters:
      rec - The record.
      Returns:
      The record as written (its identifier set), null when the store is unavailable.
      Throws:
      NullPointerException - If a required member is null.
      IllegalArgumentException - If the application ID or device ID is empty or too long.
      SQLException - For SQL errors.
    • assignDevice

      public boolean assignDevice(long id, String deviceID) throws SQLException
      Gives a record the device identifier the server gave its Browser after the record was written: the Browser was remembered (stay signed in, or trusted for the second step) in the session the record is of, so its rows and its device token share one identifier.
      Parameters:
      id - The record.
      deviceID - The device identifier.
      Returns:
      true when the row was updated.
      Throws:
      SQLException - For SQL errors.
    • purge

      public int purge(int days) throws SQLException
      Deletes the records older than a number of days: the daily purge (DV-6).
      Parameters:
      days - The days kept, positive.
      Returns:
      The number of rows deleted.
      Throws:
      IllegalArgumentException - If days is not positive.
      SQLException - For SQL errors.
    • list

      public List<SignInRecordStore.Record> list(long uid, int limit) throws SQLException
      Lists the records of a user, the most recent first.
      Parameters:
      uid - The user.
      limit - The most rows, positive.
      Returns:
      The records, possibly none; none when the store is unavailable.
      Throws:
      SQLException - For SQL errors.
    • firstAndLastPerDevice

      public List<SignInRecordInfo> firstAndLastPerDevice(long uid) throws SQLException
      Gets the first and the last record of every device and application of a user: what the devices lists show (SN-5), the most recent last sign-in first.
      Parameters:
      uid - The user.
      Returns:
      One entry per device and application, possibly none; none when the store is unavailable.
      Throws:
      SQLException - For SQL errors.
    • placeOf

      public static String placeOf(String city, String region, String country)
      Describes a place: "city, region, country", a part left out when unknown or when it IS the part said before it ("Monaco, Monaco" is said once). The whole part is compared: until CC-FIX-LOCK-SMALLS a part was left out when the text so far ENDED with it, so a region whose name ends with its country lost the country ("Paris, Ile-de-France" for Paris, Ile-de-France, France). The one writer of this text: the sign-in records, and through ClientPlace the failed sign-ins, the security events, the account notices and their mails.
      Parameters:
      city - The city, null for unknown.
      region - The region, null for unknown.
      country - The country, null for unknown.
      Returns:
      The place, null when nothing is known.