DNS Service Provider

1. Revision History
2. About this Document
   1. Purpose
   2. Intended Audience
   3. Documentation Conventions
3. Introduction to DNS Provider
4. DNS Provider in DRL
   1. About
   2. DNS URL Syntax
   3. Attribute Identifiers
   4. API Mapping
   5. Environment Properties
   6. DNS Resolver
   7. Federation
5. Appendix: Usage Examples
6. References

Revision History

Version	Version Information	Date
Initial version	Alexei Zakharov, Nadya Morozova: document created.	March 23, 2006
Formatting update	Nadya Morozova	September 21, 2006

About This Document

Purpose

This document introduces the DRL implementation of the DNS service provider for JNDI, the Java* Naming Directory Interface. The document gives details on the DNS provider design, includes an overall description of the package, and includes helpful usage examples. The description documents the first version of the DRL DNS service provider deployed in March 2006.

Intended Audience

The target audience for the document includes a wide community of engineers interested in using the DNS service provider for JNDI and in further work with the product to contribute to its development. The document assumes that readers are familiar with the Java* programming language, the Java* Naming Directory Interface, and common concepts of the DNS protocol.

Documentation Conventions

This document uses the unified conventions for the DRL documentation kit.

Back to Top

Introduction to DNS Provider

The DNS service provider enables Java* applications to access information stored in the Domain Name System database by means of the Java* Naming and Directory Interface [1]. The provider presents the DNS namespace as a tree of JNDI directory contexts, and DNS resource records as JNDI attributes.

Back to Top

DNS Provider in DRL

This part of the document describes the DRL implementation of the DNS provider as a whole and defines the API mapping, environment properties usage, and other specific aspects.

About

This is an independent implementation of the DNS service provider for JNDI. More detailed information on JNDI and JNDI service providers can be found at [1].

In DRL, the DNS service provider is a directory context associated with a domain name. This way, DNS resource records correspond to JNDI attributes. The DNS support functionality is mainly represented by the following classes of the org.apache.harmony.jndi.provider.dns package:

• The DNSContext class represents the DNS context and implements the DirContext interface
• The DNSName class represents DNS names and implements the Name interface
• The DNSNameParser class enables parsing DNS names and implements the NameParser interface
• The Resolver class and the related set of classes contain DNS specific algorithms and protocol messages functionality

DNS URL Syntax

The DNS URL, or DNS Pseudo URL, passes the initial information to the DNS context as a value for the java.naming.provider.url property or as an argument to a method of the initial context via the DNS URL provider. The DNS URL is defined in the following format:

dns:[//host[:port]][/domain]

A given combination of host and port indicates the DNS server to be used for serving requests about a given domain. Given partial data, the following values are used instead of missing parameters:

• If host is missing, localhost is used.
• If port is missing, 53 is taken by default.
• If host and port are missing, the DNS server is set to the default of localhost:53.
• If domain is missing, the root domain . is used.

Back to Top

Attribute Identifiers

Because this provider presents DNS resource records in the form of JNDI attributes, the exact format of attribute identifiers must be defined. These identifiers are accepted by different methods of the DNS provider. An identifier consists of the following combination of DNS class and type information:

[CLASS_IDENTIFIER] TYPE_IDENTIFIER

Currently supported class identifiers:

• IN - Internet class
• HS - Hesiod class (not tested)

Currently supported type identifiers:

• A - address record
• NS - name server record
• CNAME - canonical name for record
• SOA - start of authority record
• PTR - name pointer record
• MX - mail exchange
• TXT - text record
• HINFO - host information
• SRV - location of services record

If the class identifier is missing, the provider assumes the IN class identifier. For an unsupported attribute type, calling getAttributes() returns a numerical value rather than its type ID. The symbol "" indicates ANY type or class, so that an empty string stands for any type in any class.

For more details about DNS resource record classes and types, see RFC 1035 [2].

Back to Top

API Mapping

The DNSContext class, the main class of the DRL DNS provider, implements the DirContext interface. Because DNS allows a read-only service, DNSContext provides only a part of the overall DirContext functionality.

Below is the list of supported DirContext methods grouped by functionality. All other methods throw javax.naming.OperationNotSupportedException.

Environment operations

addToEnvironment()
getEnvironent()
removeFromEnvironment()

Operations with DNS names

composeName()
getNameInNamespace()
getNameParser()

Querying attribute values

getAttributes()

This method queries the attribute values from the remote DNS server or the local provider's cache.

Lookup operations

lookup()
lookupLink()

The lookup algorithm works as follows:

1. Determines the attribute identifier (ID) contained in the org.apache.harmony.jndi.provider.dns.lookup.attr property. If the property value contains no attribute identifier, the TXT attribute is used.
2. Calls getAttributes() to retrieve the values of attributes with the identifier determined at step 1 for the requested domain name.
3. Calls DriverManager.getObjectInstance() to obtain the object instance for the requested domain name and the retrieved attribute value(s).
4. Returns the object instance to the user application.

Note

The user object factory must be able to create object instances for an object of the org.apache.harmony.jndi.provider.dns.DNSContext class [1]. If no object factories have been specified, the lookup methods return an instance of DNSContext.

List operations

list()
listBindings()

These methods list the entire content of the DNS zone via DNS zone transfer mechanism.

Releasing all resources

close()

Note

Currently, this method does nothing because it has nothing to release.

Back to Top

Environment Properties

The DNS service provider accepts a number of environment properties as shown in the table below.

Property Name	Function
java.naming.authoritative	Sets the authoritative bit [2] for all outgoing messages when TRUE.
org.apache.harmony.jndi.provider.dns.lookup.attr	Specifies the attribute identifier to be used in the lookup algorithm.
org.apache.harmony.jndi.provider.dns.recursion	Sets the recursion bit for outgoing messages when TRUE.
org.apache.harmony.jndi.provider.dns.timeout.initial	Indicates the initial timeout. When accessing remote data, the DNS client tries to query all possible remote servers with this value taken as a timeout. If this fails, the client increases the initial timeout value by two times. If this also fails, a value 4 times greater than the initial timeout is taken and so on (x8, x16, ... ) until the maximum number of timeout retries is reached, see the description of property org.apache.harmony.jndi.provider.dns.timeout.retries.
org.apache.harmony.jndi.provider.dns.timeout.retries	Sets the number of timeout retries, that is, the maximum number of retries that can be performed when accessing a remote DNS server. If all attempts fail and the maximum number of retries is reached, the user gets an error message, see the description of property org.apache.harmony.jndi.provider.dns.timeout.initial.
org.apache.harmony.jndi.providers.dns.threads.max	Determines the maximum number of threads that can be started by a single instance of the DNS context. The default value is 7.
java.naming.provider.url	Enumerates the initial DNS URLs. Multiple URLs must go in a space-separated list, see DNS URL Syntax. During instantiation, the DNS provider fills its internal tables with the given DNS server and controlled domain pairs. The domain part of all URLs must be identical. The newly created DNS context is associated with this domain name.

Back to Top

DNS Resolver

The DRL DNS provider includes an independent fully-functional DNS resolver with its own SLIST table and local cache. The SLIST table and the cache are singleton classes shared among all instances of the resolver. The resolver conforms with RFC 1034 on general principles and algorithms used by the resolver, and with RFC 1035 on respective records and message formats. The standards RFC 1123, 2181, and 2782 are also relevant [2].

Back to Top

Federation

The DLR DNS provider has built-in federation support. Implicit next naming system is determined dynamically. If the DNS context encounters the border of the DNS namespace, it calls the DirectoryManager.getContinuationContext( ) method and forwards the call to the obtained next naming system context.

Unsupported methods, such as bind() and rename(), also perform the initial check. The user gets javax.naming.OperationNotSupportedException for these methods only if the requested name is entirely inside the DNS namespace.

Back to Top

Appendix: Usage Examples

Below is an example of using the provider as the initial context. In the example, the DNSContextFactory class is specified as the default factory for producing initial contexts.

Hashtable env = new Hashtable();

DirectoryContext ctx;

Attributes attrs;



env.put(Context.INITIAL_CONTEXT_FACTORY,

        "org.apache.harmony.jndi.provider.dns.DNSContextFactory");

env.put(Context.PROVIDER_URL,

        "dns://dns01.example.com/subdomain.example.com");

ctx = new InitialDirContext(env);



// Obtain A and CNAME records for server1.subdomain.example.com

attrs = ctx.getAttributes("server1", new String[] {"A", "CNAME"});

The provider can also be accessed by passing a DNS URL to any initial context method that accepts string arguments. For that, set the following property before calling a method of the initial context:

env.put(Context.URL_PKG_PREFIXES, "org.apache.harmony.jndi.provider.dns");

ctx = new InitialDirContext(env);



// Add server with IP address 192.168.1.111 to SLIST as a server

// responsible for serving requests about host11.subdomain.example.com

// Retrieve A and HINFO records for host11.subdomin.example.com

attrs = ctx.getAttributes("dns://192.168.1.111/host11.subdomain.example.com",

                          new String[] {"A", "HINFO"});

The class dnsURLContext actually serves requests of this type.

Back to Top

References

[1] Java* Naming And Directory Interface, http://java.sun.com/j2se/1.5.0/docs/guide/jndi/index.html

[2] Internet Engineering Task Force, Requests for Comments, http://www.ietf.org/

Back to Top

* Other brands and names are the property of their respective owners.