Quick Start on WSO2 Carbon Studio

Archived Content
This article is provided for historical perspective only, and may not reflect current conditions. Please refer to relevant product page for more up-to-date product information and resources.
  • By Chathuri Wimalasena
  • 13 Oct, 2010


We assume that you have successfully installed WSO2 Carbon Studio in Eclipse and you are ready to begin with. Before we continue, make sure that you are in Java EE perspective, if it is not set by default. To set the perspective, go to Window -> Open Perspective -> Other and select Java EE. To check whether you have installed all the features successfully, go to File -> New -> Other and you will see a new catogery called "WSO2" which conatins all the Carbon Studio related features.


Creating a CApp Project

In the Carbon Studio, we have a concept called Carbon Application Project (CApp Project) which is a normal Java project, but with a different nature. Creating a CApp project is the basic for trying out all the other features. To create a CApp project, go to File -> New -> Project and select Carbon Application Project.

Give a name to the project and click Finish.

Now you will see a new CApp project has been created with the given name, according to the following structure.

CApp Project Structure

As you can see, CApp project consist of following structure.

  • Server Roles
  • java-src
  • Artifacts
  • root-artifact.xml

Now I will give you a brief introduction to each main item of the project structure.

Server Roles

If you expand Server Roles folder, you will see all the default Server Roles that are defined by Carbon Studio.

These roles are defined to WSO2 products. To each artifact, we can define a server role. Server Role will decide to which server that artifact should be deployed at the runtime. For example, if you create an ESB artifact, say a proxy service artifact, you will need to specify the Server Role as "Enterprice Service Bus". From the server side, server role is defined in the carbon.xml

You can find the carbon.xml of a server from carbon-home/repository/conf and you will see a new entry called "ServerRoles".


By default it has the value of ".*" which implies, that the server will allow all the artifacts to be deployed in to the server.If you want to specify, exact server role, you have to specify it inside above block. Suppose you want to specify "ESB" server role, then the ServerRoles element will be as below.


One carbon server can have more than one server role as well. For example, if you take ESB, it has service hosting feature as well. As a result we can give "ApplicationServer" role to ESB as well. Multiple server roles are defined in the carbon.xml as below.


Server roles that are defined in the carbon.xml will be mapped with the server roles defined to each artifact that is created in Carbon Studio. Each artifact has a configuration file called artifact.xml where you can define the server role. When you create an artifact default server role will be set initially. For example, if you create an ESB related artifact (i.e. endpoint, proxy service, sequence or local entry), "EnterpriseServiceBus"  server role will be set by default. You can change the server role if you want as well. 

When you set a server role to artifact, you will see that artifact is listed under the specified server role.

You can change the server role defined for an artifact by drag-drop as well.

After dropping, if you click on the artifact.xml of the dropped artifact, you will see that the server role has been changed accordingly.

During the deployment time, artifacts will be deployed according to the specified server role in the artifact.xml and carbon.xml of the server. For example, suppose you are deploying your carbon application project in to an  ESB server and you set  "EnterpriseServiceBus"  server role in the carbon.xml. Now artifacts which have "EnterpriseServiceBus"  server role will be deployed in to ESB server. Other artifacts which have server role other than "EnterpriseServiceBus" will be ignored during deployment.


This is where you create java classes. We need to create java classes when creating artifacts such as Axis2 Services, ESB Custom Mediators, Registry Handlers, Registry Filters and Data Service Validators. All the classes will be saved in the java-src folder.


All the artifacts that are created in Carbon Application project will be saved under Artifacts folder.


This is the main configuration file for the Carbon Application. It contains information regarding name, version, existing artifacts etc.

You can create new artifacts from the root-artifact.xml by clicking on the "Create New Artifact" button.

root-artifact.xml is the place where you define which artifacts should be included when creating the Carbon Archive (.CAR) file. You have to tick the artifacts that you wanted to be included in to CAR file from the "Existing Artifacts" list.

You can create the Carbon Archive(CAR) file from root-artifact.xml as well. To create a CAR file select "Create Archive" button at the right hand top corner.

Now you have successfully created a "Carbon Application Project" and hope you have a better understanding on the components of a CApp project. You can create artifacts in several ways. As I mentioned earlier, you can create artifacts from root-artifact.xml by clicking "Create New Artifact" button. Else you can right click on the CApp project and go to New, you will see all the Carbon Studio artifacts are listed and you can select what artifact you want to create.

As another method, you can go to File -> New -> Other and expand Artifacts category under WSO2 and select the artifact you need to create.

Congratulations !!! Now you are in a good state to go and dig deeper in to WSO2 Carbon Studio. Good Luck !!!