OpenJDK / portola / portola
changeset 27771:360714d431ab
8061253: Spec cleanup for some security-related classes
Reviewed-by: mullan
line wrap: on
line diff
--- a/jdk/src/java.base/share/classes/java/security/KeyStore.java Tue Nov 25 10:41:40 2014 -0800 +++ b/jdk/src/java.base/share/classes/java/security/KeyStore.java Wed Nov 26 15:28:46 2014 +0800 @@ -416,7 +416,8 @@ /** * Retrieves the attributes associated with an entry. - * <p> + * + * @implSpec * The default implementation returns an empty {@code Set}. * * @return an unmodifiable {@code Set} of attributes, possibly empty
--- a/jdk/src/java.base/share/classes/java/security/Principal.java Tue Nov 25 10:41:40 2014 -0800 +++ b/jdk/src/java.base/share/classes/java/security/Principal.java Wed Nov 26 15:28:46 2014 +0800 @@ -74,7 +74,8 @@ /** * Returns true if the specified subject is implied by this principal. * - * <p>The default implementation of this method returns true if + * @implSpec + * The default implementation of this method returns true if * {@code subject} is non-null and contains at least one principal that * is equal to this principal. *
--- a/jdk/src/java.base/share/classes/javax/security/auth/Destroyable.java Tue Nov 25 10:41:40 2014 -0800 +++ b/jdk/src/java.base/share/classes/javax/security/auth/Destroyable.java Wed Nov 26 15:28:46 2014 +0800 @@ -41,7 +41,7 @@ * on this {@code Object} will result in an * {@code IllegalStateException} being thrown. * - * <p> + * @implSpec * The default implementation throws {@code DestroyFailedException}. * * @exception DestroyFailedException if the destroy operation fails. <p> @@ -56,7 +56,7 @@ /** * Determine if this {@code Object} has been destroyed. * - * <p> + * @implSpec * The default implementation returns false. * * @return true if this {@code Object} has been destroyed,
--- a/jdk/src/java.security.jgss/share/classes/javax/security/auth/kerberos/EncryptionKey.java Tue Nov 25 10:41:40 2014 -0800 +++ b/jdk/src/java.security.jgss/share/classes/javax/security/auth/kerberos/EncryptionKey.java Wed Nov 26 15:28:46 2014 +0800 @@ -158,6 +158,11 @@ return destroyed; } + /** + * Returns an informative textual representation of this {@code EncryptionKey}. + * + * @return an informative textual representation of this {@code EncryptionKey}. + */ @Override public String toString() { if (destroyed) { @@ -166,6 +171,11 @@ return "key " + key.toString(); } + /** + * Returns a hash code for this {@code EncryptionKey}. + * + * @return a hash code for this {@code EncryptionKey}. + */ @Override public int hashCode() { int result = 17; @@ -177,15 +187,17 @@ } /** - * Compares the specified Object with this key for equality. - * Returns true if the given object is also a + * Compares the specified object with this key for equality. + * Returns true if the given object is also an * {@code EncryptionKey} and the two - * {@code EncryptionKey} instances are equivalent. + * {@code EncryptionKey} instances are equivalent. More formally two + * {@code EncryptionKey} instances are equal if they have equal key types + * and key material. + * A destroyed {@code EncryptionKey} object is only equal to itself. * - * @param other the Object to compare to - * @return true if the specified object is equal to this EncryptionKey, - * false otherwise. NOTE: Returns false if either of the EncryptionKey - * objects has been destroyed. + * @param other the object to compare to + * @return true if the specified object is equal to this + * {@code EncryptionKey}, false otherwise. */ @Override public boolean equals(Object other) {
--- a/jdk/src/java.security.jgss/share/classes/javax/security/auth/kerberos/KerberosCredMessage.java Tue Nov 25 10:41:40 2014 -0800 +++ b/jdk/src/java.security.jgss/share/classes/javax/security/auth/kerberos/KerberosCredMessage.java Wed Nov 26 15:28:46 2014 +0800 @@ -130,6 +130,11 @@ return destroyed; } + /** + * Returns an informative textual representation of this {@code KerberosCredMessage}. + * + * @return an informative textual representation of this {@code KerberosCredMessage}. + */ @Override public String toString() { if (destroyed) { @@ -140,6 +145,11 @@ } } + /** + * Returns a hash code for this {@code KerberosCredMessage}. + * + * @return a hash code for this {@code KerberosCredMessage}. + */ @Override public int hashCode() { if (isDestroyed()) { @@ -149,6 +159,19 @@ } } + /** + * Compares the specified object with this {@code KerberosCredMessage} + * for equality. Returns true if the given object is also a + * {@code KerberosCredMessage} and the two {@code KerberosCredMessage} + * instances are equivalent. More formally two {@code KerberosCredMessage} + * instances are equal if they have equal sender, recipient, and encoded + * KRB_CRED messages. + * A destroyed {@code KerberosCredMessage} object is only equal to itself. + * + * @param other the object to compare to + * @return true if the specified object is equal to this + * {@code KerberosCredMessage}, false otherwise. + */ @Override public boolean equals(Object other) { if (other == this) {
--- a/jdk/src/java.security.jgss/share/classes/javax/security/auth/kerberos/KerberosKey.java Tue Nov 25 10:41:40 2014 -0800 +++ b/jdk/src/java.security.jgss/share/classes/javax/security/auth/kerberos/KerberosKey.java Wed Nov 26 15:28:46 2014 +0800 @@ -61,10 +61,10 @@ * * It might be necessary for the application to be granted a * {@link javax.security.auth.PrivateCredentialPermission - * PrivateCredentialPermission} if it needs to access the KerberosKey + * PrivateCredentialPermission} if it needs to access the {@code KerberosKey} * instance from a Subject. This permission is not needed when the * application depends on the default JGSS Kerberos mechanism to access the - * KerberosKey. In that case, however, the application will need an + * {@code KerberosKey}. In that case, however, the application will need an * appropriate * {@link javax.security.auth.kerberos.ServicePermission ServicePermission}.<p> * @@ -113,9 +113,9 @@ private transient boolean destroyed = false; /** - * Constructs a KerberosKey from the given bytes when the key type and - * key version number are known. This can be used when reading the secret - * key information from a Kerberos "keytab". + * Constructs a {@code KerberosKey} from the given bytes when the key type + * and key version number are known. This can be used when reading the + * secret key information from a Kerberos "keytab". * * @param principal the principal that this secret key belongs to * @param keyBytes the key material for the secret key @@ -133,9 +133,9 @@ } /** - * Constructs a KerberosKey from a principal's password using the specified - * algorithm name. The algorithm name (case insensitive) should be provided - * as the encryption type string defined on the IANA + * Constructs a {@code KerberosKey} from a principal's password using the + * specified algorithm name. The algorithm name (case insensitive) should + * be provided as the encryption type string defined on the IANA * <a href="https://www.iana.org/assignments/kerberos-parameters/kerberos-parameters.xhtml#kerberos-parameters-1">Kerberos Encryption Type Numbers</a> * page. The version number of the key generated will be 0. * @@ -261,6 +261,11 @@ return destroyed; } + /** + * Returns an informative textual representation of this {@code KerberosKey}. + * + * @return an informative textual representation of this {@code KerberosKey}. + */ public String toString() { if (destroyed) { return "Destroyed KerberosKey"; @@ -271,9 +276,9 @@ } /** - * Returns a hashcode for this KerberosKey. + * Returns a hash code for this {@code KerberosKey}. * - * @return a hashCode() for the {@code KerberosKey} + * @return a hash code for this {@code KerberosKey}. * @since 1.6 */ public int hashCode() { @@ -290,15 +295,15 @@ } /** - * Compares the specified Object with this KerberosKey for equality. - * Returns true if the given object is also a + * Compares the specified object with this {@code KerberosKey} for + * equality. Returns true if the given object is also a * {@code KerberosKey} and the two * {@code KerberosKey} instances are equivalent. + * A destroyed {@code KerberosKey} object is only equal to itself. * - * @param other the Object to compare to - * @return true if the specified object is equal to this KerberosKey, - * false otherwise. NOTE: Returns false if either of the KerberosKey - * objects has been destroyed. + * @param other the object to compare to + * @return true if the specified object is equal to this {@code KerberosKey}, + * false otherwise. * @since 1.6 */ public boolean equals(Object other) {
--- a/jdk/src/java.security.jgss/share/classes/javax/security/auth/kerberos/KerberosPrincipal.java Tue Nov 25 10:41:40 2014 -0800 +++ b/jdk/src/java.security.jgss/share/classes/javax/security/auth/kerberos/KerberosPrincipal.java Wed Nov 26 15:28:46 2014 +0800 @@ -88,8 +88,8 @@ /** - * Constructs a KerberosPrincipal from the provided string input. The - * name type for this principal defaults to + * Constructs a {@code KerberosPrincipal} from the provided string input. + * The name type for this principal defaults to * {@link #KRB_NT_PRINCIPAL KRB_NT_PRINCIPAL} * This string is assumed to contain a name in the format * that is specified in Section 2.1.1. (Kerberos Principal Name Form) of @@ -127,7 +127,7 @@ } /** - * Constructs a KerberosPrincipal from the provided string and + * Constructs a {@code KerberosPrincipal} from the provided string and * name type input. The string is assumed to contain a name in the * format that is specified in Section 2.1 (Mandatory Name Forms) of * <a href=http://www.ietf.org/rfc/rfc1964.txt>RFC 1964</a>. @@ -137,7 +137,7 @@ * (for example, <i>duke@FOO.COM</i>, is a valid input string for the * name type, KRB_NT_PRINCIPAL where <i>duke</i> * represents a principal, and <i>FOO.COM</i> represents a realm). - + * * <p> 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 @@ -179,28 +179,28 @@ } /** - * Returns a hashcode for this principal. The hash code is defined to - * be the result of the following calculation: + * Returns a hash code for this {@code KerberosPrincipal}. The hash code + * is defined to be the result of the following calculation: * <pre>{@code * hashCode = getName().hashCode(); * }</pre> * - * @return a hashCode() for the {@code KerberosPrincipal} + * @return a hash code for this {@code KerberosPrincipal}. */ public int hashCode() { return getName().hashCode(); } /** - * Compares the specified Object with this Principal for equality. + * Compares the specified object with this principal for equality. * Returns true if the given object is also a * {@code KerberosPrincipal} and the two * {@code KerberosPrincipal} instances are equivalent. * More formally two {@code KerberosPrincipal} instances are equal * if the values returned by {@code getName()} are equal. * - * @param other the Object to compare to - * @return true if the Object passed in represents the same principal + * @param other the object to compare to + * @return true if the object passed in represents the same principal * as this one, false otherwise. */ public boolean equals(Object other) { @@ -217,11 +217,11 @@ } /** - * Save the KerberosPrincipal object to a stream + * Save the {@code KerberosPrincipal} object to a stream * * @serialData this {@code KerberosPrincipal} is serialized * by writing out the PrincipalName and the - * realm in their DER-encoded form as specified in Section 5.2.2 of + * Realm in their DER-encoded form as specified in Section 5.2.2 of * <a href=http://www.ietf.org/rfc/rfc4120.txt> RFC4120</a>. */ private void writeObject(ObjectOutputStream oos) @@ -268,7 +268,7 @@ } /** - * Returns the name type of the KerberosPrincipal. Valid name types + * Returns the name type of the {@code KerberosPrincipal}. Valid name types * are specified in Section 6.2 of * <a href=http://www.ietf.org/rfc/rfc4120.txt> RFC4120</a>. * @@ -278,7 +278,11 @@ return nameType; } - // Inherits javadocs from Object + /** + * Returns an informative textual representation of this {@code KerberosPrincipal}. + * + * @return an informative textual representation of this {@code KerberosPrincipal}. + */ public String toString() { return getName(); }
--- a/jdk/src/java.security.jgss/share/classes/javax/security/auth/kerberos/KerberosTicket.java Tue Nov 25 10:41:40 2014 -0800 +++ b/jdk/src/java.security.jgss/share/classes/javax/security/auth/kerberos/KerberosTicket.java Wed Nov 26 15:28:46 2014 +0800 @@ -53,10 +53,10 @@ * * It might be necessary for the application to be granted a * {@link javax.security.auth.PrivateCredentialPermission - * PrivateCredentialPermission} if it needs to access a KerberosTicket - * instance from a Subject. This permission is not needed when the + * PrivateCredentialPermission} if it needs to access a {@code KerberosTicket} + * instance from a {@code Subject}. This permission is not needed when the * application depends on the default JGSS Kerberos mechanism to access the - * KerberosTicket. In that case, however, the application will need an + * {@code KerberosTicket}. In that case, however, the application will need an * appropriate * {@link javax.security.auth.kerberos.ServicePermission ServicePermission}. * <p> @@ -193,7 +193,7 @@ private transient boolean destroyed = false; /** - * Constructs a KerberosTicket using credentials information that a + * Constructs a {@code KerberosTicket} using credentials information that a * client either receives from a KDC or reads from a cache. * * @param asn1Encoding the ASN.1 encoding of the ticket as defined by @@ -565,8 +565,8 @@ try { krb5Creds = new sun.security.krb5.Credentials(asn1Encoding, - client.toString(), - server.toString(), + client.getName(), + server.getName(), sessionKey.getEncoded(), sessionKey.getKeyType(), flags, @@ -644,6 +644,11 @@ return destroyed; } + /** + * Returns an informative textual representation of this {@code KerberosTicket}. + * + * @return an informative textual representation of this {@code KerberosTicket}. + */ public String toString() { if (destroyed) { return "Destroyed KerberosTicket"; @@ -677,9 +682,9 @@ } /** - * Returns a hashcode for this KerberosTicket. + * Returns a hash code for this {@code KerberosTicket}. * - * @return a hashCode() for the {@code KerberosTicket} + * @return a hash code for this {@code KerberosTicket}. * @since 1.6 */ public int hashCode() { @@ -714,15 +719,15 @@ } /** - * Compares the specified Object with this KerberosTicket for equality. + * Compares the specified object with this {@code KerberosTicket} for equality. * Returns true if the given object is also a * {@code KerberosTicket} and the two * {@code KerberosTicket} instances are equivalent. + * A destroyed {@code KerberosTicket} object is only equal to itself. * - * @param other the Object to compare to - * @return true if the specified object is equal to this KerberosTicket, - * false otherwise. NOTE: Returns false if either of the KerberosTicket - * objects has been destroyed. + * @param other the object to compare to + * @return true if the specified object is equal to this {@code KerberosTicket}, + * false otherwise. * @since 1.6 */ public boolean equals(Object other) {
--- a/jdk/src/java.security.jgss/share/classes/javax/security/auth/kerberos/KeyTab.java Tue Nov 25 10:41:40 2014 -0800 +++ b/jdk/src/java.security.jgss/share/classes/javax/security/auth/kerberos/KeyTab.java Wed Nov 26 15:28:46 2014 +0800 @@ -58,10 +58,10 @@ * <p> * It might be necessary for the application to be granted a * {@link javax.security.auth.PrivateCredentialPermission - * PrivateCredentialPermission} if it needs to access the KeyTab - * instance from a Subject. This permission is not needed when the + * PrivateCredentialPermission} if it needs to access the {@code KeyTab} + * instance from a {@code Subject}. This permission is not needed when the * application depends on the default JGSS Kerberos mechanism to access the - * KeyTab. In that case, however, the application will need an appropriate + * {@code KeyTab}. In that case, however, the application will need an appropriate * {@link javax.security.auth.kerberos.ServicePermission ServicePermission}. * <p> * The keytab file format is described at @@ -249,7 +249,7 @@ * could potentially be expired. * <p> * If there is any error (say, I/O error or format error) - * during the reading process of the KeyTab file, a saved result should be + * during the reading process of the keytab file, a saved result should be * returned. If there is no saved result (say, this is the first time this * method is called, or, all previous read attempts failed), an empty array * should be returned. This can make sure the result is not drastically @@ -316,6 +316,11 @@ return !takeSnapshot().isMissing(); } + /** + * Returns an informative textual representation of this {@code KeyTab}. + * + * @return an informative textual representation of this {@code KeyTab}. + */ public String toString() { String s = (file == null) ? "Default keytab" : file.toString(); if (!bound) return s; @@ -324,22 +329,22 @@ } /** - * Returns a hashcode for this KeyTab. + * Returns a hash code for this {@code KeyTab}. * - * @return a hashCode() for the {@code KeyTab} + * @return a hash code for this {@code KeyTab}. */ public int hashCode() { return Objects.hash(file, princ, bound); } /** - * Compares the specified Object with this KeyTab for equality. + * Compares the specified object with this {@code KeyTab} for equality. * Returns true if the given object is also a * {@code KeyTab} and the two * {@code KeyTab} instances are equivalent. * - * @param other the Object to compare to - * @return true if the specified object is equal to this KeyTab + * @param other the object to compare to + * @return true if the specified object is equal to this {@code KeyTab} */ public boolean equals(Object other) { if (other == this) @@ -359,9 +364,9 @@ * Returns the service principal this {@code KeyTab} object * is bound to. Returns {@code null} if it's not bound. * <p> - * Please note the deprecated constructors create a KeyTab object bound for - * some unknown principal. In this case, this method also returns null. - * User can call {@link #isBound()} to verify this case. + * Please note the deprecated constructors create a {@code KeyTab} object + * bound for some unknown principal. In this case, this method also returns + * null. User can call {@link #isBound()} to verify this case. * @return the service principal * @since 1.8 */