Author: psteitz Date: Tue Dec 28 06:58:51 2004 New Revision: 123514 URL: http://svn.apache.org/viewcvs?view=rev&rev=123514 Log: Updated to reflect new packaging, XmlConfigurator namespace option. Modified: incubator/directory/naming/trunk/xdocs/building.xml incubator/directory/naming/trunk/xdocs/using.xml
Modified: incubator/directory/naming/trunk/xdocs/building.xml Url: http://svn.apache.org/viewcvs/incubator/directory/naming/trunk/xdocs/building.xml?view=diff&rev=123514&p1=incubator/directory/naming/trunk/xdocs/building.xml&r1=123513&p2=incubator/directory/naming/trunk/xdocs/building.xml&r2=123514 ============================================================================== --- incubator/directory/naming/trunk/xdocs/building.xml (original) +++ incubator/directory/naming/trunk/xdocs/building.xml Tue Dec 28 06:58:51 2004 @@ -8,9 +8,12 @@ <section name="Maven targets"> <p> - Naming consists of two subprojects: core and factory. These can be built separately - by executing maven build targets from the /core or /factory directories. All subprojects can be - built using the following targets, executed from the top level directory/naming directory: + Naming consists of six subprojects: naming-core, naming-factory, + naming-java, naming-management, naming-resources, and naming-config. + These can be built separately by executing maven build targets from + the subproject directories. All subprojects can be + built using the following targets, executed from the top level + directory/naming directory: <ul> <li>multiproject:clean -- cleans all subprojects</li> <li>multiproject:install -- builds, tests and jars all subprojects</li> @@ -22,28 +25,27 @@ </section> <section name="Dependencies"> <p> - The dependencies common to both subprojects are the ones that appear in the top level - project.xml, viz.: - <ul> - <li>Commons Collections 2.1</li> - <li>JUnit 3.7 (compile time only)</li> - </ul> - The core subproject also depends on the following for its MBean and Service: - <ul> - <li>MX4j's JMX 1.1.1 (</li> - </ul> - The factory subproject depends on core and has the following additional dependencies: - <ul> - <li>Commons DBCP 1.0 and Commons Pool 1.0.1 (only required if using the default - resource factory to obtain database connections)</li> - <li>Commons Digester 1.4.1 (for reading XML configuration files)</li> - <li>Commons Logging 1.0.3</li> - <li>Commons BeanUtils 1.6.1 (runtime only for digester)</li> - <li>Commons Lang 1.0.1</li> - <li>jta-spec 1.0.1 (uses the spec jars from geronimo for compiling) </li> - <li>javamail 1.2 (uses the spec jars from geronimo for compiling)</li> - <li>hsqldb 1.7.1 (testing only - used to setup a simple database to perform resource factory testing)</li> - </ul> + All other subprojects depend on naming-core, which has no external + dependencies beyond jdk 1.4+. The dependencies of the other subprojects are: + <table> + <tr><th>Subproject</th><th>Dependencies</th></tr> + <tr><td>Naming Java</td><td>naming-core</td></tr> + <tr><td>Naming Factory</td> + <td>naming-core, geronimo-spec-javamail (1.3.1-rc1) + </td></tr> + <tr><td>Naming Resources</td> + <td>naming-core, commons-collections (3.1)</td></tr> + <tr><td>Naming Management</td> + <td>naming-core, naming-java, mx4j-jmx (1.1.1)</td></tr> + <tr><td>Naming Config</td> + <td>naming-core, naming-factory, naming-java, + commons-logging (1.0.3), commons-collections (3.1), + commons-beanutils (1.6.1), commons-digester (1.4.1), + commons-lang (1.0.1), commons-dbcp (1.0), + commons-pool (1.0.1), + hsqldb (1.7.1, test runtime only) + </td></tr> + </table> </p> </section> </body> Modified: incubator/directory/naming/trunk/xdocs/using.xml Url: http://svn.apache.org/viewcvs/incubator/directory/naming/trunk/xdocs/using.xml?view=diff&rev=123514&p1=incubator/directory/naming/trunk/xdocs/using.xml&r1=123513&p2=incubator/directory/naming/trunk/xdocs/using.xml&r2=123514 ============================================================================== --- incubator/directory/naming/trunk/xdocs/using.xml (original) +++ incubator/directory/naming/trunk/xdocs/using.xml Tue Dec 28 06:58:51 2004 @@ -6,24 +6,14 @@ <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"> + <section name="Configuring JNDI resources using XMLConfigurator"> <p> The <code>XMLConfigurator</code> allows you set JNDI environment entries - and to configure and load JNDI resources in the "java:comp/env" namespace - using xml configuration files. The xml syntax is similar to that used by - Jakarta Tomcat's <code>server.xml</code> and the J2EE <code>web.xml</code> - configuration files. For a full introduction to JNDI resources and resource factories, see + and to configure and load JNDI resources using xml configuration files. + The xml syntax is similar to that used by Jakarta Tomcat's + <code>server.xml</code> and the J2EE <code>web.xml</code> + configuration files. 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> @@ -50,11 +40,11 @@ The <code>environment</code> entries achieve the same effect as <code>env-entry</code> elements in <code>web.xml</code>. The <code>resource</code> elements behave like <code>Resource</code> elements - in <code>server.xml</code>. Note that here "resource" starts with a - lower case "r" and the <code>parameter</code> elements are its content - (In Tomcat's <code>server.xml</code>, <code>Resource</code> is an empty - tag and the parameters are included in a <code>ResourceParams</code> - element.) + in <code>server.xml</code>. Note that here "resource" starts with a + lower case "r" and the <code>parameter</code> elements are its content + (In Tomcat's <code>server.xml</code>, <code>Resource</code> is an empty + tag and the parameters are included in a <code>ResourceParams</code> + element.) </p> <p> Here is an example, showing how to configure a database connection pool and @@ -64,28 +54,28 @@ 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> + <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> @@ -107,7 +97,7 @@ 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")); +XmlConfigurator.loadConfiguration(getClass().getResourceAsStream("/example-jndi.xml")); </source> </p> </li> @@ -115,9 +105,9 @@ <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"); +Context ctx = new InitialContext(); +Context env = (Context) ctx.lookup("java:comp/env"); +DataSource ds = (DataSource) env.lookup("jdbc/pool"); </source> </p> </li> @@ -125,25 +115,45 @@ <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(); - } - } +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> + As in the example above, by default the root of the namespace created by + the <code>XmlConfigurator</code> is "java:comp/env". This may be overridden + by supplying a <code>name</code> attribute in the top-level + <code>context</code> element. For example, + <source><![CDATA[ +<naming> + <context name="myApp/config"> + ... same as above ... + </context> +</naming> + ]]> + </source> + would allow you to use + <source> +Context ctx = new InitialContext(); +Context env = (Context) ctx.lookup("myApp/config"); +DataSource ds = (DataSource) env.lookup("jdbc/pool"); + </source> + </p> + </section> + <section 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 @@ -153,10 +163,10 @@ 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.naming.java.javaURLContextFactory"); - env.put(Context.URL_PKG_PREFIXES,"org.apache.naming"); +Hashtable env = new Hashtable(); +env.put(Context.INITIAL_CONTEXT_FACTORY, + "org.apache.naming.java.javaURLContextFactory"); +env.put(Context.URL_PKG_PREFIXES,"org.apache.naming"); </source> </p> <p> @@ -169,10 +179,10 @@ 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)); +compContext = initialContext.createSubcontext("java:comp"); +envContext = compContext.createSubcontext("env"); +envContext.bind("host", "www.apache.org"); +envContext.bind("port", new Integer(80)); </source> </p> <p> @@ -180,8 +190,7 @@ 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> + </p> </section> </body> </document>
