| 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 [OSGi Alliance](http://www.osgi.org/Download/Release4V42) |
| . |