Versions Compared

Old Version 18

changes.mady.by.user Former user

Saved on

compared with

New Version Current

changes.mady.by.user Former user

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

BAM Mediator is a mediator for WSO2 ESB that captures data events from the ESB mediation sequences and sends to any server with a listening Thrift port such as WSO2 BAM or WSO2 CEP servers. The Thrift port receives data events via a Thrift API. It uses a binary protocol and enables fast data transmission between the ESB and a Thrift port.

...

Info

NOTE: The steps below show how to set up WSO2 BAM as the Thrift server to which WSO2 ESB sends data events. The , but the same steps apply to any other server with a listening Thrift port, such as WSO2 CEP.

Installing BAM Mediator Aggregate Feature

  1. Download WSO2 ESB version 4.5.x or later from from http://wso2.com/products/enterprise-service-bus. Since Since BAM mediator Mediator Aggregate feature is available by default from ESB 4.6.0 onwards, you do not have to install it separately if you use a newer ESB version.

  2. Since both ESB and BAM servers are run concurrently, you must change the default port of one server to avoid any port conflicts. To change the port of ESB, apply an offset in <ESB_HOME>/repository/conf/carbon.xml file. For example,

    Code Block
    languagehtml/xml
    <!-- Ports offset. This entry will set the value of the ports defined below to the define value + Offset. e.g. Offset=2 and HTTPS port=9443 will set the effective HTTPS port to 9445-->
<Offset>2</Offset>
  3. Start the WSO2 ESB server as follows:
    • on Linux, run <ESB_HOME>/bin/wso2server.sh

    • on MS Windows, run <ESB_HOME>/bin/wso2server.bat

  4. After starting the server, log in to the ESB's management console and select Configure -> Features -> Repository Management menu.
  5. Add a new P2 repository using either a URL or from a file system. For more information on adding a P2 feature repository, see Managing the Feature Repository.
  6. Once done, navigate to Available Features tab and select the repository added in the previous step.
  7. Click Find Features button. It can take a while to list out all the available features in the feature repository. Once listed, select BAM Mediator Aggregate feature. If you can't see this feature, retry with one of the following suggestions:

    • Deselect the Group features by category check box and then click Find Features button again.
    • Try adding a more recent P2 repository. It is possible the one you have is deprecated.
    • Check for the feature in the Installed Features tab.
  8. Once the feature is selected, click Install and proceed with the installation. For more information on feature installation, see Installing and Managing Features.
  9. Once the installation is completed, restart the WSO2 ESB.

...

The following sections explain how to use the existing BAM Mediator configuration when editing a mediation sequence, using a sample scenario.

Table of Contents
maxLevel4
minLevel4

Configuring

...

server profiles and streams
Anchor
Configure BAM Server Profiles and Streams
Configure BAM Server Profiles and Streams

Before adding a BAM mediator to a mediator sequence, you must update the BAM mediator configurations. Configuration information is considered as a set of BAM server profiles, which contain transport and credential data required to connect to the BAM server. In each BAM server profile, you must define one or many event stream configurations. Streams contain Thrift API event stream related information like Stream Name, Stream Version etc. and the data to be extracted from the configuration context of the mediation sequence. The steps below explain this.

  1. Navigate to the ESB management console and select Configure -> BAM -> Server Profile menu.
  2. If there are no existing profiles, add one using the Add Profile link. If there are existing profiles, you can edit them using the Edit Profile link.
  3. Enter the profile information in the page that opens. For example,Some of the fields are described below:

    • Server Credential: admin/admin by default
    • Server Transport: Thrift as the default Protocol
    • Enable Load Balancer: Enable if want to load balance with Thrift from the client side to several hosts. Then enter comma separated connection URLs of hosts as URL Set. e.g.: tcp://10.200.3.218:7611, tcp://10.100.3.97:7611. refer more details on using load balancing publishing in this page.
    • Enable Security: If message confidentiality is required from ESB server to BAM server, select this option.
    • IP Address: IP of the BAM server's Thrift server. By default, it is the IP address of the localhost.
    • Receiver Port:  If security is not enabled, this option will have to be given. Enter 7611 by default, which is the Thrift server port.
    • Authentication Port: Port number is 100 times greater than the Receiver Port, if the latter exists. Default Authentication Port number is 7711.
    • Test Server button: Using this, availability of the BAM server can be tested for the given IP Address and the Authentication Port.
  4. Define a set of stream configurations. For example,
    Each stream must have the following defined:

    • Name: Stream Name can be any string with alpha-numeric characters.
    • Version: Stream Version distinguishes different streams with the same Stream Name. Default version should be 1.0.0.
    • Nickname: This is a user-preferred nick name to the Stream Name in alpha-numeric characters.
    • Description: A description about the particular stream defined by Stream Name/Stream Version pair. Description should also consist of alpha-numeric characters.
    • Dump header/Dump body, options: If you want to record SOAP header or SOAP body of messages respectively. 
    • Stream Properties: You can extract several types of properties from the message. Properties are divided into two as Value and Expression.
      • Value: A constant alpha-numeric string value entered to Value field is set as the property.
      • Expression: The given expression in Value field is considered as an expression and executed on the message to get the property. XPath properties and functions available in ESB are valid in the expression. (Note : At the moment, there is no way to add namespaces to xpath expressions which is to be completed in future. It is given in JIRA https://wso2.org/jira/browse/BAM-539 . As a workaround, you can use Property Mediator in ESB, to get the xpath and add it to the message context as a property which can then be captured from the BAM mediator using the get-property expression.)
      • Type drop down list: The required type to be converted in which the property should be sent via Thrift
       
    At the time you define the mediator definition, you can select a stream from the ones you define here.
  5. After Stream Payload and Stream Properties are added/edited, click Update to reflect changes in the specific stream configuration.
  6. Once all configurations are made to the BAM Server Profile, click Save.
  7. Click the BAM Server Profile link at the top of the page to see the new profiles. Similarly, you can add any number of server profiles and unique stream configurations under one BAM server profile.

Setting the backend server for ESB endpoint

In order to test the functionality of the BAM mediator, you must define a sample WSDL proxy service along with an endpoint service to the WSDL proxy service. Here are the steps to create an endpoint service:

  1. Go to <ESB_HOME>/samples/axis2Server/src/SimpleStockQuoteService and build the backend service with Apache Ant (You must have Apache Ant installed).
  2. Go to <ESB_HOME>/samples/axis2Server and run the Axis2 server.

    • In Linux: axis2server.sh
    • In Windows: axis2server.bat
  3. Test whether the proxy service WSDL exists in http://localhost:9000/services/SimpleStockQuoteService?wsdl.

Adding a proxy service to

...

the ESB

These are the steps to create a sample WSDL Proxy Service to test the BAM mediator.

  1. Go to ESB management console and select Main→Web Services→Add→Proxy Service from the side panel.
  2. Click on WSDL Based Proxy to create a new WSDL based proxy.
  3. Fill the form .as follows:
    1. Insert a suitable Proxy Service Name (eg: Simple_Stock_Quote_Service_Proxy).
    2. Set http://localhost:9000/services/SimpleStockQuoteService?wsdl as the WSDL URI.
    3. Set SimpleStockQuoteService as the WSDL Service.service
    4. Set SimpleStockQuoteServiceHttpSoap11Endpoint as the WSDL Port.
    Image RemovedImage Added
  4. Click Create.
  5. Select Click on the newly created proxy's name (here Simple_Stock_Quote_Service_Proxy ) form the shown list to see the Service Dashboard of itin this case) to go to its dashboard.

Adding

...

BAM Mediator to WSDL

...

proxy service

After creating a sample WSDL Proxy Serviceproxy service, the user can add one or more BAM mediators to the sequence of WSDL Proxy Service as follows.

  1. Go to the ESB's management console and select Main→Main > Axis2 Services→List from side panelServices > List menu.
  2. Click on Simple_Stock_Quote_Service_Proxy to go to its dashboard.
  3. Click on Edit link under category , Specific Configuration.Click on Next> button and then click Next.
  4. Select option Define Inline under category , Define In Sequence and then click on its the Create link associated with it.
  5. Click on Configuration Registry link, select [Sequence]-fault from the drop down list and click OK button. Image Removed
  6. Click on Add Child link on the Root, select Agent→BAM Agent > BAM from menus.
    Image RemovedImage Added
  7. Select BAM element from the sequence tree and go to the form appeared below.
  8. Select Server Profile from the available set of server profiles in the drop down list.
  9. Select .
  10. In the form that appears, select a Server Profile and a Stream Name from the available set of stream names with the selected BAM server profile in the drop down list.Select Stream Version from the available set of stream versions with the selected stream name in the drop down list.
    Image RemovedClick Update button. You can observe lists. Similarly, select a Stream Version. For example,
    Image Added

  11. Click Update. You can view the mediator XML generated for the BAM Mediator by

    clicking on 

    selecting the switch to source view

    link

    option.

    You can

    To go back to the design view

    by clicking on

    , click switch to design view

    link.
    The mediator XML is in the following format. (This is an example.)

    . Given below is an example how the mediator XML looks:

    Code Block
    languagehtml/xml
    <bam xmlns="http://ws.apache.org/ns/synapse">
      
    
   <serverProfile name="profile1">
         
    
      <streamConfig name="stream1" version="1.0.0" ></streamConfig>
      
    
   </serverProfile>
    
</bam>

    Image Removed

    Add more mediators to the WSDL Proxy Service if required.
  12. Click Save button.
  13. Click Next> button.
  14. Click Finish button. Now the , then Next and then Finish.
The BAM mediator is now added to the WSDL 
...
proxy service named Simple_Stock_Quote_Service_Proxy.
...
Send Messages To the ESB
At the moment all above mentioned steps should be finished to 
 Anchor
Sending Messages to ESB
Sending Messages to ESB
Sending messages to the ESB
Before you test the BAM mediator, finish all steps discussed above. In this step the user can section, we send custom messages through the previously created WSDL Proxy Service WSDL proxy service created earlier and test whether they are correctly stored in the a Cassandra database. This is only an example, but the same type of steps can be followed to use the BAM mediator in the production environment.
...
steps apply in any a production scenario, using any Thrift listening port.
  1. Download and start WSO2 BAM. Be sure to use a port different to WSO2 ESB to avoid any port conflicts (at this point, WSO2 ESB must be downloaded and started).
  2. Go to <ESB_HOME>/samples/axis2Client and build the backend service with Apache Ant as follows:
    ant stockquote -Daddurl=https://localhost:8244/services/Simple_Stock_Quote_Service_Proxy -Dmode=fullquote -Dsymbol=testString

    (Here NOTE: addurl value should must be given from the https HTTPS endpoint located in Simple_Stock_Quote_Service_Proxy's service dashboard that can be navigated by going . To see the dashboard, go to the ESB management console Main→Web Services→List from side panel and selecting , select Main > Web Services > List menu and select Simple_Stock_Quote_Service_Proxy. Any You can use a preferred string can be used instead of the testString for symbol ) Now .

    Check if the BAM mediator in the proxy service, Simple_Stock_Quote_Service_Proxy should have has dumped data extracted from the ESB to the key-space , EVENT_KS in the Cassandra database, with the column family name same as the Stream Name. Data To view data in the Cassandra database can be seen from , see the Cassandra Explorer in the BAM server. 
    Image Removed
...
  1. Given below is an example screenshot:
    Image Added