Author: pnedonosko Date: 2010-03-25 06:56:01 -0400 (Thu, 25 Mar 2010) New Revision: 2115 Added: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel/jndi-naming.xml Removed: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel/initial-context-binder-service.xml Modified: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel.xml Log: EXOJCR-573: docs about DataSources binding in runtime Deleted: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel/initial-context-binder-service.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel/initial-context-binder-service.xml 2010-03-25 10:52:28 UTC (rev 2114) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel/initial-context-binder-service.xml 2010-03-25 10:56:01 UTC (rev 2115) @@ -1,60 +0,0 @@ -<?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"> -<chapter> - <?dbhtml filename="ch-initial-context-binder-service.html"?> - - <title>Initial Context Binder</title> - - <section> - <title>About</title> - - <para>Initial Context Binder is responsible for binding references at - runtime, persisting in file and automatically rebinding after restart. - Java temp directory is used to persist references in bind-references.xml - file.</para> - </section> - - <section> - <title>API</title> - - <para>Service provide methods for binding reference.</para> - - <programlisting>public void bind(String bindName, String className, String factory, String factoryLocation, Map&lt;String, String&gt; refAddr) throws NamingException, FileNotFoundException, XMLStreamException;</programlisting> - - <itemizedlist> - <listitem> - <para>bindName - name of binding</para> - </listitem> - - <listitem> - <para>className - the fully-qualified name of the class of the object - to which this Reference refers</para> - </listitem> - - <listitem> - <para>factory - the name of the factory class for creating an instance - of the object to which this Reference refers</para> - </listitem> - - <listitem> - <para>factoryLocation - the location of the factory class</para> - </listitem> - - <listitem> - <para>refAddr - object's properties map</para> - </listitem> - </itemizedlist> - </section> - - <section> - <title>A configuration examples</title> - - <para>Service's configuration.</para> - - <programlisting>&lt;component&gt; - &lt;key&gt;org.exoplatform.services.naming.InitialContextBinder&lt;/key&gt; - &lt;type&gt;org.exoplatform.services.naming.InitialContextBinder&lt;/type&gt; -&lt;/component&gt;</programlisting> - </section> -</chapter> Added: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel/jndi-naming.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel/jndi-naming.xml (rev 0) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel/jndi-naming.xml 2010-03-25 10:56:01 UTC (rev 2115) @@ -0,0 +1,248 @@ +<?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"> +<chapter> + <?dbhtml filename="ch-jndi-naming.html"?> + + <title>JNDI naming</title> + + <section> + <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> + <title>How it works</title> + + <para>Make sure you understand the <ulink + url="http://java.sun.com/products/jndi/1.2/javadoc/index.html"&... Naming + and Directory InterfaceTM (JNDI)</ulink> concepts before using this + service.</para> + + <section> + <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> checks if this property + is already set as a System property + (<envar>System.getProperty(name)</envar>) and sets 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> it just sets 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> + <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> + <title>Configuration examples</title> + + <para>The <envar>InitialContextInitializer</envar> configuration + example:</para> + + <para><programlisting> &lt;component&gt; + &lt;type&gt;org.exoplatform.services.naming.InitialContextInitializer&lt;/type&gt; + &lt;init-params&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> + + <para>The BindReferencePlugin component plugin configuration example (for + JDBC datasource):</para> + + <para><programlisting> &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></para> + </section> + + <section> + <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> + <title>InitialContextInitializer API</title> + + <para><envar>InitialContextInitalizer</envar> also provides feature of + references binding in runtime. References have bind in runtime will be + persisted and automatically rebinded on a next system start. Java temp + directory is used to persist references in bind-references.xml + file.</para> + + <para>Service provide methods for binding reference.</para> + + <programlisting> + public void bind(String bindName, + String className, + String factory, + String factoryLocation, + Map&lt;String, String&gt; refAddr) + throws NamingException, FileNotFoundException, XMLStreamException;</programlisting> + + <itemizedlist> + <listitem> + <para><envar>bindName</envar> - name of binding</para> + </listitem> + + <listitem> + <para><envar>className</envar> - the fully-qualified name of the class + of the object to which this Reference refers</para> + </listitem> + + <listitem> + <para><envar>factory</envar> - the name of the factory class for + creating an instance of the object to which this Reference + refers</para> + </listitem> + + <listitem> + <para><envar>factoryLocation</envar> - the location of the factory + class</para> + </listitem> + + <listitem> + <para><envar>refAddr</envar> - object's properties map</para> + </listitem> + </itemizedlist> + + <para>Example of usage:</para> + + <programlisting> + // obtain InitialContextInitializer instance from ExoContainer (e.g. PortalContainer) + InitialContextInitializer initContext = (InitialContextInitializer)container.getComponentInstanceOfType(InitialContextInitializer.class); + + Map&lt;String, String&gt; refAddr = new HashMap&lt;String, String&gt;(); + refAddr.put("driverClassName", "oracle.jdbc.OracleDriver"); + refAddr.put("url", "jdbc:oracle:thin:@oraclehost:1521:orcl"); + refAddr.put("username", "exouser"); + refAddr.put("password", "exopassword"); + + initContext.bind("jdbcexco", "javax.sql.DataSource", "org.apache.commons.dbcp.BasicDataSourceFactory", null, refAddr); + + // try to get just bound DataSource + DataSource ds = (DataSource)new InitialContext().lookup("jdbcexo");</programlisting> + </section> +</chapter> Modified: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel.xml =================================================================== --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel.xml 2010-03-25 10:52:28 UTC (rev 2114) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel.xml 2010-03-25 10:56:01 UTC (rev 2115) @@ -18,7 +18,7 @@ <xi:include href="kernel/transaction-service.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="kernel/initial-context-binder-service.xml" + <xi:include href="kernel/jndi-naming.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </part>