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.
<dependency> <groupId>com.github.h-thurow</groupId> <artifactId>simple-jndi</artifactId> <version>0.17.2</version> </dependency>
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 jndi.properties file, which somehow needs to go into your classpath. This jndi.properties needs two mandatory values:
This property, java.naming.factory.initial, is a part of the jndi specification.
The second required parameter, org.osjava.sj.root, 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 org.osjava.sj.root=/home/hen/gj/simple-jndi/config/
# relative directory, using the default file protocol org.osjava.sj.root=config/
# 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 org.osjava.sj.pathSeparator to the separator used in org.osjava.sj.root to ensure platform independency of your jndi.properties file. org.osjava.sj.root=file1.cfg:directory1/file.properties:directory2
Not required, but highly recommended is setting org.osjava.sj.jndi.shared = true too.
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 org.osjava.sj.root 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:
admin=fred quantity=5 enabled=true
The following pieces of Java are all legal ways in which to get values from Simple-JNDI. They assume that you set org.osjava.sj.root=config 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")
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:
quantity=5 quantity.type=java.lang.Integer enabled=true enabled.type=java.lang.Boolean
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 city.name = 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 "org.osjava.sj.delimiter=/" unless you follow this description. And as you might anticipate already: "type" is a reserved word with Simple-JNDI.
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 org.osjava.sj.delimiter 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 "org.osjava.sj.delimiter=/" 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.
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
Shared or unshared context?
org.osjava.sj.jndi.shared=true 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
org.osjava.sj.space property. Whatever the property is set to will be automatically prepended to every value loaded into the system. Thus
org.osjava.sj.space=java:comp/env simulates the JNDI environment of Tomcat. The org.osjava.sj.space property is not subject to delimiter parsing, so even when org.osjava.sj.delimiter 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 default.properties 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 "java:comp.properties" 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
org.osjava.sj.colon.replace property. If, for example, you choose to replace a
org.osjava.sj.colon.replace=--), then you will need a file named
java--comp.properties, or a directory named
java--comp containing a file "env.properties".
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
org.osjava.sj.jndi.ignoreClose = true
Really closing those contexts is a little bit tricky now:
Hashtable env = new InitialContext().getEnvironment(); env.remove("org.osjava.sj.jndi.ignoreClose"); env.put("java.naming.factory.initial", "org.osjava.sj.SimpleJndiContextFactory"); new InitialContext(env).close();
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
This project is based on old https://github.com/hen/osjava/tree/master/simple-jndi .
- Several bugs fixed and many new tests added. See Failed Tests in 0.11.4.1
- 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.