Page History

...

PrivilegedCarbonContext

PrivilegedCarbonContext is  is a special subclass of of CarbonContext, which allows you to perform privileged operations such as, setting the tenant ID and domain, starting or ending tenant flows and more. This class can only be used by Carbon components that have the permission to get hold of an instance of the the PrivilegedCarbonContext. An instance of of PrivilegedCarbonContext can  can only be obtained using the static methods outlined in Obtaining the PrivilegedCarbonContext.

Obtaining the PrivilegedCarbonContext

All of the following methods have The following method has to be statically invoked, and will return an instance of PrivilegedCarbonContext. 
For example, of PrivilegedCarbonContext.getCurrentContext()

getThreadLocalCarbonContext()

Obtain the the PrivilegedCarbonContext from  by using data stored in the current current Thread. ; PrivilegedCarbonContext.getThreadLocalCarbonContext() performs better than the other PrivilegedCarbonContext.getCurrentContext() method, as the PrivilegedCarbonContext.getCurrentContext() method will first try to get the data from MessageContext, failing which it will try ConfigurationContext and AxisConfiguration, and only finally try to get the data from the ThreadLocal variable. As . As a result, in cases like the deployers, where you can be sure that the deployment scheduler thread would set the the ThreadLocal data data, you should directly call the the getThreadLocalCarbonContext method method. You should have an idea, under which thread you are executing. It is better to resolve the the CarbonContext outside  outside that util method, as opposed to resolving the CarbonContext within the method. If calling CarbonContext.getCurrentContext returns a CarbonContext with tenantId=-1 or tenantDomain=null, that means, some upstream code has not populated the data needed for the CarbonContext; therefore, you have to first look into fixing this issue.

getCurrentContext()

This method will attempt to obtain an instance of a CarbonContext using the MessageContext which is stored as a Thread local variable. This method will lookup the MessageContext to see whether a CarbonContext is available on either the HTTP Session, or the AxisConfiguration available through the MessageContext. If an instance is not available, this method will return the current CarbonContext using data from the ThreadLocal copy.

Setting information into PrivilegedCarbonContext

If the data backed by the the PrivilegedCarbonContext has  has been created for the first time, you have to populate information (such as, tenant ID, tenant domain etc.) needed by the downstream code, so that the code can simply get hold of an instance of of CarbonContext or  or PrivilegedCarbonContext, and start using it. Populating this data can be done using the following setter methods.

...

This method sets the tenant ID in the the CarbonContext. The tenant domain corresponding to this tenant ID will not be resolved.

...

This method sets the tenant ID in the the CarbonContext. The tenant domain corresponding to this tenant ID will be resolved, if if resolveTenantDomain is  is set to to true.

setUsername(String username)

If there is a user logged in, this method sets that user's username in the the PrivilegedCarbonContext.

setTenantDomain(String tenantDomain)

This method sets the tenant domain on this this CarbonContext instance instance. This method will not automatically resolve the tenant ID based on the tenant domain.

...

This method sets the tenant domain on this this CarbonContext instance instance. If If resolveTenantId is  is set to to true, the tenant ID corresponding to the the tenantDomain will be resolved internally.

...

This method sets the tenant specific specific UserRealm.

setRegistry(RegistryType type, Registry registry)

...

try{

   PrivilegedCarbonContext.startTenantFlow();
    PrivilegedCarbonContext privilegedCarbonContext =
               PrivilegedCarbonContext.getCurrentContextgetThreadLocalCarbonContext()
   privilegedCarbonContext.setTenantId(tenantId);
   privilegedCarbonContext.setTenantDomain(tenantDomain);
   // set other stuff like registry etc. if needed

  doSomething();
} finally {
   PrivilegedCarbonContext.endTenantFlow();
}

Inside the the doSomething() method method, now if you call call CarbonContext.getCurrentContext or  or PrivilegedCarbonContext.getCurrentContext or PrivilegedCarbonContext.getThreadLocalCarbonContext, you will get the newly created data. The code that started the tenant flow is referred to as the upstream code, and all the code that gets called after starting the tenant flow are referred to as the downstream code. One example where you may start a tenant flow is when the super tenant runs tasks on behalf of a tenant. In the latter mentioned instance it may have a loop; and within that loop start a tenant flow for tenants, run the task as that tenant, get back to the super tenant mode (endTenantFlow), switch back to another tenant(startTenantFlow), run the task of the second tenant, get back to super tenant mode, and so on.

PrivilegedCarbonContext.startTenantFlow()

This method starts a new tenant flow, and creates a new holder for tenant data. Thereafter, until until endTenantFlow is  is called, the getCarbonContext() and  and getThreadLocalCarbonContext()methods will return the data related to the newly created tenant data holder. Once Once startTenantFlow is  is called, set the tenant ID, tenant domain and other tenant specific data.

...

This methods will end the tenant flow and restore the previous previous CarbonContext.

The following diagram depicts during an execution of a thread, how we can start as a super tenant, then switch to tenant 'x' and carryout some actions, and later switch to tenant 'y' and carryout some actions and continue.

Image RemovedImage Added

Getting Information from PrivilegedCarbonContext

• getTenantDomain(boolean resolve)
• getTenantId(boolean resolve)
• getRegistry(RegistryType type)
• Object getOSGiService(Class clazz)
• List<Object> getOSGiServices(Class clazz)

getTenantDomain(boolean resolve)

This method retrieves the tenant domain, and if if resolve is  is set to to true, it will try to resolve the domain using the tenant ID.

...

This method retrieves the tenant ID, and if if resolve is set to true, it will try to resolve the tenant ID using the tenant domain.

...

This method retrieves the Registry of the tenant of type type RegistryType.

RegistryTypes

• USERSYSTEM_CONFIGURATION - The system configuration registry of the currently logged in usertenant.USER
• SYSTEM_GOVERNANCE - The governance registry of the currently logged in user.
• SYSTEM_CONFIGURATION - The configuration registry of the system.
• LOCAL_REPOSITORY - The local repository of the systemtenant.

Object getOSGiService(Class clazz)

This method obtains the first instance of the OSGi services found for the interface or class clazz.class clazz.

List<Object> getOSGiServices(Class clazz)

This method obtai ns all OSGi service instances found for interface or class clazz. 

Miscellaneous Methods

• public static void unloadTenant(int tenantId)
• public static void destroyCurrentContext()

...

public static void destroyCurrentContext()

This method destroys the current current ThreadLocal CarbonContext.

CarbonContext

The The CarbonContext is  is designed for normal tenants to retrieve information from the Carbon runtime. In the super tenant mode, for this to work the relevant data has to be set so that tenants can retrieve information using the CarbonContext.

...

• getThreadLocalCarbonContext()

• getCurrentContext()

getThreadLocalCarbonContext()

This methods method obtains the the CarbonContext from  by using the data stored in the current thread. : The CarbonContext.getThreadLocalCarbonContext() method performs better than the other CarbonContext.getCurrentContext() method.

...

()

...

This method will attempt to obtain an instance of a CarbonContext using the MessageContext, which is stored as a ThreadLocal variable, and will lookup the MessageContext to see whether a CarbonContext is available on either the HTTP Session or the AxisConfiguration available through the MessageContext. If an instance is not available, this method will return the current CarbonContext, using data from the ThreadLocal copy.

Retrieving information

The following methods allow tenants to retrieve information relevant to those tenants from the Carbon runtime.

...

• USER_CONFIGURATION - The configuration registry of the currently logged in user.
• USER_GOVERNANCE - The governance registry of the currently logged in user.
• SYSTEM_CONFIGURATION - The system configuration registry of the tenantconfiguration registry of the system.
• SYSTEM_GOVERNANCE - The governance registry of the system.
• LOCAL_REPOSITORY - The local repository of the system.

UserRealm getUserRealm()

...

This method obtains a JNDI-context with the given initialization properties.

Method description
properties - the properties required to create the JNDI-context instance.
NamingException - if the operation fails, the naming exception will be thrown.

Context getJNDIContext() throws NamingException

This method obtains a JNDI-context.

Method description 
NamingException NamingException - if the operation fails, the naming exception will be thrown.

...

This method is used to discover a set of service endpoints belonging the defined scopes. Therefore, when this method is executed the list of service endpoints will be returned.

Method description
scopes - the scopes in which to look-up for the service.