# Configuration Reload

The system will perform a periodic check on the configuration files, configured
by `configuration-file-refresh-period`, with the default at 5000, in
milliseconds.

Once the configuration file is changed (broker.xml) the following modules will
be reloaded automatically:

- Address Settings
- Security Settings
- Diverts
- Addresses & queues


**Note:**

Deletion of Address's and Queue's, not auto created is controlled by Address Settings

* config-delete-addresses
   * OFF (DEFAULT) - will not remove upon config reload.
   * FORCE - will remove the address and its queues upon config reload, even if messages remains, losing the messages in the address & queues.

* config-delete-queues
   * OFF (DEFAULT) - will not remove upon config reload.
   * FORCE - will remove the queue upon config reload, even if messages remains, losing the messages in the queue.


By default both settings are OFF as such address & queues won't be removed upon
reload, given the risk of losing messages.

When OFF You may execute explicit CLI or Management operations to remove
address & queues.

## Reloadable Parameters

The broker configuration file has 2 main parts, `<core>` and `<jms>`. Some of
the parameters in the 2 parts are monitored and, if modified, reloaded into the
broker at runtime.

**Note:** Elements under `<jms>` are **deprecated**. Users are encouraged to
use `<core>` configuration entities.

> **Note:**
>
> Most parameters reloaded take effect immediately after reloading. However
> there are some that won’t take any effect unless you restarting the broker.
> Such parameters are specifically indicated in the following text.

### `<core>`

#### `<security-settings>`

* `<security-setting>` element

Changes to any `<security-setting>` elements will be reloaded. Each
`<security-setting>` defines security roles for a matched address.

* The `match` attribute

  This attribute defines the address for which the security-setting is
  defined. It can take wildcards such as ‘#’ and ‘*’.

* The `<permission>` sub-elements

Each `<security-setting>` can have a list of `<permission>` elements, each
of which defines a specific permission-roles mapping.  Each permission has 2
attributes ‘type’ and ‘roles’. The ‘type’ attribute defines the type of
operation allowed, the ‘roles’ defines which roles are allowed to perform such
operation. Refer to the user’s manual for a list of operations that can be
defined.

> **Note:**
>
> Once loaded the security-settings will take effect immediately. Any new
> clients will subject to the new security settings. Any existing clients will
> subject to the new settings as well, as soon as they performs a new
> security-sensitive operation.

Below lists the effects of adding, deleting and updating of an
element/attribute within the `<security-settings>` element, whether a change
can be done or can’t be done.

Operation | Add | Delete | Update
---|---|---|---
`<security-settings>` | X* (at most one element is allowed) | Deleting it means delete the whole security settings from the running broker. | N/A*
`<security-setting>` | Adding one element means adding a new set of security roles for an address in the running broker | Deleting one element means removing a set of security roles for an address in the running broker | Updating one element means updating the security roles for an address (if match attribute is not changed), or means removing the old match address settings and adding a new one (if match attribute is changed)
attribute `match` | N/A* | X* | Changing this value is same as deleting the whole <security-setting> with the old match value and adding
`<permission>` | Adding one means adding  a new permission definition to runtime broker | Deleting a permission from the runtime broker | Updating a permission-roles in the runtime broker
attribute `type` | N/A* | X* | Changing the type value means remove the permission of the old one and add the permission of this type to the running broker.
attribute `roles` | N/A* | X* | Changing the ‘roles’ value means updating the permission’s allowed roles to the running broker

> * `N/A` means this operation is not applicable.
> * `X` means this operation is not allowed.

#### `<address-settings>`

* `<address-settings>` element

Changes to elements under `<address-settings>` will be reloaded into runtime
broker. It contains a list of `<address-setting>` elements.

   * `<address-setting>` element

   Each address-setting element has a ‘match’ attribute that defines an address
   pattern for which this address-setting is defined. It also has a list of
   sub-elements used to define the properties of a matching address.

   > **Note:** 
   >
   > Parameters reloaded in this category will take effect immediately
   > after reloading. The effect of deletion of Address's and Queue's, not auto
   > created is controlled by parameter `config-delete-addresses` and
   > `config-delete-queues` as described in the doc.

Below lists the effects of adding, deleting and updating of an
element/attribute within the address-settings element, whether a change can be
done or can’t be done.

Operation | Add | Delete | Update
---|---|---|---
`<address-settings>` | X(at most one element is allowed) | Deleting it means delete the whole address settings from the running broker | N/A
`<address-setting>` | Adding one element means adding a set of address-setting for a new address in the running broker | Deleting one  means removing a set of address-setting for an address in the running broker | Updating one element means updating the address setting for an address (if match attribute is not changed), or means removing the old match address settings and adding a new one (if match attribute is changed)
attribute `match` | N/A | X | Changing this value is same as deleting the whole <address-setting> with the old match value and adding a new one with the new match value.
`<dead-letter-address>` | X (no more than one can be present) | Removing the configured dead-letter-address address from running broker. | The dead letter address of the matching address will be updated after reloading
`<expiry-address>` | X (no more than one can be present) | Removing the configured expiry address from running broker. | The expiry address of the matching address will be updated after reloading
`<expiry-delay>` | X (no more than one can be present) | The configured expiry-delay will be removed from running broker. | The expiry-delay for the matching address will be updated after reloading.
`<redelivery-delay>` | X (no more than one can be present) | The configured redelivery-delay will be removed from running broker after reloading | The redelivery-delay for the matchin address will be updated after reloading.
`<redelivery-delay-multiplier>` | X (no more than one can be present) | The configured redelivery-delay-multiplier will be removed from running broker after reloading. | The redelivery-delay-multiplier will be updated after reloading.
`<max-redelivery-delay>` |  X (no more than one can be present) | The configured max-redelivery-delay will be removed from running broker after reloading. | The max-redelivery-delay will be updated after reloading.
`<max-delivery-attempts>` | X (no more than one can be present) | The configured max-delivery-attempts will be removed from running broker after reloading. | The max-delivery-attempts will be updated after reloading.
`<max-size-bytes>` | X (no more than one can be present) | The configured max-size-bytes will be removed from running broker after reloading. | The max-size-bytes will be updated after reloading.
`<page-size-bytes>` | X (no more than one can be present) | The configured page-size-bytes will be removed from running broker after reloading. | The page-size-bytes will be updated after reloading.
`<page-max-cache-size>` | X (no more than one can be present) | The configured page-max-cache-size will be removed from running broker after reloading. | The page-max-cache-size will be updated after reloading.
`<address-full-policy>` | X (no more than one can be present) | The configured address-full-policy will be removed from running broker after reloading. | The address-full-policy will be updated after reloading.
`<message-counter-history-day-limit>` | X (no more than one can be present) | The configured message-counter-history-day-limit will be removed from running broker after reloading. | The message-counter-history-day-limit will be updated after reloading.
`<last-value-queue>` | X (no more than one can be present) | The configured last-value-queue will be removed from running broker after reloading (no longer a last value queue). | The last-value-queue will be updated after reloading.
`<redistribution-delay>` | X (no more than one can be present) | The configured redistribution-delay will be removed from running broker after reloading. | The redistribution-delay will be updated after reloading.
`<send-to-dla-on-no-route>` | X (no more than one can be present) | The configured send-to-dla-on-no-route will be removed from running broker after reloading. | The send-to-dla-on-no-route will be updated after reloading.
`<slow-consumer-threshold>` | X (no more than one can be present) | The configured slow-consumer-threshold will be removed from running broker after reloading. | The slow-consumer-threshold will be updated after reloading.
`<slow-consumer-policy>` | X (no more than one can be present) | The configured slow-consumer-policy will be removed from running broker after reloading. | The slow-consumer-policy will be updated after reloading.
`<slow-consumer-check-period>` | X (no more than one can be present) | The configured slow-consumer-check-period will be removed from running broker after reloading. (meaning the slow consumer checker thread will be cancelled) | The slow-consumer-check-period will be updated after reloading.
`<auto-create-queues>` | X (no more than one can be present) | The configured auto-create-queues will be removed from running broker after reloading. | The auto-create-queues will be updated after reloading.
`<auto-delete-queues>` | X (no more than one can be present) | The configured auto-delete-queues will be removed from running broker after reloading. | The auto-delete-queues will be updated after reloading.
`<config-delete-queues>` | X (no more than one can be present) | The configured config-delete-queues will be removed from running broker after reloading. | The config-delete-queues will be updated after reloading.
`<auto-create-addresses>` | X (no more than one can be present) | The configured auto-create-addresses will be removed from running broker after reloading. | The auto-create-addresses will be updated after reloading.
`<auto-delete-addresses>` | X (no more than one can be present) | The configured auto-delete-addresses will be removed from running broker after reloading. | The auto-delete-addresses will be updated after reloading.
`<config-delete-addresses>` | X (no more than one can be present) | The configured config-delete-addresses will be removed from running broker after reloading. | The config-delete-addresses will be updated after reloading.
`<management-browse-page-size>` | X (no more than one can be present) | The configured management-browse-page-size will be removed from running broker after reloading. | The management-browse-page-size will be updated after reloading.
`<default-purge-on-no-consumers>` | X (no more than one can be present) | The configured default-purge-on-no-consumers will be removed from running broker after reloading. | The default-purge-on-no-consumers will be updated after reloading.
`<default-max-consumers>` | X (no more than one can be present) | The configured default-max-consumers will be removed from running broker after reloading. | The default-max-consumers will be updated after reloading.
`<default-queue-routing-type>` | X (no more than one can be present) | The configured default-queue-routing-type will be removed from running broker after reloading. | The default-queue-routing-type will be updated after reloading.
`<default-address-routing-type>` | X (no more than one can be present) | The configured default-address-routing-type will be removed from running broker after reloading. | The default-address-routing-type will be updated after reloading.


#### `<diverts>`

All `<divert>` elements will be reloaded. Each `<divert>` element has a ‘name’
and several sub-elements that defines the properties of a divert.

> **Note:**
>
> Reloading `<diverts>` only resulting in deploying new diverts. Existing diverts
> won’t get undeployed even if you delete a `<divert>` element. Nor an existing
> divert will be updated if its element is updated after reloading.  To make
> this happen you need a restart of the broker.

Below lists the effects of adding, deleting and updating of an
element/attribute within the diverts element, whether a change can be done or
can’t be done.

Operation | Add | Delete | Update
---|---|---|---
`<diverts>` | X (no more than one can be present) | Deleting it means delete  (undeploy) all diverts in running broker. | N/A
`<divert>` | Adding a new divert. It will be deployed after reloading | No effect on the deployed divert.(unless restarting broker, in which case the divert will no longer be deployed) | No effect on the deployed divert (unless restarting broker, in which case the divert will be redeployed)
attribute `name` | N/A | X | A new divert with the name will be deployed. (if it is not already there in broker). Otherwise no effect.
`<transformer-class-name>` | X (no more than one can be present) | No effect on the deployed divert.(unless restarting broker, in which case the divert will be deployed without the transformer class) | No effect on the deployed divert.(unless restarting broker, in which case the divert has the transformer class)
`<exclusive>` | X (no more than one can be present) | No effect on the deployed divert.(unless restarting broker) | No effect on the deployed divert.(unless restarting broker)
`<routing-name>` | X (no more than one can be present) | No effect on the deployed divert.(unless restarting broker) | No effect on the deployed divert.(unless restarting broker)
`<address>` | X (no more than one can be present) | No effect on the deployed divert.(unless restarting broker) | No effect on the deployed divert.(unless restarting broker)
`<forwarding-address>` | X (no more than one can be present) | No effect on the deployed divert.(unless restarting broker) | No effect on the deployed divert.(unless restarting broker)
`<filter>` | X (no more than one can be present) | No effect on the deployed divert.(unless restarting broker) | No effect on the deployed divert.(unless restarting broker)
`<routing-type>` | X (no more than one can be present) | No effect on the deployed divert.(unless restarting broker) | No effect on the deployed divert.(unless restarting broker)

#### `<addresses>`

The `<addresses>` element contains a list `<address>` elements. Once changed,
all `<address>` elements in `<addresses>` will be reloaded.

> **Note:**
>
> Once reloaded, all new addresses (as well as the pre-configured queues) will
> be deployed to the running broker and all those that are missing from the
> configuration will be undeployed.

> **Note:**
>
> Parameters reloaded in this category will take effect immediately after
> reloading.  The effect of deletion of Address's and Queue's, not auto created
> is controlled by parameter `config-delete-addresses` and
> `config-delete-queues` as described in this doc.

Below lists the effects of adding, deleting and updating of an
element/attribute within the `<addresses>` element, whether a change can be
done or can’t be done.

Operation | Add | Delete | Update
---|---|---|---
`<addresses>` | X(no more than one is present) | Deleting it means delete  (undeploy) all diverts in running broker. | N/A
`<address>` | A new address will be deployed in the running broker | The corresponding address will be undeployed. | N/A
attribute `name` | N/A | X | After reloading the address of the old name will be undeployed and the new will be deployed.
`<anycast>` | X(no more than one is present) | The anycast routing type will be undeployed from this address, as well as its containing queues after reloading | N/A
`<queue>`(under `<anycast>`) | An anycast queue will be deployed after reloading | The anycast queue will be undeployed | For updating queues please see next section `<queues>`
`<multicast>` | X(no more than one is present) | The multicast routing type will be undeployed from this address, as well as its containing queues after reloading | N/A
`<queue>`(under `<multicast>`) | A multicast queue will be deployed after reloading | The multicast queue will be undeployed | For updating queues please see next section `<queues>`

#### `<queues>`

The `<queues>` element contains a list `<queue>` elements. Once changed, all
`<queue>` elements in `<queues>` will be reloaded.

> **Note:**
>
> Once reloaded, all new queues will be deployed to the running broker and all
> queues that are missing from the configuration will be undeployed.

> **Note:**
>
> Parameters reloaded in this category will take effect immediately after
> reloading.  The effect of deletion of Address's and Queue's, not auto created
> is controlled by parameter `config-delete-addresses` and
> `config-delete-queues` as described in this doc.

Below lists the effects of adding, deleting and updating of an
element/attribute within the `<queues>` element, and whether a change can be
done or can’t be done.

Operation | Add | Delete | Update
---|---|---|---
`<queues>` | X(no more than one is present) | Deleting it means delete  (undeploy) all queues from running broker. | N/A
`<queue>` | A new queue is deployed after reloading | The queue will be undeployed after reloading. | N/A
attribute `name` | N/A | X | A queue with new name will be deployed and the queue with old name will be updeployed after reloading (see Note above).
attribute `max-consumers` | If max-consumers > current consumers max-consumers will update on reload | max-consumers will be set back to the default `-1` | If max-consumers > current consumers max-consumers will update on reload
attribute `purge-on-no-consumers` | On reload purge-on-no-consumers will be updated | Will be set back to the default `false` | On reload purge-on-no-consumers will be updated
attribute `address` | N/A | No effect unless starting broker | No effect unless starting broker
attribute `filter` | N/A | No effect unless starting broker | No effect unless starting broker
attribute `durable` | N/A | No effect unless starting broker | No effect unless starting broker

### `<jms>` *(Deprecated)*

#### `<queue>`

Changes to any `<queue>` elements will be reloaded to the running broker.

> **Note:**
>
> Once reloaded, new queues defined in the new changes will be deployed to the
> running broker. However existing queues won’t get undeployed even if the
> matching element is deleted/missing. Also new queue elements matching
> existing queues won’t get re-created – they remain unchanged.

Operation | Add | Delete | Update
---|---|---|---
`<queue>` | A new jms queue will be deployed after reloading | No effect unless starting broker | No effect unless starting broker
attribute `<name>` | N/A | X | A jms queue of the new name will be deployed after reloading
`<selector>` | X(no more than one is present) | No effect unless starting broker | No effect unless starting broker
`<durable>` | X(no more than one is present) | No effect unless starting broker | No effect unless starting broker

#### `<topic>`

Changes to any `<topic>` elements will be reloaded to the running broker.

> **Note:**
>
> Once reloaded, new topics defined in the new changes will be deployed to the
> running broker. However existing topics won’t get undeployed even if the
> matching element is deleted/missing. Also any `<topic>` elements matching
> existing topics won’t get re-deployed – they remain unchanged.

Operation | Add | Delete | Update
---|---|---|---
`<topic>` | A new jms topic will be deployed after reloading | No effect unless starting broker | No effect unless starting broker
attribute `name` | N/A | X | A jms topic of the new name will be deployed after reloading