Summary

Update the specification and implementation of DefaultStyledDocument.setCharacterAttributes() to allow only positive lengths. Additionally clarify the documentation on the handling of ranges which exceed the length of the text.

Problem

The specification of DefaultStyledDocument.setCharacterAttributes() incorrectly states that the length parameter must be >= 0. In fact the implementation ignores zero .. but then lets through negative values which should not be allowed and will lead to exceptions. Also the javadoc does not explain what happens if the offset is greater than the length of the text, or if the offset together with the length parameter exceed the length of the text.

Solution

Update the specification for the length parameter, from >= 0 to > 0. Update the implementation to disallow negative values. Update the specification to explain handling of the other out of range cases.

Specification

class javax.swing.text.DefaultStyledDocument

      * A write lock is held by this operation while changes
      * are being made, and a DocumentEvent is sent to the listeners
      * after the change has been successfully completed.
+     *
+     * <p>
+     * {@code offset} and {@code length} define the range of the text
+     * over which the attributes are set.
+     * If the length is &lt;= 0, then no action is taken  and the method
+     * just returns.
+     * If the offset is &lt;=0 or &gt; the length of the text then no
+     * action is taken, and the method just returns.
+     * Otherwise if {@code offset + length} will exceed the length of
+     * the  text then the affected range is truncated.
+     * </p>
+     *
        *
     * <p>
     * This method is thread safe, although most Swing methods
     * are not. Please see
     * <A HREF="https://docs.oracle.com/javase/tutorial/uiswing/concurrency/index.html">Concurrency
     * in Swing</A> for more information.
     *
    * @param offset the offset in the document &gt;= 0
 -   * @param length the length &gt;= 0
 +   * @param length the length &gt; 0.
     * @param s the attributes
     * @param replace true if the previous attributes should be replaced
     *  before setting the new attributes
     */
    public void setCharacterAttributes(int offset, int length, AttributeSet s, boolean replace) {