WSO2 Carbon Context and it's usages in WSO2 Products

  • By Sanjeewa Malalgoda
  • 4 Apr, 2012


The WSO2 Carbon Context is a runtime container for your app(s). You can leverage the benefits of the Carbon Context runtime API to obtain contextual information about various actors utilizing your web apps and web services. The Carbon Context allows you to access 5 APIs and has several utility methods. Whenever you create something user specific, we create the Carbon Context for that user to store specific data.

The 5 APIs are as follows

  1. Registry
  2. User Realm
  3. Cache
  4. Billing
  5. Throttling

Billing and Throttling are however not available in the current version of WSO2 Carbon. This article will explain all 5 APIs and how you can use them in your enterprise applications.

Applies To

WSO2 Carbon 3.2.2


We can obtain an instance of a registry in this CarbonContext instance. We can use registry to store any type of data or metadata as resources including contracts, models, workflows, WSDLs, Word documents, server configurations and more. Revisions, versions with check pointing and rollback for any resource or resource collections, Full-text search, metadata search, tagging Register externally stored resources including via Microsoft Sharepoint Define behaviors that trigger automatically based on resource type.

Here are some registry operations

Get meta data, import resource, rename resource with other name, move or copy to different path.

Create,get or restore existing resource version.

Add,remove or get association.

Apply,remove or get tags for resource

Add,remove,edit,get or delete comment for given resource

Add or get ratings for given resource

Search content, create or remove links to resources

Restore, dump or delete resource

Here is the sample code on how to use registry

We can get registry instance by calling method getRegistry() by passing registry type

CarbonContext cCtx = CarbonContext.getCurrentContext(); 
Registry registry = cCtx.getRegistry(RegistryType.SYSTEM_CONFIGURATION); 
String registryType = RegistryType.SYSTEM_GOVERNANCE.toString(); 
if(registryType != null) { 
 registry = cCtx.getRegistry(RegistryType.valueOf(registryType)); 

Resource resource = registry.newResource(); 
resource.setContent("value to be add"); 
String resourcePath = "resource path"; 
registry.put(resourcePath, resource); 

02. Cache

We can obtain the default cache instance from Carbon Context. We can use cache to store some value with key. Here are few operations that we can perform on cache

Add entry to cache by providing key and value

Get value from cache by providing key

Clear cache entry by passing cache key or clear entire cache.

Here is the sample code on how to use cache

Cache example

Store data in cache as key value pairs

CarbonContext cCtx = CarbonContext.getCurrentContext(); 
cCtx.getCache().put(key, value); 

Get cached value by passing key

String content = (String)cCtx.getCache().get(key); 

03.User Realm

We can obtain the user realm in this CarbonContext instance by calling getUserRealm(). The WSO2 User Manager authenticates users from different types of user stores and currently has the capability to easily plug-in to JDBC, LDAP, and Acegi to perform authentication. For applications that need complete user management features such as add/edit/delete users, roles and permissions, the WSO2 User Manager provides an implementation of the Realm interface which supports all these operations.
Carbon Realm service has 3 Main sub items as follows

01. Authorization Manager

02.User Manager

03.Profile manager

Now we will look at each item in detail and also we will see what are the possible operations available with each item.

01. Authorization Manager

We can use authorization manager to do various authorization tests on roles and users such as

Check weather user or role authorized for given action for given resource.

Get allowed roles or users for resource by passing resource and action.

Get allowed and denied roles or users for resource.

Authorize or deny role oe user for given action for given resource.

Clear resource, user or role authorizations.

Clear roles and users action or authorization on all resources for given role name.

Populate permission tree and clear permission tree.

02.User Manager

This is used to manage users and roles on system such as

Authenticate user names with credentials.

List out users roles names and check weather user or role existing or not

Get users list for given role

Get roles list for given user

Add and delete users and roles, update credentials,

Update role list of users, update user list of role,

Set user claim values, delete user claim values and etc.

03.Profile manager

With the Profile Manager you can

Manipulate various profile configurations

Update and delete profile configurations

Set and add claims

04. Billing

Billing or bill generation can be done on a monthly basis. Bill generation is scheduled on the last day of each month. This date can be configured as you wish. When the bill generation is complete, customers or tenants are informed via email. By adding Billing Manager to the Carbon Context, programmers can access their billing information such as billing packages, monthly rates, balance forward, and monthly bill. This option will be available in a future release of WSO2 Carbon.

05. Throttling

Throttling is used to avoid excess usage of resources and bandwidth. The Throttling Manager periodically checks usage records available (the data captured by the usage metering agent), evaluates throttling rules and defines a set of actions for each and every tenant.

These actions contain what tenants can do, cannot do and what error messages that need to be shown. These rules are written in Drools. Drools is a business rules management system (BRMS) with a forward chaining inference based rules engine, more correctly known as a production rule system, using an enhanced implementation of the Rete algorithm.

In the WSO2 Stratos throttling component we use drools for throttling configurations and provide a user interface to change rules in an easier way. After evaluating throttling rules for each tenant, we will store the validation information (what each tenant is allow to do and what should be blocked) in registry with the tenant ID. By adding throttling manager to configuration context, developers can set the permissible actions (validation information) for given tenant. This throttling manager will also available with in a future release of WSO2 Carbon.


Carbon Context is strictly bound to the Carbon execution run time and is very useful for developers to access context sensitive information without knowing the underlying implementation details. In each time we create user specific environment we create Carbon Context for that user to store specific data. The 5 APIs are Registry,User Realm, Cache, Billing and Throttling. Billing and Throttling will be added to Carbon Context in future and currently it's not available. You can use these API methods within you'r applications to make them more efficient and productive. Also these API methods will help application developers to save their time in a considerable amount.


Sanjeewa Malalgoda, Software Engineer, WSO2, sanjeewa AT wso2 DOT com

About Author

  • Sanjeewa Malalgoda
  • Associate Director, Engineering | Architect at WSO2
  • WSO2