Access property files via JNDI lookups. Get a DataSource from JNDI.
Switch branches/tags
Clone or download
Latest commit be69a30 Mar 3, 2018


Simple-JNDI is intended to solve two problems. The first is that of finding a container independent way of opening a database connection, the second is to access application configurations easily from anywhere in your application. If your only intention is to test or use classes that depend on Tomcat's JNDI environment outside of Tomcat or you are only in need of a JNDI based DataSource give TomcatJNDI (not to be confused with Simple-JNDI) a try.

Simple-JNDI's JNDI implementation is entirely memory based. No server instance is started. The structure of a root directory serves as a model for the contexts structure. The contexts get populated with Objects defined by .properties files, XML files or Windows-style .ini files. Of course you can bind Objects programmatically to contexts too.



or download from here.

Installing Simple-JNDI

After download, installing Simple-JNDI is as simple as adding the simple-jndi jar to your classpath. Some of the features do however need additional dependencies. To get connection-pooling you will need commons-dbcp, commons-dbcp2 or HikariCP.

Setting up Simple-JNDI

This is where all the work goes in a Simple-JNDI installation. Firstly you need a file, which somehow needs to go into your classpath. This needs two mandatory values:

This property, java.naming.factory.initial, is a part of the jndi specification.

The second required parameter,, is the location of your simple-jndi root, which is the location in which simple-jndi looks for values when code asks for them. The following code block details a few examples with explanatory comments.

# absolute directory, using the default file protocol
# relative directory, using the default file protocol
# NEW in 0.13.0: Specify a list of files and/or directories. Separate them by the platform specific path separator. 
# From 0.17.2 on you should also set to the separator used in to ensure platform independency of your file.

Not required, but highly recommended is setting = true too.

See also Load property files with any extension from any location.

Declaratively create your contexts and context objects

Simple-JNDI stores values in multiple .properties, xml or ini files. The files are located under a root directory as specified with the property.

Directory names and file names become part of the lookup key. Each delimited tree-node becomes a JNDI Context, while the leaves are implementations. The only exceptions are pseudo sub-values, which you will see with DataSources.

The easiest way to understand is to consider an example. Imagine a file-structure looking like,


in which the file looks like:


The following pieces of Java are all legal ways in which to get values from Simple-JNDI. They assume that you set and that you instantiated ctxt by executing 'InitialContext ctxt = new InitialContext();'.

  • String value = (String) ctxt.lookup("application1.users.admin")
  • String value = (String) ctxt.lookup("application1.users.quantity")
  • String value = (String) ctxt.lookup("application1.users.enabled")

Further information.

Lookup typed properties, not only Strings

In the above example it would be favourable to lookup "quantity" as Integer and "enabled" as Boolean. To achieve this you can type your properties:


Thereafter you can call typed properties:

    Integer value = (Integer) ctxt.lookup("application1.users.quantity");
    Boolean value = (Boolean) ctxt.lookup("application1.users.enabled");

The following types are supported: Byte, Short, Integer, Long, Float, Double, Character.

Also supported are Maps (0.16.0):

    city.type = java.util.Map
    city.citizens = 3.520.031 = Berlin

Now you can lookup a Map:

    Map myMap = (Map) ctx.lookup("city");
    assertEquals("3.520.031", myMap.get("citizens"));

For further map examples see here.

Note that you have to write "quantity/type=java.lang.Integer" and "enabled/type=java.lang.Boolean" when setting "" unless you follow this description. And as you might anticipate already: "type" is a reserved word with Simple-JNDI.

See also
A more elegant way to lookup typed properties (New in 0.14.0)
Load self-defined types as Beans (New in 0.15.0)
Instantiate beans and set their properties (New in 0.17.0)

Lookup pathes with "/" as context separator instead of "."

So far we used "." as context separator in lookup pathes like in


But more usual in JNDI world are lookup pathes like


This is what is for. If not specified, then a '.' is chosen. To use "/" as separator in lookup pathes set

Note that you can not mix up different separators in property names and lookup pathes. When setting "" and using namespaced property names you can not declare "a.b.c=123". You have to declare "a/b/c=123". See also ENC problem.

See also Use slash separated lookup pathes with dot separated property names (New in 0.14.0)


The most popular object to get from JNDI is an object of type javax.sql.DataSource, allowing the developer to obtain JDBC connections to databases. Simple-JNDI supports this out of the box. See

DataSource Configuration DBCP 2 and Commons Pool 2 (New in 0.15.0)
DataSource Configuration HikariCP (New in 0.15.0)
DataSource Configuration (commons dbcp 1)
Usage with Spring - Inject a DataSource into beans

See also TomcatJNDI: Only interested in a DataSource?

Shared or unshared context?

Setting will put the in-memory JNDI implementation into a mode whereby all InitialContexts share the same memory. By default this is not set, so every new InitialContext() call will provide an independent InitialContext that does not share its memory with the other contexts. This could be not what you want when using a DataSource or a connection pool because everytime you call new InitialContext() in your application a new DataSource or a new connection pool is created. Also when binding an object to a specific context by calling Context.bind() this object will be not visible in the context provided by a subsequent "new InitialContext()" call.

Dealing with "java:comp/env" (Enterprise Naming Context, ENC) while loading

Set the property. Whatever the property is set to will be automatically prepended to every value loaded into the system. Thus simulates the JNDI environment of Tomcat. The property is not subject to delimiter parsing, so even when is set to ".", you have to lookup "java:comp/env", not "java:comp.env". See also ENC problem.

Another way to achieve a similar result is putting a directly under your root. In this file declare all your context objects that should reside under "java:comp/env" by prefixing all properties with "java:comp/env", e. g. "java:comp/env/my/size=186". This way you can set some context objects in "java:comp/env" and other objects in a different name space.

You could also put a file named "" in your root directory or name a directory under your root directory "java:comp". But Windows does not like having a : in a filename, so to deal with the : you can use the property. If, for example, you choose to replace a : with -- (ie, then you will need a file named, or a directory named java--comp containing a file "".

Context.close() and Context.destroySubcontext()

Either methods will recursively destroy every context and dereference all contained objects. So when writing JUnit tests, it is good practice to call close() in tearDown() and reinitialize the JNDI environment in setUp() by calling new InitialContext(). But do not forget to close your datasources by yourself.

New in 0.16.0: There are situations where you want prevent SimpleJNDI from closing the contexts this way when close() is called. See issue Multiple datasources created when using Spring JNDI template. To do so set = true

Really closing those contexts is a little bit tricky now:

Hashtable env = new InitialContext().getEnvironment();
env.put("java.naming.factory.initial", "");
new InitialContext(env).close();

Thread considerations

Any object manually bound to a context after SimpleJNDI's initialization will be visible in any thread looking up the object. But to guarantee the visibility of modifications to an object in all threads after it was bound you have to use the set-after-write trick:

InitialContext ic = new InitialContext();
List<City> cities = (List<City>) ic.lookup("Cities");
cities.add(new City("Berlin"));
ic.rebind("Cities", cities); // rebind guarantees visibility in all threads

See also

Change log


Creating Integration Tests with JNDI

Explanatory note

This project is based on old .

  • Several bugs fixed and many new tests added. See Failed Tests in
  • Changed the way contexts are shared, because of ContextNotEmptyException with type=javax.sql.DataSource and Beans. In shared mode subcontexts and bound objects are now managed per context and not in a single static map for the same reason.
  • Tests ported to JUnit 4.
  • Maven 2/3 support.
  • Support for additional basic datatypes (Byte, Short, Integer, Long, Float, Double, Character) in type declaration.