Carbon JNDI

OSGi JNDI Services Specification

This specification defines how JNDI can be used in an OSGi application. Usage of standard JNDI APIs could break modularity in OSGi applications. Following is an extract from the OSGi JNDI services specification and it explains why.

“The JNDI as used in the Java SE environment relies on the class loading model provided by the JDK to find providers. By default, it attempts to load the JNDI provider class using the Thread Context Class Loader. In an OSGi environment, this type of Context creation is not desirable since it relies on the JNDI provider classes being visible to the JNDI client, or require it to set the Context Class Loader; in both cases breaking modularity. For modularity reasons, it is important that clients are not required to express a dependency on the implementation of services they use.”

This specification consists of following key parts.

• OSGi Service Model — How clients interact with JNDI when running inside an OSGi Framework.
• JNDI Provider Model — How JNDI providers can advertise their existence so they are available to OSGi and traditional clients.
• Traditional Model — How traditional JNDI applications and providers can continue to work in an OSGi Framework without needing to be rewritten when certain precautions are taken.
• OSGi URL Scheme — This allows JNDI based applications consumer OSGi services.

JNDI Context Manager Service

Usage of the standard JNDI API in OSGI is not recommended due to various class loading issues as explained above. Therefore OSGi JNDI services specification has introduced an OSGi service called JNDIContextManager to get InitialContext objects. This service exposes following methods. Check here for the complete OSGi JNDI API classes.

public interface JNDIContextManager {

     public Context newInitialContext() 
                throws NamingException;

     public Context newInitialContext(Map<?, ?> environment) 
                throws NamingException;

     public DirContext newInitialDirContext() 
                throws NamingException;

     public DirContext newInitialDirContext(Map<?, ?> environment)
                throws NamingException;

}

Following is a sample usage of the OSGi JNDI API. Click here for the complete source code of this sample.

public void start(BundleContext bundleContext) throws Exception {

 // 1) Retrieve the service reference instance for the  
       JNDIContextManager OSGi service. 
 ServiceReference<JNDIContextManager> contextManagerSRef =                        
     bundleContext.getServiceReference(JNDIContextManager.class);

 // 2) Get the JNDIContextManager service from the service 
       reference.
 JNDIContextManager jndiContextManager =   
      Optional.ofNullable(contextManagerSRef)
          .map(bundleContext::getService)
          .orElseThrow(() -> new RuntimeException(“
                 JNDIContextManager service is not available.”));

 // 3) Get the initial context. 
 Context initialContext = jndiContextManager.newInitialContext();

 // 4) Look up for the required data source.
 DataSource dataSource = (DataSource)   
 initialContext.lookup(“java:comp/env/jdbc/wso2carbonDB”);

}

Traditional Client Model

Existing java code which uses standard JNDI API should work in an OSGi environments. This is to make it easy to wrap legacy code as OSGi bundles and make them work in an OSGi environments. Carbon JNDI supports this aspect of the OSGi JNDI services specification. Click here for a sample bundle.

OSGi URL Scheme

This URL scheme allows you to access OSGi services in the service registry using JNDI API. This is quite useful in consuming services in places where you don’t have access to BundleContext instance.

Following code returns an OSGi service of type CarbonRuntime. If there are multiple services with the same service key, then we return the service with the highest service.ranking service property. If the values of the service.ranking properties are equal, then we returns the service with lowest service.id property. If you want to get the list of all matching services, then you should use list and listBindings methods of the JNDI Context API. You can find the complete sample here.

InitialContext context = new InitialContext();

CarbonRuntime service = 
       (CarbonRuntime) context.lookup(   
             “osgi:service/org.wso2.carbon.kernel.CarbonRuntime”);