directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From pste...@apache.org
Subject svn commit: rev 1389 - incubator/directory/naming/trunk/xdocs
Date Mon, 08 Dec 2003 06:19:47 GMT
Author: psteitz
Date: Sun Dec  7 22:19:46 2003
New Revision: 1389

Added:
   incubator/directory/naming/trunk/xdocs/using.xml
Modified:
   incubator/directory/naming/trunk/xdocs/navigation.xml
Log:
Added basic usage doc.

Modified: incubator/directory/naming/trunk/xdocs/navigation.xml
==============================================================================
--- incubator/directory/naming/trunk/xdocs/navigation.xml	(original)
+++ incubator/directory/naming/trunk/xdocs/navigation.xml	Sun Dec  7 22:19:46 2003
@@ -10,6 +10,7 @@
     <menu name="Naming">
       <item name="Overview"              href="/index.html"/>
       <item name="Building"              href="/building.html"/>
+      <item name="Using"              href="/using.html"/>
     </menu>
     
     <menu name="Projects">

Added: incubator/directory/naming/trunk/xdocs/using.xml
==============================================================================
--- (empty file)
+++ incubator/directory/naming/trunk/xdocs/using.xml	Sun Dec  7 22:19:46 2003
@@ -0,0 +1,158 @@
+<?xml version="1.0"?>
+<document>
+ <properties>
+  <title>Using naming</title>
+ </properties>
+
+ <body>
+
+ <section name="Introduction">
+   <p>
+   </p>
+ </section>
+ 
+ <section name="Installation and setup">
+   <p>
+   </p>
+ </section>
+
+ <section name="Examples">
+   <subsection name="Configuring JNDI resources using XMLConfigurator">
+     <p>
+     The <code>XMLConfigurator</code> allows you to configure and load JNDI 
+     resources using xml configuration files using a syntax very similar to that 
+     used by Jakarta Tomcat's server.xml file. [FIXME -- add schema/dtd reference.]
+     For a full introduction to JNDI resources and resource factories, see
+     <a href="http://jakarta.apache.org/tomcat/tomcat-5.0-doc/jndi-resources-howto.html">
+     Tomcat JNDI Resources HOW-TO</a>
+     </p>
+     <p>
+     Here is an example, showing how to configure a database connection pool and 
+     then get a connection from the pool in your application.
+     </p>
+     <p>
+       Start by setting up a JNDI environment including a datasource in an xml 
+       configuration file, like so:
+       <source><![CDATA[
+        <naming>
+          <context>
+            <resource name="jdbc/pool" type="javax.sql.DataSource">
+              <parameter>
+                <name>driverClassName</name>
+                <value>org.hsqldb.jdbcDriver</value>
+              </parameter>
+              <parameter>
+                <name>url</name>
+                <value>jdbc:hsqldb:target/hsqldb</value>
+             </parameter>
+             <parameter>
+               <name>username</name>
+               <value>sa</value>
+             </parameter>
+             <parameter>
+               <name>password</name>
+               <value></value>
+             </parameter>
+           </resource>
+         </context>
+       </naming>
+       ]]>
+       </source>
+     </p>
+     <p>
+       The JNDI resource being configured above is a database connection pool. Naming
+       provides a default resource factory for database connection pools using Jakarta
+       Commons DBCP.  This is the factory that will be used to create the pool. In order

+       for this factory to work, you need to have Jakarta Commons DBCP (version 1.0) 
+       and Jakarta Commons Pool (version 1.0.1) in your classpath. 
+     </p>
+     <p>
+       The parameters that follow specify the database driver, url, username and password.

+     </p>
+     <p>
+       To use a connection from the pool at run time, you need to do three things:
+       <ol>
+         <li>
+           <p>
+             Initialize JNDI using the xml configuration file above. Assuming the xml file
+             is stored in "/example-jndi.xml", you can do this in one line:
+             <source>
+               XmlConfigurator.loadConfiguration(getClass().getResourceAsStream("/example-jndi.xml"));
+             </source>
+           </p>
+         </li>
+         <li>
+           <p>
+             Perform a JNDI lookup to get a DataSource reference:
+             <source>
+               Context ctx = new InitialContext();
+               Context env = (Context) ctx.lookup("java:comp/env");
+               DataSource ds = (DataSource) env.lookup("jdbc/pool");
+             </source>
+           </p>
+         </li>
+         <li>
+           <p>
+             Use the reference to access the database:
+             <source>
+               Connection con = null;
+               try {
+                   con = ds.getConnection();
+                   // use con to access db
+                   ...
+               } finally {
+                   // cleanup database access objects
+                   ...
+                   if (con != null) { 
+                      con.close(); 
+                   }
+               }
+             </source>
+           </p>
+         </li>
+       </ol>
+     </p>
+   </subsection>
+   <subsection name="Using the Naming APIs directly to set up JNDI">
+     <p>
+       To set up and use a JNDI naming context using the JNDI APIs directly, 
+       you need to set some JNDI environment properties, create an initial context
+       and then use the standard JNDI APIs to set up bindings and perform lookups.
+     </p>
+     <p>
+       You can use a jndi.properties properties file to set the environment properties 
+       for the initial context, or you can do it as follows in your code:
+       <source>
+         Hashtable env = new Hashtable();
+         env.put(Context.INITIAL_CONTEXT_FACTORY,
+            "org.apache.directory.naming.java.javaURLContextFactory");
+         env.put(Context.URL_PKG_PREFIXES,"org.apache.directory.naming");
+        </source>
+     </p>
+     <p>
+       Then create the initial context:
+       <source>
+         Context initialContext = new InitialContext(env);
+       </source>
+     </p>
+     <p>
+       Once created, you can add bindings to the context using the 
+       <code>javax.naming.Context</code> API:
+       <source>
+         compContext = initialContext.createSubcontext("java:comp");
+         envContext =  compContext.createSubcontext("env");
+         envContext.bind("host", "www.apache.org");
+         envContext.bind("port", new Integer(80)); 
+       </source>
+     </p>
+     <p>
+       Now <code>initialContext.lookup("java:comp/env/host"))</code> will return

+       a <code>String</code> holding the value "www.apache.org" and 
+       <code>initialContext.lookup("java:comp/env/port"))</code> will return
an
+       <code>Integer</code> with <code>intValue</code> equal to 80.
+     </p>      
+   </subsection>
+ </section>      
+ </body>
+</document>
+

Mime
View raw message