You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by ps...@apache.org on 2003/12/08 07:19:47 UTC
svn commit: rev 1389 - incubator/directory/naming/trunk/xdocs
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>
+