1.2 Getting Started

The following sections explain what you need to do to use the LDAP JDBC Driver for the first time.

1.2.1 Accessing the Required Java Classes

A JDBC driver is a collection of Java classes that conform to the JDBC specification. For the LDAP JDBC Driver, these classes are contained in the jar file, ldapjdbc.jar. This jar file must be in the Java class path in order to use the LDAP JDBC Driver. The installation program installs the ldapjdbc.jar file on your machine in the c:\Novell\Java\lib directory unless you specify a path.

The LDAP JDBC Driver is implemented on top of the LDAP Extensions and Controls for JNDI. The LDAP Extensions and Controls for JNDI require the following jar files:

Table 1-1 Jar File Description

Jar File

Description

jndi.jar

JNDI 1.2 (Java Naming and Directory Interface) is a Java standard extension API. This is included with JDK 1.4

ldap.jar

LDAP (Light-weight Directory Access Protocol) provider allows JNDI to access eDirectory and other directories over LDAP. This is included with JDK 1.4.

providerUtil.jar

Provides utility functions for JNDI providers. This is included with JDK 1.4.

novbp.jar

Provides access to the eDirectory specific features through LDAP extensions. This is available by downloading NDK: LDAP Extensions and Controls for JNDI.

1.2.2 Loading the Driver

One of the classes in a JDBC driver is designated as the main driver class. This main driver class must be loaded by your program or by the database tool you are using. The name of the main driver class for the LDAP JDBC Driver is com.novell.sql.LDAPDriver. This class is locate in the ldapjdbc.jar file.

Database tools provide a mechanism for you to specify this class name, and then the tool loads the driver. If you are programming directly to the LDAP JDBC Driver, use the following line of code to load the driver.

      Class.forName("com.novell.sql.LDAPDriver");

This line of code causes the com.novell.sqo.LDAPDriver class to be loaded. When this class is loaded, it registers itself with the JDBC DriverManager class which makes it available for use.

1.2.3 Establishing a Connection

The JDBC protocol uses a URL for the following:

  • Identify the JDBC driver
  • Specify the database to connect to
  • Pass property values to the driver

The URL is always used when programming directly to the driver using the JAVA language and is generally used by most database access tools. The URL for the LDAP JDBC Driver has the following format:

   JDBC:LDAP:<ldap server>[;<property name>=<attribute name>]* [;baseDN=<base DN>]

The following table describes each part of the URL.

Table 1-2 Field Description of an LDAP URL

URL Segment

Description

JDBC:LDAP

Specifies that you are using the JDBC protocol and a subprotocol, LDAP. In other words, the URL says you want a JDBC driver that can communicate with an LDAP server.

:<ldap server>

Identifies the LDAP server the driver should connect to. Its value should contain two forward slashes followed by either the server’s IP address or the domain name.

[;<property name> = <property value>]*

Identifies an optional list of property name and value pairs with an equals sign separating the name and the value and a semicolon delimiting multiple name and value pairs.

The JDBC driver supports the following properties.

Table 1-3 Properties Supported by the JDBC Driver

Property Name

Description

user

The distinguished name of the user entry that will authenticate to the directory. The rights of this user will determine the access rights the driver has to the directory. If the user property is omitted an anonymous bind will be attempted.

password

The password for the user specified by the user property

baseDN

Specifies which container in the tree the driver will report from. Only entries below this container will be contained in the report.

useCleartext

By default the JDBC driver attempts to use an SSL connection to eDirectory. If an SSL connection cannot be established, the driver returns an error. If this property is specified with a value of “true,” a non-secure, non-SSL connection will be established. Since such a connection will pass data and the user password on the network in clear text (not encrypted), this property should only be used in testing environments where the secrecy of passwords in not critical.

When programming in Java, a connection is created by passing the URL to the getConnection method of the DriverManager Class. Several examples are shown below. Note that there are three versions of the getConnection method.

Example 1

   String url = "JDBC:LDAP://137.64.215.139" +
                ";user=cn=jbrown,o=acme" +
                ";password=myPassword" +
                ";baseDN=ou=enginerring,o=ACME";
   
   Connection conn = DriverManager.getConnection(url);

Example 2

   String url = "JDBC:LDAP://137.64.215.139" + 
                ";baseDN=ou=enginerring,o=ACME";
   
   Connection conn = DriverManager.getConnection(url,
                                             "cn=jbrown,o=acme",
                                              "myPassword");

Example 3

   String url = "JDBC:LDAP://ldapserver.ACME.com" + 
   
   Properties props = new Properties();
   props.put("user", "cn=jbrown,o=acme");
   props.put("password", "myPassword");
   props.put("baseDN", "ou=engineering,o=ACME");
   
   Connection conn = DriverManager.getConnection(url, props);

Once a connection has been established you can use the connection object to execute one or more queries.

1.2.4 Obtaining More Information

For more information on using the JDBC interface, see the following sites: