{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 a topology definition (ie. {{topology.xml}}) and [server properties|Container Configuration] (ie. {{server.properties}}).

This document will explain to you how to properly configure the topology of your Petals ESB cluster.

{column}
{column:width=350px}
{panel:title=Table of contents}{toc}{panel}
{panel:title=Contributors}{contributors:order=name|mode=list}{panel}
{column}
{section}

h1. Topology composition

A Petals ESB cluster is composed of a *domain* divided into *sub-domains* that contain the *containers*. A sub-domain aims to limit the visibility of service endpoints.
Inside a sub-domain:
* all service providers can be seen by all service consumers without restrictions,
* all service providers must be accessible directly to all service consumers.

Using a gateway, it is possible to interact between sub-domains pairs:
* by default, service endpoints of a sub-domain are not propagated to other sub-domains,
* the gateway is configured to propagated a selection of service endpoints in both ways,
* a message sent from a service consumer located into the sub-domain #1 to a service provider located in sub-domain #2 will pass through the gateway.

*Note: in the current version of Petals ESB, the notion "sub-domain" is not fully implemented, and the "gateway" is not yet available. The processing is as if the domain contains only one sub-domain: all service endpoints can be seen by all.*

* you want to prevent to add or remove container from your sub-domain,
* you don't plan hot topology refactoring

{code:lang=xml}<tns:sub-domain name="your-subdomain-name" mode="static">{code}

{code:lang=xml}<tns:sub-domain name="your-sub-domain-name" mode="dynamic">{code}

As we have seen, the {{topology.xml}} resource 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">
<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: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 |
| {{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 |
{center}

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. Appendix

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].