wso2 / carbon-jndi Goto Github PK

Carbon JNDI project provides an In-memory JNDI service provider implementation as well as an implementation of the OSGi JNDI Service specification.

The Java Naming and Directory Interface (JNDI) is a registry technology in Java applications, both in the Java SE and Java EE space. JNDI provides a vendor-neutral set of APIs that allow clients to interact with a naming service from different vendors.

Usually JNDI usages in Java SE heavily depends on the single flat classpath model provided by JDK. e.g. JNDI providers are loaded using the Thread context class loader. This approach does not work or not suitable for OSGi environments because this creates a dependency between JNDI client and the JNDI provider implementation. This breaks modularity defined in OSGi. Therefore OSGi JNDI service specification define following models to resolve this issue.

• 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.

• In-memory JNDI service provider implementation.
• OSGi JNDI Service specification implementation.
• Mechanism to plug in custom InitialContextFactory and ObjectFactories in an OSGi environment.

A client bundle which needs to use JNDI in OSGi should use the JNDI Context Manager service. Creating an InitialContext using new InitialContext() method is not recommended in OSGi environments due to class loading complexities.

ServiceReference<JNDIContextManager> contextManagerSRef = bundleContext.getServiceReference(
        JNDIContextManager.class);

JNDIContextManager jndiContextManager = Optional.ofNullable(contextManagerSRef)
                .map(bundleContext::getService)
                .orElseThrow(() -> new RuntimeException("JNDIContextManager service is not available."));

Context initialContext = jndiContextManager.newInitialContext();

DataSource dataSource = (DataSource) initialContext.lookup("java:comp/env/jdbc/wso2carbonDB");

This way of creating the InitialContext is also supported by the OSGi JNDI Service specification.

InitialContext initialContext = new InitialContext();  

Context envContext = initialContext.createSubcontext("java:comp/env");

DataSource dataSource = (DataSource) envContext.lookup("jdbc/wso2carbonDB");

Following service component retrieves the JNDIContextManager and create InitialContext.

public class ActivatorComponent {
    @Reference(
            name = "org.osgi.service.jndi",
            service = JNDIContextManager.class,
            cardinality = ReferenceCardinality.AT_LEAST_ONE,
            policy = ReferencePolicy.DYNAMIC,
            unbind = "unbindNDIContextManager"
    )
    protected void bindJNDIContextManager(JNDIContextManager jndiContextManager) throws NamingException {

        Context initialContext = jndiContextManager.newInitialContext();

        DataSource dataSource = (DataSource) initialContext.lookup("java:comp/env/jdbc/wso2carbonDB");
    }

    protected void unbindNDIContextManager(JNDIContextManager jndiContextManager) throws NamingException  {
        jndiContextManager.newInitialContext().close();
    }
}

An OSGI URL scheme is available for users to access services in service registry. This URL scheme can have the format osgi:service/ or osgi:framework/bundleContext No spaces are allowed between the terms. Thi OSGi URL scheme can be used to perform lookup of a OSGi service using the interface and the filter. Following is an example lookup for an OSGi service using JNDI

        FooService fooService = new FooServiceImpl();
        
        ServiceRegistration<FooService> fooServiceRegistration = bundleContext.registerService(
                FooService.class, fooService, propertyMap);
                
        Context context = jndiContextManager.newInitialContext();

        Object service = context.lookup("osgi:service/org.wso2.carbon.jndi.osgi.services.FooService");

Above lookup is equal to accessing the OSGi service from bundle context as below,

        ServiceReference serviceReference = ctx.getServiceReference("org.wso2.carbon.jndi.osgi.services.FooService", filter);
        Object ctxService = ctx.getService(reference);

If Multiple services were registered with the same Service class, all services can be obtained calling listBindings method. Calling the listBindings method will produce a NamingEnumeration object that provides Binding objects. A Binding object contains the name, class of the service, and the service object.

        NamingEnumeration<Binding> listBindings =
                context.listBindings("osgi:service/org.wso2.carbon.jndi.osgi.services.FooService");

        if(listBindings.hasMoreElements()) {

        Binding binding = listBindings.nextElement();
        
        }

When the Context class list method is called, the Naming Enumeration object provides a NameClassPair object. This NameClassPair object will include the name and class of each service in the Context. The list method can be useful in cases where a client wishes to iterate over the available services without actually getting them. If the service itself is required, then listBindings method should be used.

       NamingEnumeration<NameClassPair> namingEnumeration =
                context.list("osgi:service/org.wso2.carbon.jndi.osgi.services.FooService");

        if(namingEnumeration.hasMoreElements()) {

        NameClassPair nameClassPair = namingEnumeration.nextElement();
        
        }

For full source code, see [Carbon JNDI samples] (samples).

Use Maven snippet:

<dependency>
    <groupId>org.wso2.carbon.jndi</groupId>
    <artifactId>org.wso2.carbon.jndi</artifactId>
    <version>${carbon.jndi.version}</version>
</dependency>

Use following Maven repository for snapshot versions of Carbon JNDI.

<repository>
    <id>wso2.snapshots</id>
    <name>WSO2 Snapshot Repository</name>
    <url>http://maven.wso2.org/nexus/content/repositories/snapshots/</url>
    <snapshots>
        <enabled>true</enabled>
        <updatePolicy>daily</updatePolicy>
    </snapshots>
    <releases>
        <enabled>false</enabled>
    </releases>
</repository>

Use following Maven repository for released stable versions of Carbon JNDI.

<repository>
    <id>wso2.releases</id>
    <name>WSO2 Releases Repository</name>
    <url>http://maven.wso2.org/nexus/content/repositories/releases/</url>
    <releases>
        <enabled>true</enabled>
        <updatePolicy>daily</updatePolicy>
        <checksumPolicy>ignore</checksumPolicy>
    </releases>
</repository>

Clone this repository first (git clone https://github.com/wso2/carbon-jndi.git) and use Maven install to build mvn clean install.

Pull requests are highly encouraged and we recommend you to create a GitHub issue to discuss the issue or feature that you are contributing to.

Carbon JNDI is available under the Apache 2 License.

Copyright (c) 2016, WSO2 Inc. (http://www.wso2.org) All Rights Reserved.