This document contains all the use cases related to the Petals BC Gateway component.
Use cases are ordered by their complexity, from the most simple to the most complex ones.


h1. Simple Use Cases

h2. Proxy SOAP over 2 Petals ESB nodes connected using the Petals BC Gateway

{tip}This use case runs with the Petals ESB Enterprise Pack 5.2.0. Its source code is available [here|https://svn.petalslink.org/svnroot/trunk/product/dev/prod/petals/petals-samples/petals-samples-gateway-soap-proxy].{tip}

The goal of this use-case is to show you how to configure the service units of BS SOAP and BC Gateway on two Petals ESB linked together create a SOAP proxy:
* to import into Petals ESB #2, an external service,
* to connect Petals ESB #1 and #2 with the Petals BC Gateway. The connection is secured using SSL,
* to export to outside an internal Petals service of the Petals ESB #1.

To secure the connection between both Petals ESBs, we rely on SSL that takes care of the actor certifications and the encryption:
* the provider domain is certified/authenticated at consumer domain level through the public part of the its certificate,
* and, the consumer domain is certified/authenticated at provider domain level through the public part of the its certificate.

!Overview.png!

h3. About the external service provider

An external service provider 'ArticleServiceContinuation' is available as [CXF webservice|https://svn.petalslink.org/svnroot/trunk/product/dev/prod/petals/petals-samples/petals-samples-soap/cxf-server] at [http://localhost:8450/articleServiceContinuation?wsdl].

To start it, just execute the following Maven command line in its directory project:
{code}
mvn clean verify exec:java
{code}

h3. About the deployment architecture

Our sample deployment architecture is composed of two Petals ESB (#1 and #2) connected with the Petals BC Gateway. In a Petals BC Gateway point of view, Petals ESB #1 is the consumer domain, and Petals ESB #2 is the provider domain. Each Petals ESB is based on a standalone Petals topology.

h3. Running the use case

h4. Generating certificates

h5. Generating the provider domain certificate

The provider domain certificate can be generated through specific keystore 'Provider Domain' containing the private/public key pair of the provider domain, as following command line:
{code}
keytool -genkey -alias provider-domain-key -keyalg RSA -keysize 2048 \
-dname "CN=Provider Domain, OU=Petals, O=Linagora, L=Grasse, ST=AM, C=FR" \
-storetype PKCS12 -storepass providerdomainpwd -keystore /tmp/provider-domain.pfx
keytool -exportcert -rfc -alias provider-domain-key \
-keystore /tmp/provider-domain.pfx -storepass providerdomainpwd \
-file /tmp/provider-domain-cert.pem
openssl pkcs12 -in /tmp/provider-domain.pfx --password pass:providerdomainpwd \
-nodes -nocerts -legacy \
-out /tmp/provider-domain-private-key.pk12.pem
openssl pkcs8 -topk8 \
-in /tmp/provider-domain-private-key.pk12.pem -inform PEM \
-out /tmp/provider-domain-private-key.pk8.pem -outform PEM -v1 PBE-SHA1-3DES \
-passout pass:providerdomainpwd
{code}

h5. Generating the consumer domain certificate

The consumer domain certificate can be generated through specific keystore 'Consumer Domain' containing the private/public key pair of the consumer domain, as following command line:
{code}
keytool -genkey -alias consumer-domain-key -keyalg RSA -keysize 2048 \
-dname "CN=Consumer Domain, OU=Petals, O=Linagora, L=Grasse, ST=AM, C=FR" \
-storetype PKCS12 -storepass consumerdomainpwd -keystore /tmp/consumer-domain.pfx
keytool -exportcert -rfc -alias consumer-domain-key \

h4. Starting the consumer domain

With a first fresh installation of the Petals ESB ZIP archive exploded in directory '{{consumer-domain}}', launch the default standalone topology:
{code}
~/consumer-domain/petals-esb-default-zip-5.2.0/bin$ ./petals-esb.sh
___ ____ __ ___ __ ____ ____ ____ ___
/ _ \ / __// /_ / _ | / / / __/ / __// __// _ )
/ ___// _/ / __// __ | / /__ _\ \ / _/ _\ \ / _ |
/_/ /___/ \__//_/ |_|/____//___/ /___//___//____/

Initializing logging subsystem
2024/02/19 11:12:26,005 GMT+0100 INFO [Petals.Launcher] : Logging system initialised
2024/02/19 11:12:26,016 GMT+0100 INFO [Petals.Launcher] : Initializing container's classloader...
2024/02/19 11:12:26,040 GMT+0100 INFO [Petals.Launcher] : Initializing server...
2024/02/19 11:12:26,529 GMT+0100 INFO [Petals.Launcher] : Starting server...
sample-0 2024/02/19 11:12:26,538 GMT+0100 INFO [Petals.System.Extensions.PreExtensionsManager] : Pre-extension found but not activated: Petals Embedded Registry Overlay
sample-0 2024/02/19 11:12:26,669 GMT+0100 INFO [Petals.Communication.RMIConnector] : JMX RMI server started at : service:jmx:rmi:///jndi/rmi://localhost:7700/PetalsJMX
sample-0 2024/02/19 11:12:26,684 GMT+0100 INFO [Petals.Communication.TopologyService] : Using standalone shared area implementation for static one-container domain: org.ow2.petals.microkernel.communication.sharedarea.StandaloneSharedAreaImpl
sample-0 2024/02/19 11:12:26,709 GMT+0100 INFO [Petals.Communication.TopologyService] : Shared area loaded
sample-0 2024/02/19 11:12:26,722 GMT+0100 INFO [Petals.Extensions.AutoLoaderService] : Petals extension "Autoloader" started.
sample-0 2024/02/19 11:12:26,723 GMT+0100 INFO [Petals.System.Extensions.PostExtensionsManager] : Post-extension loaded: Petals ESB Autoloader
sample-0 2024/02/19 11:12:26,740 GMT+0100 INFO [Petals.Transporter.NioTransportProtocol.NioServerAgent] : The NIO transporter server is ready to process requests on /0.0.0.0:7800.
sample-0 2024/02/19 11:12:26,753 GMT+0100 INFO [Petals.Server] : Server STARTED
{code}

h4. Starting the provider domain

With a first fresh installation of the Petals ESB ZIP archive exploded in directory '{{provider-domain}}':
* configure ports to avoid conflicts with the ones of the consumer domain. Edit the file '{{topology.xml}}' and update values for '{{rmi-port}}' and '{{tcp-port}}', for example to '{{7710}}' and '{{7810}}',
* and, launch the default standalone topology:

{code}
~/provider-domain/petals-esb-default-zip-5.2.0/bin$ ./petals-esb.sh
___ ____ __ ___ __ ____ ____ ____ ___
/ _ \ / __// /_ / _ | / / / __/ / __// __// _ )
/ ___// _/ / __// __ | / /__ _\ \ / _/ _\ \ / _ |
/_/ /___/ \__//_/ |_|/____//___/ /___//___//____/

Initializing logging subsystem
2024/02/19 11:12:26,005 GMT+0100 INFO [Petals.Launcher] : Logging system initialised
2024/02/19 11:12:26,016 GMT+0100 INFO [Petals.Launcher] : Initializing container's classloader...
2024/02/19 11:12:26,040 GMT+0100 INFO [Petals.Launcher] : Initializing server...
2024/02/19 11:12:26,529 GMT+0100 INFO [Petals.Launcher] : Starting server...
sample-0 2024/02/19 11:12:26,538 GMT+0100 INFO [Petals.System.Extensions.PreExtensionsManager] : Pre-extension found but not activated: Petals Embedded Registry Overlay
sample-0 2024/02/19 11:12:26,669 GMT+0100 INFO [Petals.Communication.RMIConnector] : JMX RMI server started at : service:jmx:rmi:///jndi/rmi://localhost:7710/PetalsJMX
sample-0 2024/02/19 11:12:26,684 GMT+0100 INFO [Petals.Communication.TopologyService] : Using standalone shared area implementation for static one-container domain: org.ow2.petals.microkernel.communication.sharedarea.StandaloneSharedAreaImpl
sample-0 2024/02/19 11:12:26,709 GMT+0100 INFO [Petals.Communication.TopologyService] : Shared area loaded
sample-0 2024/02/19 11:12:26,722 GMT+0100 INFO [Petals.Extensions.AutoLoaderService] : Petals extension "Autoloader" started.
sample-0 2024/02/19 11:12:26,723 GMT+0100 INFO [Petals.System.Extensions.PostExtensionsManager] : Post-extension loaded: Petals ESB Autoloader
sample-0 2024/02/19 11:12:26,740 GMT+0100 INFO [Petals.Transporter.NioTransportProtocol.NioServerAgent] : The NIO transporter server is ready to process requests on /0.0.0.0:7810.
sample-0 2024/02/19 11:12:26,753 GMT+0100 INFO [Petals.Server] : Server STARTED
{code}

h4. Deploying Petals service configurations

echo "petals-esb-2.gw-domain.auth-name=s3cr3t" >> /tmp/petals-placeholders.properties
echo "petals-esb-2.gw-domain.certificate-file=/tmp/provider-domain-cert.pem" >> /tmp/petals-placeholders.properties
echo "petals-esb-2.gw-domain.private-key-file=/tmp/provider-domain-private-key.pk8.pem" >> /tmp/petals-placeholders.properties
echo "petals-esb-2.gw-domain.private-key-passphrase=providerdomainpwd" >> /tmp/petals-placeholders.properties
{code}

The following Petals artifacts must be deployed on the consumer domain:
{code}
petals-cli.sh -c -- deploy -u mvn:org.ow2.petals/petals-bc-soap/5.0.1/zip
petals-cli.sh -c -- deploy -u mvn:org.ow2.petals/petals-bc-gateway/1.1.0/zip -D propertiesFile=file:///tmp/petals-placeholders.properties
petals-cli.sh -c -- deploy -u mvn:org.ow2.petals.samples.gateway-soap-proxy/sa-gateway-soap-proxy-consumer-domain/1.0.0-SNAPSHOT/zip
{code}

And, the following Petals artifacts must be deployed on the provider domain:
{code}
petals-cli.sh -h localhost -n 7710 -u petals -p petals -c -- deploy -u mvn:org.ow2.petals/petals-bc-soap/5.0.1/zip -D httpPort=8085
petals-cli.sh -h localhost -n 7710 -u petals -p petals -c -- deploy -u mvn:org.ow2.petals/petals-bc-gateway/1.1.0/zip -D propertiesFile=file:///tmp/petals-placeholders.properties
petals-cli.sh -h localhost -n 7710 -u petals -p petals -c -- bc-gateway.add-transport-listener -i default -p 7910
petals-cli.sh -h localhost -n 7710 -u petals -p petals -c -- deploy -u mvn:org.ow2.petals.samples.gateway-soap-proxy/sa-gateway-soap-proxy-provider-domain/1.0.0-SNAPSHOT/zip
{code}

h4. Invoking the service with SoapUI

The service {{ArticleServiceContinuation}} is available through HTTP (see http://localhost:8084/petals/services/ArticleServiceContinuation?wsdl)

Use SoapUI to invoke ! Sample requests are available into the [SoapUI project|https://svn.petalslink.org/svnroot/trunk/product/dev/prod/petals/petals-samples/petals-samples-gateway-soap-proxy/su-SOAP-consume/src/main/soapui/Petals-ESB---Samples---SOAP-Proxy-over-tow-Petals-domains-soapui-project.xml].

h1. Complex Use Cases

These use cases involve several Petals components including the Petals BC Gateway component.

{contentbylabel:labels=uc-gateway|showLabels=false|showSpace=false}