Archive for January 12, 2010

WSO2 ESB Directories and Configuration Files

The WSO2 ESB is an Open Source Enterprise Service Bus (ESB) available based on the lightweight Apache Synapse ESB. Refer installation guide for complete detailed instructions for installing WSO2 ESB. When WSO2 ESB binary distribution is extracted, the top level directory structure is as follows,

1. bin : Consists of the required set of shell scripts and batch files for Unix/Linux users and Windows users respectively. These scripts can be used to start WSO2 ESB, start available samples, change administrator password, etc.

2. conf : All the global configuration files are stored here.

– axis2.xml:

Because WSO2 ESB is based on Apache Synapse ESB which uses the Apache Axis2 SOAP engine, it can be used for WSO2 ESB also as a SOAP engine. The global configuration or the underlying transport and Web services support of the Axis2 engine is specified in axis2.xml. The settings configured in the axis2.xml file are directly applied to the server at startup time. In axis2.xml file, there are clearly mentioned how the configurations can be done.

The HTTP and HTTPS ports used by the ESB HTTP-NIO transport can be configured by following line under ‘transportReceiver’ sections in both HTTP and HTTPS.

<parameter name="port" locked="false">8280</parameter>

The bind address values can also be configured if necessary. To configure the bind address for the server, define the following parameter under the HTTP and HTTPS transport receiver configuration,

<parameter name="bind-address" locked="false">hostname or IP address</parameter>

Bind address is used to restrict the server to listening to a single address, and can be used to permit multiple servers on the same machine listening to different IP addresses.

– synaps.xml:

The synapse.xml configures the mediation rules and configuration for the ESB. Mediation sequences can be defined within the synapse.xml configuration or within the Registry.

Therefore synaps.xml should include the following registry definition.

<syn:registry provider="org.wso2.carbon.mediation.registry.WSO2Registry">
        <syn:parameter name="cachableDuration">15000</syn:parameter>
</syn:registry>

The synaps.xml holds two special sequences named as “main” and “fault”. These may be defined within the synapse.xml, or externally via the Registry. If both are not found, those will be created automatically.

– carbon.xml:

The main server configuration file and this represents all the system properties such as carbon.home, WebContextRoot, front end back end separation configuration, axis2 related configuration etc.

– registry.xml:

There is an embedded WSO2 G-Reg which uses the embedded H2 database in ESB. The configurations related to this embedded registry are stored in the registry.xml file.

<ReadOnly>false</ReadOnly>

Here in <ReadOnly> tags ‘false’ is set so that the ESB will be able to store resources or write values to the registry and reading the existing resources. By making this value ‘true’ the ESB can be made only to read the existing resources avoiding storing resources and reading values to the registry.

The embedded registry instance can be pointed to a database other than the default embedded H2 database. To change the database used by the registry or change the location of the database files, highlighted components of the following section need to edited.

<dbconfig name="wso2registry">
        <url>jdbc:h2:database/WSO2CARBON_DB</url>
        <userName>wso2carbon</userName>
        <password>wso2carbon</password>
        <driverName>org.h2.Driver</driverName>
        <maxActive>50</maxActive>
        <maxWait>60000</maxWait>
        <minIdle>5</minIdle>
</dbconfig>

WSO2 ESB can work with a remotely hosted WSO2 G-Reg instance also. This is very important and useful in production deployment scenarios. Using this feature, several WSO2 ESB instances can work with the same registry and database with effectively sharing the configurations and other resources among all the ESB instances.

– transport.xml :

This can be used to change the ports used by the ESB management console and other parameters by changing the default configuration. By default the management console would accept HTTPS requests on port 9443.

<parameter name="port">9443</parameter>

3. database

Embedded H2 database used by WSO2ESB and associated files are contained in this directory. The database is setup during the first startup of the ESB. Therefore this directory is required when the ESB is using the embedded H2 database. The embedded registry can be cleaned by passing –cleanRegistry argument to ESB startup script.

<!– @page { margin: 0.79in } P { margin-bottom: 0.08in } –>

4. Dbscripts

There are scripts for creating required database tables on different database management systems like MySql, Oracle, derby, MsSql, etc. These scripts are stored in this directory.

5. lib
Contains all the jar files and OSGi bundles required by the embedded Tomcat instance including the log4j.properties file used by the ESB.

6. logs
All the server logs created during server runtime will be stored here.

7. repository
All the OSGi bundles, service artifacts, modules, sample configurations and related resources used by the WSO2 ESB instance and all the necessary OSGi bundles at server runtime. External dependency jars can be added
to repository/components/lib or repository/components/extensions. These jars will be automatically converted into OSGi bundles on ESB startup. After copying the relevant jars to the relevant locations the server must be restarted.

8. resources
Contains additional resources required by WSO2 ESB.

9. samples
Contains the sample Axis2 server, sample Axis2 client, source code of the sample services and clients and the ANT scripts required to build and run them.

<parameter name="port">9443</parameter>
Advertisements