org.geotools.arcsde.jndi (Geotools modules 21.0 API)

Class Summary
Class	Description
ArcSDEConnectionFactory	A `ObjectFactory` to create an ArcSDE `connection pool` to be JNDI managed.
SharedSessionPool	A `session pool` that is not closable and hence can be shared between different applications/datastores when referenced by a JNDI context.

Package org.geotools.arcsde.jndi Description

This package contains relevant classes to support configuring a GeoTools ArcSDE


 ISessionPool

(a pool of connections to an ArcSDE server) inside a Java Naming and Directory Interface (JNDI) context.

Since ArcSDE uses a legacy protocol to communicate between the ArcSDE service instance and the ArcSDE Java API, and it's not possible to connect to an ArcSDE service through the java JDBC API, we can't use the standard javax.sql.DataSource object factories. Hence, we provide a custom javax.naming.ObjectFactory specialized in creating ArcSDE connection pools for the GeoTools library.

Configuration inside a J2EE Container

The JNDI specification acts only at the API level, so how to configure a given resource to be accessible through JNDI is J2EE Container specific. Some of them provide a means to configure an ObjectFactory to provide a specific kind of resource (whether it is a JDBC DataSource, a standard Java Bean or any other object type). For instance, the Apache Tomcat container provides such a mechanism, but the JBoss Application Server does not, even though it uses Apache Tomcat internally.

Classpath configuration for container-wide shared connection pools

Whether an ArcSDE connection pool is going to be shared among different web applications on the same J2EE container is a matter of how you lay out the ArcSDE Jars on the classpath. That is, if you want to achieve a container instance wide shared session pool (for example to have various GeoServer instances sharing the same connection pool), you need to drop certain jar files in the container's shared libraries folder instead of inside <geoserver war>/WEB-INF/lib. For instance, the following jars shall be put on such a shared library directory:

jsde_sdk.jar, jpe_sdk.jar and icu4j.jar from your ArcSDE Java SDK installation.
gt-arcsde-common-<version>.jar
commons-pool-1.3.jar (or whatever commons-pool version the gt-arcsde-common depends on)

gt-arcsde-.jar, which provides the actual DataStore implementation may be placed inside your app's WEB-INF/lib directory though.

The following are configuration examples to set up GeoServer for Tomcat and JBoss with ArcSDE JNDI support, but apply to any other web application where you want to use GeoTools with ArcSDE and JNDI.

First off, you need to add an entry on the web application's WEB-INF/web.xml file to indicate the JNDI resource that's going to be available for the application. Open the WEB-INF/web.xml file and add an entry as the following as the last element before </web-app>:

 
 <resource-ref>
   <description>JNDI arcsde resource configuration</description>
   <res-ref-name>geotools/arcsde</res-ref-name>
   <res-type>org.geotools.arcsde.session.ISessionPool</res-type>
   <res-auth>Container</res-auth>
 </resource-ref>

Where the values for description and res-ref-name are of your choice, res-ref-name being the path under which the arcsde connection pool is configured on your JNDI container (see bellow for instructions on how to configure such a resource on Tomcat and JBoss).

Configuration in Tomcat

Copy the jsde_sdk.jar, jpe_sdk.jar, icu4j.jar, commons-pool-1.3.jar and gt-arcsde-common-<version>.jar files to the Tomcat shared libs folder (either /lib or /common/lib folder, depending on your Tomcat version).
Expand geoserver.war into /webapps
copy gt-arcsde-<version>.jar to /webapps/geoserver/WEB-INF/lib

Finally, configure the ArcSDE Connection Factory as explained in the Adding Custom Resource Factories section of the Tomcat's JNDI Resources HOW-TO. That is, add an entry as the following to the file

<catalina
 home>/conf/context.xml

as a child of the root <Context> element:

 
   <Resource name="geotools/arcsde" auth="Container" type="org.geotools.arcsde.session.ISessionPool"
             factory="org.geotools.arcsde.jndi.ArcSDEConnectionFactory"
             server="<arcsde server>"
             user="<arcsde user name>"
             password="<arcsde user password>"
             instance="<arcsde database name>"
             port="<arcsde instance port number>"
   />

And that's it. Now you're able to select the ArcSDE JNDI DataStore factory and use the "geotools/arcsde" (or whatever entry name of your choice) as the DataStore's JNDI resource path name.

Configuration in JBoss Application Server (4.0.3+)

JBoss provides an extensible mechanism to configure any kind of object as a JNDI resource starting with JBoss version 4.0.3. Prior versions do not provide this mechanism and hence it is not possible to configure a GeoTools ArcSDE connection pool for versions lower than 4.0.3. Disregard what the JBoss documentation says on its JNDI Resources HOW-TO , that seems to be a verbatim copy of the Tomcat documentation but is just not supported.

To configure a JNDI ArcSDE session pool on JBoss, you need to create an xml file containing the managed bean definition that configures the ArcSDE connection pool. You can call this file as you want, for example geoserver-service.xml, and place it on the deploy folder for the JBoss configuration that you're going to run. For example, <jboss installation dir>/server/default/deploy/geoserver-service.xml

The contents of the geoserver-service.xml file shall be as following. For more information about this kind of configuration consult the JBoss' JNDIBindingServiceMgr documentation.

 
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE server PUBLIC "-//JBoss//DTD MBean Service 4.0//EN"
           "http://www.jboss.org/j2ee/dtd/jboss-service_4_0.dtd">
 <server>
    <mbean code="org.jboss.naming.JNDIBindingServiceMgr"
         name="jboss.tests:service=JNDIBindingServiceMgr">
       <attribute name="BindingsConfig" serialDataType="jbxb">
          <jndi:bindings
         xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:jndi="urn:jboss:jndi-binding-service:1.0"
         xs:schemaLocation="urn:jboss:jndi-binding-service:1.0 resource:jndi-binding-service_1_0.xsd">

             <jndi:binding name="geotools/arcsdeGlobal">
                <java:properties xmlns:java="urn:jboss:java-properties"
                         xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
                         xs:schemaLocation="urn:jboss:java-properties resource:java-properties_1_0.xsd">
                   <java:property>
                      <java:key>server</java:key>
                      <java:value>172.16.241.128</java:value>
                   </java:property>
                   <java:property>
                      <java:key>port</java:key>
                      <java:value>5151</java:value>
                   </java:property>
                   <java:property>
                      <java:key>instance</java:key>
                      <java:value>sde</java:value>
                   </java:property>
                   <java:property>
                      <java:key>user</java:key>
                      <java:value>sde</java:value>
                   </java:property>
                   <java:property>
                      <java:key>password</java:key>
                      <java:value>sde</java:value>
                   </java:property>
                   <java:property>
                      <java:key>pool.minConnections</java:key>
                      <java:value>2</java:value>
                   </java:property>
                   <java:property>
                      <java:key>pool.maxConnections</java:key>
                      <java:value>10</java:value>
                   </java:property>
                   <java:property>
                      <java:key>pool.timeOut</java:key>
                      <java:value>1000</java:value>
                   </java:property>
                </java:properties>
             </jndi:binding>

          </jndi:bindings>
       </attribute>
       <depends>jboss:service=Naming</depends>
    </mbean>
 </server>

What we're doing here is to create a java.util.Properties object containing the connection parameters, and storing it on the JNDI container at the geotools/arcsdeGlobal path. This is going to be a globally accessible resource that the ArcSDEConnectionFactory will use to create the appropriate connection pool.

But to get this resource visible to your web application, there's one more step missing. In addition to the resource-ref entry in WEB-INF/web.xml mentioned above, JBoss requires an extra config file to manage the indirection between your web application and the globally configured JNDI resource. You'll need to create a file called jboss-web.xml as a sibling of WEB-INF/web.xml with the following content:

 
 
 
     
         geotools/arcsde
         org.geotools.arcsde.session.ISessionPool
         geotools/arcsdeGlobal

Where geotools/arcsdeGlobal is the name of the globally configured resource, and geotools/arcsde is the JNDI name by which the resource will actually be accessible to your web application, and shall match the name used for the resource-ref entry in WEB-INF/web.xml.

Now you're ready to select the ArcSDE JNDI DataStore factory and use the "geotools/arcsde" (or whatever entry name of your choice you have configured) as the DataStore's JNDI resource path name.