Java example source code file (Document.java)

This example Java source code file (Document.java) is included in the alvinalexander.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Learn more about this Java project at its project page.

Java - Java tags/keywords

attributeset, badlocationexception, document, element, event, gui, object, position, segment, streamdescriptionproperty, string, swing, titleproperty

The Document.java Java example source code

/*
 * Copyright (c) 1997, 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
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */
package javax.swing.text;

import javax.swing.event.*;

/**
 * <p>
 * The <code>Document is a container for text that serves
 * as the model for swing text components.  The goal for this
 * interface is to scale from very simple needs (a plain text textfield)
 * to complex needs (an HTML or XML document, for example).
 *
 * <p>Content
 * <p>
 * At the simplest level, text can be
 * modeled as a linear sequence of characters. To support
 * internationalization, the Swing text model uses
 * <a href="http://www.unicode.org/">unicode characters.
 * The sequence of characters displayed in a text component is
 * generally referred to as the component's <em>content.
 * <p>
 * To refer to locations within the sequence, the coordinates
 * used are the location between two characters.  As the diagram
 * below shows, a location in a text document can be referred to
 * as a position, or an offset. This position is zero-based.
 * <p style="text-align:center">.
 * <p>The following methods give access to the character data
 * that makes up the content.
 * <ul>
 * <li>{@link #getLength()}
 * <li>{@link #getText(int, int)}
 * <li>{@link #getText(int, int, javax.swing.text.Segment)}
 * </ul>
 * <p>Structure
 * <p>
 * Text is rarely represented simply as featureless content. Rather,
 * text typically has some sort of structure associated with it.
 * Exactly what structure is modeled is up to a particular Document
 * implementation.  It might be as simple as no structure (i.e. a
 * simple text field), or it might be something like diagram below.
 * <p style="text-align:center">
 * <p>
 * The unit of structure (i.e. a node of the tree) is referred to
 * by the <a href="Element.html">Element interface.  Each Element
 * can be tagged with a set of attributes.  These attributes
 * (name/value pairs) are defined by the
 * <a href="AttributeSet.html">AttributeSet interface.
 * <p>The following methods give access to the document structure.
 * <ul>
 * <li>{@link #getDefaultRootElement()}
 * <li>{@link #getRootElements()}
 * </ul>
 *
 * <p>Mutations
 * <p>
 * All documents need to be able to add and remove simple text.
 * Typically, text is inserted and removed via gestures from
 * a keyboard or a mouse.  What effect the insertion or removal
 * has upon the document structure is entirely up to the
 * implementation of the document.
 * <p>The following methods are related to mutation of the
 * document content:
 * <ul>
 * <li>{@link #insertString(int, java.lang.String, javax.swing.text.AttributeSet)}
 * <li>{@link #remove(int, int)}
 * <li>{@link #createPosition(int)}
 * </ul>
 *
 * <p>Notification
 * <p>
 * Mutations to the <code>Document must be communicated to
 * interested observers.  The notification of change follows the event model
 * guidelines that are specified for JavaBeans.  In the JavaBeans
 * event model, once an event notification is dispatched, all listeners
 * must be notified before any further mutations occur to the source
 * of the event.  Further, order of delivery is not guaranteed.
 * <p>
 * Notification is provided as two separate events,
 * <a href="../event/DocumentEvent.html">DocumentEvent, and
 * <a href="../event/UndoableEditEvent.html">UndoableEditEvent.
 * If a mutation is made to a <code>Document through its api,
 * a <code>DocumentEvent will be sent to all of the registered
 * <code>DocumentListeners.  If the Document
 * implementation supports undo/redo capabilities, an
 * <code>UndoableEditEvent will be sent
 * to all of the registered <code>UndoableEditListeners.
 * If an undoable edit is undone, a <code>DocumentEvent should be
 * fired from the Document to indicate it has changed again.
 * In this case however, there should be no <code>UndoableEditEvent
 * generated since that edit is actually the source of the change
 * rather than a mutation to the <code>Document made through its
 * api.
 * <p style="text-align:center">addDocumentListener(DocumentListener)
 * <li>removeDocumentListener(DocumentListener)
 * <li>addUndoableEditListener(UndoableEditListener)
 * <li>removeUndoableEditListener(UndoableEditListener)
 * </ul>
 *
 * <p>Properties
 * <p>
 * Document implementations will generally have some set of properties
 * associated with them at runtime.  Two well known properties are the
 * <a href="#StreamDescriptionProperty">StreamDescriptionProperty,
 * which can be used to describe where the <code>Document came from,
 * and the <a href="#TitleProperty">TitleProperty, which can be used to
 * name the <code>Document.  The methods related to the properties are:
 * <ul>
 * <li>{@link #getProperty(java.lang.Object)}
 * <li>{@link #putProperty(java.lang.Object, java.lang.Object)}
 * </ul>
 *
 * <p>For more information on the Document class, see
 * <a href="http://java.sun.com/products/jfc/tsc">The Swing Connection
 * and most particularly the article,
 * <a href="http://java.sun.com/products/jfc/tsc/articles/text/element_interface">
 * The Element Interface</a>.
 *
 * @author  Timothy Prinzing
 *
 * @see javax.swing.event.DocumentEvent
 * @see javax.swing.event.DocumentListener
 * @see javax.swing.event.UndoableEditEvent
 * @see javax.swing.event.UndoableEditListener
 * @see Element
 * @see Position
 * @see AttributeSet
 */
public interface Document {

    /**
     * Returns number of characters of content currently
     * in the document.
     *
     * @return number of characters >= 0
     */
    public int getLength();

    /**
     * Registers the given observer to begin receiving notifications
     * when changes are made to the document.
     *
     * @param listener the observer to register
     * @see Document#removeDocumentListener
     */
    public void addDocumentListener(DocumentListener listener);

    /**
     * Unregisters the given observer from the notification list
     * so it will no longer receive change updates.
     *
     * @param listener the observer to register
     * @see Document#addDocumentListener
     */
    public void removeDocumentListener(DocumentListener listener);

    /**
     * Registers the given observer to begin receiving notifications
     * when undoable edits are made to the document.
     *
     * @param listener the observer to register
     * @see javax.swing.event.UndoableEditEvent
     */
    public void addUndoableEditListener(UndoableEditListener listener);

    /**
     * Unregisters the given observer from the notification list
     * so it will no longer receive updates.
     *
     * @param listener the observer to register
     * @see javax.swing.event.UndoableEditEvent
     */
    public void removeUndoableEditListener(UndoableEditListener listener);

    /**
     * Gets the properties associated with the document.
     *
     * @param key a non-<code>null property key
     * @return the properties
     * @see #putProperty(Object, Object)
     */
    public Object getProperty(Object key);

    /**
     * Associates a property with the document.  Two standard
     * property keys provided are: <a href="#StreamDescriptionProperty">
     * <code>StreamDescriptionProperty and
     * <a href="#TitleProperty">TitleProperty.
     * Other properties, such as author, may also be defined.
     *
     * @param key the non-<code>null property key
     * @param value the property value
     * @see #getProperty(Object)
     */
    public void putProperty(Object key, Object value);

    /**
     * Removes a portion of the content of the document.
     * This will cause a DocumentEvent of type
     * DocumentEvent.EventType.REMOVE to be sent to the
     * registered DocumentListeners, unless an exception
     * is thrown.  The notification will be sent to the
     * listeners by calling the removeUpdate method on the
     * DocumentListeners.
     * <p>
     * To ensure reasonable behavior in the face
     * of concurrency, the event is dispatched after the
     * mutation has occurred. This means that by the time a
     * notification of removal is dispatched, the document
     * has already been updated and any marks created by
     * <code>createPosition have already changed.
     * For a removal, the end of the removal range is collapsed
     * down to the start of the range, and any marks in the removal
     * range are collapsed down to the start of the range.
     * <p style="text-align:center">
     *
     *   int nleft = doc.getDocumentLength();
     *   Segment text = new Segment();
     *   int offs = 0;
     *   text.setPartialReturn(true);
     *   while (nleft > 0) {
     *       doc.getText(offs, nleft, text);
     *       // do someting with text
     *       nleft -= text.count;
     *       offs += text.count;
     *   }
     *
     * </code>

* * @param offset the offset into the document representing the desired * start of the text >= 0 * @param length the length of the desired string >= 0 * @param txt the Segment object to return the text in * * @exception BadLocationException Some portion of the given range * was not a valid part of the document. The location in the exception * is the first bad position encountered. */ public void getText(int offset, int length, Segment txt) throws BadLocationException; /** * Returns a position that represents the start of the document. The * position returned can be counted on to track change and stay * located at the beginning of the document. * * @return the position */ public Position getStartPosition(); /** * Returns a position that represents the end of the document. The * position returned can be counted on to track change and stay * located at the end of the document. * * @return the position */ public Position getEndPosition(); /** * This method allows an application to mark a place in * a sequence of character content. This mark can then be * used to tracks change as insertions and removals are made * in the content. The policy is that insertions always * occur prior to the current position (the most common case) * unless the insertion location is zero, in which case the * insertion is forced to a position that follows the * original position. * * @param offs the offset from the start of the document >= 0 * @return the position * @exception BadLocationException if the given position does not * represent a valid location in the associated document */ public Position createPosition(int offs) throws BadLocationException; /** * Returns all of the root elements that are defined. * <p> * Typically there will be only one document structure, but the interface * supports building an arbitrary number of structural projections over the * text data. The document can have multiple root elements to support * multiple document structures. Some examples might be: * </p> * <ul> * <li>Text direction. * <li>Lexical token streams. * <li>Parse trees. * <li>Conversions to formats other than the native format. * <li>Modification specifications. * <li>Annotations. * </ul> * * @return the root element */ public Element[] getRootElements(); /** * Returns the root element that views should be based upon, * unless some other mechanism for assigning views to element * structures is provided. * * @return the root element */ public Element getDefaultRootElement(); /** * Allows the model to be safely rendered in the presence * of concurrency, if the model supports being updated asynchronously. * The given runnable will be executed in a way that allows it * to safely read the model with no changes while the runnable * is being executed. The runnable itself may <em>not * make any mutations. * * @param r a <code>Runnable used to render the model */ public void render(Runnable r); /** * The property name for the description of the stream * used to initialize the document. This should be used * if the document was initialized from a stream and * anything is known about the stream. */ public static final String StreamDescriptionProperty = "stream"; /** * The property name for the title of the document, if * there is one. */ public static final String TitleProperty = "title"; }