| <!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> |