{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

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:

{code:lang=xml}
<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">

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

h2. Provider Domain A

h2. Consumer Domain B

h1. Service Rewriting

h1. Service Unit Configuration

h2. Consumer Domain

h2. Provider Domain

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

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

{include:0 CDK Component Configuration Table 5.6.0}

{center}{*}Configuration of the component, Gateway part*{center}
{table-plus}
|| {color:#333333}Parameter{color} || {color:#333333}Description{color} || {color:#333333}Default{color} || {color:#333333}Required{color} || 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 | {center}6{center} | {center}No{center} | {center}Installation{center} |
| 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 | {center}6{center} | {center}No{center} | {center}Installation{center} |

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