OpenJDK 27 · com.sun.jndi.dns.DnsName · APIdia, the JavaDoc alternative

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.

Field Summary

Modifier and Type	Field and Description
private String	domain
private ArrayList<String>	labels
private short	octets
private static final long	serialVersionUID Hides javax.naming.Name.serialVersionUID.

Constructor Summary

Access	Constructor and Description
public	DnsName() Constructs a `DnsName` representing the empty domain name.
public	DnsName(String the domain name to parse name) Constructs a `DnsName` representing a given domain name.
private	DnsName(DnsName n, int beg, int end)

Method Summary

Modifier and Type	Method and Description
public Name	add(String comp) Implements javax.naming.Name.add. Adds a single component to the end of this name.
public Name	add(int pos, String comp) Implements javax.naming.Name.add. Adds a single component at a specified position within this name.
public Name	addAll(Name suffix) Implements javax.naming.Name.addAll. Adds the components of a name -- in order -- to the end of this name.
public Name	addAll(int pos, Name n) Implements javax.naming.Name.addAll. Adds the components of a name -- in order -- at a specified position within this name.
public Object	clone() Overrides java.lang.Object.clone. Implements javax.naming.Name.clone. Generates a new copy of this name.
private static int	compareLabels(String label1, String label2)
private int	compareRange(int beg, int end, Name n)
public int	compareTo(Object obj) Implements javax.naming.Name.compareTo. Compares this name with another name for order.
public boolean	endsWith(Name n) Implements javax.naming.Name.endsWith. Determines whether this name ends with a specified suffix.
public boolean	equals(Object obj) Overrides java.lang.Object.equals. Indicates whether some other object is "equal to" this one.
private static void	escape(StringBuilder buf, String label)
public String	get(int pos) Implements javax.naming.Name.get. Retrieves a component of this name.
public Enumeration<String>	getAll() Implements javax.naming.Name.getAll. Retrieves the components of this name as an enumeration of strings.
private static char	getEscapedOctet(String name, int pos)
pack-priv String	getKey(int i)
public short	getOctets()
public Name	getPrefix(int pos) Implements javax.naming.Name.getPrefix. Creates a name whose components consist of a prefix of the components of this name.
public Name	getSuffix(int pos) Implements javax.naming.Name.getSuffix. Creates a name whose components consist of a suffix of the components in this name.
public int	hashCode() Overrides java.lang.Object.hashCode. Returns a hash code value for this object.
pack-priv boolean	hasRootLabel()
private static boolean	isDigit(char c)
public boolean	isEmpty() Implements javax.naming.Name.isEmpty. Determines whether this name is empty.
public boolean	isHostName() Does this domain name follow host name syntax?
private static boolean	isHostNameChar(char c)
private static boolean	isHostNameLabel(String label)
private static String	keyForLabel(String label)
private void	parse(String name)
private void	readObject(ObjectInputStream s)
public Object	remove(int pos) Implements javax.naming.Name.remove. Removes a component from this name.
public int	size() Implements javax.naming.Name.size. Returns the number of components in this name.
public boolean	startsWith(Name n) Implements javax.naming.Name.startsWith. Determines whether this name starts with a specified prefix.
public String	toString() Overrides java.lang.Object.toString. Returns a string representation of the object.
private static void	verifyLabel(String label)
private void	writeObject(ObjectOutputStream s) Serializes only the domain name string, for compactness and to avoid any implementation dependency.

Inherited from java.lang.Object:: finalize getClass notify notifyAll wait wait wait

Field Detail

domain	back to summary
private String domain

labels	back to summary
private ArrayList<String> labels

octets	back to summary
private short octets

serialVersionUID	back to summary
private static final long serialVersionUID Hides javax.naming.Name.serialVersionUID.

Constructor Detail

DnsName	back to summary
public DnsName() Constructs a `DnsName` representing the empty domain name.

DnsName back to summary

DnsName	back to summary
public DnsName(String name) throws InvalidNameException Constructs a `DnsName` representing a given domain name. Parameters name:String the domain name to parse Exceptions InvalidNameException: if `name` does not conform to DNS syntax.

public DnsName(String name) throws InvalidNameException

Constructs a DnsName representing a given domain name.

Parameters

name:String: the domain name to parse

Exceptions

InvalidNameException:: if name does not conform to DNS syntax.

DnsName	back to summary
private DnsName(DnsName n, int beg, int end)

Method Detail

add back to summary

add	back to summary
public Name add(String comp) throws InvalidNameException Implements javax.naming.Name.add. Doc from javax.naming.Name.add. Adds a single component to the end of this name. Exceptions InvalidNameException: if adding `comp` would violate the syntax rules of this name

public Name add(String comp) throws InvalidNameException

Implements javax.naming.Name.add.

Doc from javax.naming.Name.add.

Adds a single component to the end of this name.

Exceptions

InvalidNameException:: if adding comp would violate the syntax rules of this name

add back to summary

add	back to summary
public Name add(int pos, String comp) throws InvalidNameException Implements javax.naming.Name.add. Doc from javax.naming.Name.add. 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. Exceptions InvalidNameException: if adding `comp` would violate the syntax rules of this name

public Name add(int pos, String comp) throws InvalidNameException

Implements javax.naming.Name.add.

Doc from javax.naming.Name.add.

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.

Exceptions

InvalidNameException:: if adding comp would violate the syntax rules of this name

addAll back to summary

addAll	back to summary
public Name addAll(Name suffix) throws InvalidNameException Implements javax.naming.Name.addAll. Doc from javax.naming.Name.addAll. Adds the components of a name -- in order -- to the end of this name. Exceptions InvalidNameException: if `suffix` is not a valid name, or if the addition of the components would violate the syntax rules of this name

public Name addAll(Name suffix) throws InvalidNameException

Implements javax.naming.Name.addAll.

Doc from javax.naming.Name.addAll.

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

Exceptions

InvalidNameException:: if suffix is not a valid name, or if the addition of the components would violate the syntax rules of this name

addAll back to summary

addAll	back to summary
public Name addAll(int pos, Name n) throws InvalidNameException Implements javax.naming.Name.addAll. Doc from javax.naming.Name.addAll. 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. Exceptions InvalidNameException: if `n` is not a valid name, or if the addition of the components would violate the syntax rules of this name

public Name addAll(int pos, Name n) throws InvalidNameException

Implements javax.naming.Name.addAll.

Doc from javax.naming.Name.addAll.

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.

Exceptions

InvalidNameException:: if n is not a valid name, or if the addition of the components would violate the syntax rules of this name

clone	back to summary
public Object clone() Overrides java.lang.Object.clone. Implements javax.naming.Name.clone. Doc from javax.naming.Name.clone. Generates a new copy of this name. Subsequent changes to the components of this name will not affect the new copy, and vice versa.

clone

back to summary

public Object clone()

Overrides java.lang.Object.clone.

Implements javax.naming.Name.clone.

Doc from javax.naming.Name.clone.

Generates a new copy of this name. Subsequent changes to the components of this name will not affect the new copy, and vice versa.

compareLabels	back to summary
private static int compareLabels(String label1, String label2)

compareRange	back to summary
private int compareRange(int beg, int end, Name n)

compareTo back to summary

compareTo	back to summary
public int compareTo(Object obj) Implements javax.naming.Name.compareTo. Doc from javax.naming.Name.compareTo. 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.

public int compareTo(Object obj)

Implements javax.naming.Name.compareTo.

Doc from javax.naming.Name.compareTo.

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.

endsWith back to summary

endsWith	back to summary
public boolean endsWith(Name n) Implements javax.naming.Name.endsWith. Doc from javax.naming.Name.endsWith. Determines whether this name ends with a specified suffix. A name `n` is a suffix if it is equal to `getSuffix(size()-n.size())`.

public boolean endsWith(Name n)

Implements javax.naming.Name.endsWith.

Doc from javax.naming.Name.endsWith.

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

equals back to summary

equals	back to summary
public boolean equals(Object obj) Overrides java.lang.Object.equals. Doc from java.lang.Object.equals. 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`. An equivalence relation partitions the elements it operates on into equivalence classes; all the members of an equivalence class are equal to each other. Members of an equivalence class are substitutable for each other, at least for some purposes.

public boolean equals(Object obj)

Overrides java.lang.Object.equals.

Doc from java.lang.Object.equals.

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.

An equivalence relation partitions the elements it operates on into equivalence classes; all the members of an equivalence class are equal to each other. Members of an equivalence class are substitutable for each other, at least for some purposes.

escape	back to summary
private static void escape(StringBuilder buf, String label)

get	back to summary
public String get(int pos) Implements javax.naming.Name.get. Doc from javax.naming.Name.get. Retrieves a component of this name.

get

back to summary

public String get(int pos)

Implements javax.naming.Name.get.

Doc from javax.naming.Name.get.

Retrieves a component of this name.

getAll	back to summary
public Enumeration<String> getAll() Implements javax.naming.Name.getAll. Doc from javax.naming.Name.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.

getAll

back to summary

public Enumeration<String> getAll()

Implements javax.naming.Name.getAll.

Doc from javax.naming.Name.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.

getEscapedOctet	back to summary
private static char getEscapedOctet(String name, int pos) throws InvalidNameException

getKey	back to summary
pack-priv String getKey(int i)

getOctets	back to summary
public short getOctets()

getPrefix	back to summary
public Name getPrefix(int pos) Implements javax.naming.Name.getPrefix. Doc from javax.naming.Name.getPrefix. 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.

getPrefix

back to summary

public Name getPrefix(int pos)

Implements javax.naming.Name.getPrefix.

Doc from javax.naming.Name.getPrefix.

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.

getSuffix	back to summary
public Name getSuffix(int pos) Implements javax.naming.Name.getSuffix. Doc from javax.naming.Name.getSuffix. 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.

getSuffix

back to summary

public Name getSuffix(int pos)

Implements javax.naming.Name.getSuffix.

Doc from javax.naming.Name.getSuffix.

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.

hashCode back to summary

hashCode	back to summary
public int hashCode() Overrides java.lang.Object.hashCode. Doc from java.lang.Object.hashCode. Returns a hash code value for this object. This method is supported for the benefit of hash tables such as those provided by `java.util.HashMap`. 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` 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` 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 hash tables.

public int hashCode()

Overrides java.lang.Object.hashCode.

Doc from java.lang.Object.hashCode.

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

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 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 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 hash tables.

hasRootLabel	back to summary
pack-priv boolean hasRootLabel()

isDigit	back to summary
private static boolean isDigit(char c)

isEmpty	back to summary
public boolean isEmpty() Implements javax.naming.Name.isEmpty. Doc from javax.naming.Name.isEmpty. Determines whether this name is empty. An empty name is one with zero components.

isEmpty

back to summary

public boolean isEmpty()

Implements javax.naming.Name.isEmpty.

Doc from javax.naming.Name.isEmpty.

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

isHostName	back to summary
public boolean isHostName() Does this domain name follow host name syntax?

isHostNameChar	back to summary
private static boolean isHostNameChar(char c)

isHostNameLabel	back to summary
private static boolean isHostNameLabel(String label)

keyForLabel	back to summary
private static String keyForLabel(String label)

parse	back to summary
private void parse(String name) throws InvalidNameException

readObject	back to summary
private void readObject(ObjectInputStream s) throws IOException, ClassNotFoundException

remove	back to summary
public Object remove(int pos) Implements javax.naming.Name.remove. Doc from javax.naming.Name.remove. 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.

remove

back to summary

public Object remove(int pos)

Implements javax.naming.Name.remove.

Doc from javax.naming.Name.remove.

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.

size	back to summary
public int size() Implements javax.naming.Name.size. Doc from javax.naming.Name.size. Returns the number of components in this name.

size

back to summary

public int size()

Implements javax.naming.Name.size.

Doc from javax.naming.Name.size.

Returns the number of components in this name.

startsWith back to summary

startsWith	back to summary
public boolean startsWith(Name n) Implements javax.naming.Name.startsWith. Doc from javax.naming.Name.startsWith. Determines whether this name starts with a specified prefix. A name `n` is a prefix if it is equal to `getPrefix(n.size())`.

public boolean startsWith(Name n)

Implements javax.naming.Name.startsWith.

Doc from javax.naming.Name.startsWith.

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

toString back to summary

toString	back to summary
public String toString() Overrides java.lang.Object.toString. Doc from java.lang.Object.toString. Returns a string representation of the object. Satisfying this method's contract implies a non-`null` result must be returned.

public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object. Satisfying this method's contract implies a non-null result must be returned.

verifyLabel	back to summary
private static void verifyLabel(String label) throws InvalidNameException

writeObject	back to summary
private void writeObject(ObjectOutputStream s) throws IOException Serializes only the domain name string, for compactness and to avoid any implementation dependency. Serial data The domain name string.

writeObject

back to summary

private void writeObject(ObjectOutputStream s) throws IOException

Serializes only the domain name string, for compactness and to avoid any implementation dependency.

Serial data: The domain name string.

public final Class DnsName

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail