{section}
{column}
h1. Introduction
When a topology is declared as [dynamic|Topology Configuration], several operating tasks can be done to modify the topology:
* move a running container from a domain to another domain,
* detach a running container from its current domain.
When a topology is declared as [static|Topology Configuration], the topology can't be modified, but can be deleted from the registry cluster for administrative reasons.
{column}
{column:width=350px}
{panel:title=Operating Topologies}{toc}{panel}
{panel:title=Contributors}{contributors:order=name|mode=list}{panel}
{column}
{section}
h1. Dynamic Topologies
h2. Moving a container
Both a container of an autonomous topology and a container member of a more complex topology can be attached to another existing topology (aka domain).
{gliffy:name=Moving a container standalone|align=center|border=false|version=7}
The attachment is realized through the JMX API (or [Petals CLI|petalsclisnapshot:Petals ESB CLI 3.3.0-SNAPSHOT]) of the container to move using the method '{{attachContainerTo}}' of the MBean '{{Topology}}' with the following parameters:
* a container member of the target domain,
* the topology pass-phrase of this remote container.
During the attachment process, the container attached is reconfigured to use the registry of the target domain. After the attachment, the endpoints of the container moved are available in the target topology, and not in the initial topology anymore.
h2. Detaching a container
Any container member of a dynamic domain can be hot-detached at any moment. After detachment, the container is running in a dedicated standalone topology, i.e., in a dedicated domain.
{gliffy:name=Detaching a container|align=center|border=false|version=6}
The detachment is realized through the JMX API (or [Petals CLI|petalsclisnapshot:Petals ESB CLI 3.3.0-SNAPSHOT]) of the container to detach using the method '{{detachContainer}}' of the MBean '{{Topology}}'.
After the detachment, the endpoints of the container are not available in the initial topology anymore and are moved to the new one.
h2. Empty Topologies
When all container of a dynamic domain are detached from it, then the topology is empty.
In that case, the empty topology is automatically removed from the registry cluster.
h1. Static Topologies
By definition, static topologies can't be modified once registered in a registry cluster the first time.
But for administrative reasons, it can be desired to clean a topology by deleting it from the registry cluster.
This can be done using the command '{{delete-topology}}' of [Petals Registry CLI|petalsregclisnapshot:Petals Registry CLI 1.3.0-SNAPSHOT]).
h1. Appendix: under the hood
h2. Topology storage
At runtime, the topologies are in practice stored on the registry.
The containers store them there, read them from there, and potentially modify them, which notify the other containers of the topology of the modification.
This is how dynamic topologies are implemented for example.
h2. Standalone container
A container that is alone in its static topology is a standalone container.
It uses a specific in-memory implementation of the registry client which works without an actual running registry.
It can still leave it to join another dynamic topology, see below.
h2. Starting a new topology
When the first container of a topology is started, the topology is not yet stored on the registry, the following thus happens:
- the container reads its own {{topology.xml}} file, and extract the registry information from it,
- it connects to the registry and registers there the topology.
When the other containers of the topology are started, the following happens:
- the container reads its own {{topology.xml}} file, and extract the registry information from it,
- it connects to the registry and read there the topology,
- it ensures it is coherent with its own {{topology.xml}} file to prevent misconfigurations,
- from there on, it uses the data in the topology stored on the registry only.
h2. Joining a topology
When a container joins a topology, it is already in another topology, and the following happens:
- it retrieves the remote topology from another container belonging to it,
- it validates that it can leave its current topology (i.e, if it's dynamic) and join the new one (i.e., if it's dynamic or static but belongs to it),
- it pauses endpoint resolution: no new exchange will be sent by this container,
- it leaves its current topology (other containers of the topology will be notified by the registry): no new exchanges will be received by this container,
- it waits for exchanges to finish being processed,
- it joins the new topology (other containers of the topology will be notified by the registry),
- it registers its endpoints their and exchanges communications are re-established.
{column}
h1. Introduction
When a topology is declared as [dynamic|Topology Configuration], several operating tasks can be done to modify the topology:
* move a running container from a domain to another domain,
* detach a running container from its current domain.
When a topology is declared as [static|Topology Configuration], the topology can't be modified, but can be deleted from the registry cluster for administrative reasons.
{column}
{column:width=350px}
{panel:title=Operating Topologies}{toc}{panel}
{panel:title=Contributors}{contributors:order=name|mode=list}{panel}
{column}
{section}
h1. Dynamic Topologies
h2. Moving a container
Both a container of an autonomous topology and a container member of a more complex topology can be attached to another existing topology (aka domain).
{gliffy:name=Moving a container standalone|align=center|border=false|version=7}
The attachment is realized through the JMX API (or [Petals CLI|petalsclisnapshot:Petals ESB CLI 3.3.0-SNAPSHOT]) of the container to move using the method '{{attachContainerTo}}' of the MBean '{{Topology}}' with the following parameters:
* a container member of the target domain,
* the topology pass-phrase of this remote container.
During the attachment process, the container attached is reconfigured to use the registry of the target domain. After the attachment, the endpoints of the container moved are available in the target topology, and not in the initial topology anymore.
h2. Detaching a container
Any container member of a dynamic domain can be hot-detached at any moment. After detachment, the container is running in a dedicated standalone topology, i.e., in a dedicated domain.
{gliffy:name=Detaching a container|align=center|border=false|version=6}
The detachment is realized through the JMX API (or [Petals CLI|petalsclisnapshot:Petals ESB CLI 3.3.0-SNAPSHOT]) of the container to detach using the method '{{detachContainer}}' of the MBean '{{Topology}}'.
After the detachment, the endpoints of the container are not available in the initial topology anymore and are moved to the new one.
h2. Empty Topologies
When all container of a dynamic domain are detached from it, then the topology is empty.
In that case, the empty topology is automatically removed from the registry cluster.
h1. Static Topologies
By definition, static topologies can't be modified once registered in a registry cluster the first time.
But for administrative reasons, it can be desired to clean a topology by deleting it from the registry cluster.
This can be done using the command '{{delete-topology}}' of [Petals Registry CLI|petalsregclisnapshot:Petals Registry CLI 1.3.0-SNAPSHOT]).
h1. Appendix: under the hood
h2. Topology storage
At runtime, the topologies are in practice stored on the registry.
The containers store them there, read them from there, and potentially modify them, which notify the other containers of the topology of the modification.
This is how dynamic topologies are implemented for example.
h2. Standalone container
A container that is alone in its static topology is a standalone container.
It uses a specific in-memory implementation of the registry client which works without an actual running registry.
It can still leave it to join another dynamic topology, see below.
h2. Starting a new topology
When the first container of a topology is started, the topology is not yet stored on the registry, the following thus happens:
- the container reads its own {{topology.xml}} file, and extract the registry information from it,
- it connects to the registry and registers there the topology.
When the other containers of the topology are started, the following happens:
- the container reads its own {{topology.xml}} file, and extract the registry information from it,
- it connects to the registry and read there the topology,
- it ensures it is coherent with its own {{topology.xml}} file to prevent misconfigurations,
- from there on, it uses the data in the topology stored on the registry only.
h2. Joining a topology
When a container joins a topology, it is already in another topology, and the following happens:
- it retrieves the remote topology from another container belonging to it,
- it validates that it can leave its current topology (i.e, if it's dynamic) and join the new one (i.e., if it's dynamic or static but belongs to it),
- it pauses endpoint resolution: no new exchange will be sent by this container,
- it leaves its current topology (other containers of the topology will be notified by the registry): no new exchanges will be received by this container,
- it waits for exchanges to finish being processed,
- it joins the new topology (other containers of the topology will be notified by the registry),
- it registers its endpoints their and exchanges communications are re-established.