public final class

DnsName

extends Object
implements Name
java.lang.Object
   ↳ com.sun.jndi.dns.DnsName

Class Overview

DnsName implements compound names for DNS as specified by RFCs 1034 and 1035, and as updated and clarified by RFCs 1123 and 2181.

The labels in a domain name correspond to JNDI atomic names. Each label must be less than 64 octets in length, and only the optional root label at the end of the name may be 0 octets long. The sum of the lengths of all labels in a name, plus the number of non-root labels plus 1, must be less than 256. The textual representation of a domain name consists of the labels, escaped as needed, dot-separated, and ordered right-to-left.

A label consists of a sequence of octets, each of which may have any value from 0 to 255.

Host names are a subset of domain names. Their labels contain only ASCII letters, digits, and hyphens, and none may begin or end with a hyphen. While names not conforming to these rules may be valid domain names, they will not be usable by a number of DNS applications, and should in most cases be avoided.

DNS does not specify an encoding (such as UTF-8) to use for octets with non-ASCII values. As of this writing there is some work going on in this area, but it is not yet finalized. DnsName currently converts any non-ASCII octets into characters using ISO-LATIN-1 encoding, in effect taking the value of each octet and storing it directly into the low-order byte of a Java character and vice versa. As a consequence, no character in a DNS name will ever have a non-zero high-order byte. When the work on internationalizing domain names has stabilized (see for example draft-ietf-idn-idna-10.txt), DnsName may be updated to conform to that work.

Backslash (\) is used as the escape character in the textual representation of a domain name. The character sequence `\DDD', where DDD is a 3-digit decimal number (with leading zeros if needed), represents the octet whose value is DDD. The character sequence `\C', where C is a character other than '0' through '9', represents the octet whose value is that of C (again using ISO-LATIN-1 encoding); this is particularly useful for escaping '.' or backslash itself. Backslash is otherwise not allowed in a domain name. Note that escape characters are interpreted when a name is parsed. So, for example, the character sequences `S', `\S', and `\083' each represent the same one-octet name. The toString() method does not generally insert escape sequences except where necessary. If, however, the DnsName was constructed using unneeded escapes, those escapes may appear in the toString result.

Atomic names passed as parameters to methods of DnsName, and those returned by them, are unescaped. So, for example, (new DnsName()).add("a.b") creates an object representing the one-label domain name a\.b, and calling get(0) on this object returns "a.b".

While DNS names are case-preserving, comparisons between them are case-insensitive. When comparing names containing non-ASCII octets, DnsName uses case-insensitive comparison between pairs of ASCII values, and exact binary comparison otherwise.

A DnsName instance is not synchronized against concurrent access by multiple threads.

Summary

[Expand]
Inherited Constants
From interface javax.naming.Name
Public Constructors
DnsName()
Constructs a DnsName representing the empty domain name.
DnsName(String name)
Constructs a DnsName representing a given domain name.
Public Methods
Name add(int pos, String comp)
Adds a single component at a specified position within this name.
Name add(String comp)
Adds a single component to the end of this name.
Name addAll(int pos, Name n)
Adds the components of a name -- in order -- at a specified position within this name.
Name addAll(Name suffix)
Adds the components of a name -- in order -- to the end of this name.
Object clone()
Creates and returns a copy of this object.
int compareTo(Object obj)
Compares this name with another name for order.
boolean endsWith(Name n)
Determines whether this name ends with a specified suffix.
boolean equals(Object obj)
Indicates whether some other object is "equal to" this one.
String get(int pos)
Retrieves a component of this name.
Enumeration getAll()
Retrieves the components of this name as an enumeration of strings.
short getOctets()
Name getPrefix(int pos)
Creates a name whose components consist of a prefix of the components of this name.
Name getSuffix(int pos)
Creates a name whose components consist of a suffix of the components in this name.
int hashCode()
Returns a hash code value for the object.
boolean isEmpty()
Determines whether this name is empty.
boolean isHostName()
Does this domain name follow host name syntax?
Object remove(int pos)
Removes a component from this name.
int size()
Returns the number of components in this name.
boolean startsWith(Name n)
Determines whether this name starts with a specified prefix.
String toString()
Returns a string representation of the object.
[Expand]
Inherited Methods
From class java.lang.Object
From interface java.lang.Comparable
From interface javax.naming.Name

Public Constructors

public DnsName ()

Constructs a DnsName representing the empty domain name.

public DnsName (String name)

Constructs a DnsName representing a given domain name.

Parameters
name the domain name to parse
Throws
InvalidNameException if name does not conform to DNS syntax.

Public Methods

public Name add (int pos, String comp)

Adds a single component at a specified position within this name. Components of this name at or after the index of the new component are shifted up by one (away from index 0) to accommodate the new component.

Parameters
pos the index at which to add the new component. Must be in the range [0,size()].
comp the component to add
Returns
  • the updated name (not a new one)
Throws
InvalidNameException

public Name add (String comp)

Adds a single component to the end of this name.

Parameters
comp the component to add
Returns
  • the updated name (not a new one)
Throws
InvalidNameException

public Name addAll (int pos, Name n)

Adds the components of a name -- in order -- at a specified position within this name. Components of this name at or after the index of the first new component are shifted up (away from 0) to accommodate the new components.

Parameters
pos the index in this name at which to add the new components. Must be in the range [0,size()].
n the components to add
Returns
  • the updated name (not a new one)
Throws
InvalidNameException

public Name addAll (Name suffix)

Adds the components of a name -- in order -- to the end of this name.

Parameters
suffix the components to add
Returns
  • the updated name (not a new one)
Throws
InvalidNameException

public Object clone ()

Creates and returns a copy of this object. The precise meaning of "copy" may depend on the class of the object. The general intent is that, for any object x, the expression: 

 x.clone() != x
will be true, and that the expression: 
 x.clone().getClass() == x.getClass()
will be true, but these are not absolute requirements. While it is typically the case that: 
 x.clone().equals(x)
will be true, this is not an absolute requirement.

By convention, the returned object should be obtained by calling super.clone. If a class and all of its superclasses (except Object) obey this convention, it will be the case that x.clone().getClass() == x.getClass().

By convention, the object returned by this method should be independent of this object (which is being cloned). To achieve this independence, it may be necessary to modify one or more fields of the object returned by super.clone before returning it. Typically, this means copying any mutable objects that comprise the internal "deep structure" of the object being cloned and replacing the references to these objects with references to the copies. If a class contains only primitive fields or references to immutable objects, then it is usually the case that no fields in the object returned by super.clone need to be modified.

The method clone for class Object performs a specific cloning operation. First, if the class of this object does not implement the interface Cloneable, then a CloneNotSupportedException is thrown. Note that all arrays are considered to implement the interface Cloneable. Otherwise, this method creates a new instance of the class of this object and initializes all its fields with exactly the contents of the corresponding fields of this object, as if by assignment; the contents of the fields are not themselves cloned. Thus, this method performs a "shallow copy" of this object, not a "deep copy" operation.

The class Object does not itself implement the interface Cloneable, so calling the clone method on an object whose class is Object will result in throwing an exception at run time.

Returns
  • a clone of this instance.

public int compareTo (Object obj)

Compares this name with another name for order. Returns a negative integer, zero, or a positive integer as this name is less than, equal to, or greater than the given name.

As with Object.equals(), the notion of ordering for names depends on the class that implements this interface. For example, the ordering may be based on lexicographical ordering of the name components. Specific attributes of the name, such as how it treats case, may affect the ordering. In general, two names of different classes may not be compared.

Parameters
obj the non-null object to compare against.
Returns
  • a negative integer, zero, or a positive integer as this name is less than, equal to, or greater than the given name

public boolean endsWith (Name n)

Determines whether this name ends with a specified suffix. A name n is a suffix if it is equal to getSuffix(size()-n.size()).

Parameters
n the name to check
Returns
  • true if n is a suffix of this name, false otherwise

public boolean equals (Object obj)

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

  • It is reflexive: for any non-null reference value x, x.equals(x) should return true.
  • It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
  • It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
  • It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
  • For any non-null reference value x, x.equals(null) should return false.

The equals method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any non-null reference values x and y, this method returns true if and only if x and y refer to the same object (x == y has the value true).

Note that it is generally necessary to override the hashCode method whenever this method is overridden, so as to maintain the general contract for the hashCode method, which states that equal objects must have equal hash codes.

Parameters
obj the reference object with which to compare.
Returns
  • true if this object is the same as the obj argument; false otherwise.

public String get (int pos)

Retrieves a component of this name.

Parameters
pos the 0-based index of the component to retrieve. Must be in the range [0,size()).
Returns
  • the component at index posn

public Enumeration getAll ()

Retrieves the components of this name as an enumeration of strings. The effect on the enumeration of updates to this name is undefined. If the name has zero components, an empty (non-null) enumeration is returned.

Returns
  • an enumeration of the components of this name, each a string

public short getOctets ()

public Name getPrefix (int pos)

Creates a name whose components consist of a prefix of the components of this name. Subsequent changes to this name will not affect the name that is returned and vice versa.

Parameters
pos the 0-based index of the component at which to stop. Must be in the range [0,size()].
Returns
  • a name consisting of the components at indexes in the range [0,posn).

public Name getSuffix (int pos)

Creates a name whose components consist of a suffix of the components in this name. Subsequent changes to this name do not affect the name that is returned and vice versa.

Parameters
pos the 0-based index of the component at which to start. Must be in the range [0,size()].
Returns
  • a name consisting of the components at indexes in the range [posn,size()). If posn is equal to size(), an empty name is returned.

public int hashCode ()

Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the equals(java.lang.Object) method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hashtables.

As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the JavaTM programming language.)

Returns
  • a hash code value for this object.

public boolean isEmpty ()

Determines whether this name is empty. An empty name is one with zero components.

Returns
  • true if this name is empty, false otherwise

public boolean isHostName ()

Does this domain name follow host name syntax?

public Object remove (int pos)

Removes a component from this name. The component of this name at the specified position is removed. Components with indexes greater than this position are shifted down (toward index 0) by one.

Parameters
pos the index of the component to remove. Must be in the range [0,size()).
Returns
  • the component removed (a String)

public int size ()

Returns the number of components in this name.

Returns
  • the number of components in this name

public boolean startsWith (Name n)

Determines whether this name starts with a specified prefix. A name n is a prefix if it is equal to getPrefix(n.size()).

Parameters
n the name to check
Returns
  • true if n is a prefix of this name, false otherwise

public String toString ()

Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of: 

 getClass().getName() + '@' + Integer.toHexString(hashCode())

Returns
  • a string representation of the object.