src/java.naming/share/classes/javax/naming/ldap/StartTlsResponse.java

*** 40,50 ****
   * and no extended response value is defined.
   *
   *<p>
   * The Start TLS extended request and response are used to establish
   * a TLS connection over the existing LDAP connection associated with
!  * the JNDI context on which <tt>extendedOperation()</tt> is invoked.
   * Typically, a JNDI program uses the StartTLS extended request and response
   * classes as follows.
   * <blockquote><pre>
   * import javax.naming.ldap.*;
   *
--- 40,50 ----
   * and no extended response value is defined.
   *
   *<p>
   * The Start TLS extended request and response are used to establish
   * a TLS connection over the existing LDAP connection associated with
!  * the JNDI context on which {@code extendedOperation()} is invoked.
   * Typically, a JNDI program uses the StartTLS extended request and response
   * classes as follows.
   * <blockquote><pre>
   * import javax.naming.ldap.*;
   *
*** 120,130 ****
      // StartTls-specific methods
  
      /**
       * Overrides the default list of cipher suites enabled for use on the
       * TLS connection. The cipher suites must have already been listed by
!      * <tt>SSLSocketFactory.getSupportedCipherSuites()</tt> as being supported.
       * Even if a suite has been enabled, it still might not be used because
       * the peer does not support it, or because the requisite certificates
       * (and private keys) are not available.
       *
       * @param suites The non-null list of names of all the cipher suites to
--- 120,130 ----
      // StartTls-specific methods
  
      /**
       * Overrides the default list of cipher suites enabled for use on the
       * TLS connection. The cipher suites must have already been listed by
!      * {@code SSLSocketFactory.getSupportedCipherSuites()} as being supported.
       * Even if a suite has been enabled, it still might not be used because
       * the peer does not support it, or because the requisite certificates
       * (and private keys) are not available.
       *
       * @param suites The non-null list of names of all the cipher suites to
*** 132,158 ****
       * @see #negotiate
       */
      public abstract void setEnabledCipherSuites(String[] suites);
  
      /**
!      * Sets the hostname verifier used by <tt>negotiate()</tt>
       * after the TLS handshake has completed and the default hostname
       * verification has failed.
!      * <tt>setHostnameVerifier()</tt> must be called before
!      * <tt>negotiate()</tt> is invoked for it to have effect.
       * If called after
!      * <tt>negotiate()</tt>, this method does not do anything.
       *
       * @param verifier The non-null hostname verifier callback.
       * @see #negotiate
       */
      public abstract void setHostnameVerifier(HostnameVerifier verifier);
  
      /**
       * Negotiates a TLS session using the default SSL socket factory.
       * <p>
!      * This method is equivalent to <tt>negotiate(null)</tt>.
       *
       * @return The negotiated SSL session
       * @throws IOException If an IO error was encountered while establishing
       * the TLS session.
       * @see #setEnabledCipherSuites
--- 132,158 ----
       * @see #negotiate
       */
      public abstract void setEnabledCipherSuites(String[] suites);
  
      /**
!      * Sets the hostname verifier used by {@code negotiate()}
       * after the TLS handshake has completed and the default hostname
       * verification has failed.
!      * {@code setHostnameVerifier()} must be called before
!      * {@code negotiate()} is invoked for it to have effect.
       * If called after
!      * {@code negotiate()}, this method does not do anything.
       *
       * @param verifier The non-null hostname verifier callback.
       * @see #negotiate
       */
      public abstract void setHostnameVerifier(HostnameVerifier verifier);
  
      /**
       * Negotiates a TLS session using the default SSL socket factory.
       * <p>
!      * This method is equivalent to {@code negotiate(null)}.
       *
       * @return The negotiated SSL session
       * @throws IOException If an IO error was encountered while establishing
       * the TLS session.
       * @see #setEnabledCipherSuites
*** 165,184 ****
       * <p>
       * Creates an SSL socket using the supplied SSL socket factory and
       * attaches it to the existing connection. Performs the TLS handshake
       * and returns the negotiated session information.
       * <p>
!      * If cipher suites have been set via <tt>setEnabledCipherSuites</tt>
       * then they are enabled before the TLS handshake begins.
       * <p>
       * Hostname verification is performed after the TLS handshake completes.
       * The default hostname verification performs a match of the server's
       * hostname against the hostname information found in the server's certificate.
       * If this verification fails and no callback has been set via
!      * <tt>setHostnameVerifier</tt> then the negotiation fails.
       * If this verification fails and a callback has been set via
!      * <tt>setHostnameVerifier</tt>, then the callback is used to determine whether
       * the negotiation succeeds.
       * <p>
       * If an error occurs then the SSL socket is closed and an IOException
       * is thrown. The underlying connection remains intact.
       *
--- 165,184 ----
       * <p>
       * Creates an SSL socket using the supplied SSL socket factory and
       * attaches it to the existing connection. Performs the TLS handshake
       * and returns the negotiated session information.
       * <p>
!      * If cipher suites have been set via {@code setEnabledCipherSuites}
       * then they are enabled before the TLS handshake begins.
       * <p>
       * Hostname verification is performed after the TLS handshake completes.
       * The default hostname verification performs a match of the server's
       * hostname against the hostname information found in the server's certificate.
       * If this verification fails and no callback has been set via
!      * {@code setHostnameVerifier} then the negotiation fails.
       * If this verification fails and a callback has been set via
!      * {@code setHostnameVerifier}, then the callback is used to determine whether
       * the negotiation succeeds.
       * <p>
       * If an error occurs then the SSL socket is closed and an IOException
       * is thrown. The underlying connection remains intact.
       *