Класс AbstractDocument

Реализация интерфейса документа, служащая основой для реализации различных типов документов. На этом уровне политики очень мало, поэтому сложность использования возрастает.

Этот класс реализует механизм блокировки для документа. Он позволяет множественным читателям или одному писателю, и писатели должны дождаться, пока все наблюдатели за документом будут уведомлены о предыдущем изменении, прежде чем начать другую мутацию документа. Чтение блокировки приобретается и освобождается с помощью метода render. Запись блокировки приобретается методами, которые изменяют документ, и удерживается на протяжении всего вызова метода. Уведомление выполняется в потоке, который произвел изменение, и поток имеет полный доступ для чтения к документу на протяжении всего периода уведомления, но другие читатели блокируются до завершения уведомления. Уведомление — это уведомление о событии типа beans, которое не позволяет дальнейших мутаций до тех пор, пока все слушатели не будут уведомлены.

Любые модели, являющиеся подклассами этого класса и используемые совместно с текстовым компонентом, имеющим реализацию внешнего вида, производной от BasicTextUI, могут быть безопасно обновлены асинхронно, поскольку весь доступ к иерархии представления сериализуется BasicTextUI, если документ имеет тип AbstractDocument. Блокировка предполагает, что отдельный поток будет обращаться к иерархии представления только из методов DocumentListener, и что в одно время будет активен только один поток событий.

Если требуется поддержка конкурентности, это влечёт следующие дополнительные последствия. Путь кода для любой реализации DocumentListener и любой реализации UndoListener должен быть потокобезопасным и не должен обращаться к блокировке компонента, если требуется предотвращение тупиков. Методы repaint и revalidate на JComponent безопасны.

AbstractDocument моделирует подразумеваемый разрыв в конце документа. Среди прочего это позволяет разместить курсор после последнего символа. В результате этого, getLength возвращает значение на единицу меньше длины Content. Если вы создаёте свой собственный Content, убедитесь, что инициализировали его с дополнительным символом. Обратитесь к StringContent и GapContent для примеров этого. Ещё один аспект этого заключается в том, что элементы, моделирующие неявный конечный символ, будут иметь endOffset == (getLength() + 1). Например, в DefaultStyledDocument getParagraphElement(getLength()).getEndOffset() == getLength() + 1 .

Предупреждение: Сериализованные объекты этого класса не будут совместимы с будущими версиями Swing. Текущая поддержка сериализации подходит для краткосрочного хранения или RMI между приложениями, использующими одну и ту же версию Swing. Начиная с 1.4, поддержка долгосрочного хранения всех JavaBeans™ была добавлена в пакет java.beans. Пожалуйста, обратитесь к XMLEncoder.

Поля

listenerList

protected EventListenerList listenerList

Список слушателей событий для документа.

BAD_LOCATION

protected static final String BAD_LOCATION

Сообщение об ошибке, указывающее на неправильное расположение.

См. также:

Значения константных полей

ParagraphElementName

public static final String ParagraphElementName

Имя элементов, используемых для представления абзацев

См. также:

Значения константных полей

ContentElementName

public static final String ContentElementName

Имя элементов, используемых для представления содержимого

См. также:

Значения константных полей

SectionElementName

public static final String SectionElementName

Имя элементов, используемых для хранения разделов (строк/абзацев).

См. также:

Значения константных полей

BidiElementName

public static final String BidiElementName

Имя элементов, используемых для хранения однонаправленного блока

См. также:

Значения константных полей

ElementNameAttribute

public static final String ElementNameAttribute

Имя атрибута, используемого для указания имён элементов.

См. также:

Значения константных полей

Конструкторы

AbstractDocument

protected AbstractDocument(AbstractDocument.Content data)

Создаёт новый AbstractDocument, обернутый вокруг некоторого указанного механизма хранения содержимого.

Параметры:

data - содержимое

AbstractDocument

protected AbstractDocument(AbstractDocument.Content data,
                           AbstractDocument.AttributeContext context)

Создаёт новый AbstractDocument, обернутый вокруг некоторого указанного механизма хранения содержимого.

Параметры:

data - содержимое

context - контекст атрибутов

Методы

getDocumentProperties

public Dictionary<Object,Object> getDocumentProperties()

Поддерживает управление набором свойств. Вызывающие стороны могут использовать словарь documentProperties для аннотирования документа свойствами, относящимися ко всему документу.

Возвращает:

не-null Dictionary

См. также:

setDocumentProperties(java.util.Dictionary<java.lang.Object, java.lang.Object>)

setDocumentProperties

public void setDocumentProperties(Dictionary<Object,Object> x)

Заменяет словарь свойств документа для этого документа.

Параметры:

x - новый словарь

См. также:

getDocumentProperties()

fireInsertUpdate

protected void fireInsertUpdate(DocumentEvent e)

Уведомляет всех слушателей, которые проявили интерес к уведомлениям об этом типе событий. Экземпляр события создаётся лениво с использованием параметров, переданных в метод fire.

Параметры:

e - событие

См. также:

EventListenerList

fireChangedUpdate

protected void fireChangedUpdate(DocumentEvent e)

Уведомляет всех слушателей, которые проявили интерес к уведомлениям об этом типе событий. Экземпляр события создаётся лениво с использованием параметров, переданных в метод fire.

Параметры:

e - событие

См. также:

EventListenerList

fireRemoveUpdate

protected void fireRemoveUpdate(DocumentEvent e)

Уведомляет всех слушателей, которые проявили интерес к уведомлениям об этом типе событий. Экземпляр события создаётся лениво с использованием параметров, переданных в метод fire.

Параметры:

e - событие

См. также:

EventListenerList

fireUndoableEditUpdate

protected void fireUndoableEditUpdate(UndoableEditEvent e)

Уведомляет всех слушателей, которые проявили интерес к уведомлениям об этом типе событий. Экземпляр события создаётся лениво с использованием параметров, переданных в метод fire.

Параметры:

e - событие

См. также:

EventListenerList

getListeners

public <T extends EventListener> T[] getListeners(Class<T> listenerType)

DocumentListener[] mls = (DocumentListener[])(d.getListeners(DocumentListener.class));

Параметры:

listenerType - тип запрашиваемых слушателей; этот параметр должен указать интерфейс, унаследованный от java.util.EventListener

Возвращает:

массив всех объектов, зарегистрированных как FooListener на этом компоненте, или пустой массив, если такие слушатели не были добавлены

Исключения:

ClassCastException - если listenerType не указывает класс или интерфейс, реализующий java.util.EventListener

С тех пор:

1.3

См. также:

getDocumentListeners(), getUndoableEditListeners()

getAsynchronousLoadPriority

public int getAsynchronousLoadPriority()

Получает приоритет асинхронной загрузки. Если меньше нуля, документ не должен загружаться асинхронно.

Возвращает:

приоритет асинхронной загрузки или -1 если документ не должен загружаться асинхронно

setAsynchronousLoadPriority

public void setAsynchronousLoadPriority(int p)

Устанавливает приоритет асинхронной загрузки.

Параметры:

p - новый приоритет асинхронной загрузки; значение меньше нуля означает, что документ не должен загружаться асинхронно

setDocumentFilter

public void setDocumentFilter(DocumentFilter filter)

Устанавливает DocumentFilter. DocumentFilter передаётся insert и remove для условного разрешения вставки/удаления текста. Значение null указывает, что фильтрация не будет происходить.

Параметры:

filter - DocumentFilter используемый для ограничения текста

С тех пор:

1.4

См. также:

getDocumentFilter()

getDocumentFilter

public DocumentFilter getDocumentFilter()

Возвращает DocumentFilter ответственный за фильтрацию вставки/удаления. Возвращаемое значение null подразумевает, что фильтрация не должна происходить.

Возвращает:

DocumentFilter

С тех пор:

1.4

См. также:

setDocumentFilter(javax.swing.text.DocumentFilter)

render

public void render(Runnable r)

Указано в:

render в интерфейсе Document

Параметры:

r - рендерер для выполнения

getLength

public int getLength()

Возвращает длину данных. Это число символов содержимого, представляющих данные пользователя.

Указано в:

getLength в интерфейсе Document

Возвращает:

длина >= 0

См. также:

Document.getLength()

addDocumentListener

public void addDocumentListener(DocumentListener listener)

Добавляет слушателя событий документа для уведомления о любых изменениях.

Указано в:

addDocumentListener в интерфейсе Document

Параметры:

listener - DocumentListener для добавления

См. также:

Document.addDocumentListener(javax.swing.event.DocumentListener)

removeDocumentListener

public void removeDocumentListener(DocumentListener listener)

Удаляет слушателя событий документа.

Указано в:

removeDocumentListener в интерфейсе Document

Параметры:

listener - DocumentListener для удаления

См. также:

Document.removeDocumentListener(javax.swing.event.DocumentListener)

getDocumentListeners

public DocumentListener[] getDocumentListeners()

Возвращает массив всех слушателей документов, зарегистрированных в этом документе.

Возвращает:

все DocumentListener этого документа или пустой массив, если в настоящее время нет зарегистрированных слушателей документов

С:

1.4

См. также:

addDocumentListener(javax.swing.event.DocumentListener), removeDocumentListener(javax.swing.event.DocumentListener)

addUndoableEditListener

public void addUndoableEditListener(UndoableEditListener listener)

Добавляет слушателя отмены для уведомления обо всех изменениях. Операции отмены/повтор, выполняемые над UndoableEdit приведут к запуску соответствующего события DocumentEvent, чтобы обеспечить синхронизацию представления(ий) с моделью.

Указано в:

addUndoableEditListener в интерфейсе Document

Параметры:

listener - добавляемый UndoableEditListener

См. также:

Document.addUndoableEditListener(javax.swing.event.UndoableEditListener)

removeUndoableEditListener

public void removeUndoableEditListener(UndoableEditListener listener)

Удаляет слушателя отмены.

Указано в:

removeUndoableEditListener в интерфейсе Document

Параметры:

listener - удаляемый UndoableEditListener

См. также:

Document.removeDocumentListener(javax.swing.event.DocumentListener)

getUndoableEditListeners

public UndoableEditListener[] getUndoableEditListeners()

Возвращает массив всех зарегистрированных слушателей отменяемых изменений в этом документе.

Возвращает:

все UndoableEditListener этого документа или пустой массив, если в настоящее время нет зарегистрированных слушателей отменяемых изменений

С:

1.4

См. также:

addUndoableEditListener(javax.swing.event.UndoableEditListener), removeUndoableEditListener(javax.swing.event.UndoableEditListener)

getProperty

public final Object getProperty(Object key)

Удобный метод для поиска значения свойства. Он эквивалентен:

getDocumentProperties().get(key);

Указано в:

getProperty в интерфейсе Document

Параметры:

key - ключ свойства, не являющийся null

Возвращает:

значение этого свойства или null

См. также:

getDocumentProperties()

putProperty

public final void putProperty(Object key,
                              Object value)

Удобный метод для хранения значения свойства. Он эквивалентен:

getDocumentProperties().put(key, value);

Указано в:

putProperty в интерфейсе Document

Параметры:

key - ключ свойства, не являющийся null

value - значение свойства

См. также:

getDocumentProperties()

remove

public void remove(int offs,
                   int len)
            throws BadLocationException

Указано в:

remove в интерфейсе Document

Параметры:

offs - начальный смещение >= 0

len - количество удаляемых символов >= 0

Исключения:

BadLocationException - заданная позиция удаления не является допустимой позицией в документе

См. также:

Document.remove(int, int)

replace

public void replace(int offset,
                    int length,
                    String text,
                    AttributeSet attrs)
             throws BadLocationException

Удаляет область текста от offset до offset + length, и заменяет ее на text. Реализация зависит от реализации; некоторые реализации могут рассматривать это как две отдельные операции: удаление, за которым следует вставка; другие могут рассматривать замену как атомную операцию.

Параметры:

offset - индекс дочернего элемента

length - длина удаляемого текста, может быть 0, что означает, что ничего не удалять

text - текст для вставки, null означает, что текст не нужно вставлять

attrs - набор атрибутов, указывающих на атрибуты вставляемого текста, null является допустимым и, как правило, рассматривается как пустой набор атрибутов, но точная интерпретация остается за подклассом

Исключения:

BadLocationException - заданная позиция не является допустимой позицией в документе

С:

1.4

insertString

public void insertString(int offs,
                         String str,
                         AttributeSet a)
                  throws BadLocationException

Указано в:

insertString в интерфейсе Document

Параметры:

offs - начальное смещение >= 0

str - строка для вставки; ничего не делает с null/пустыми строками

a - атрибуты для вставляемого содержимого

Исключения:

BadLocationException - заданная позиция вставки не является допустимой позицией в документе

См. также:

Document.insertString(int, java.lang.String, javax.swing.text.AttributeSet)

getText

public String getText(int offset,
                      int length)
               throws BadLocationException

Получает последовательность текста из документа.

Указано в:

getText в интерфейсе Document

Параметры:

offset - начальное смещение >= 0

length - количество извлекаемых символов >= 0

Возвращает:

текст

Исключения:

BadLocationException - заданный диапазон включает позицию, которая не является допустимой позицией в документе

См. также:

Document.getText(int, int)

getText

public void getText(int offset,
                    int length,
                    Segment txt)
             throws BadLocationException

  int nleft = doc.getDocumentLength();
   Segment text = new Segment();
   int offs = 0;
   text.setPartialReturn(true);
   while (nleft > 0) {
       doc.getText(offs, nleft, text);
       // do something with text
       nleft -= text.count;
       offs += text.count;
   }

Указано в:

getText в интерфейсе Document

Параметры:

offset - начальное смещение >= 0

length - количество извлекаемых символов >= 0

txt - объект Segment для извлечения текста

Исключения:

BadLocationException - заданный диапазон включает позицию, которая не является допустимой позицией в документе

createPosition

public Position createPosition(int offs)
                        throws BadLocationException

Указано в:

createPosition в интерфейсе Document

Параметры:

offs - позиция в модели >= 0

Возвращает:

позицию

Исключения:

BadLocationException - если заданная позиция не представляет допустимое местоположение в связанном документе

См. также:

Document.createPosition(int)

getStartPosition

public final Position getStartPosition()

Возвращает позицию, представляющую начало документа. Возвращаемая позиция гарантированно отслеживает изменения и остается в начале документа.

Указано в:

getStartPosition в интерфейсе Document

Возвращает:

позицию

getEndPosition

public final Position getEndPosition()

Возвращает позицию, представляющую конец документа. Возвращаемая позиция гарантированно отслеживает изменения и остается в конце документа.

Указано в:

getEndPosition в интерфейсе Document

Возвращает:

позицию

getRootElements

public Element[] getRootElements()

Получает все определенные корневые элементы. Обычно их будет только один, поэтому в реализации по умолчанию возвращается корневой элемент по умолчанию.

Указано в:

getRootElements в интерфейсе Document

Возвращает:

корневой элемент

getDefaultRootElement

public abstract Element getDefaultRootElement()

Возвращает корневой элемент, на основе которого должны строиться представления, если не предусмотрен другой механизм для назначения представлений элементам структуры.

Указано в:

getDefaultRootElement в интерфейсе Document

Возвращает:

корневой элемент

См. также:

Document.getDefaultRootElement()

getBidiRootElement

public Element getBidiRootElement()

Возвращает корневой элемент двунаправленной структуры для этого документа. Его дочерние элементы представляют собой последовательности символов с заданным уровнем Unicode Bidi.

getParagraphElement

public abstract Element getParagraphElement(int pos)

Получить элемент абзаца, содержащий заданную позицию. Подклассы должны определить для себя, что именно представляет собой абзац. Они должны помнить, что абзац должен по меньшей мере быть единицей текста, над которой выполняется алгоритм двунаправленной обработки Unicode.

Параметры:

pos - начальное смещение >= 0

Возвращает:

элемент

getAttributeContext

protected final AbstractDocument.AttributeContext getAttributeContext()

Извлекает контекст для управления атрибутами. Этот метод эффективно устанавливает стратегию, используемую для сжатия информации AttributeSet.

Возвращает:

контекст

insertUpdate

protected void insertUpdate(AbstractDocument.DefaultDocumentEvent chng,
                            AttributeSet attr)

Обновляет структуру документа в результате вставки текста. Это произойдёт в рамках блокировки записи. Если подкласс этого класса переопределяет этот метод, он должен также делегировать суперклассу.

Параметры:

chng - описание изменения

attr - атрибуты для изменения

removeUpdate

protected void removeUpdate(AbstractDocument.DefaultDocumentEvent chng)

Обновляет любую структуру документа в результате удаления текста. Этот метод вызывается до фактического удаления текста из содержимого. Это произойдёт в рамках блокировки записи. Если подкласс этого класса переопределяет этот метод, он должен также делегировать суперклассу.

Параметры:

chng - описание изменения

postRemoveUpdate

protected void postRemoveUpdate(AbstractDocument.DefaultDocumentEvent chng)

Обновляет любую структуру документа в результате удаления текста. Этот метод вызывается после удаления текста из содержимого. Это произойдёт в рамках блокировки записи. Если подкласс этого класса переопределяет этот метод, он должен также делегировать суперклассу.

Параметры:

chng - описание изменения

dump

public void dump(PrintStream out)

Выводит диагностическую информацию.

Параметры:

out - поток вывода

getContent

protected final AbstractDocument.Content getContent()

Получает содержимое документа.

Возвращает:

содержимое

createLeafElement

protected Element createLeafElement(Element parent,
                                    AttributeSet a,
                                    int p0,
                                    int p1)

Создаёт элемент листа документа. Точка входа, через которую создаются элементы для представления структуры документа. Поскольку эта реализация разделяет структуру и содержимое, элементы растут автоматически при расширении содержимого, поэтому разделение существующих элементов выполняется. Сам документ решает, как генерировать элементы, предоставляя гибкость в типе используемых элементов.

Параметры:

parent - родительский элемент

a - атрибуты элемента

p0 - начало диапазона >= 0

p1 - конец диапазона >= p0

Возвращает:

новый элемент

createBranchElement

protected Element createBranchElement(Element parent,
                                      AttributeSet a)

Создаёт элемент ветви документа, который может содержать другие элементы.

Параметры:

parent - родительский элемент

a - атрибуты

Возвращает:

элемент

getCurrentWriter

protected final Thread getCurrentWriter()

Извлекает текущую нить записи, если она существует. Это можно использовать для определения, вызывается ли метод в рамках существующего изменения или необходимо получить блокировку и начать новую транзакцию.

Возвращает:

нить, активно изменяющая документ, или null, если изменений нет

writeLock

protected final void writeLock()

Исключения:

IllegalStateException - выбрасывается при неправомерной попытке блокировки. Если документ реализован должным образом, это может произойти только в том случае, если слушатель документа пытается изменить документ. Эта ситуация нарушает модель событий Bean, где порядок доставки не гарантируется, и все слушатели должны быть уведомлены до дальнейших изменений.

writeUnlock

protected final void writeUnlock()

Освобождает блокировку записи, ранее полученную с помощью writeLock. После уменьшения счётчика блокировки, если нет ни одной ожидающей блокировки, это позволит новой нити записи или чтения.

См. также:

writeLock()

readLock

public final void readLock()

Получает блокировку для начала чтения некоторого состояния из документа. Одновременно может быть несколько читателей. Запись блокирует читателей до завершения уведомления слушателей об изменении. Этот метод следует использовать очень осторожно, чтобы избежать непреднамеренного нарушения целостности документа. Он всегда должен быть сбалансирован с readUnlock.

См. также:

readUnlock()

readUnlock

public final void readUnlock()

Выполняет разблокировку чтения. Это сигнализирует о том, что один из читателей закончил работу. Если больше нет читателей, то запись может возобновиться. Это должно быть сбалансировано с readLock и должно произойти в операторе finally, чтобы баланс был гарантирован. Ниже приведен пример.

    readLock();
     try {
         // do something
     } finally {
         readUnlock();
     }

См. также:

readLock()