Summary

Add some clarification on the usage of the Kerberos configuration file and the java.security.krb5.realm system property in the KerberosPrincipal class.

Problem

The constructors of KerberosPrincipal claim that

If the input name does not contain a realm, the default realm is used.
The default realm can be specified either in a Kerberos configuration
file or via the java.security.krb5.realm system property".

Some people might think that only the creation of a KerberosPrincipal will trigger the reading of the configuration file or the system property, and incorrectly assume they can safely set the system property before creating a KerberosPrincipal. The fact is that the file and the system property are used by all kerberos-related functions and the default realm is cached after first read. For example, the default realm will be read and cached when a KeyTab is created or a JAAS Krb5LoginModule is loaded. If an application tries to set the system property after any of these, the default realm will not be updated.

Solution

Add some clarification to the KerberosPrincipal constructors.

Specification

Add the following paragraph in two existing KerberosPrincipal constructors:

 * <p>Note that when this class or any other Kerberos-related class is
 * initially loaded and initialized, it may read and cache the default
 * realm from the Kerberos configuration file or via the
 * java.security.krb5.realm system property (the value will be empty if
 * no default realm is specified), such that any subsequent calls to set
 * or change the default realm by setting the java.security.krb5.realm
 * system property may be ignored.