doc/jndi_dns/DNSsupport.htm

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> <title>DNS Service Provider</title> <link rel="Stylesheet" type="text/css" href="../harmony.css"> </head> <body> <p class="title"> <a name="top"></a>DNS Service Provider </p> <p class="TOCHeading"> <a href="#Revision_History">Revision History</a> </p> <p class="TOCHeading"> <a href="#Disclaimer_and_Legal">Disclaimer and Legal Information</a> </p> <p class="TOCHeading"> <a href="#About_This_Document">About This Document</a> </p> <p class="TOC"> <a href="#Purpose">Purpose</a> </p> <p class="TOC"> <a href="#Intended_Audience">Intended Audience</a> </p> <p class="TOC"> <a href="#Documentation_Conventions">Documentation Conventions</a> </p> <p class="TOCHeading"> <a href="#DNS_Provider_Overview">Introduction to DNS Provider </a> </p> <p class="TOCHeading"> <a href="#DNS_Provider_in_DRL">DNS Provider in DRL</a> </p> <p class="TOC"> <a href="#About_DRL_DNS">About</a> </p> <p class="TOC"> <a href="#DNS_URL_Syntax">DNS URL Syntax</a> </p> <p class="TOC"> <a href="#Attribute_Identifiers">Attribute Identifiers</a> </p> <p class="TOC"> <a href="#API_Mapping">API Mapping</a> </p> <p class="TOC"> <a href="#Environment_Properties">Environment Properties</a> </p> <p class="TOC"> <a href="#DNS_Resolver">DNS Resolver</a> </p> <p class="TOC"> <a href="#Federation">Federation</a> </p> <p class="TOCHeading"> <a href="#Appendix_Usage_Examples">Appendix: Usage Examples</a> </p> <p class="TOCHeading"> <a href="#References">References</a> </p> <h1> <a name="Revision_History"></a>Revision History </h1> <table border="0" cellpadding="0" width="100%"> <tbody> <tr> <td class="TableHeading" width="24%"> Version </td> <td class="TableHeading" width="49%"> Version Information </td> <td class="TableHeading"> Date </td> </tr> <tr> <td class="TableCell" width="24%"> Initial version </td> <td class="TableCell" width="49%"> Alexei Zakharov, Nadya Morozova: document created. </td> <td class="TableCell">  March 23, 2006 </td> </tr> </tbody> </table> <h1> <a name="Disclaimer_and_Legal"></a>Disclaimer and Legal Information </h1> <p> Copyright 2005-2006 The Apache Software Foundation or its licensors, as applicable. </p> <p> 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 <a href="http://www.apache.org/licenses/LICENSE-2.0" target="_blank"> http://www.apache.org/licenses/LICENSE-2.0</a>. </p> <p> 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. </p> <h1> <a name="About_This_Document"></a>About This Document </h1> <h2> <a name="Purpose"></a>Purpose </h2> <p> This document introduces the DRL implementation of the DNS service provider for JNDI, the Java<a href="#*">*</a> 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. </p> <h2> <a name="Intended_Audience"></a>Intended Audience </h2> <p> 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<a href="#*">*</a> programming language, the Java<a href="#*">*</a> Naming Directory Interface, and common concepts of the DNS protocol. </p> <h2> <a name="Documentation_Conventions"></a>Documentation Conventions </h2> <p> This document uses the <a href="conventions.htm">unified conventions</a> for the DRL documentation kit. </p> <p class="backtotop"> <a href="#top">Back to Top</a> </p> <h1> <a name="DNS_Provider_Overview"></a>Introduction to DNS Provider </h1> <p> The DNS service provider enables Java<a href="#*">*</a> applications to access information stored in the Domain Name System database by means of the Java<a href="#*">*</a> Naming and Directory Interface [<a href="#JNDI">1</a>]. The provider presents the DNS namespace as a tree of JNDI directory contexts, and DNS resource records as JNDI attributes. </p> <p class="backtotop"><a href="#top">Back to Top</a> </p> <h1> <a name="DNS_Provider_in_DRL"></a>DNS Provider in DRL </h1> <p> 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. </p> <h2> <a name="About_DRL_DNS"></a>About </h2> <p><font face="Arial" size="2"><span style="font-size: 10pt; font-family: Arial;" lang="EN-US">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 </span></font>[<a href="DNSsupport.htm#JNDI">1</a>]. </p> <p> 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 <code>org.apache.harmony.jndi.provider.dns</code> package: </p> <ul> <li> The <code>DNSContext</code> class represents the DNS context and implements the <code>DirContext</code> interface </li> <li> The <code>DNSName</code> class represents DNS names and implements the <code>Name</code> interface </li> <li> The <code>DNSNameParser</code> class enables parsing DNS names and implements the <code>NameParser</code> interface </li> <li> The <code>Resolver</code> class and the related set of classes contain DNS specific algorithms and protocol messages functionality </li> </ul> <h2> <a name="DNS_URL_Syntax"></a>DNS URL Syntax </h2> <p> The DNS URL, or <i>DNS Pseudo URL</i>, passes the initial information to the DNS context as a value for the <code>java.naming.provider.url</code> 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: </p> <pre>dns:[//host[:port]][/domain]<br></pre> <p> A given combination of <code>host</code> and <code>port</code> 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: </p> <ul> <li> If <code>host</code> is missing, <code>localhost</code> is used. </li> <li> If <code>port</code> is missing, <code>53</code> is taken by default. </li> <li> If <code>host</code> and <code>port</code> are missing, the DNS server is set to the default of <code>localhost:53</code>. </li> <li> If <code>domain</code> is missing, the root domain <code>.</code> is used. </li> </ul> <p class="backtotop"> <a href="#top">Back to Top</a> </p> <h2> <a name="Attribute_Identifiers"></a>Attribute Identifiers </h2> <p> 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: </p> <pre>[CLASS_IDENTIFIER] TYPE_IDENTIFIER<br></pre> <p> Currently supported class identifiers: </p> <ul> <li> <code>IN</code> - Internet class </li> <li> <code>HS</code> - Hesiod class (not tested) </li> </ul> <p> Currently supported type identifiers: </p> <ul> <li> <code>A</code> - address record </li> <li> <code>NS</code> - name server record </li> <li> <code>CNAME</code> - canonical name for record </li> <li> <code>SOA</code> - start of authority record </li> <li> <code>PTR</code> - name pointer record </li> <li> <code>MX</code> - mail exchange </li> <li> <code>TXT</code> - text record </li> <li> <code>HINFO</code> - host information </li> <li> <code>SRV</code> - location of services record </li> </ul> <p> If the class identifier is missing, the provider assumes the <code>IN</code> class identifier. For an unsupported attribute type, calling <code>getAttributes()</code> returns a numerical value rather than its type ID. The symbol <code>""</code> indicates <code>ANY</code> type or class, so that an empty string stands for any type in any class. </p> <p> For more details about DNS resource record classes and types, see RFC 1035 [<a href="#RFC">2</a>]. </p> <p class="backtotop"> <a href="#top">Back to Top</a> </p> <h2> <a name="API_Mapping"></a>API Mapping </h2> <p> The <code>DNSContext</code> class, the main class of the DRL DNS provider, implements the <code>DirContext</code> interface. Because DNS allows a read-only service, <code>DNSContext</code> provides only a part of the overall <code>DirContext</code> functionality. </p> <p> Below is the list of supported <code>DirContext</code> methods grouped by functionality. All other methods throw <code>javax.naming.OperationNotSupportedException</code>. </p> <p class="class"> Environment operations</p> <p class="notetext"> <code>addToEnvironment()</code> <br> <code>getEnvironent()</code><br> <code>removeFromEnvironment()</code> </p> <p class="class"> Operations with DNS names </p> <p class="notetext"> <code>composeName()</code><br> <code>getNameInNamespace()</code><br> <code>getNameParser()</code> </p> <p class="class"> Querying attribute values </p> <p class="notetext"> <code>getAttributes()</code> </p> <p> This method queries the attribute values from the remote DNS server or the local provider's cache. </p> <p class="class"> <a name="Lookup"></a>Lookup operations </p> <p class="notetext"> <code>lookup()</code><br> <code>lookupLink()</code> </p> <p> The lookup algorithm works as follows: </p> <ol> <li> Determines the attribute identifier (ID) contained in the <code>org.apache.harmony.jndi.provider.dns.lookup.attr</code> property. If the property value contains no attribute identifier, the <code>TXT</code> attribute is used. </li> <li> Calls <code>getAttributes()</code> to retrieve the values of attributes with the identifier determined at step 1 for the requested domain name. </li> <li> Calls <code>DriverManager.getObjectInstance()</code> to obtain the object instance for the requested domain name and the retrieved attribute value(s). </li> <li> Returns the object instance to the user application. </li> </ol> <p class="note"> Note </p> <p class="notetext"> The user object factory must be able to create object instances for an object of the <code>org.apache.harmony.jndi.provider.dns.DNSContext</code> class [<a href="#JNDI">1</a>]. If no object factories have been specified, the lookup methods return an instance of <code>DNSContext</code>. </p> <p class="class"> List operations </p> <p class="notetext"> <code>list()</code><br> <code>listBindings()</code> </p> <p> These methods list the entire content of the DNS zone via DNS zone transfer mechanism. </p> <p class="class"> Releasing all resources </p> <p class="notetext"> <code>close()</code> </p> <p class="note"> Note </p> <p class="notetext"> Currently, this method does nothing because it has nothing to release.<br> </p> <p class="backtotop"> <br> <a href="#top">Back to Top</a> </p> <h2> <a name="Environment_Properties"></a>Environment Properties </h2> <p> The DNS service provider accepts a number of environment properties as shown in the table below. </p> <table> <tbody> <tr> <td colspan="1" class="TableHeading"> Property Name </td> <td class="TableHeading" width="394"> Function </td> </tr> <tr> <td class="TableCell"> <code> java.naming.authoritative</code> </td> <td class="TableCell">Sets the authoritative bit [<a href="#RFC">2</a>] for all outgoing messages when <code>TRUE</code>. </td> </tr> <tr> <td class="TableCell"> <code>org.apache.harmony.jndi.provider.dns.lookup.attr</code> </td> <td class="TableCell"> Specifies the attribute identifier to be used in the <a href="#Lookup">lookup algorithm</a>. </td> </tr> <tr> <td class="TableCell"> <code>org.apache.harmony.jndi.provider.dns.recursion</code> </td> <td class="TableCell">Sets the recursion bit for outgoing messages when <code>TRUE</code>. </td> </tr> <tr> <td class="TableCell"> <code>org.apache.harmony.jndi.provider.dns.timeout.initial</code> </td> <td class="TableCell">Indicates the initial timeout. <p> 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 <code>org.apache.harmony.jndi.provider.dns.timeout.retries</code>. </p> </td> </tr> <tr> <td class="TableCell"> <code>org.apache.harmony.jndi.provider.dns.timeout.retries</code> </td> <td class="TableCell">Sets the number of timeout retries, that is, the maximum number of retries that can be performed when accessing a remote DNS server. <p>If all attempts fail and the maximum number of retries is reached, the user gets an error message, see the description of property <code>org.apache.harmony.jndi.provider.dns.timeout.initial</code>. </p> </td> </tr> <tr> <td class="TableCell"> <code>org.apache.harmony.jndi.providers.dns.threads.max</code> </td> <td class="TableCell">Determines the maximum number of threads that can be started by a single instance of the DNS context. The default value is 7. </td> </tr> <tr> <td class="TableCell"> <code>java.naming.provider.url</code> </td> <td class="TableCell">Enumerates the initial DNS URLs. <p>Multiple URLs must go in a space-separated list, see <a href="#DNS_URL_Syntax">DNS URL Syntax</a>. 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.</p> </td> </tr> </tbody> </table> <p class="backtotop"> <a href="#top">Back to Top</a> </p> <h2> <a name="DNS_Resolver"></a>DNS Resolver </h2> <p> 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 [<a href="#RFC">2</a>]. </p> <p class="backtotop"> <a href="#top">Back to Top</a> </p> <h2> <a name="Federation"></a>Federation </h2> <p> 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 <code>DirectoryManager.getContinuationContext</code><code>(</code><code>)</code> method and forwards the call to the obtained next naming system context. </p> <p>Unsupported methods, such as <code>bind(</code><code>) </code>and <code>rename()</code>, also perform the initial check. The user gets <code>javax.naming.OperationNotSupportedException</code> for these methods only if the requested name is entirely inside the DNS namespace. </p> <p class="backtotop"> <a href="#top">Back to Top</a> </p> <h1> <a name="Appendix_Usage_Examples"></a>Appendix: Usage Examples </h1> <p> Below is an example of using the provider as the initial context. In the example, the <code>DNSContextFactory</code> class is specified as the default factory for producing initial contexts. </p> <pre>Hashtable env = new Hashtable();<br>DirectoryContext ctx;<br>Attributes attrs;<br><br>env.put(Context.INITIAL_CONTEXT_FACTORY, <br> "org.apache.harmony.jndi.provider.dns.DNSContextFactory");<br>env.put(Context.PROVIDER_URL, <br> "dns://dns01.example.com/subdomain.example.com");<br>ctx = new InitialDirContext(env);<br><br>// Obtain A and CNAME records for server1.subdomain.example.com <br>attrs = ctx.getAttributes("server1", new String[] {"A", "CNAME"});<br></pre> <p> 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: </p> <pre>env.put(Context.URL_PKG_PREFIXES, "org.apache.harmony.jndi.provider.dns");<br>ctx = new InitialDirContext(env);<br><br>// Add server with IP address 192.168.1.111 to SLIST as a server<br>// responsible for serving requests about host11.subdomain.example.com <br>// Retrieve A and HINFO records for host11.subdomin.example.com <br>attrs = ctx.getAttributes("dns://192.168.1.111/host11.subdomain.example.com",<br> new String[] {"A", "HINFO"});<br></pre> <p> The class <code>dnsURLContext</code> actually serves requests of this type. </p> <p class="backtotop"> <a href="#top">Back to Top</a> </p> <h1> <a name="References"></a>References </h1> <p>[<a name="JNDI"></a>1] Java<a href="#*">*</a> Naming And Directory Interface, <a href="http://java.sun.com/j2se/1.5.0/docs/guide/jndi/index.html" target="_blank">http://java.sun.com/j2se/1.5.0/docs/guide/jndi/index.html</a> </p> <p>[<a name="RFC"></a>2] Internet Engineering Task Force, Requests for Comments, <a href="http://www.ietf.org/" target="_blank">http://www.ietf.org/</a> </p> <p> </p> <p class="backtotop"> <a href="#top">Back to Top</a> </p> <p> <a name="*">*</a> Other brands and names are the property of their respective owners. </p> </body> </html>

doc/jndi_dns/DNSsupport.htm (350 lines of code) (raw):