svn commit: r1550511 - in /karaf/trunk/manual/src/main/webapp/users-guide: enterprise.conf index.conf jndi.conf

[jb...@apache.org]

Author: jbonofre
Date: Thu Dec 12 20:19:17 2013
New Revision: 1550511

URL: http://svn.apache.org/r1550511
Log:
[KARAF-2511] Add JNDI section in the user guide

Added:
    karaf/trunk/manual/src/main/webapp/users-guide/jndi.conf
Modified:
    karaf/trunk/manual/src/main/webapp/users-guide/enterprise.conf
    karaf/trunk/manual/src/main/webapp/users-guide/index.conf

Modified: karaf/trunk/manual/src/main/webapp/users-guide/enterprise.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/users-guide/enterprise.conf?rev=1550511&r1=1550510&r2=1550511&view=diff
==============================================================================
--- karaf/trunk/manual/src/main/webapp/users-guide/enterprise.conf (original)
+++ karaf/trunk/manual/src/main/webapp/users-guide/enterprise.conf Thu Dec 12 20:19:17 2013
@@ -6,5 +6,7 @@ These features are not installed by defa
 
 The enterprise features available are:
 
-* [WebContainer|webcontainer] providing a complete JSP/Servlet support. These feature turns Apache Karaf as a complete
+* [WebContainer (JSP/Servlet)|webcontainer] providing a complete JSP/Servlet support. These feature turns Apache Karaf as a complete
  web container where you can deploy web application (as you can do in Apache Tomcat, or other JEE application servers).
+* [Naming (JNDI)|jndi] providing a complete Java Naming and Directory Interface support. Apache Karaf provides a complete
+ JNDI "server" (context) where you can create name to identify Objects (especially OSGi services).

Modified: karaf/trunk/manual/src/main/webapp/users-guide/index.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/users-guide/index.conf?rev=1550511&r1=1550510&r2=1550511&view=diff
==============================================================================
--- karaf/trunk/manual/src/main/webapp/users-guide/index.conf (original)
+++ karaf/trunk/manual/src/main/webapp/users-guide/index.conf Thu Dec 12 20:19:17 2013
@@ -17,7 +17,7 @@ h1. Users Guide
 * [OBR|obr]
 * [Enterprise|enterprise]
 ** [WebContainer (JSP/Servlet)|webcontainer]
-** Naming (JNDI)
+** [Naming (JNDI)|jndi]
 ** Transaction (JTA)
 ** DataSource (JDBC)
 ** MOM (JMS)

Added: karaf/trunk/manual/src/main/webapp/users-guide/jndi.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/users-guide/jndi.conf?rev=1550511&view=auto
==============================================================================
--- karaf/trunk/manual/src/main/webapp/users-guide/jndi.conf (added)
+++ karaf/trunk/manual/src/main/webapp/users-guide/jndi.conf Thu Dec 12 20:19:17 2013
@@ -0,0 +1,190 @@
+h1. Naming (JNDI)
+
+The Apache Karaf Naming (JNDI) is an optional enterprise feature.
+
+You have to install the {{jndi}} feature first:
+
+{code}
+karaf@root()> feature:install jndi
+{code}
+
+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.
+
+h2. 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:
+
+{code}
+osgi:service/<interface>[/<filter>]
+{code}
+
+For instance, you can directly use JNDI to get a OSGi service:
+
+{code}
+Context ctx = new InitialContext();
+Runnable r = (Runnable) ctx.lookup("osgi:service/java.lang.Runnable");
+{code}
+
+h2. 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:
+
+{code}
+Context ctx = new InitialContext();
+Runnable r = (Runnable) ctx.lookup("this/is/the/name");
+{code}
+
+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.
+
+h2. Commands
+
+Apache Karaf provides specific commands to manipulate the JNDI service.
+
+h3. {{jndi:list}}
+
+The {{jndi:list}} command lists all JNDI names. It groups both the JNDI names from the {{osgi:service}} scheme and the
+regular JNDI names:
+
+{code}
+karaf@root()> jndi:list
+JNDI Name         | Class Name
+------------------------------------------------------------------
+osgi:service/jndi | org.apache.karaf.jndi.internal.JndiServiceImpl
+jndi/service      | org.apache.karaf.jndi.internal.JndiServiceImpl
+{code}
+
+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:list}} 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:
+
+{code}
+karaf@root()> jndi:list jndi
+JNDI Name | Class Name
+----------------------------------------------------------
+service   | org.apache.karaf.jndi.internal.JndiServiceImpl
+{code}
+
+{warning}
+The {{jndi:list}} lists only names (the full qualified name). It means that the empty JNDI sub-contexts are not displayed.
+{warning}
+
+h3. {{jndi:create}}
+
+The {{jndi:create}} command creates a new JNDI sub-context:
+
+{code}
+karaf@root()> jndi:create my/company
+{code}
+
+h3. {{jndi:delete}}
+
+The {{jndi:delete}} command deletes a JNDI sub-context:
+
+{code}
+karaf@root()> jndi:delete my/company
+{code}
+
+h3. {{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:
+
+{code}
+karaf@root()> jndi:alias bean/services/jndi aliases/services/jndi
+karaf@root()> jndi:list
+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
+{code}
+
+or a name from the {{osgi:service}} schema:
+
+{code}
+karaf@root()> jndi:alias osgi:service/jndi alias/jndi/service
+karaf@root()> jndi:list
+JNDI Name          | Class Name
+-------------------------------------------------------------------
+osgi:service/jndi  | org.apache.karaf.jndi.internal.JndiServiceImpl
+alias/jndi/service | org.apache.karaf.jndi.internal.JndiServiceImpl
+{code}
+
+NB: the {{jndi:alias}} automatically creates all required JNDI sub-contexts.
+
+h3. {{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}}:
+
+{code}
+karaf@root()> jndi:bind 344 services/kar
+karaf@root()> jndi:list
+JNDI Name         | Class Name
+-------------------------------------------------------------------------------
+osgi:service/jndi | org.apache.karaf.jndi.internal.JndiServiceImpl
+services/kar      | org.apache.karaf.kar.internal.KarServiceImpl
+{code}
+
+h3. {{jndi:unbind}}
+
+The {{jndi:unbind}} command unbind a given JNDI name:
+
+{code}
+karaf@root()> jndi:list
+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:list
+JNDI Name         | Class Name
+-------------------------------------------------------------------------------
+osgi:service/jndi | org.apache.karaf.jndi.internal.JndiServiceImpl
+{code}
+
+{warning}
+It's not possible to unbind a name from the {{osgi:service}} schema, as it's linked to a OSGi service.
+{warning}
+
+h2. 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=*}}.
+
+h3. Attribute
+
+The {{Names}} attribute provides a map containing all JNDI names and class names from both {{osgi:service}} scheme
+and the regular JNDI service.
+
+h3. 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.
\ No newline at end of file