{section}
{column}
h1. On the Petals ESB Topology
\\
Petals ESB is a fully distributed ESB that features many types of topology both dynamically or statically. The topology of a Petals ESB cluster can be configured through the {{$PETALS_HOME/conf/topology.xml}} and {{$PETALS_HOME/conf/server.properties}} files.
This document will explain to you how to properly configure the topology of your Petals ESB cluster.
h1. Configuring the domain mode
Petals ESB supports three differents domain modes :
* standalone : the Petals ESB cluster is limited to one node, you can't add new ones.
* static : the topology is static, no new node can be added to a running Petals ESB cluster.
* dynamic : the topology is been updated regularly, so you can add new nodes to a running Petals ESB cluster.
This chapter will explain you how to choose and configure the domain mode according your needs.
h2. Choosing the domain mode
*Standalone mode*
As explained earlier, when you just have one single Petals ESB node, and you do not need any other node, you might want to use the standalone mode.
{warning}
Since Petals ESB 3.0, this mode is not supported anymore. Use a the static domain with one subdomain in master/slave mode. The only node of the cluster should then be configured in master mode.
{warning}
\\
*Static mode*
Most of the time, you know how many nodes you have in your cluster, and this number does not change over time. This mode is the most suitable for most production environments.
If you need to add a new node to the cluster, you must stop all the nodes of your Petals ESB cluster and then change every {{topology.xml}} file to reflect the topology changes.
{info}
When a Petals ESB nodes crashes, this doesn't impact the topology, but all the messages sent to the services deployed on this node are lost since the Petals ESB container does not keep track of the execution context.
{info}
\\
*Dynamic mode*
In some very specific usecases, the number of nodes in your Petals ESB cluster may vary while the whole cluster is running.
{warning}
Since dynamic mode replace the {{topology.xml}} file at each topology update this mode is not suitable for production use.
{warning}
h2. Using the static mode
*Configuring the topology.xml file*
To use the static mode, in the domain element of the topology.xml file, you just have to change the mode property to static :
{code:lang=xml}<tns:domain mode="static" name="PEtALS">{code}
See : [^static-topology-sample.xml]
h2. Using the dynamic mode
*Configuring the topology.xml file*
To use the dynamic mode, in the domain element of the topology.xml file, you just have to change the mode property to dynamic :
{code:lang=xml}<tns:domain mode="dynamic" name="PEtALS">{code}
See : [^dynamic-topology-sample.xml]
\\
*Configuring the update period*
In dynamic mode, as we've explained earlier, the topology is been updated automatically. The first topology update took place 30 seconds after the node has finished its startup procedure. Then, the topology is been updated regularly at a period configured by the *topology.update.period* property of the {{$PETALS_HOME/conf/server.properties}} file.
{noformat}
#Topology update period (in seconds)
topology.update.period=101
{noformat}
h1. Configuring the subdomain mode
Apart from configuring Petals ESB domain mode, you can also, for each subdomain, choose various modes :
* *standalone* : the subdomain can only have one node.
* *flooding* : the subdomain can have many nodes, each one knowing each other.
* *master-slave* : the subdomain can have many nodes, each node knows only one node called the master node.
The domain mode doesn't impact the way Petals ESB nodes communicate business data with each other. This only change the way endpoints-related informations are exchanged between nodes.
This chapter will explain you how to choose and configure the subdomain mode according your needs.
h2. Standalone configuration
In standalone mode, the Petals ESB cluster is limited to one node. You can only have one subdomain, also in standalone mode, with only one node, again declared as working in standalone mode.
{center}!standalone.png|height=285,width=500!{center}
{warning:title=Warning}
Again, since Petals ESB 3.x, the standalone mode is *not supported anymore*. Instead, use a the static domain with one subdomain in master/slave mode. The only node of the cluster should then be configured in master mode.
{warning}
h2. Flooding configuration
In flooding mode, each time a new service unit (registering endpoints) is installed, the node on which it has been installed propagates immediately the modification to all its peers. Business data of course is still exchanged directly between nodes, from the source directly to the destination.
{center}
!flooding.png|height=375,width=500!
{center}
A subdomain configured to use the flooding strategy can only contain node working in *peer* mode. The minimum number of peer node is one, while there is not limit on the number of peer nodes.
{warning:title=Warning}
This mode is only available when the whole domain (eg. the whole cluster) is in *static* mode.
{warning}
h2. Master/Slave configuration
In master-slave mode, every node of the cluster resynchronises itself regularly against the configuration of the master node. For now on, each node knows every all the endpoints and services deployed on the cluster. In the future, this strategy will be the only one to be maintained and will be refined to control the propagation of the informations on the cluster. As ever, business data is still exchanged directly between nodes, from the source directly to the destination.
{center}!master-slave.png|height=375,width=500!{center}
A subdomain using the master/slave strategy can only contains nodes using master or slave nodes. Each subdomain using this mode must have at least one master node. The number of slave nodes is unbounded.
{note:title=Note}
This strategy can be used both in dynamic or static domain mode. In static domain mode, every node of the cluster should be declared within the {{topology.xml}} file while in dynamic mode, you can only register the master node and the local node.
{note}
h1. Declaring containers configurations
As we have seen, the {{topology.xml}} file is used to declare the configuration of a Petals ESB cluster.
h2. Generic container configuration
Each Petals ESB container declared within must conforms to the following XML structure :
{code:lang=xml}
<tns:container name="0" type="master">
<tns:description>description of the container 0</tns:description>
<tns:host>localhost</tns:host>
<tns:user>petals</tns:user>
<tns:password>petals</tns:password>
<tns:webservice-service>
<tns:port>7600</tns:port>
<tns:prefix>petals/ws</tns:prefix>
</tns:webservice-service>
<tns:jmx-service>
<tns:rmi-port>7700</tns:rmi-port>
</tns:jmx-service>
<tns:transport-service>
<tns:tcp-port>7800</tns:tcp-port>
</tns:transport-service>
<tns:registry-service>
<tns:port>7900</tns:port>
</tns:registry-service>
</tns:container>
{code}
The meaning of these properties is summarized in the following table :
{center}
|| Property name || Default value || Required || Description ||
| {{name}} | 0 | yes | name of the container |
| {{mode}} | master | yes | mode of the node (master, slave, peer, standalone) |
| {{description}} | description of the container 0 | no | description of the container |
| {{host}} | localhost | yes | host name or ip address of the container |
| {{user}} | petals | no | jmx username |
| {{password}} | petals | no | jmx password |
|| {{webservice-service}} || || || ||
| {{port}} | 7600 | yes | administration webservices port (topology, information, ...) |
| {{prefix}} | petals/ws | yes | path of the webservice |
|| {{jmx-service}} || || || ||
| {{rmi-port}} | 7700 | yes | jmx service port |
|| {{transport-service}} || || || ||
| {{tcp-port}} | 7800 | yes |NIO transporter port |
|| {{registry-service}} || || || ||
| {{port}} | 7900 | yes | registry service port |
{center}
h2. Standalone container configuration
A container is declared to be working in standalone mode using the following XML code :
{code:lang=xml}
<tns:container name="0" type="standalone">
...
</tns:container>
{code}
{warning:title=Warning}
Again, since Petals ESB 3.x, the standalone mode is *not supported anymore*. Instead, use a the static domain with one subdomain in master/slave mode. The only node of the cluster should then be configured in master mode.
{warning}
h2. Peer container configuration
A container is declared to be working in peer mode using the following XML code :
{code:lang=xml}
<tns:container name="0" type="peer">
...
</tns:container>
{code}
This kind of containers can only be found in subdomains using the flooding strategy.
h2. Master container configuration
A container is declared to be working in master mode using the following XML code :
{code:lang=xml}
<tns:container name="0" type="master">
...
</tns:container>
{code}
A domain using the master-slave strategy must have at least one and only one master node.
h2. Slave container configuration
A container is declared to be working in mode mode using the following XML code :
{code:lang=xml}
<tns:container name="0" type="slave">
...
</tns:container>
{code}
A domain using the master-slave strategy can have an unbounded number of slave nodes.
When using the dynamic domain mode, for a slave node, you can declare only the master configuration and the slave configuration. The first topology update will rewrite the {{topology.xml}} file and update the containers list using the ones registered to the master node.
{warning:title=Warning}
You can declare two slaves node using the same name with different configuration, but in this case, the master node will only remembers the latest one.
{warning}
h1. Configuring the local container
As we have seen, the {{topology.xml}} file contains the declaration of a Petals ESB cluster. This information is not sufficient to determine which configuration must be chosen by the local container at startup. To do so, you must give a container name declared within the {{topology.xml}} file to the property {{petals.container.name}} declared in the {{server.properties}}.
{noformat}
#This property specifies the name of the container. In distributed mode, this property is mandatory
#and must match a container name in the topology.xml file
petals.container.name=0
{noformat}
The container name given to the {{petals.container.name}} property must be declared within the {{topology.xml}} file, otherwise, Petals ESB won't be able to start. This mean that you must have declared the local container configuration within the {{topology.xml}} file.
h1. Summary
The table below summarize the valid configuration for the {{topology.xml}} file :
{center}
|| Domain mode || Subdomain mode || Container mode|| Supported || Won't be deprecated ||
| standalone | standalone | standalone | (x) | (x) |
| dynamic | master-slave | master, slave | (/) | (/) |
| static | flooding | peer | (/) | (x) |
| static | master-slave | master, slave | (/) | (/) |
{center}
h1. Appendix
h2. Default configuration
The default {{topology.xml}} file is :
{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<tns:topology xmlns:tns="http://petals.ow2.org/topology"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://petals.ow2.org/topology petalsTopology.xsd">
<tns:domain mode="static" name="PEtALS">
<tns:description>The static domain configuration</tns:description>
<tns:sub-domain name="subdomain1" mode="master-slave">
<tns:description>description of the subdomain</tns:description>
<tns:container name="0" type="master">
<tns:description>description of the container 0</tns:description>
<tns:host>localhost</tns:host>
<tns:user>petals</tns:user>
<tns:password>petals</tns:password>
<tns:webservice-service>
<tns:port>7600</tns:port>
<tns:prefix>petals/ws</tns:prefix>
</tns:webservice-service>
<tns:jmx-service>
<tns:rmi-port>7700</tns:rmi-port>
</tns:jmx-service>
<tns:transport-service>
<tns:tcp-port>7800</tns:tcp-port>
</tns:transport-service>
<tns:registry-service>
<tns:port>7900</tns:port>
</tns:registry-service>
</tns:container>
</tns:sub-domain>
</tns:domain>
</tns:topology>
{code}
Download link : [^default-topology.xml]
h2. Topology XML Schema
For more information on the structure of the topology.xml file, you can consult its XML schema definition here : [^petalsTopology.xsd].
{column}
{column:width=350px}
{panel:title=Table of contents}{toc}{panel}
{panel:title=Contributors}{contributors:order=name|mode=list}{panel}
{column}
{section}
{column}
h1. On the Petals ESB Topology
\\
Petals ESB is a fully distributed ESB that features many types of topology both dynamically or statically. The topology of a Petals ESB cluster can be configured through the {{$PETALS_HOME/conf/topology.xml}} and {{$PETALS_HOME/conf/server.properties}} files.
This document will explain to you how to properly configure the topology of your Petals ESB cluster.
h1. Configuring the domain mode
Petals ESB supports three differents domain modes :
* standalone : the Petals ESB cluster is limited to one node, you can't add new ones.
* static : the topology is static, no new node can be added to a running Petals ESB cluster.
* dynamic : the topology is been updated regularly, so you can add new nodes to a running Petals ESB cluster.
This chapter will explain you how to choose and configure the domain mode according your needs.
h2. Choosing the domain mode
*Standalone mode*
As explained earlier, when you just have one single Petals ESB node, and you do not need any other node, you might want to use the standalone mode.
{warning}
Since Petals ESB 3.0, this mode is not supported anymore. Use a the static domain with one subdomain in master/slave mode. The only node of the cluster should then be configured in master mode.
{warning}
\\
*Static mode*
Most of the time, you know how many nodes you have in your cluster, and this number does not change over time. This mode is the most suitable for most production environments.
If you need to add a new node to the cluster, you must stop all the nodes of your Petals ESB cluster and then change every {{topology.xml}} file to reflect the topology changes.
{info}
When a Petals ESB nodes crashes, this doesn't impact the topology, but all the messages sent to the services deployed on this node are lost since the Petals ESB container does not keep track of the execution context.
{info}
\\
*Dynamic mode*
In some very specific usecases, the number of nodes in your Petals ESB cluster may vary while the whole cluster is running.
{warning}
Since dynamic mode replace the {{topology.xml}} file at each topology update this mode is not suitable for production use.
{warning}
h2. Using the static mode
*Configuring the topology.xml file*
To use the static mode, in the domain element of the topology.xml file, you just have to change the mode property to static :
{code:lang=xml}<tns:domain mode="static" name="PEtALS">{code}
See : [^static-topology-sample.xml]
h2. Using the dynamic mode
*Configuring the topology.xml file*
To use the dynamic mode, in the domain element of the topology.xml file, you just have to change the mode property to dynamic :
{code:lang=xml}<tns:domain mode="dynamic" name="PEtALS">{code}
See : [^dynamic-topology-sample.xml]
\\
*Configuring the update period*
In dynamic mode, as we've explained earlier, the topology is been updated automatically. The first topology update took place 30 seconds after the node has finished its startup procedure. Then, the topology is been updated regularly at a period configured by the *topology.update.period* property of the {{$PETALS_HOME/conf/server.properties}} file.
{noformat}
#Topology update period (in seconds)
topology.update.period=101
{noformat}
h1. Configuring the subdomain mode
Apart from configuring Petals ESB domain mode, you can also, for each subdomain, choose various modes :
* *standalone* : the subdomain can only have one node.
* *flooding* : the subdomain can have many nodes, each one knowing each other.
* *master-slave* : the subdomain can have many nodes, each node knows only one node called the master node.
The domain mode doesn't impact the way Petals ESB nodes communicate business data with each other. This only change the way endpoints-related informations are exchanged between nodes.
This chapter will explain you how to choose and configure the subdomain mode according your needs.
h2. Standalone configuration
In standalone mode, the Petals ESB cluster is limited to one node. You can only have one subdomain, also in standalone mode, with only one node, again declared as working in standalone mode.
{center}!standalone.png|height=285,width=500!{center}
{warning:title=Warning}
Again, since Petals ESB 3.x, the standalone mode is *not supported anymore*. Instead, use a the static domain with one subdomain in master/slave mode. The only node of the cluster should then be configured in master mode.
{warning}
h2. Flooding configuration
In flooding mode, each time a new service unit (registering endpoints) is installed, the node on which it has been installed propagates immediately the modification to all its peers. Business data of course is still exchanged directly between nodes, from the source directly to the destination.
{center}
!flooding.png|height=375,width=500!
{center}
A subdomain configured to use the flooding strategy can only contain node working in *peer* mode. The minimum number of peer node is one, while there is not limit on the number of peer nodes.
{warning:title=Warning}
This mode is only available when the whole domain (eg. the whole cluster) is in *static* mode.
{warning}
h2. Master/Slave configuration
In master-slave mode, every node of the cluster resynchronises itself regularly against the configuration of the master node. For now on, each node knows every all the endpoints and services deployed on the cluster. In the future, this strategy will be the only one to be maintained and will be refined to control the propagation of the informations on the cluster. As ever, business data is still exchanged directly between nodes, from the source directly to the destination.
{center}!master-slave.png|height=375,width=500!{center}
A subdomain using the master/slave strategy can only contains nodes using master or slave nodes. Each subdomain using this mode must have at least one master node. The number of slave nodes is unbounded.
{note:title=Note}
This strategy can be used both in dynamic or static domain mode. In static domain mode, every node of the cluster should be declared within the {{topology.xml}} file while in dynamic mode, you can only register the master node and the local node.
{note}
h1. Declaring containers configurations
As we have seen, the {{topology.xml}} file is used to declare the configuration of a Petals ESB cluster.
h2. Generic container configuration
Each Petals ESB container declared within must conforms to the following XML structure :
{code:lang=xml}
<tns:container name="0" type="master">
<tns:description>description of the container 0</tns:description>
<tns:host>localhost</tns:host>
<tns:user>petals</tns:user>
<tns:password>petals</tns:password>
<tns:webservice-service>
<tns:port>7600</tns:port>
<tns:prefix>petals/ws</tns:prefix>
</tns:webservice-service>
<tns:jmx-service>
<tns:rmi-port>7700</tns:rmi-port>
</tns:jmx-service>
<tns:transport-service>
<tns:tcp-port>7800</tns:tcp-port>
</tns:transport-service>
<tns:registry-service>
<tns:port>7900</tns:port>
</tns:registry-service>
</tns:container>
{code}
The meaning of these properties is summarized in the following table :
{center}
|| Property name || Default value || Required || Description ||
| {{name}} | 0 | yes | name of the container |
| {{mode}} | master | yes | mode of the node (master, slave, peer, standalone) |
| {{description}} | description of the container 0 | no | description of the container |
| {{host}} | localhost | yes | host name or ip address of the container |
| {{user}} | petals | no | jmx username |
| {{password}} | petals | no | jmx password |
|| {{webservice-service}} || || || ||
| {{port}} | 7600 | yes | administration webservices port (topology, information, ...) |
| {{prefix}} | petals/ws | yes | path of the webservice |
|| {{jmx-service}} || || || ||
| {{rmi-port}} | 7700 | yes | jmx service port |
|| {{transport-service}} || || || ||
| {{tcp-port}} | 7800 | yes |NIO transporter port |
|| {{registry-service}} || || || ||
| {{port}} | 7900 | yes | registry service port |
{center}
h2. Standalone container configuration
A container is declared to be working in standalone mode using the following XML code :
{code:lang=xml}
<tns:container name="0" type="standalone">
...
</tns:container>
{code}
{warning:title=Warning}
Again, since Petals ESB 3.x, the standalone mode is *not supported anymore*. Instead, use a the static domain with one subdomain in master/slave mode. The only node of the cluster should then be configured in master mode.
{warning}
h2. Peer container configuration
A container is declared to be working in peer mode using the following XML code :
{code:lang=xml}
<tns:container name="0" type="peer">
...
</tns:container>
{code}
This kind of containers can only be found in subdomains using the flooding strategy.
h2. Master container configuration
A container is declared to be working in master mode using the following XML code :
{code:lang=xml}
<tns:container name="0" type="master">
...
</tns:container>
{code}
A domain using the master-slave strategy must have at least one and only one master node.
h2. Slave container configuration
A container is declared to be working in mode mode using the following XML code :
{code:lang=xml}
<tns:container name="0" type="slave">
...
</tns:container>
{code}
A domain using the master-slave strategy can have an unbounded number of slave nodes.
When using the dynamic domain mode, for a slave node, you can declare only the master configuration and the slave configuration. The first topology update will rewrite the {{topology.xml}} file and update the containers list using the ones registered to the master node.
{warning:title=Warning}
You can declare two slaves node using the same name with different configuration, but in this case, the master node will only remembers the latest one.
{warning}
h1. Configuring the local container
As we have seen, the {{topology.xml}} file contains the declaration of a Petals ESB cluster. This information is not sufficient to determine which configuration must be chosen by the local container at startup. To do so, you must give a container name declared within the {{topology.xml}} file to the property {{petals.container.name}} declared in the {{server.properties}}.
{noformat}
#This property specifies the name of the container. In distributed mode, this property is mandatory
#and must match a container name in the topology.xml file
petals.container.name=0
{noformat}
The container name given to the {{petals.container.name}} property must be declared within the {{topology.xml}} file, otherwise, Petals ESB won't be able to start. This mean that you must have declared the local container configuration within the {{topology.xml}} file.
h1. Summary
The table below summarize the valid configuration for the {{topology.xml}} file :
{center}
|| Domain mode || Subdomain mode || Container mode|| Supported || Won't be deprecated ||
| standalone | standalone | standalone | (x) | (x) |
| dynamic | master-slave | master, slave | (/) | (/) |
| static | flooding | peer | (/) | (x) |
| static | master-slave | master, slave | (/) | (/) |
{center}
h1. Appendix
h2. Default configuration
The default {{topology.xml}} file is :
{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<tns:topology xmlns:tns="http://petals.ow2.org/topology"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://petals.ow2.org/topology petalsTopology.xsd">
<tns:domain mode="static" name="PEtALS">
<tns:description>The static domain configuration</tns:description>
<tns:sub-domain name="subdomain1" mode="master-slave">
<tns:description>description of the subdomain</tns:description>
<tns:container name="0" type="master">
<tns:description>description of the container 0</tns:description>
<tns:host>localhost</tns:host>
<tns:user>petals</tns:user>
<tns:password>petals</tns:password>
<tns:webservice-service>
<tns:port>7600</tns:port>
<tns:prefix>petals/ws</tns:prefix>
</tns:webservice-service>
<tns:jmx-service>
<tns:rmi-port>7700</tns:rmi-port>
</tns:jmx-service>
<tns:transport-service>
<tns:tcp-port>7800</tns:tcp-port>
</tns:transport-service>
<tns:registry-service>
<tns:port>7900</tns:port>
</tns:registry-service>
</tns:container>
</tns:sub-domain>
</tns:domain>
</tns:topology>
{code}
Download link : [^default-topology.xml]
h2. Topology XML Schema
For more information on the structure of the topology.xml file, you can consult its XML schema definition here : [^petalsTopology.xsd].
{column}
{column:width=350px}
{panel:title=Table of contents}{toc}{panel}
{panel:title=Contributors}{contributors:order=name|mode=list}{panel}
{column}
{section}