{section}
{column}

{multi-excerpt-include:Petals-BC-Gateway|name=features|nopanel=true}

{warning}This version must be installed on Petals ESB 5.0.0+{warning}

{tip}This version of the component is based on [Apache Netty|http://netty.io/] 4.0.36.{tip}

{column}

{column:width=40%}
{panel:title=Table of contents}{toc:outline=true}{panel}
{panel:title=Contributors}{contributors:order=name|mode=list|showAnonymous=true|showCount=true|showLastTime=true}{panel}
{column}
{section}

h1. Setting up a simple domain-to-domain propagation

Let's consider two domains A and B.
The number of containers in each of the domain is not important here: we must only select for each one container onto which the Gateway BC and its SU will deployed.

The domain A will act as the provider domain and will thus declare in its SU a set of Consumes as well as information needed to identify the consumer domain.

The domain B will act as the consumer domain and will thus declare in its SU the information needed to connect to the provider domain.

Let's consider that A will propagate several services:
* One denoted only by its interface name {{Interface1}} (hence it will matches all endpoints of that interface, potentially with different service name and of course with different endpoint names).
* One denoted by its interface name {{Interface2}} and service name {{Service2}} (hence it will matches all endpoints of that interface and service name).
* One denoted by its interface name {{Interface3}}, service name {{Service3}} and endpoint name {{endpoint3}} (hence it will match exactly one endpoint).

h2. Provider Domain A

For the provider domain, it is necessary to both define a Consumes SU and a transport listener at the component level.

h3. Consumes SU

The Consumes SU deployed on the Domain A is as follow:

{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi version="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:cdk="http://petals.ow2.org/components/extensions/version-5" xmlns:g="http://petals.ow2.org/components/petals-bc-gateway/version-1.0"
xmlns:test="http://test/">

<jbi:services binding-component="true">

<jbi:consumes interface-name="test:Interface1">

<!-- CDK specific elements -->
<cdk:mep xsi:nil="true" />

<!-- Component specific elements -->
<g:consumer domain="domainB" />

</jbi:consumes>

<jbi:consumes interface-name="test:Interface2" service-name="test:Service2">

<!-- CDK specific elements -->
<cdk:mep xsi:nil="true" />

<!-- Component specific elements -->
<g:consumer domain="domainB" />

</jbi:consumes>

<jbi:consumes interface-name="test:Interface3" service-name="test:Service3" endpoint-name="endpoint3">

<!-- CDK specific elements -->
<cdk:mep xsi:nil="true" />

<!-- Component specific elements -->
<g:consumer domain="domainB" />

</jbi:consumes>

<g:consumer-domain id="domainB" transport="transport1">
<g:auth-name>UniquelySharedBetweenA&B</g:auth-name>
</g:consumer-domain>

</jbi:services>
</jbi:jbi>
{code}

Here we see we chose to use the authentication name {{UniquelySharedBetweenA&B}} and the consumer domain will need to know this information.

{warning}The authentication name is +NOT+ meant to introduce security in the use of the Gateway BC: for that it is necessary to use [SSL|#ssl]!{warning}

{tip}The elements defined inside {{consumer-domain}} in an SU accept placeholder values.{tip}

h3. Component's Transport Listener

As we can see the Consumes SU relies on the existence of a transport called {{transport1}}.
By default there is no pre-configured transport listener on the Gateway BC but there is multiple ways to define them statically (see [#component-configuration] below) or dynamically with Petals CLI (see [petalsclisnapshot:Petals BC Gateway tooling]).

For example, we can use the following CLI command to create the transport listener before deploying the Consumes SU:
{code}
> bc-gateway.add-transport-listener -i transport1 -p 7500
{code}

Here we chose the port {{7500}} and the consumer domain will need to know this information.

h2. Consumer Domain B

For the consumer domain, it is only necessary to define a Provides SU based on the previously gathered information (authentication name, port) and hostname of the provider domain BC Gateway.
The Provides SU deployed on the Domain B is as follow:

<jbi:services binding-component="true">

<g:provider-domain id="domainA">
<g:remote-ip>domainA-hostname</g:remote-ip>
<g:remote-port>7500</g:remote-port>
<g:remote-auth-name>UniquelySharedBetweenA&B</g:remote-auth-name>
</g:provider-domain>

</jbi:services>
</jbi:jbi>
{code}

{tip}The elements defined inside {{provider-domain}} in an SU accept placeholder values.{tip}

h2. Service Propagations

If we start with one container for A and one container for B without anything on them and after:
* deploying the Gateway BC on each of the container of A and B.
* adding the transport listener on the Gateway BC of A.
* deploying the Consumes SU on the Gateway BC of A and the Provides SU on the Gateway BC of B.

{tip}The order of deployment is not very important as by default, the Provides SU will try to reconnect until it succeeds.{tip}

We can see that no endpoints have been deployed on B: this is expected because A will only propagate existing endpoints.

Now if we deploy some endpoints on domain A:
* {{InterfaceX:ServiceX:endpointX}}, then no endpoint will be activated on B.
* {{Interface1:Service1a:endpoint1a}}, then {{Interface1:Service1a:xxx}} will be activated on B.
* {{Interface1:Service1a:*endpoint1a*}} and {{Interface1:Service1a:*endpoint1b*}}, then {{Interface1:Service1a:xxx}} will be activated on B.
* {{Interface1:*Service1a*:endpoint1a}} and {{Interface1:*Service1b*:endpoint1b}}, then {{Interface1:*Service1a*:xxx}} and {{Interface1:*Service1b*:xxx}} will be activated on B.
* {{Interface2:*Service2*:endpoint2a}} and {{Interface1:*Service2b*:endpoint2b}}, then only {{Interface1:*Service2*:xxx}} will be activated on B.
* {{Interface3:Service3:endpoint3}}, then {{Interface3:Service3:xxx}} will be activated on B.
* Etc.

We can notice that the endpoint name is never propagated because it is considered that the endpoint is only a technical information to locate an endpoint in a domain.

We can also notice that what matters is always the pair interface and service name, and in case no service name is specified in the Consumes SU, then each existing service in the provider domain will be propagated as its own service.

{anchor:ssl}

h1. Service Unit Configuration

{petalslink}explain polling delay mechanism{petalslink}

{center}{*}Configuration of a consumer domain*{center}
{table-plus:columnAttributes=,,style="text-align:center;",style="text-align:center;"}
|| Parameter or +Attribute+ || Description || Default || Required ||
| +id+ | A unique name (in the SU) to identify this consumer domain configuration | \- | Yes |

| +propagation-polling-acceleration+ | The polling starts at 5sec and is multiplied by this factor after each polling until the maximum delay is attained (a value equals to 1 or less means no acceleration, i.e., the delay is always at the configured maximum) | 2.0 | Yes |
{table-plus}

h3. Consumes Element

{include:0 CDK SU Consume Configuration}

{center}{*}BC Gateway configuration of a {{consumes}} element*{center}
{table-plus:columnAttributes=,,style="text-align:center;",style="text-align:center;"}
|| Parameter || Description || Default || Required ||
| consumer | The identifier of a {{consumer-domain}} element specified in the SU | Yes (and more than once) |
{table-plus}

{center}{*}Configuration of a {{provider-domain}} element*{center}
{table-plus:columnAttributes=,,style="text-align:center;",style="text-align:center;"}
|| Parameter || Description || Default || Required ||
| +id+ | A unique name (in the SU) to identify this provider domain configuration | \- | Yes |
| remote-ip | The ip or hostname of the remote provider domain gateway | \- | Yes |

| +retry-max+ | Maximum retries before failing to connect (a negative value means infinite) | {{-1}} | Yes |
{table-plus}

h3. Provides Element

{include:0 CDK SU Provide Configuration}

{center}{*}BC Gateway configuration of a {{provides}} element*{center}
{table-plus:columnAttributes=,,style="text-align:center;",style="text-align:center;"}
|| Parameter || Description || Default || Required ||
| provider | See below | \- | Yes |
{table-plus}

{center}{*}Configuration of the {{provides}}'s {{provider}} element*{center}
{table-plus:columnAttributes=,,style="text-align:center;",style="text-align:center;"}
|| Parameter or +Attribute+ || Description || Default || Required ||
| +domain+ | The identifier of a {{provider-domain}} element specified in the SU | \- | Yes |
| provider-interface-name | The interface name of a service propagated by the provider domain that this SU will connect to (can be the same as the {{provides}}'s) | \- | Yes |
| provider-service-name | The service name of a service propagated by the provider domain that this SU will connect to (can be the same as the {{provides}}'s) | \- | Yes |
| provider-endpoint-name | The endpoint name of a service propagated by the provider domain that this SU will connect to | \- | No |
{table-plus}

{anchor:component-configuration}
h1. Component Configuration

The component configuration includes the configuration of the CDK. The following parameters correspond to the CDK configuration.

{petalslink}change the default values for the CDK thread pools...{petalslink}

{include:0 CDK Component Configuration Table 5.6.0}

{center}{*}Configuration of the component, Gateway part*{center}
{table-plus:columnAttributes=,,style="text-align:center;",style="text-align:center;"}
|| Parameter || Description || Default || Required || Scope ||
| consumer-domains-max-pool-size | Max number of threads used for handling incoming consumer partner connections: while each incoming consumer partner connection handles one exchange at a time, this limits the number of concurrent exchange processing amongst all incoming connection | 6 | No | Installation |
| provider-domains-max-pool-size | Max number of threads used for handling outgoing provider partner connections: while each outgoing provider partner connection handles one exchange at a time, this limits the number of concurrent exchange processing amongst all outgoing connection | 6 | No | Installation |

{include:0 CDK Parameter scope}

h1. Logging

The traces of Apache Netty itself can be activated through the logging configuration file of Petals ESB. The root logger for Netty is {{io.netty}}:
{code}
...
io.netty.level=INFO
...
{code}

h1. Monitoring the component

h2. Using metrics

Several probes providing metrics are included in the component, and are available through the JMX MBean '{{org.ow2.petals:type=custom,name=monitoring_*<component-id>*}}', where {{*<component-id>*}} is the unique JBI identifier of the component.

h3. Common metrics

{include:0 CDK Component Monitoring Metrics 5.6.0}

h3. Dedicated metrics

No dedicated metric is available.

h2. Receiving alerts

Several alerts are notified by the component through notification of the JMX MBean '{{org.ow2.petals:type=custom,name=monitoring_*<component-id>*}}', where {{*<component-id>*}} is the unique JBI identifier of the component.

{tip}To integrate these alerts with Nagios, see [petalsesbsnapshot:Receiving Petals ESB defects in Nagios].{tip}

h3. Common alerts

{include:0 CDK Component Monitoring Alerts 5.6.0}

h3. Dedicated alerts

No dedicated alert is available.