modules/ROOT/pages/modules/jndiproject.adoc

:doctype: book

Title: JNDIProject +++<a name="JNDIProject-Overview">++++++</a>+++

= JNDI

The Aries JNDI project aims to provide a fully compliant implementation of the OSGi Alliance JNDI Service Specification.
This specification details how to advertise InitialContextFactory and ObjectFactories in an OSGi environment.
It also defines how to obtain services from the service registry via JNDI.

+++<a name="JNDIProject-ServiceRegistryaccessfromJNDI">++++++</a>+++

== Service Registry access from JNDI

The OSGi service registry provides a centralised register/query capability for OSGi services.
A common pattern outside of OSGi is to make use of the JNDI API to access services from a directory system.
The OSGi service registry can be viewed as an example of such a system.
The Aries JNDI project provides two URL lookup mechanisms via JNDI that can be used to access the service registry.

+++<a name="JNDIProject-osgi:service">++++++</a>+++

== osgi:service

The osgi:service lookup scheme is defined by the JNDI Service Specification and follows the scheme:

 osgi:service/<interface>[/<filter>](/<filter>.html)

The interface part is an interface name, like javax.sql.DataSource, or javax.jms.ConnectionFactory.
The filter allows selection based on the properties of the service.

This example:

....
Context ctx = new InitialContext();

Runnable r = (Runnable)ctx.lookup("osgi:service/java.lang.Runnable");
....

is equivalent to this code written to the OSGi service registry API.

 BundleContext ctx = getABundleContext();
 ServiceReference ref = ctx.getServiceReference("java.lang.Runnable");
 if (ref != null) {
     Runnable r = ctx.getService(ref);
 }

Lets say you wanted to filter for a Runnable with a property called _fred_ which was mapped to _wilma_.
You could write

....
Context ctx = new InitialContext();

Runnable r =
(Runnable)ctx.lookup("osgi:service/java.lang.Runnable/(fred=wilma)");
....

which is equivalent to:

 BundleContext ctx = getABundleContext();
 ServiceReference[](.html)
  refs = ctx.getServiceReference("java.lang.Runnable", "(fred=wilma)");
 if (refs != null) {
   Runnable r = ctx.getService(refs[refs.length - 1](refs.length---1.html)
 ); }

The osgi:service namepsace returns proxies, so if the Runnable was unregistered the proxy would switch to an equivalent alternative.
If no such alternative exists then an org.osgi.framework.ServiceException with a type of ServiceException.UNREGISTERED.

+++<a name="JNDIProject-osgi:servicelist">++++++</a>+++

== osgi:servicelist

It is possible that there are multiple services in the registry that match.
In this case the osgi:servicelist lookup scheme can be used.
It has the same format as osgi:service, but it is designed to return multiple.

+++<a name="JNDIProject-aries:services">++++++</a>+++

== aries:services

The aries:services scheme works in the same way as the osgi:service scheme, but does not perform proxying.
You get the actual object back.
Care must be taken with this approach as the service could be unregistered, but the client cannot tell to stop using it.
As a result it should only be used if the service is to be used for a short period of time.
In addition their is no way to indicate that the client is no longer using the service, so clean up cannot occur.

+++<a name="JNDIProject-MoreInformation">++++++</a>+++

== More Information

For more information, check out section "126 JNDI Services Specification Version 1.0" in the "OSGi Service Platform Enterprise Specification, Release 4, Version 4.2" available for public download from the http://www.osgi.org/Download/Release4V42[OSGi Alliance] .