src/java.base/share/classes/java/lang/StringBuffer.java

*** 1,7 ****
  /*
!  * Copyright (c) 1994, 2013, Oracle and/or its affiliates. All rights reserved.
   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   *
   * This code is free software; you can redistribute it and/or modify it
   * under the terms of the GNU General Public License version 2 only, as
   * published by the Free Software Foundation.  Oracle designates this
--- 1,7 ----
  /*
!  * Copyright (c) 1994, 2018, Oracle and/or its affiliates. All rights reserved.
   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   *
   * This code is free software; you can redistribute it and/or modify it
   * under the terms of the GNU General Public License version 2 only, as
   * published by the Free Software Foundation.  Oracle designates this
*** 88,105 ****
   * class designed for use by a single thread, {@link StringBuilder}.  The
   * {@code StringBuilder} class should generally be used in preference to
   * this one, as it supports all of the same operations but it is faster, as
   * it performs no synchronization.
   *
   * @author      Arthur van Hoff
   * @see     java.lang.StringBuilder
   * @see     java.lang.String
   * @since   1.0
   */
   public final class StringBuffer
      extends AbstractStringBuilder
!     implements java.io.Serializable, CharSequence
  {
  
      /**
       * A cache of the last value returned by toString. Cleared
       * whenever the StringBuffer is modified.
--- 88,113 ----
   * class designed for use by a single thread, {@link StringBuilder}.  The
   * {@code StringBuilder} class should generally be used in preference to
   * this one, as it supports all of the same operations but it is faster, as
   * it performs no synchronization.
   *
+  * @apiNote
+  * {@code StringBuffer} implements {@code Comparable} but does not override
+  * {@link Object#equals equals}. Thus, the natural ordering of {@code StringBuffer}
+  * is inconsistent with equals. Care should be exercised if {@code StringBuffer}
+  * objects are used as keys in a {@code SortedMap} or elements in a {@code SortedSet}.
+  * See {@link Comparable}, {@link java.util.SortedMap SortedMap}, or
+  * {@link java.util.SortedSet SortedSet} for more information.
+  *
   * @author      Arthur van Hoff
   * @see     java.lang.StringBuilder
   * @see     java.lang.String
   * @since   1.0
   */
   public final class StringBuffer
      extends AbstractStringBuilder
!     implements java.io.Serializable, Comparable<StringBuffer>, CharSequence
  {
  
      /**
       * A cache of the last value returned by toString. Cleared
       * whenever the StringBuffer is modified.
*** 160,169 ****
--- 168,206 ----
      public StringBuffer(CharSequence seq) {
          this(seq.length() + 16);
          append(seq);
      }
  
+     /**
+      * Compares two {@code StringBuffer} instances lexicographically. This method
+      * follows the same rules for lexicographical comparison as defined in the
+      * {@linkplain java.lang.CharSequence#compare(java.lang.CharSequence,
+      * java.lang.CharSequence)  CharSequence.compare(this, another)} method.
+      *
+      * <p>
+      * For finer-grained, locale-sensitive String comparison, refer to
+      * {@link java.text.Collator}.
+      *
+      * @implNote
+      * This method synchronizes on {@code this}, the current object, but not
+      * {@code StringBuffer another} with which {@code this StringBuffer} is compared.
+      *
+      * @param another the {@code StringBuffer} to be compared with
+      *
+      * @return  the value {@code 0} if this {@code StringBuffer} contains the same
+      * character sequence as that of the argument {@code StringBuffer}; a negative integer
+      * if this {@code StringBuffer} is lexicographically less than the
+      * {@code StringBuffer} argument; or a positive integer if this {@code StringBuffer}
+      * is lexicographically greater than the {@code StringBuffer} argument.
+      *
+      * @since 11
+      */
+     @Override
+     public synchronized int compareTo(StringBuffer another) {
+         return super.compareTo(another);
+     }
+ 
      @Override
      public synchronized int length() {
          return count;
      }