Disclaimer and Legal Information
| Version | Version Information | Date |
| Initial version | Alexei Zakharov, Nadya Morozova: document created. | March 23, 2006 |
Copyright 2005-2006 The Apache Software Foundation or its licensors, as applicable.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
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.
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.
This document uses the unified conventions for the DRL documentation kit.
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.
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.
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:
DNSContext class represents the DNS context
and implements the DirContext interface DNSName class represents DNS names and
implements the Name interface DNSNameParser class enables parsing DNS names
and implements the NameParser interface Resolver class and the related set of classes
contain DNS specific algorithms and protocol messages functionality 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:
host is missing, localhost is
used. port is missing, 53 is taken by
default. host and port are missing, the
DNS server is set to the default of localhost:53. domain is missing, the root domain .
is used. 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].
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()
lookupLink()
The lookup algorithm works as follows:
org.apache.harmony.jndi.provider.dns.lookup.attr
property. If the property value contains no attribute identifier, the TXT
attribute is used. getAttributes() to retrieve the values of
attributes with the identifier determined at step 1 for the requested
domain name. DriverManager.getObjectInstance() to obtain
the object instance for the requested domain name and the retrieved
attribute value(s). 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.
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
|
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.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. |
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].
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.
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.
[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/
* Other brands and names are the property of their respective owners.