Realm Modifications Reference

The following tables describe the ways in which you can modify the realm definition, and the deployment consequences of each modification.

The details in these tables determine the validity of a deployment (see Responses to Deployment Tests).

Realm Property Modifications

Modification Details
Modify realm properties You can modify any realm property.

If you modify the realm property Dynamic Message Formats, then some clients could require restart. In particular, if the modification changes an application’s effective value of this parameter, then all instances of that application require restart.

Application Definition Modifications

Modification Details
Add applications You can add a new application definition.
Delete applications You can delete an application definition from the realm definition. All client instances of that application implicitly become invalid (though they continue to run). You must explicitly stop or disable those client processes (see Conditions for Disabling Clients).
Add endpoints You can add new endpoints to an application definition.
Delete endpoints You can delete an endpoint from an application definition, but only if the client does not have any publishers or subscribers on the endpoint.

If a client has publisher or subscriber objects on that endpoint, then the application throws a protocol exception.

Add transports to endpoints You can add a transport to implement an existing endpoint in an application instance. Upon deployment, existing process instances immediately bind the new transport to implement the endpoint, and attempt to establish a bus.
Delete transports from endpoints You can delete a transport from an endpoint (in an application instance). Client processes immediately stop using that transport to implement that endpoint:
  • Send to inbox calls raise an exception (when the inbox is no longer accessible).
  • Send one-to-many calls return normally, but the deleted transport does not carry messages. (If the send ability still has other operating transports, then they continue to carry messages. Otherwise the endpoint silently discards messages.)
  • Subscribers silently stop delivering messages from the deleted transport.
Enable or disable abilities You can enable or disable transport abilities of an endpoint in an application instance.

Communications on the endpoint immediately expand to use the additional ability.

A disabled ability immediately stops carrying messages:

  • Send to inbox calls raise an exception (when the inbox is no longer accessible).
  • Send one-to-many calls return normally, but the transport’s send ability does not carry messages. (The endpoint silently discards messages.)
  • The transport’s receive and receive inbox abilities silently stop delivering messages.
Manage All Formats If you modify the application parameter Message Formats Administration, then clients could require restart. In particular, if the modification changes an application’s effective value of this parameter, then all instances of that application require restart.

Transport Modifications

Modification Details
Add transports You can add new transports to an application definition.
Delete transports You can delete an existing transport definition. Client processes immediately stop using the bus on the affected transport:
  • Send to inbox calls raise an exception (when the inbox is no longer accessible).
  • Send one-to-many calls return normally, but the deleted transport does not carry messages. (If an endpoint still has other operating transports, then they continue to carry messages. Otherwise the endpoint silently discards messages.)
  • Subscribers silently stop delivering messages from the deleted transport.
Modify transport parameters You can modify the parameter values of a transport. If an application instance binds an affected transport, then it requires restart.

Format Modifications

Modification Details
Add formats You can add a new managed format to an application definition.

You can also upgrade a dynamic format to a managed format, in order to gain efficiency. When upgrading, the managed format must exactly match the existing dynamic format (that is, format name, field names, and field types). However, the managed format may also include additional fields that are not in the existing dynamic format.

For a client to use a new managed format, you must also add that format to the application’s preload formats list.

Add preload format You can add preload formats to an application definition.
Add fields You can add fields to an existing format definition.

Add fields only to the end of an existing format (that is, after all its existing fields).

  • Conforming to this rule facilitates graceful migration of client processes from the old format definition to its new definition.
  • Violating this rule is disadvantageous. All clients that use the format require restart, and they all must restart in synchrony. Clients that use one version of the format definition cannot recognize messages that use another version, so they silently discard them.
Delete fields You can delete a field from an existing format definition. All clients that use the format require restart, and they all must restart in synchrony.

Clients can recognize older format versions only if they received those versions during their initial preload from the FTL server. Clients silently discard messages with unrecognized formats.

Persistence Modifications: Store and Durable

Modification Details
Add or delete persistence clusters You can add, rename, or delete a persistence cluster.

You cannot delete a cluster definition while any of its persistence services are running.

Renaming a cluster is equivalent to deleting and re-adding the cluster definition.

Add or delete persistence stores You can add, rename, or delete a persistence store.

Deleting a store discards all messages in the store.

Renaming a store is like deleting it and creating a new, empty store.

Before deleting or renaming a store, you must first review every application definition in the realm, ensuring that none of the endpoints still refer to the store you plan to delete.

After deleting or renaming a store, all the persistence services in the cluster require restart.
  1. Use the FTL server interface to stop one persistence service. The FTL server will automatically restart that persistence service.
  2. Wait for the new persistence service to synchronize with the existing services.
  3. Repeat for each persistence service in the cluster.
Add or delete durables You can add durables to a store, or delete durables from a store.

(When deleting a static durable from a store, you must also remove subscriber name mappings to that durable.)

Modify store or durable parameters You can modify parameter values of stores and durables.

When modifying the publisher mode of a store, or the acknowledgment mode of a durable, all affected clients disconnect from the cluster (that is, the leader) and automatically reconnect.

From the moment that a subscriber object first interacts with a durable, you may no longer change a durable’s message interest, nor its matcher fields. If these configuration values must subsequently change, you can instead map the subscriber to a new durable with the correct message interest and matcher fields.

Modify the mapping from subscriber names to durables You can modify the mapping from subscriber names to static durable names for an endpoint.
Add dynamic durable templates You can add dynamic durable templates and associate endpoints with the new templates.
Modify or delete dynamic durable templates You can modify or delete dynamic durable templates. You can associate an endpoint with a different dynamic durable template. All clients that have durable subscribers on an affected endpoint require restart.
Add or delete persistence services You can add a persistence service. You can delete or rename a persistence service only if none of the services in the cluster are running.

Changes to persistence services in the realm definition usually entail parallel changes in the FTL server configuration file. Restart the FTL server to read its updated configuration file.

When adding a service, assign it a low weight, so that it does not immediately become the leader. You can raise its weight later, after it replicates the cluster’s message data.

While reforming a quorum the cluster temporarily becomes unavailable. Ensure that adding or deleting a persistence service does not prevent forming a quorum.

Modify cluster transport parameters of a persistence service It is illegal to modify cluster transports of persistence services.
Modify client transport parameters of a persistence service You can modify client transports of persistence services.
When modifying a primary client transport or any of its parameters, that persistence service and all its clients require restart.
  1. Stop the persistence service. The FTL server automatically restarts it.
  2. Wait for the restarted service to synchronize its data state with the remaining services.
  3. Restart all the clients of the restarted service.
  4. Repeat for each persistence service in the cluster for which you have modified a client transport.
Modify alternate client transport parameters of a persistence service You can modify alternate client transports of persistence services.

Adding an alternate client transport that was not previously configured does not require restart. Clients can connect using that transport immediately following successful deployment.

Deleting an alternate client transport does not require restart. Clients cannot connect nor reconnect using the deleted transport. However, existing clients can remain connected on the deleted transport.

Modifying the transport parameters of an alternate client transport requires restart of the persistence service and the clients that connect using the modified transport.
  1. Stop the persistence service. The FTL server automatically restarts it.
  2. Wait for the restarted service to synchronize its data state with the remaining services.
  3. Restart all the clients of the restarted service.
  4. Repeat for each persistence service in the cluster for which you have modified a client transport.
You can add and delete associated client host names. The persistence service does not require restart. Clients on added hosts can connect using the alternate client transport immediately following successful deployment. A client on a deleted host remains connected until the client restarts. For example:
  • If the alternate client transport already names host1 and you add host2, then upon deployment clients on host2 can connect using the alternate client transport.
  • If the alternate client transport names host1 and host3, and you delete host3, then upon deployment clients on host3 remain connected using the alternate client transport. However, a client on host3 that stops and subsequently restarts can no longer connect using the alternate client transport.
Related concepts
Related reference