Messaging User Guide
From Ogce
Contents |
OGCE WS Messenger
Build WS-Messenger from Source
Prerequisites
- Java 1.5
- Maven (tested on v 2.2.0)
Steps
- Check out the code from SVN
- Copy axis2 libraries (AXIS2_HOME/libs/*) to following folder (These libraries will be bundled along with messenger servlet):
<PROJECT_DIR>/messenger/axis2_dependencies
- Go to project folder and type (-Dmaven.test.skip=true will skip testing phase):
mvn clean install -Dmaven.test.skip=true
- Executable are located at:
| Executable | Description |
|---|---|
| broker-<version>.jar
(should be used to write client code) | <PROJECT_DIR>/broker/target |
| broker-<version>.aar
(should be used run messenger) | <PROJECT_DIR>/broker/target |
| messenger-<version>.war
(if message delivery has to decoupled from broker deploy this in a servlet container) | <PROJECT_DIR>/messenger/target/ |
| Database scripts
(Contains a scripts to create mysql tables needed for ws-messenger) | <PROJECT_DIR>/broker/src/main/resources/database_scripts |
| wsmg.broker.properties
(sample configuration file for running broker or messenger servlet) | <PROJECT_DIR>/ant/resources |
| msgbox-<version>.aar
(should be used run message box) | <PROJECT_DIR>/msgbox/target |
| msgbox-<version>.jar
(should be used write client code) | <PROJECT_DIR>/msgbox/target |
| workflow-tracking-<version>.jar
(should be used to track work flows) | <PROJECT_DIR>/workflow-tracking/target |
Assemble WS-Messenger Binary Distribution
- Copy desired Axis2 standalone distribution to (e.g. <PROJECT DIR>/distribution/axis2_releases/axis2-1.5.1)
<PROJECT_DIR>/distribution/axis2_releases
- In pom.xml ( <PROJECT_DIR>/distribution/pom.xml) at set the property 'used.axis2.release' to desired used Axis2 version (e.g. 1.5.1)
- Run the command 'mvn clean package'
- The binary distribution is located at
<PROJECT DIR>/distribution/target
Configure WS-Messenger
given below are the configurations for broker. configuration file should be named as "wsmg.broker.properties". This should be included in the class path (e.g. <BROKER_DISTRIBUTION_DIR>/) when broker starts.
| Configuration | Description | Sample Value |
|---|---|---|
| broker.jdbc.driver | Data base driver. | com.mysql.jdbc.Driver |
| broker.jdbc.url | Url string used to connect the data base | jdbc:mysql://localhost:3306/wsmg?user=wsmg&password=wsmg |
| broker.start.delivery.thread | If set to true message delivery thread will be started.
Applicable when only running broker. user must set this to 'false' if he wishes run message deliver component separately ( e.g. messenger servlet) | true or false |
| broker.socket.timeout | Connection time out in milliseconds.
Set this to '0' if user wishes connections never to be timed out. (not recommended) | 4000 |
| broker.storage.type | Specifies message, subscriptions should be stored in a database or not. | memory or persistent |
| broker.delivery.method | Specifies what mechanism to be used deliver messages.
serial – single theaded delivery parallel – dynamic thread pool based delivery pcrew – fixed thread pool based delivery | serial , parallel or pcrew |
| broker.msg.delivery.retries | number of message delivery failures before a url become black listed (default is 2) | 2 |
| consumer.expiration.time.gap | time period (in seconds) a url will be kept blacklisted (default is 5 seconds) | 5 |
| sending.batch.size | maximum number of messages to be send to a one consumer/url at time. applicable if 'broker.delivery.method' is 'pcrew'
(default is 10) | 10 |
| sending.thread.pool.size | size of the thread pool. only applicable if 'broker.delivery.method' is 'pcrew'. (default is 4) | 4 |
Run Ws-messenger
User has the option to run broker in several modes. Steps for each mode is given below.
Run standalone version supplied with binary distribution
- Unzip binary distribution.
- Create (mysql) data base tables using the script given below:
<extracted location>/database_scripts/mysqlCreationScript.sql
- Change default configurations if needed.
- - configuration file is located at:
<extracted location>/standalone-server/wsmg.broker.properties
- Run axis2 server by running the command:
- Linux -
<extracted location>/standalone-server/bin/axis2server.sh
- Windows -
<extracted location>/standalone-server/bin/axis2server.bat
Run Ws-messenger using axis2 servlet
(Tested on tomcat v 6.0.20 & axis2 v1.5.1)
- Copy broker aar file to axis2 distribution accordingly.
- Create database tables
- Set configurations appropriately:
- copy configuration file ( named wsmg.broker.properties) to
<Axis-servlet>/webapps/axis2/WEB-INF/classes
Note: a sample configuration file is located at:
<PROJECT_DIR>/ant/resources/wsmg.broker.properties
- Start tomcat server.
Run Ws-messenger using a external axis2 distribution
- Copy broker aar file to following location:
<AXIS2_DIST_HOME>/repository/services
- Copy wsmg.broker.properties file to <AXIS2_DIST_HOME>
- start axis2 server.
Run message delivery component separately
- Configure and run broker using any mode previously described, with following configuration:
broker.start.delivery.thread=false
- Deploy messenger servlet.
- Set configurations appropriately.
<TOMECAT_HOME>/webapps/messenger/WEB-INF/classes/wsmg.broker.properties
- Start tomcat.
Run Samples
Sample programs are located at: <Extracted location>/client-api/samples
Prerequisites:
- Apache Ant (tested on 1.7.1)
Steps:
- Run WS-messenger in any mode previously described.
- Configure samples following the instructions given in README.TXT (located in every sample directory)
- Run following command:
ant run
Run WS-Notification Viewer
method 1:
- Extract binary distribution.
- Go to following location:
<extracted location>/gui/
- execute script startGUI.sh
method 2:
Following command will run the WS-Notification Viewer, provided that 'BROKER_CLASS_PATH' contain paths to axis2 libraries and broker-<version>.jar
java -classpath "$BROKER_CLASS_PATH" wsmg.gui.NotificationViewer
OGCE Message Box
Build OGCE-Message Box
Message box is a sub module of OGCE – WS Messenger, therefore once the OGCE-Messenger is built message box binaries will be available at following locations:
| Executable | Location |
|---|---|
| msgbox-<version>.jar
(should be used to write client code) | <PROJECT_DIR>/msgbox/target |
| msgbox-<version>.aar
(should be used run msgbox) | <PROJECT_DIR>/msgbox/target |
Assemble message box distribution
Message box binaries are automatically included in distribution.
Configure message box
| Configuration | Description | Sample Value |
|---|---|---|
| msgBox.jdbc.driver | Data base driver. | com.mysql.jdbc.Driver |
| msgBox.jdbc.url | Url string used to connect the data base | jdbc:mysql://127.0.0.1:3306/wsmg?user=wsmg&password=wsmg |
| msgBox.usedatabase | If set to 'true' use MySql database. If set to 'false' use inmemory implementation. In this scenario database settings i.e-broker.jdbc.url is not required. | true or false |
Run Message Box
- Unzip binary distribution.
- Create (mysql) data base tables using the script given below:
<extracted location>/database_scripts/msgbox_tables.sql
- Set configuration values by editing msgBox.properties file located in extracted folder.
- Copy ‘msgBox.properties’ file into Axis2’s WEB-INF/classes folder.
- Now Copy msgbox-1.0.aar into Axis2 webapps folder if Axis2 runs as a standalone application or in to axis2/WEB-INF/services folder if Axis2 runs as a servlet with Tomcat.
