SVN structure

Orbit - Third-party libraries

Import third-party libraries that are required for Carbon Core and Convert them into OSGI bundles (Jar to OSGI). Here, we use a pom.xml to convert the jar to an OSGI bundle and we redefine the version as follows - third_party_library_version + wso2_version

Example: for cassandra-jdbc we use the 1.2.5 version and redefine the version as 1.2.5.wso2v1.

Kernel - Carbon core

This will be the foundation for all carbon products (WSO2 Carbon platform). This has the implementation that are common to all Carbon products, such as clustering, transport, security, logging, etc. The WSO2 Carbon Platform diagram below will provide a detailed explanation.

Platform - Carbon products

This section consists of carbon components for carbon products. platform/dependencies - Note that this section again imports third-party libraries that are needed only for specific carbon products. After obtaining the third-party dependencies, again we use platform/dependencies/orbit to convert them to an OSGI bundle.

The build sequence in platform:

• Dependencies
• Service-stubs
  • UI component - Front End
• Components
  • Server component (Processing) - Back End
  • Note that if the component wsdl is updated, then we have to update it back to the service-stubs again by building the service-stubs and then finally build the feature.
• Features
  • Create the features by combining the server component, service-stubs and UI components together. Therefore, if necessary, those features can be installed into the carbon products when instances are running
• Products
  • Finally, in this section, we build the product
    • Here, if we look at the build sequence, we first build styles then samples and then services
    • Next, we build features first and then p2-profile. This will install the features that are specific to the product.
    • Then we build distribution, which will generate the final product; thereafter, we finally build the integration, which will test the product (test automation).

Product structure

In a product, note the following folder structure.

repository/component/
                     lib/
                     dropins/
                     plugins/

• lib - If we need to use the third-party library (jar), which is not an OSGI bundle, we put it here
• dropins - If we need to use the-third party library, which is already an OSGI bundle, we put it here
• plugins - All the OSGI bundles that come as default when building the product will be included here

Let’s have a look at the structure of a Carbon component.

The server component will have the following basic folder structure.

process/
        src/
        resources/
        meta-inf/
             services.xml

We use the services.xml to expose the services at front-end (UI).

Using Axis2, we can access the services exposed at the back-end. In the service stub, using wsdl2java maven-antrun-plugin, we generate the service implementation to create the clients at front-end so that we can use it in UI.

Once the component is built, we release it as a feature, and by using p2-repo, we can install the feature into the carbon product using Feature Manager.

An Aggregate/Composite Feature consists of 3 sections.

• Server feature
• Console feature
• Common feature, if any

Get more information on Carbon Features.

WSO2 uses this architecture because it aids clustering.

Find out more about WSO2 Carbon Architecture.

Best practices

• Always create the pom from scratch. This will prevent adding unnecessary dependencies
• If there are any common dependencies for all the sub maven projects, add them to the parent pom
• Maintain the versions in parent pom as parameters and use them in sub projects to define the versions. Then, whenever there’s an update on the versions, it will be easy to update
• Do not copy/paste the code, re-use the code through OSGI, Util methods, etc
• Write tests for your code. This will gain a good percentage of code coverage. Otherwise developers will not know whether changes will break functionality or not until it is too late
• Understand Multi Tenancy and design for Multi Tenancy. Making code work for multiple tenants needs some careful designing. It may not be straightforward in some cases
• Click here for more information on best practices 

Now that you have a basic knowledge about the architecture, you can follow the tutorial on How to write a WSO2 Carbon Component.