Design and Implementation of the Native Repository

Let’s start in the SQL schema, locate the table m_resource and add administrativeOperationalStateAdministrativeAvailabilityStatus column to it. Consider logical order of the columns - even though it’s not relevant for upgraded DB, it is relevant for future readability. Notice, how columns for items from subcontainers are grouped in existing tables. If the column requires a comment - like this one to clarify the actual path - add it before the column line.

What type is it? Simple things are easy (TEXT, INTEGER), some items require multiple columns (references, poly-strings), follow the patterns used previously for such cases. Our administrativeOperationalStateAdministrativeAvailabilityStatus is enum type - great! Read the next bullet how to do that. Some multi-value types can be represented by arrays like TEXT[] or JSONB columns. If we’re talking about whole new multi-value container, whoa-whoa…​ that’s out of scope of this humble instruction sheet!

If the type is previously unused enum, we’ve got just a bit more work to do. First we need to add CREATE TYPE for it to the schema. Find the section with custom types, read its intro comment and add the enum specification. Very likely it will be "schema enum", not specialized repository internal enum - that’s typical. Use the class name for the custom type to make things as obvious as possible, so it’s AdministrativeAvailabilityStatusType for our case. Copy/paste the values to avoid any mistake…​ other than copy/paste error, that is.

Let’s change the "M-class", MResource in our example. Simply add public field for the column, like public AdministrativeAvailabilityStatusType administrativeOperationalStateAdministrativeAvailabilityStatus. Keep the order consistent with the table. BTW, "M" does not stand for "mapping", we will see mapping class later.

Now it’s great time to update SqaleRepoAddDeleteObjectTest! Find the method testing mapping for this class and add value and assert for the new item. Feel free to add the method if this entity/object type is not yet tested - just like I did in another example. Run the test, it should fail for the new attribute, which is a good sign.

We need to declare the new column in a "Q-class" which extends from Querydsl type hierarchy. Technically it’s mapping for Querydsl, but it’s still not "our" mapping for midPoint (soon, I promise!). For our example, it’s QResource - and there are two sections:

Now it’s time to add the insert code. Finally, we’re getting to the "mapping class" - QResourceMapping in our case. Locate toRowObjectWithoutFullObject and add something like this there:

row.xxx = node.getXxx();

var administrativeOperationalState = schemaObject.getAdministrativeOperationalState();
if (administrativeOperationalState != null) {
  row.administrativeOperationalStateAdministrativeAvailabilityStatus =
    administrativeOperationalState.getAdministrativeAvailabilityStatus();
}

Nearly there! We still need one more thing to support searching and modifications too. Go to the constructor of the mapping class (QResourceMapping for us) and add (respecting the right order again, of course!) something like this:

addItemMapping(F_XXX, enumMapper(q -> q.xxx));

addNestedMapping(F_ADMINISTRATIVE_OPERATIONAL_STATE, AdministrativeOperationalStateType.class)
  .addItemMapping(AdministrativeOperationalStateType.F_ADMINISTRATIVE_AVAILABILITY_STATUS,
    enumMapper(q -> q.administrativeOperationalStateAdministrativeAvailabilityStatus));

Write the search test.

And SQL alter script, of course! We need to prepare SQL command for upgrade script postgres-new-upgrade.sql. Prepare the right ALTER command and test it on an existing database without the change. Wrap the change inside apply_change call - use the examples already available in the file. Don’t forget to bump the change identifier for each chagne. Revert the change and test it again by calling the apply_change procedure from the upgrade script. Check that the change was applied and also that subsequent call skips the change.

Update the last indicated change in the main SQL scipt! This is the last line in postgres-new.sql saying call apply_change…​. The number here should match the last used change identifier in the upgrade script. This is important to avoid applying any change more than once.

New persisted object type must be declared. Add the new value MESSAGE_TEMPLATE to the ObjectType enum in both postgres-new.sql and postgres-new-upgrade-audit.sql. This value will be later added in the MObjectType Java enum, but that requires some other classes we don’t have yet.

Also, prepare and test upgrade command to the same effect just above the bottom comment in both postgres-new-upgrade.sql and postgres-new-upgrade-audit.sql. Adding the type value in both files is critical for cases when audit is used in a separate schema/database. We will wrap this inside apply_change (or apply_audit_change for audit SQL) so it is executed only if not applied yet. We will write it in an idempotent fashion (IF NOT EXISTS), not only because we can and it is more flexible, but because, again, it is critical, this time for cases when audit and main repo share the same database and both upgrade scripts are run for the same schema:

-- MID-7484, always add some relevant comment or a related issue
-- We add the new enum value in separate change, because it must be committed before it is used.
call apply_change(2, $aa$
ALTER TYPE ObjectType ADD VALUE IF NOT EXISTS 'MESSAGE_TEMPLATE' AFTER 'LOOKUP_TABLE';
$aa$);

Continue with the table definition in postgres-new.sql. Again, this one is very simple, we can copy/paste and carefully modify existing simple tables like m_dashboard for instance. Use search to be sure all m_dashboard strings are replaced with m_message_template as appropriate, especially for the trigger and index names. Replace the object type values in the objectType column definition.

Add the same creation statements in the upgrade script postgres-new-upgrade.sql just after the ALTER from the previous step. You can use a single apply_change block for it, unless commit is required after any of the statements. As always, use a new change number (first parameter) for each change.

After all changes in SQL upgrade files, update the last lines in the main and audit SQL files containing the call apply_[audit_]change calls - just repeat the last change number there. Be careful not to mix the numbers between the main and audit SQL scripts.

Now it’s time to add the mapping Java classes to the native repository module repo-sqale. For a minimal mapping example see the classes in the package named com.evolveum.midpoint.repo.sqale.qmodel.node. Typically, three classes are needed:

With the Java mapping classes ready, we can add the value inside MObjectType. Respectfully, we will conform to the alphabetical order and add the following code after the lookup table line:

MESSAGE_TEMPLATE(QMessageTemplate.class, MessageTemplateType.class),

New mapping for object must be also registered in SqaleRepositoryBeanConfig.sqlRepoContext() method. Find the right place (again, typically alphabetically) and add the following line:

.register(MessageTemplateType.COMPLEX_TYPE, QMessageTemplateMapping.init(repositoryContext))

Finally, we will add a simple add (insert) test for the class. This proves that the midPoint can add objects of this type. Because there are no columns specific to this type, we simply test that the row is added, as we presume we can trust the existing code handling the super-type columns (already tested). In more interesting cases you may also add a search test into SqaleRepoSearchTest, etc.