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 Detail

      • updateSchema

        void updateSchema​(java.lang.String moduleId,
                          java.util.List<? extends SchemaFeature> features)
                   throws java.sql.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:
        java.sql.SQLException
      • updatePersistentRecords

        void updatePersistentRecords​(RecordMeta<?>... recordMeta)
                              throws java.sql.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:
        java.sql.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​(java.lang.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

        java.util.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.