FeaturesThe component BC Gateway enables to create secured (encrypted and authenticated) bridges between Petals domains governed by separate entities.
From the point of view of this BC, one (or several in case of HA) container in each Petals domain will either play the role of provider domain or consumer domain:
By default the Gateway BC takes care of reconnecting in case of disconnection, polling for changes in the activated endpoints to keep the consumer domain a mirror of the provider domain and it is possible to rewrite propagated services names in the consumer domain if needed. By service, we mean one as defined in a WSDL: it is specified by an interface name and a service name.
Service Units ConfigurationIn terms of configuration (i.e., definition of Service Units), this results in two different artefacts: Consumes and Provides SUs. The particularity of the Gateway BC is that, while Consumes SUs explicitly define which are the consumed services that are going to be propagated from their domain, Provides SUs do not have to (but can) define the services that are going to be propagated to their domain: these are inferred based on the services actually propagated by the provider domain. Component Transport ListenersTechnically, the component onto which the Consumes SUs are deployed must define how to listen to incoming connections (on a host and TCP port currently) from Provides SUs.
|
Table of contents
Contributors
No contributors found for: authors on selected page(s)
|
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).
Provider Domain A
For the provider domain, it is necessary to both define a Consumes SU and a transport listener at the component level.
Consumes SU
The Consumes SU deployed on the Domain A is as follow:
<?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>
Here we see we chose to use the authentication name UniquelySharedBetweenA&B and the consumer domain will need to know this information.
The authentication name is NOT meant to introduce security in the use of the Gateway BC: for that it is necessary to use SSL! |
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 Petals BC Gateway tooling).
For example, we can use the following CLI command to create the transport listener before deploying the Consumes SU:
> bc-gateway.add-transport-listener -i transport1 -p 7500
Here we chose the port 7500 and the consumer domain will need to know this information.
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:
<?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"> <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>
Examples of 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.
The order of deployment is not very important as by default, the Provides SU will try to reconnect until it succeeds. |
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.
Using SSL to authenticate and encrypt exchanges between domains
In order to secure connections between provider and consumer domain, it is possible to rely on SSL.
SSL itself takes care of the encryption, but it is necessary for the provider domain, and optionally for the consumer domain, to have a certificate shared between parties to authenticate them.
There can't thus be encryption without authentication of at least the provider domain and ideally also of the consumer domain!
Authenticating only the Provider Domain
For a provider domain, using SSL means to define a certificate that consumer domains that connect to it can use to authenticate it.
The certificate is a public information and the provider domain owns also a private key that it can use to answers authentication challenges from the consumer domain.
Provider Domain A
On the provider side, the consumer-domain element must be updated with the following parameters:
<?xml version="1.0" encoding="UTF-8"?> <jbi:jbi ...> <jbi:services binding-component="true"> ... <g:consumer-domain id="domainB" transport="transport1"> <g:auth-name>UniquelySharedBetweenA&B</g:auth-name> <g:certificate>path/to/a/certificate+provider.crt</g:certificate> <g:key>path/to/the/key.pem</g:key> <g:passphrase>secret-to-unlock-the-key<g:passphrase> </g:consumer-domain> </jbi:services> </jbi:jbi>
Note that this means that setting up SSL is done per consumer domain that will connect to this SU, but nothing prevent us to configure the same certificate for multiple consumer domains of course!
Consumer Domain B
On the consumer side, the consumer-domain element must be updated with the following parameters:
<?xml version="1.0" encoding="UTF-8"?> <jbi:jbi ..."> <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:remote-certificate>path/to/the/certificate-provider.crt</g:remote-certificate> </g:provider-domain> </jbi:services> </jbi:jbi>
Authenticating both the Provider and Consumer domains
Optionally, it is also possible to superpose on this basic SSL setup the use of a certificate that the provider domain will use to authenticate the consumer domain.
The later will also own a private key then.
Provider Domain A
On the provider side, the consumer-domain element must be updated with the following parameters:
<?xml version="1.0" encoding="UTF-8"?> <jbi:jbi ...> <jbi:services binding-component="true"> ... <g:consumer-domain id="domainB" transport="transport1"> <g:auth-name>UniquelySharedBetweenA&B</g:auth-name> <g:certificate>path/to/a/certificate-provider.crt</g:certificate> <g:key>path/to/the/key.pem</g:key> <g:passphrase>secret-to-unlock-the-key<g:passphrase> <g:remote-certificate>path/to/the/certificate-consumer.crt </g:consumer-domain> </jbi:services> </jbi:jbi>
This means that even if multiple Provides SUs connects to this provider domain, they all must use the same certificate as it is a mean to authenticate a consumer domain and not an individual node of this domain.
Consumer Domain B
On the consumer side, the consumer-domain element must be updated with the following parameters:
<?xml version="1.0" encoding="UTF-8"?> <jbi:jbi ..."> <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:remote-certificate>path/to/the/certificate-provider.crt</g:remote-certificate> <g:certificate>path/to/a/certificate-consumer.crt</g:certificate> <g:key>path/to/the/key.pem</g:key> <g:passphrase>secret-to-unlock-the-key<g:passphrase> </g:provider-domain> </jbi:services> </jbi:jbi>
Service Unit Configuration
Consumes SU
In a Consumes SU, one must declare at least one 'consumer-domain' and some 'consumes' element to determine the services to be propagated to one or several of these consumer domains.
The 'consumes' element can't override each other for the same 'consumer-domain':
- If there is a 'consumes' of type Interface:Service:endpoint, then there can't be another 'consumes' of type Interface:Service:endpoint, Interface:Service: or Interface:: defined for the same consumer-domain.
- If there is a 'consumes' of type Interface:Service:, then there can't be another 'consumes' of type Interface:Service: or Interface:: defined for the same 'consumer-domain'.
- If there is a 'consumes' of type Interface::, then there can't be another 'consumes' of type Interface:: defined for the same 'consumer-domain'.
Configuration
All needed information must be defined in the service-unit JBI descriptor. This JBI descriptor is configured through parameters divided in following groups:
- JBI parameters that defines the service provider identification,
- CDK parameters that are parameters driving the service consumer implementation at CDK layer,
- CDK interceptor parameters that are parameters driving interceptors at CDK layer,
- Dedicated parameters that are parameters driving the service consumer implementation at component layer:
- Defining the provider domain linked to the current consumer domain.
CDK parameters defining service consumer implementation
The following parameters correspond to the CDK configuration of the service consumer implementation.
A service consumer is defined into the section 'consumes' of the JBI descriptor, containing:
Parameter
|
Description
|
Default
|
Required
|
Support placeholders
|
---|---|---|---|---|
interface-name
|
Interface name of the service provider to invoke. | -
|
Yes
|
No
|
service-name
|
Service name of the service provider to invoke. | -
|
No
|
No
|
endpoint-name
|
Endpoint name of the service provider to invoke. | -
|
No
|
No
|
timeout
|
Timeout in milliseconds of a synchronous send. This parameter can be used in conjunction with the sendSync(Exchange exchange) method of the Listeners. Set 0 for an infinite timeout. | 30000 | No
|
Yes
|
operation
|
Operation to call on the service provider. If no operation is specified in the Message Exchange to send, this parameter will be used. | -
|
No
|
No
|
activate-flow-tracing
|
Enable ('true') or disable ('false') the flow tracing for this service consumer. This value overrides the value defined at component level and can be overridden at incoming exchange level. | Value defined at component level | No
|
Yes
|
propagate-flow-tracing-activation
|
Control whether the flow tracing activation state must be propagated to next flow steps or not. If 'true', the flow tracing activation state is propagated to the invoked service provider. This value overrides the value defined at component level. | Value defined at component | No
|
Yes
|
su-interceptors
|
Service unit interceptor configuration. See Service unit interceptor configuration. | -
|
No
|
No
|
mep
|
Message exchange pattern to use. | -
|
Yes
|
No
|
CDK parameters driving interceptors
The following parameters drive interceptors at CDK layer.
Interceptors can be defined to inject some post or pre-processing in the service provider processing or service consumer processing.
Using interceptor is very sensitive and must be manipulated only by power users. A non properly coded interceptor engaged in a component can lead to uncontrolled behaviors, out of the standard process.
Example of an interceptor configuration:
<?xml version="1.0" encoding="UTF-8"?> <jbi:jbi xmlns:jbi="http://java.sun.com/xml/ns/jbi" xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5"> <jbi:services> <jbi:provides|consumes> <!--...--> <petalsCDK:su-interceptors> <petalsCDK:send> <petalsCDK:interceptor name="myInterceptorName"> <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param> <petalsCDK:param name="myParamName2">myParamValue2</petalsCDK:param> </petalsCDK:interceptor> </petalsCDK:send> <petalsCDK:accept> <petalsCDK:interceptor name="myInterceptorName"> <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param> </petalsCDK:interceptor> </petalsCDK:accept> <petalsCDK:send-response> <petalsCDK:Interceptor name="myInterceptorName"> <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param> </petalsCDK:Interceptor> </petalsCDK:send-response> <petalsCDK:accept-response> <petalsCDK:Interceptor name="myInterceptorName"> <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param> </petalsCDK:Interceptor> </petalsCDK:accept-response> </petalsCDK:su-interceptors> <!--...--> </jbi:provides|consumes> <!--...--> </jbi:services> </jbi:jbi>
Interceptors configuration for SU (CDK)
Parameter | Description | Default | Required |
---|---|---|---|
send | Interceptor dedicated to send phase, for an exchange sent by a consumer | - | No |
accept | Interceptor dedicated to receive phase, for an exchange received by a provider | - | No |
send-response | Interceptor dedicated to send phase, for an exchange (a response) received by a consumer | - | No |
accept-response | Interceptor dedicated to receive phase, for an exchange sent (a response) by a provider | - | No |
interceptor - name | Logical name of the interceptor instance defined at component level, see CDK Component Interceptor configuration. | - | Yes |
param[] - name | The name of the parameter to use for the interceptor for this SU | - | No |
param[] | The value of the parameter to use for the interceptor for this SU | - | No |
Dedicated configuration
Definition of the provider domain linked to the current consumer domain
A consumer domain is defined through a sub-element 'consumer-domain' under the JBI element'services.
Attribute or element | Description | Default value | Required | Support of placeholders |
---|---|---|---|---|
id | A unique name (in the SU) to identify this consumer domain configuration | - | Yes | Yes |
transport | The identifier of a transport listener configured in the component | - | Yes | Yes |
auth-name | A unique name (in the transport listener) to be shared with the consumer domain that will connect to this SU | - | Yes | Yes |
remote-certificate | The path to a shared SSL certificate (X.509 certificate in PEM format) used to authenticate the consumer domain that will connect to this SU (relative path means in the SU, absolute path means on the filesystem) | - | No | Yes |
certificate | The path to a shared SSL certificate used to secure the connections (relative path means in the SU, absolute path means on the filesystem) | - | Yes if remote-certificate is specified | Yes |
key | The path to a private SSL key (PKCS#8 private key in PEM format) for the SSL certificate specified with certificate (relative path means in the SU, absolute path means on the filesystem) | - | Yes if certificate is specified, else ignored | Yes |
passphrase | The passphrase to unlock the SSL key specified with key | - | Only if key is specified and needs a passphrase, else ignored | Yes |
propagation-polling-max-delay | The maximum delay between polling done by this SU to check new or removed endpoints in the domain (a 0 or negative value means no polling) in milliseconds | 5000 | Yes | 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 | Yes |
Service consumer
To link a service consumer to an external service proBy default all service providers are exported with their current names to all consumer domains. You can select which service provider is exported in a given provider domain, evantually rewriting its names. Please use the following parameters of the element 'provides':
Element | Description | Default value | Required | Support of placeholders |
---|---|---|---|---|
consumer | The identifier of a consumer-domain element specified in the SU | Yes (and more than once) | No |
Note that in consumes elements for the Gateway BC, it has no meaning to specify a mep or an operation: they will be ignored, thus it is recommended to always set the mep to nil (because it is required to specify it):
<cdk:mep xsi:nil="true" />
Provides SU
In a Provides SU, one must declare at least one provider-domain and optionally some provides element to determine how the services are being propagated from one of the provider domains.
The 'provides' element must have a 'provider' element and these can't override each other for the same 'provider-domain':
- If there is a 'provides' with a 'provider' of type Interface:Service:endpoint, then there can't be another 'provides' with a 'provider' of type Interface:Service:endpoint or Interface:Service: defined for the same 'provider-domain'.
- If there is a 'provides' with a 'provider' of type Interface:Service:, then there can't be another 'provides' with a 'provider' of type Interface:Service: defined for the same 'provider-domain'.
Configuration
All needed information must be defined in the service-unit JBI descriptor. This JBI descriptor is configured through parameters divided in following groups:
- JBI parameters that defines the service provider identification,
- CDK parameters that are parameters driving the service consumer implementation at CDK layer,
- CDK interceptor parameters that are parameters driving interceptors at CDK layer,
- Dedicated parameters that are parameters driving the service consumer implementation at component layer:
- Defining the provider domain,
- Defining the service providers exported.
CDK parameters defining service consumer implementation
The following parameters correspond to the CDK configuration of the service consumer implementation.
A service consumer is defined into the section 'consumes' of the JBI descriptor, containing:
Parameter
|
Description
|
Default
|
Required
|
Support placeholders
|
---|---|---|---|---|
interface-name
|
Interface name of the service provider to invoke. | -
|
Yes
|
No
|
service-name
|
Service name of the service provider to invoke. | -
|
No
|
No
|
endpoint-name
|
Endpoint name of the service provider to invoke. | -
|
No
|
No
|
timeout
|
Timeout in milliseconds of a synchronous send. This parameter can be used in conjunction with the sendSync(Exchange exchange) method of the Listeners. Set 0 for an infinite timeout. | 30000 | No
|
Yes
|
operation
|
Operation to call on the service provider. If no operation is specified in the Message Exchange to send, this parameter will be used. | -
|
No
|
No
|
activate-flow-tracing
|
Enable ('true') or disable ('false') the flow tracing for this service consumer. This value overrides the value defined at component level and can be overridden at incoming exchange level. | Value defined at component level | No
|
Yes
|
propagate-flow-tracing-activation
|
Control whether the flow tracing activation state must be propagated to next flow steps or not. If 'true', the flow tracing activation state is propagated to the invoked service provider. This value overrides the value defined at component level. | Value defined at component | No
|
Yes
|
su-interceptors
|
Service unit interceptor configuration. See Service unit interceptor configuration. | -
|
No
|
No
|
mep
|
Message exchange pattern to use. | -
|
Yes
|
No
|
CDK parameters driving interceptors
The following parameters drive interceptors at CDK layer.
Interceptors can be defined to inject some post or pre-processing in the service provider processing or service consumer processing.
Using interceptor is very sensitive and must be manipulated only by power users. A non properly coded interceptor engaged in a component can lead to uncontrolled behaviors, out of the standard process.
Example of an interceptor configuration:
<?xml version="1.0" encoding="UTF-8"?> <jbi:jbi xmlns:jbi="http://java.sun.com/xml/ns/jbi" xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5"> <jbi:services> <jbi:provides|consumes> <!--...--> <petalsCDK:su-interceptors> <petalsCDK:send> <petalsCDK:interceptor name="myInterceptorName"> <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param> <petalsCDK:param name="myParamName2">myParamValue2</petalsCDK:param> </petalsCDK:interceptor> </petalsCDK:send> <petalsCDK:accept> <petalsCDK:interceptor name="myInterceptorName"> <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param> </petalsCDK:interceptor> </petalsCDK:accept> <petalsCDK:send-response> <petalsCDK:Interceptor name="myInterceptorName"> <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param> </petalsCDK:Interceptor> </petalsCDK:send-response> <petalsCDK:accept-response> <petalsCDK:Interceptor name="myInterceptorName"> <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param> </petalsCDK:Interceptor> </petalsCDK:accept-response> </petalsCDK:su-interceptors> <!--...--> </jbi:provides|consumes> <!--...--> </jbi:services> </jbi:jbi>
Interceptors configuration for SU (CDK)
Parameter | Description | Default | Required |
---|---|---|---|
send | Interceptor dedicated to send phase, for an exchange sent by a consumer | - | No |
accept | Interceptor dedicated to receive phase, for an exchange received by a provider | - | No |
send-response | Interceptor dedicated to send phase, for an exchange (a response) received by a consumer | - | No |
accept-response | Interceptor dedicated to receive phase, for an exchange sent (a response) by a provider | - | No |
interceptor - name | Logical name of the interceptor instance defined at component level, see CDK Component Interceptor configuration. | - | Yes |
param[] - name | The name of the parameter to use for the interceptor for this SU | - | No |
param[] | The value of the parameter to use for the interceptor for this SU | - | No |
Dedicated configuration
Provider domain definition
A provider domain is defined through a sub-element 'provider-domain' under the JBI element'services.
Attribute or element | Description | Default value | Required | Support of placeholders |
---|---|---|---|---|
id | A unique name (in the SU) to identify this provider domain configuration | - | Yes | Yes |
remote-ip | The ip or hostname of the remote provider domain gateway | - | Yes | Yes |
remote-port | The port of the remote provider domain gateway | 7500 | Yes | Yes |
remote-auth-name | A name to be shared with the provider domain that this SU will connect to | - | Yes | Yes |
certificate | The path to a shared SSL certificate used to authenticate me (relative path means in the SU, absolute path means on the filesystem) | - | No | Yes |
key | The path to a private SSL key (PKCS#8 private key in PEM format) for the SSL certificate specified with certificate (relative path means in the SU, absolute path means on the filesystem) | - | Yes if certificate is specified, else ignored | Yes |
passphrase | The passphrase to unlock the SSL key specified with key | - | Yes if key is specified and needs a passphrase, else ignored | Yes |
remote-certificate | The path to a shared SSL certificate (X.509 certificate in PEM format) used to authenticate the provider domain that this SU will connect to (relative path means in the SU, absolute path means on the filesystem) | - | Yes if certificate is specified | Yes |
propagate-all | Set to false to propagate only the services declared as provides in the SU | true | Yes | Yes |
retry-delay | Delay between retry in case of disconnection in milliseconds | 5000 | Yes | Yes |
retry-max | Maximum retries before failing to connect (a negative value means infinite) | -1 | Yes | Yes |
Service provider export
By default all service providers are exported with their current names to all consumer domains. You can select which service provider is exported in a given provider domain, evantually rewriting its names. Please use the following parameters of the element 'provides':
Attribute or element | Description | Default value | Required | Support of placeholders |
---|---|---|---|---|
domain | The identifier of a provider-domain element specified in the SU | - | Yes | No |
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 | No |
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 | No |
provider-endpoint-name | The endpoint name of a service propagated by the provider domain that this SU will connect to | - | No | No |
Service unit content
The service unit has to contain the following elements, packaged in the archive:
- the META-INF/jbi.xml descriptor file as described above.
service-unit.zip + META-INF - jbi.xml (as defined above)
Example
<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:jg="http://petals.ow2.org/components/petals-bc-gateway/version-1.0" xmlns:hello="http://petals.ow2.org"> <jbi:services binding-component="true"> <jg:provider-domain id="gw-domain-1-0"> <jg:remote-auth-name>${domain.1.gateway.secret}</jg:remote-auth-name> <jg:remote-ip>${domain.1.0.gateway.host}</jg:remote-ip> <jg:remote-port>${domain.1.0.gateway.port}</jg:remote-port> </jg:provider-domain> <jg:provider-domain id="gw-domain-1-1"> <jg:remote-auth-name>${domain.1.gateway.secret}</jg:remote-auth-name> <jg:remote-ip>${domain.1.1.gateway.host}</jg:remote-ip> <jg:remote-port>${domain.1.1.gateway.port}</jg:remote-port> </jg:provider-domain> </jbi:services> </jbi:jbi>
Configuring the component
The component can be configured through the parameters of its JBI descriptor file. These parameters are divided in following groups:
- JBI parameters that have not to be changed otherwise the component will not work,
- CDK parameters that are parameters driving the processing of the CDK layer,
- and parameters dedicated to the Gateway part:
- consumer domain,
- provider domain.
<jbi:jbi xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5" xmlns:jbi="http://java.sun.com/xml/ns/jbi" version="1.0" xmlns:rest="http://petals.ow2.org/components/rest/version-1"> <jbi:component type="binding-component"> ... <petalsCDK:acceptor-pool-size /> <petalsCDK:acceptor-retry-number /> <petalsCDK:acceptor-retry-wait /> <petalsCDK:acceptor-stop-max-wait /> <petalsCDK:processor-pool-size /> <petalsCDK:processor-max-pool-size /> <petalsCDK:processor-keep-alive-time /> <petalsCDK:processor-stop-max-wait /> <petalsCDK:time-beetween-async-cleaner-runs /> <petalsCDK:properties-file /> <petalsCDK:monitoring-sampling-period /> <petalsCDK:activate-flow-tracing /> <petalsCDK:propagate-flow-tracing-activation /> ... <g:consumer-domains-max-pool-size /> <g:provider-domains-max-pool-size /> ... </jbi:component> </jbi:jbi>
CDK parameters
The component configuration includes the configuration of the CDK. The following parameters correspond to the CDK configuration.
Parameter | Description | Default | Scope* |
---|---|---|---|
acceptor-pool-size | The size of the thread pool used to accept Message Exchanges from the NMR. Once a message is accepted, its processing is delegated to the processor pool thread. | 1 |
Runtime |
acceptor-retry-number | Number of tries to submit a message exchange to a processor for processing before to declare that it cannot be processed. | 40 |
Installation |
acceptor-retry-wait | Base duration, in milliseconds, to wait between two processing submission tries. At each try, the new duration is the previous one plus this base duration. | 250 |
Installation |
acceptor-stop-max-wait | The max duration (in milliseconds) before, on component stop, each acceptor is stopped by force. | 500 |
Runtime |
processor-pool-size | The size of the thread pool used to process Message Exchanges. Once a message is accepted, its processing is delegated to one of the thread of this pool. | 10 | Runtime |
processor-max-pool-size | The maximum size of the thread pool used to process Message Exchanges. The difference between this size and the processor-pool-size represents the dynamic threads that can be created and destroyed during overhead processing time. |
50 |
Runtime |
processor-keep-alive-time | When the number of processors is greater than the core, this is the maximum time that excess idle processors will wait for new tasks before terminating, in seconds. |
300 |
Runtime |
processor-stop-max-wait | The max duration (in milliseconds) of message exchange processing on stop phase (for all processors). |
15000 |
Runtime |
time-beetween-async-cleaner-runs | The time (in milliseconds) between two runs of the asynchronous message exchange cleaner. |
2000 |
Installation |
properties-file | Name of the file containing properties used as reference by other parameters. Parameters reference the property name using a placeholder in the following pattern ${myPropertyName}. At runtime, the expression is replaced by the value of the property. The properties file can be reloaded using the JMX API of the component. The runtime configuration MBean provides an operation to reload these place holders. Check the service unit parameters that support this reloading. The value of this parameter is :
|
- | Installation |
monitoring-sampling-period | Period, in seconds, of a sample used by response time probes of the monitoring feature. | 300 | Installation |
activate-flow-tracing | Enable ('true') or disable ('false') the flow tracing. This value can be overridden at service consumer or service provider level, or at exchange level. | true | Runtime |
propagate-flow-tracing-activation | Control whether the flow tracing activation state must be propagated to next flow steps or not. If 'true', the flow tracing activation state is propagated. This value can be overridden at service consumer level. | true | Runtime |
component-interceptors | Component interceptor configuration. See CDK Component interceptor configuration. | - | See Maven Petals plugin to known how to inject component interceptor configuration in component configuration |
* Definition of CDK parameter scopes:
- Installation: The parameter can be set during the installation of the component, by using the installation MBean (see JBI specifications for details about the installation sequence). If the parameter is optional and has not been defined during the development of the component, it is not available at installation time.
- Runtime: The paramater can be set during the installation of the component and during runtime. The runtime configuration can be changed using the CDK custom MBean named RuntimeConfiguration. If the parameter is optional and has not been defined during the development of the component, it is not available at installation and runtime times.
Note that the parameters processor-pool-size and processor-max-pool-size defaults respectively to 1 and 6 in the Gateway BC. |
Interception configuration
Interceptors can be defined to inject some post or pre-processing in the component during service processing.
Using interceptor is very sensitive and must be manipulated only by power users. A non properly coded interceptor engaged in a component can lead to uncontrolled behaviors, out of the standard process.
Example of an interceptor configuration:
<?xml version="1.0" encoding="UTF-8"?> <jbi:jbi xmlns:jbi="http://java.sun.com/xml/ns/jbi" xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5" ...> <jbi:component> <!--...--> <petalsCDK:component-interceptors> <petalsCDK:interceptor active="true" class="org.ow2.petals.myInterceptor" name="myInterceptorName"> <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param> <petalsCDK:param name="myParamName2">myParamValue2</petalsCDK:param> </petalsCDK:interceptor> </petalsCDK:component-interceptors> <!--...--> </jbi:component> </jbi:jbi>
Interceptors configuration for Component (CDK)
Parameter | Description | Default | Required |
---|---|---|---|
interceptor - class | Name of the interceptor class to implement. This class must extend the abstract class org.ow2.petals.component.common.interceptor.Interceptor. This class must be loadable from the component classloader, or in a dependent Shared Library classloader. | - | Yes |
interceptor - name | Logical name of the interceptor instance. It is referenced at service unit level to register this interceptor for services of the service unit. See SU Interceptor configuration. | - | Yes |
interceptor - active | If true, the Interceptor instance is activated for every SU deployed on the component. If false, the Interceptor can be activated: -by the InterceptorManager Mbean at runtime, to activate the interceptor for every deployed SU. -by a SU configuration |
- | Yes |
param[] - name | The name of the parameter to use for the interceptor. | - | No |
param[] | The value of the parameter to use for the interceptor. | - | No |
Dedicated configuration
These parameters drive features proposed by the component and configure the Gateway part:
- consumer domain,
- provider domain.
Parameters of the consumer domain part
Parameter | Description | Default | Required | Scope |
---|---|---|---|---|
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 |
Parameters of the provider domain part
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 |
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:
... io.netty.level=INFO ...
Business monitoring
MONIT traces
Each service provider exposed in Petals ESB is able to log MONIT traces with following information:
- on service provider invocation, when receiving an incoming request, with following attributes:
- traceCode set to provideFlowStepBegin,
- flowInstanceId set to the flow instance identifier retrieved from the incoming request,
- flowStepId set to an UUID value,
- flowStepInterfaceName set to the service provider interface name,
- flowStepServiceName set to the service provider service name,
- flowStepOperationName set to the operation of the invoked service provider,
- flowStepEndpointName set to the service provider endpoint name,
- flowPreviousStepId set to the step identifier of the previous step, retrieved from the incoming request.
- on external service provider invocation, when sending a request to the external service provider, with following attributes:
- traceCode set to provideExtFlowStepBegin,
- flowInstanceId set to the flow instance identifier retrieved from the incoming request,
- flowStepId set to an UUID value,
- flowPreviousStepId set to the step identifier of the previous step that is the internal processing of the incoming request into the BC.
- on external service provider termination, when receiving the outgoing response of the external service provider, with following attributes:
- traceCode set to provideExtFlowStepEnd or provideExtFlowStepFailure,
- flowInstanceId set to the flow instance identifier retrieved from the incoming request,
- flowStepId set to the flow step identifier defined for the external service provider invocation.
- on service provider termination, when returning the outgoing response, with following attributes:
- traceCode set to provideFlowStepEnd or provideFlowStepFailure,
- flowInstanceId set to the flow instance identifier retrieved from the incoming request,
- flowStepId set to the flow step identifier defined on incoming request receipt.
Flow tracing activation
The flow tracing (ie. MONIT traces generation) is defined according to the property 'org.ow2.petals.monitoring.business.activate-flow-tracing' of the incoming request. If the property does not exist, the parameter activate-flow-tracing of the service provider definition will be inspected. If no parameter is defined at service provider level, the component configuration parameter 'activate-flow-tracing' is used. Finally, by default, the flow tracing is enabled.
Flow tracing propagation
The flow tracing propagation from a service provider implemented with this component to another service provider is driven by the parameter 'propagate-flow-tracing-activation' of the associated service consumer definitions. If no parameter is defined at service consumer level, the component configuration parameter 'propagate-flow-tracing-activation' is used. Finally, by default, the flow tracing propagation is enabled.
Monitoring the component
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.
Common metrics
The following metrics are provided through the Petals CDK, and are common to all components:
Metrics, as MBean attribute | Description | Detail of the value | Configurable |
---|---|---|---|
MessageExchangeAcceptorThreadPoolMaxSize | The maximum number of threads of the message exchange acceptor thread pool | integer value, since the last startup of the component | yes, through acceptor-pool-size |
MessageExchangeAcceptorThreadPoolCurrentSize | The current number of threads of the message exchange acceptor thread pool. Should be always equals to MessageExchangeAcceptorThreadPoolMaxSize. | instant integer value | no |
MessageExchangeAcceptorCurrentWorking | The current number of working message exchange acceptors. | instant long value | no |
MessageExchangeAcceptorMaxWorking | The max number of working message exchange acceptors. | long value, since the last startup of the component | no |
MessageExchangeAcceptorAbsoluteDurations | The aggregated durations of the working message exchange acceptors since the last startup of the component. | n-tuple value containing, in nanosecond:
|
no |
MessageExchangeAcceptorRelativeDurations | The aggregated durations of the working message exchange acceptors on the last sample. | n-tuple value containing, in nanosecond:
|
no |
MessageExchangeProcessorAbsoluteDurations | The aggregated durations of the working message exchange processor since the last startup of the component. | n-tuple value containing, in milliseconds:
|
no |
MessageExchangeProcessorRelativeDurations | The aggregated durations of the working message exchange processor on the last sample. | n-tuple value containing, in milliseconds:
|
no |
MessageExchangeProcessorThreadPoolActiveThreadsCurrent | The current number of active threads of the message exchange processor thread pool | instant integer value | no |
MessageExchangeProcessorThreadPoolActiveThreadsMax | The maximum number of threads of the message exchange processor thread pool that was active | integer value, since the last startup of the component | no |
MessageExchangeProcessorThreadPoolIdleThreadsCurrent | The current number of idle threads of the message exchange processor thread pool | instant integer value | no |
MessageExchangeProcessorThreadPoolIdleThreadsMax | The maximum number of threads of the message exchange processor thread pool that was idle | integer value, since the last startup of the component | no |
MessageExchangeProcessorThreadPoolMaxSize | The maximum size, in threads, of the message exchange processor thread pool | instant integer value | yes, through http-thread-pool-size-max |
MessageExchangeProcessorThreadPoolMinSize | The minimum size, in threads, of the message exchange processor thread pool | instant integer value | yes, through http-thread-pool-size-min |
MessageExchangeProcessorThreadPoolQueuedRequestsCurrent | The current number of enqueued requests waiting to be processed by the message exchange processor thread pool | instant integer value | no |
MessageExchangeProcessorThreadPoolQueuedRequestsMax | The maximum number of enqueued requests waiting to be processed by the message exchange processor thread pool since the last startup of the component | instant integer value | no |
ServiceProviderInvocations | The number of service provider invocations grouped by:
|
integer counter value since the last startup of the component | no |
ServiceProviderInvocationsResponseTimeAbs | The aggregated response times of the service provider invocations since the last startup of the component grouped by:
|
n-tuple value containing, in millisecond:
|
no |
ServiceProviderInvocationsResponseTimeRel | The aggregated response times of the service provider invocations on the last sample, grouped by:
|
n-tuple value containing, in millisecond:
|
no |
Dedicated metrics
No dedicated metric is available.
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.
To integrate these alerts with Nagios, see Receiving Petals ESB defects in Nagios. |
Common alerts
Defect | JMX Notification |
---|---|
A message exchange acceptor thread is dead |
|
No more thread is available in the message exchange acceptor thread pool |
|
No more thread is available to run a message exchange processor |
|
Dedicated alerts
No dedicated alert is available.