| // |
| // Licensed under the Apache License, Version 2.0 (the "License"); |
| // you may not use this file except in compliance with the License. |
| // You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| // |
| |
| ==== Naming (JNDI) |
| |
| The Apache Karaf Naming (JNDI) is an optional enterprise feature. |
| |
| You have to install the `jndi` feature first: |
| |
| ---- |
| karaf@root()> feature:install jndi |
| ---- |
| |
| Apache Karaf provides a complete JNDI support. |
| |
| You have two parts in the Apache Karaf JNDI support: |
| |
| * a fully compliant implementation of the OSGi Alliance JNDI Service specification. |
| * a more "regular" JNDI context, containing different names that you can administrate. |
| |
| ===== OSGi Services Registry and JNDI |
| |
| The OSGi Service Registry provides a centralized register/query capabilities for OSGi services. |
| |
| A common pattern outside of OSGi is to make use of JNDI API to access services from a directory system. |
| The OSGi service registry can be viewed as an example of such a system. |
| |
| Apache Karaf supports the `osgi:service` lookup scheme as defined by the JNDI Service Specification. |
| |
| The schema is: |
| |
| ---- |
| osgi:service/<interface>[/<filter>] |
| ---- |
| |
| For instance, you can directly use JNDI to get a OSGi service: |
| |
| ---- |
| Context ctx = new InitialContext(); |
| Runnable r = (Runnable) ctx.lookup("osgi:service/java.lang.Runnable"); |
| ---- |
| |
| ===== JNDI service |
| |
| Apache Karaf also supports regular JNDI, including a directoy system where you can register name bindings, sub-context, etc. |
| |
| It supports the standard JNDI API: |
| |
| ---- |
| Context ctx = new InitialContext(); |
| Runnable r = (Runnable) ctx.lookup("this/is/the/name"); |
| ---- |
| |
| It also allows you to bind some OSGi services as "pure" JNDI name. In that case, you don't have to use the specific |
| `osgi:service` scheme. |
| |
| ===== Commands |
| |
| Apache Karaf provides specific commands to manipulate the JNDI service. |
| |
| ====== `jndi:names` |
| |
| The `jndi:names` command lists all JNDI names. It groups both the JNDI names from the `osgi:service` scheme and the |
| regular JNDI names: |
| |
| ---- |
| karaf@root()> jndi:names |
| JNDI Name | Class Name |
| ------------------------------------------------------------------ |
| osgi:service/jndi | org.apache.karaf.jndi.internal.JndiServiceImpl |
| jndi/service | org.apache.karaf.jndi.internal.JndiServiceImpl |
| ---- |
| |
| We can see here the `osgi:service/jndi` name (using the `osgi:service` scheme) and `jndi/service` name (using the |
| regular JNDI service). |
| |
| The `jndi:names` command accepts an optional `context` argument to list names on the given context. |
| |
| For instance, you can list only names in the `jndi` sub-context: |
| |
| ---- |
| karaf@root()> jndi:names jndi |
| JNDI Name | Class Name |
| ---------------------------------------------------------- |
| service | org.apache.karaf.jndi.internal.JndiServiceImpl |
| ---- |
| |
| [NOTE] |
| ==== |
| The `jndi:names` lists only names (the full qualified name). It means that the empty JNDI sub-contexts are not displayed. |
| To display all JNDI sub-contexts (empty or not), you can use the `jndi:contexts` command. |
| ==== |
| |
| ====== `jndi:contexts` |
| |
| The `jndi:contexts` command lists all JNDI sub-contexts: |
| |
| ---- |
| karaf@root()> jndi:contexts |
| JNDI Sub-Context |
| ---------------- |
| other/context |
| foo/bar |
| ---- |
| |
| ====== `jndi:create` |
| |
| The `jndi:create` command creates a new JNDI sub-context: |
| |
| ---- |
| karaf@root()> jndi:create my/company |
| ---- |
| |
| ====== `jndi:delete` |
| |
| The `jndi:delete` command deletes a JNDI sub-context: |
| |
| ---- |
| karaf@root()> jndi:delete my/company |
| ---- |
| |
| ====== `jndi:alias` |
| |
| The `jndi:alias` command creates a new JNDI name (alias) with an existing one. |
| |
| The existing JNDI name can be a regular one: |
| |
| ---- |
| karaf@root()> jndi:alias bean/services/jndi aliases/services/jndi |
| karaf@root()> jndi:names |
| JNDI Name | Class Name |
| ---------------------------------------------------------------------- |
| osgi:service/jndi | org.apache.karaf.jndi.internal.JndiServiceImpl |
| bean/services/jndi | org.apache.karaf.jndi.internal.JndiServiceImpl |
| aliases/services/jndi | org.apache.karaf.jndi.internal.JndiServiceImpl |
| ---- |
| |
| or a name from the `osgi:service` schema: |
| |
| ---- |
| karaf@root()> jndi:alias osgi:service/jndi alias/jndi/service |
| karaf@root()> jndi:names |
| JNDI Name | Class Name |
| ------------------------------------------------------------------- |
| osgi:service/jndi | org.apache.karaf.jndi.internal.JndiServiceImpl |
| alias/jndi/service | org.apache.karaf.jndi.internal.JndiServiceImpl |
| ---- |
| |
| [NOTE] |
| ==== |
| The `jndi:alias` automatically creates all required JNDI sub-contexts. |
| ==== |
| |
| ====== `jndi:bind` |
| |
| The `jndi:bind` command binds an OSGi service with a JNDI name. |
| |
| The `jndi:bind` command requires an OSGi service ID and a JNDI name. The OSGi service ID can be found using the `service:list` command. |
| |
| For instance, we can bind the OSGi service with ID 344 with the JNDI name `services/kar`: |
| |
| ---- |
| karaf@root()> jndi:bind 344 services/kar |
| karaf@root()> jndi:names |
| JNDI Name | Class Name |
| ------------------------------------------------------------------------------- |
| osgi:service/jndi | org.apache.karaf.jndi.internal.JndiServiceImpl |
| services/kar | org.apache.karaf.kar.internal.KarServiceImpl |
| ---- |
| |
| ====== `jndi:unbind` |
| |
| The `jndi:unbind` command unbind a given JNDI name: |
| |
| ---- |
| karaf@root()> jndi:names |
| JNDI Name | Class Name |
| ------------------------------------------------------------------------------- |
| osgi:service/jndi | org.apache.karaf.jndi.internal.JndiServiceImpl |
| services/kar | org.apache.karaf.kar.internal.KarServiceImpl |
| karaf@root()> jndi:unbind services/kar |
| karaf@root()> jndi:names |
| JNDI Name | Class Name |
| ------------------------------------------------------------------------------- |
| osgi:service/jndi | org.apache.karaf.jndi.internal.JndiServiceImpl |
| ---- |
| |
| [NOTE] |
| ==== |
| It's not possible to unbind a name from the `osgi:service` schema, as it's linked to a OSGi service. |
| ==== |
| |
| ===== JMX JndiMBean |
| |
| The JMX JndiMBean provides the JNDI names, and the operations to manipulate the JNDI service. |
| |
| The object name to use is `org.apache.karaf:type=jndi,name=*`. |
| |
| ====== Attributes |
| |
| The `Names` attribute provides a map containing all JNDI names and class names from both `osgi:service` scheme |
| and the regular JNDI service. |
| |
| The `Contexts` attribute provides a list containing all JNDI sub-contexts. |
| |
| ====== Operations |
| |
| * `getNames(context)` provides a map containing JNDI names and class names in a given JNDI sub-context. |
| * `create(context)` creates a new JNDI sub-context. |
| * `delete(context)` deletes a JNDI sub-context. |
| * `alias(name, alias` creates a JNDI name (alias) for a given one. |
| * `bind(serviceId, name` binds a JNDI name using an OSGi service (identified by its ID). |
| * `unbind(name)` unbinds a JNDI name. |