Package com.inductiveautomation.ignition.gateway.localdb

Interface SchemaUpdater

public interface SchemaUpdater
The SchemaUpdate is used by modules to manage the state of the internal database. It is used to update the tables used by PersistentRecords, and to perform upgrade logic through module provided SchemaFeatures.

  • Method Details

    • updateSchema

      void updateSchema(String moduleId, List<? extends SchemaFeature> features) throws SQLException
      Modules should call updateSchema to apply all of the SchemaFeatures they have. A SchemaFeature is keyed by name so that it will never by applied twice to the same database.
      Throws:
      SQLException

    • updatePersistentRecords

      void updatePersistentRecords(Iterable<SRecordMeta<? extends SRecordInstance>> recordMetas) throws SQLException
      See updatePersistentRecords(RecordMeta...)
      Throws:
      SQLException

    • updatePersistentRecords

      void updatePersistentRecords(RecordMeta<?>... recordMeta) throws SQLException

      Modules must call this during their GatewayModuleHook.setup(com.inductiveautomation.ignition.gateway.model.GatewayContext) routine for all of the PersistentRecords that they add to the system (not during startup).

      This will update the internal database's underlying database schema to support the given records. If this is the first time a record has been registered, then the table representing it will be created. If the record has been changed from the last time it was seen, the table will be modified to support any new columns. Note that new fields added to existing records that have the SFieldFlags.SMANDATORY flag (a.k.a. "NOT NULL") must have a default value, as existing records will be unable to set the new column to NULL.

      Throws:
      SQLException

    • ensureRecordExists

      void ensureRecordExists(PersistentRecord record)

      Ensures that a persistent record with the given record's key values exists in the database. If not, this record is inserted. Note that this is done on the local database only - not through the cluster. Appropriate for module startup for static records.

      The typical usage pattern for this is for records that always have exactly one row. During startup, you create a record with your "default values" and explicitly set its ID to zero, and then call this function with that prototype record. If the record with ID zero already exists, your prototype will be thrown away. If it doesn't exist, then your prototype is inserted.

    • findRecordMeta

      @Nullable SRecordMeta<? extends SRecordInstance> findRecordMeta(String tableName)
      Finds the record meta for the given tablename, or null if no such record is known.

    • isNewDatabase

      boolean isNewDatabase()
      Indicates that this is a new internal database, created during the most recent startup.
      Returns:
      True if a new internal database was created during startup.

    • tableExists

      boolean tableExists(RecordMeta<?> meta)
      Returns whether the table already exists for the given meta. Does not validate the columns of the meta. It is useful when deciding whether to upgrade one set of records to a different type.

    • findReferencingRecords

      List<RecordInstanceForeignKey> findReferencingRecords(SRecordInstance record)

      Returns all of the record instances that refer to the provided record through foreign keys. In other words, returns the rows that have a dependency on the record.

      Note that in the case of ExtensionPoint records, it returns the parent record (that is, the "profile" record) of the dependent record, not the actual setting record defining the foreign key. This is because it's the parent, not the sub record, that has a name and type suitable for display.

    • needsAlterDdl

      boolean needsAlterDdl(RecordMeta<?> meta)
      Returns whether the table for the given meta needs further modifications. Does validate columns, constraints, and sequences. If table doesn't exist, then will return false.
      Parameters:
      meta - RecordMeta for which indicates what table should be checked against.
      Returns:
      boolean indicating whether table for RecordMeta needs DDL alteration. If table doesn't exist, then will return false;