<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<section id="Kernel.JNDINaming">
  <title>JNDI naming</title>
  <para>This section provides you the basic knowledge about JNDI naming, such as, what it is, how it works and how it is used.</para>

  <section id="Kernel.JNDINaming.Prerequisites">
    <title>Prerequisites</title>

    <para>We need to configure JNDI environment properties and Reference
    binding with the eXo container standard mechanism.</para>

    <para>The Naming service covers:</para>

    <para><itemizedlist>
        <listitem>
          <para>Configuring the current Naming Context Factory implemented as
          an ExoContainer Component
          <envar>org.exoplatform.services.naming.InitialContextInitializer</envar>.</para>
        </listitem>

        <listitem>
          <para>Binding Objects (References) to the current Context using
          <envar>org.exoplatform.services.naming.BindReferencePlugin</envar>
          component plugin.</para>
        </listitem>
      </itemizedlist></para>
  </section>

  <section id="Kernel.JNDINaming.How_it_works">
    <title>How it works</title>

    <para>Make sure you understand the <ulink
    url="http://www.oracle.com/technetwork/java/jndi/docs/index.html">Java Naming
    and Directory InterfaceTM (JNDI)</ulink> concepts before using this
    service.</para>

    <section id="Kernel.JNDINaming.How_it_works.JNDI_System_property_initialization">
      <title>JNDI System property initialization</title>

      <para>After the start time the Context Initializer
      (org.exoplatform.services.naming.InitialContextInitializer) traverses
      all initial parameters (that concern the Naming Context) configured in
      <envar>default-properties</envar> and
      <envar>mandatory-properties</envar> (see Configuration examples)
      and:</para>

      <itemizedlist>
        <listitem>
          <para>For <envar>default-properties</envar>: Check if this property
          is already set as a System property
          (<envar>System.getProperty(name)</envar>) and set this property if
          it's not found. Using those properties is recommended with a third
          party Naming service provider.</para>
        </listitem>

        <listitem>
          <para>For <envar>mandatory-properties</envar>: Set the property
          without checking.</para>
        </listitem>
      </itemizedlist>

      <para>Standard JNDI properties:</para>

      <itemizedlist>
        <listitem>
          <para><envar>java.naming.factory.initial</envar></para>
        </listitem>

        <listitem>
          <para><envar>java.naming.provider.url</envar></para>
        </listitem>
      </itemizedlist>

      <para>and others (see JNDI docs)</para>
    </section>

    <section id="Kernel.JNDINaming.JNDI_ref_binding">
      <title>JNDI reference binding</title>

      <para>Another responsibility of Context Initializer
      <envar>org.exoplatform.services.naming.InitialContextInitializer</envar>
      is binding of preconfigured references to the naming context. For this
      purpose, it uses a standard eXo component plugin mechanism and in
      particular the
      <envar>org.exoplatform.services.naming.BindReferencePlugin</envar>
      component plugin. The configuration of this plugin includes three
      mandatory value parameters:</para>

      <itemizedlist>
        <listitem>
          <para><envar>bind-name</envar>: the name of binding
          reference.</para>
        </listitem>

        <listitem>
          <para><envar>class-name</envar>: the type of binding
          reference.</para>
        </listitem>

        <listitem>
          <para><envar>factory</envar>: the object factory type.</para>
        </listitem>
      </itemizedlist>

      <para>And also <envar>ref-addresses</envar> property parameter with a
      set of references' properties. (see Configuration examples) Context
      Initializer uses those parameters to bind the neccessary reference
      automatically.</para>
    </section>
  </section>

  <section id="Kernel.JNDINaming.Configuration_examples">
    <title>Configuration examples</title>

    <para>The <envar>InitialContextInitializer</envar> configuration
    example:</para>

    <programlisting language="xml">  &lt;component&gt;
    &lt;type&gt;org.exoplatform.services.naming.InitialContextInitializer&lt;/type&gt;
    &lt;init-params&gt;
      &lt;value-param&gt;.
        &lt;name&gt;bindings-store-path&lt;/name&gt;.
        &lt;value&gt;bind-references.xml&lt;/value&gt;.
      &lt;/value-param&gt;.
      &lt;value-param&gt; 
        &lt;name&gt;overload-context-factory&lt;/name&gt; 
        &lt;value&gt;true&lt;/value&gt; 
      &lt;/value-param&gt;
      &lt;properties-param&gt;
        &lt;name&gt;default-properties&lt;/name&gt;
        &lt;description&gt;Default initial context properties&lt;/description&gt;
        &lt;property name="java.naming.factory.initial" value="org.exoplatform.services.naming.SimpleContextFactory"/&gt;
      &lt;/properties-param&gt;
      &lt;properties-param&gt;
        &lt;name&gt;mandatory-properties&lt;/name&gt;
        &lt;description&gt;Mandatory initial context properties&lt;/description&gt;
        &lt;property name="java.naming.provider.url" value="rmi://localhost:9999"/&gt;
      &lt;/properties-param&gt;
    &lt;/init-params&gt;
  &lt;/component&gt;</programlisting>

    <para>where</para>

    <para><emphasis role="bold">binding-store-path</emphasis> is file path
    which stores binded datasources in runtime</para>

    <para><emphasis role="bold">overload-context-factory</emphasis> allows to
    overload the default initial context factory by a context factory that is
    ExoContainer aware and that is able to delegate to the original initial
    context factory if it detects that it is not in the eXo scope. By default
    the feature is disabled since it is only required on AS that don't share
    the objects by default like tomcat but unlike JBoss AS</para>

    <para>The <envar>BindReferencePlugin</envar> component plugin
    configuration example (for JDBC datasource):</para>

    <programlisting language="xml">  &lt;component-plugins&gt; 
    &lt;component-plugin&gt; 
      &lt;name&gt;bind.datasource&lt;/name&gt;
      &lt;set-method&gt;addPlugin&lt;/set-method&gt;
      &lt;type&gt;org.exoplatform.services.naming.BindReferencePlugin&lt;/type&gt;
      &lt;init-params&gt;
        &lt;value-param&gt;
          &lt;name&gt;bind-name&lt;/name&gt;
          &lt;value&gt;jdbcjcr&lt;/value&gt;
        &lt;/value-param&gt;
        &lt;value-param&gt;
          &lt;name&gt;class-name&lt;/name&gt;
          &lt;value&gt;javax.sql.DataSource&lt;/value&gt;
        &lt;/value-param&gt;  
        &lt;value-param&gt;
          &lt;name&gt;factory&lt;/name&gt;
          &lt;value&gt;org.apache.commons.dbcp.BasicDataSourceFactory&lt;/value&gt;
        &lt;/value-param&gt;
        &lt;properties-param&gt;
          &lt;name&gt;ref-addresses&lt;/name&gt;
          &lt;description&gt;ref-addresses&lt;/description&gt;
          &lt;property name="driverClassName" value="org.hsqldb.jdbcDriver"/&gt;
          &lt;property name="url" value="jdbc:hsqldb:file:target/temp/data/portal"/&gt;
          &lt;property name="username" value="sa"/&gt;
          &lt;property name="password" value=""/&gt;
        &lt;/properties-param&gt;     
      &lt;/init-params&gt;    
  &lt;/component-plugin&gt;</programlisting>
  </section>

  <section id="Kernel.JNDINaming.Recommendations_for_application_developers">
    <title>Recommendations for Application Developers</title>

    <para><itemizedlist>
        <listitem>
          <para><envar>SimpleContextFactory</envar> is created for testing
          purposes only, do not use it for production.</para>
        </listitem>

        <listitem>
          <para>In J2EE environment use Naming Factory objects provided with
          the Application Server.</para>
        </listitem>
      </itemizedlist></para>
  </section>
</section>
