Strolch: Realms

Realms implement multi-tenant capabilities. A Strolch agent can have an arbitrary number of realms configured and each realm has its own persistence configuration, allowing to separate mandates completely.

A realm can run in one of the following modes:

EMPTY
This is a transient data store mode, where no model changes are persisted - they are only kept in memory. When the Strolch agent is started, this realm is empty as no data is loaded.
TRANSIENT
This is the same as EMPTY, but with the difference that when the Strolch agent is started, a model file is parsed and the in-memory realm is populated with the elements parsed from the model file.
CACHED
In this mode, all data is stored in-memory, and any changes made are written back to the persistence layer. This allows for fast in-memory qeuries, but makes sure no data is lost when the agent is restarted.

Realms are mostly hidden from a developer as a StrolchTransaction exposes all important operations needed to access Strolch objects. A developer will however need to configure the realms for their specific project. If the project only requires one realm, then the defaultRealm can be used, where the developer only is required to configure the mode and any relevant model file.

If the mode is CACHED, then the PersistenceHandler component is required to be configured, so that the DAOs know how to access the underlying database.

The configuration in the StrolchConfiguration.xml file is as follows:

<StrolchConfiguration>
  <env id="dev">
    ...
    <Component>
      <name>RealmHandler</name>
      <api>li.strolch.agent.api.RealmHandler</api>
      <impl>li.strolch.agent.impl.DefaultRealmHandler</impl>
      <depends>PrivilegeHandler</depends>
      <!-- if CACHED: -->
      <!--depends>PersistenceHandler</depends-->
      <Properties>
        <dataStoreMode>EMPTY|TRANSIENT|CACHED</dataStoreMode>
        <dataStoreFile>StrolchModel.xml</dataStoreFile>
      </Properties>
    </Component>
    ...
  </env>
</StrolchConfiguration>

A multi-realm configuration would be as follows. Note how the defaultRealm is still enabled, and has its configuration as before. Further the PostgreSQL PersistenceHandler is configured to show how the realms are connected to the persistence handler:

<StrolchConfiguration>
  <env id="dev">
    ...
    <Component>
      <name>RealmHandler</name>
      <api>li.strolch.agent.api.RealmHandler</api>
      <impl>li.strolch.agent.impl.DefaultRealmHandler</impl>
      <depends>PrivilegeHandler</depends>
      <depends>PersistenceHandler</depends>
      <Properties>
        <realms>defaultRealm, cachedRealm</realms>
        <dataStoreMode>TRANSIENT</dataStoreMode>
        <dataStoreFile>DefaultRealm.xml</dataStoreFile>
        <dataStoreMode.cachedRealm>CACHED</dataStoreMode.cachedRealm>
        <dataStoreMode.emptyRealm>EMPTY</dataStoreMode.emptyRealm>
      </Properties>
    </Component>

    <Component>
      <name>PersistenceHandler</name>
      <api>li.strolch.persistence.api.PersistenceHandler</api>
      <impl>li.strolch.persistence.postgresql.PostgreSqlPersistenceHandler</impl>
      <Properties>
        <allowSchemaCreation>true</allowSchemaCreation>
        <allowSchemaDrop>true</allowSchemaDrop>

        <db.url.cachedRealm>jdbc:postgresql://localhost/testdb2</db.url.cachedRealm>
        <db.username.cachedRealm>testuser2</db.username.cachedRealm>
        <db.password.cachedRealm>test</db.password.cachedRealm>
        <db.pool.maximumPoolSize.cachedRealm>1</db.pool.maximumPoolSize.cachedRealm>
      </Properties>
    </Component>
    ...
  </env>
</StrolchConfiguration>

Accessing a realm is done in multiple ways. Important is to note, that a user should use the StrolchTransaction object, instead of accessing the Realm directly.

Opening a transaction is done from a Service by calling one of the openTx()-methods. Nevertheless, the realm can be accessed as follows:

ComponentContainer container = getAgent().getContainer();
StrolchRealm realm = container.getRealm(StrolchConstants.DEFAULT_REALM);
try(StrolchTransaction tx = realm.openTx()) {
  Resource resource = tx.getResourceBy("TestType", "MyTestResource");
  ...
}

Documentation: Realms