Valid 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. Some transports require the application process to restart (in order to establish their 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 realm 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 servers 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.

When deleting or renaming a store, all the persistence server processes in the cluster require restart. You must first stop all the servers, then restart all servers (note that this resets the cluster’s data state to empty).

To avoid data reset, you can delete all the durables from a store, instead of deleting the store itself. (You can delete the store later, at a time when data reset is acceptable.)

Before deleting 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.

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. All clients that have durable subscribers on that endpoint require restart.
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 servers You can add a persistence server. You can delete or rename a persistence server only if none of the servers in the cluster are running.

When adding a server, 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 server does not prevent forming a quorum.

Modify cluster transport parameters of a persistence server You can modify cluster transports of persistence servers.

When modifying even one cluster transport or any of its parameters, all persistence servers require restart. You must first stop all servers, then restart all servers (note that this resets the cluster’s data state to empty).

Modify client transport parameters of a persistence server You can modify client transports of persistence servers.

When modifying a primary client transport or any of its parameters, that persistence server and all its clients require restart. If you modify the client transports of several servers, stop and restart them one at a time, so that the cluster retains its data state.

Modify alternate client transport parameters of a persistence server You can modify alternate client transports of persistence servers.

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 server and the clients that connect using the modified transport.

You can add and delete associated client host names. The persistence server 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