Класс AbstractDocument
- Все реализованные интерфейсы:
Serializable, Document
- Прямые известные подклассы:
DefaultStyledDocument, PlainDocument
public abstract class AbstractDocument extends Object implements Document, Serializable
Этот класс реализует механизм блокировки документа. Он допускает нескольких читателей или одного писателя; писатели должны ждать, пока все наблюдатели документа не получат уведомление о предыдущем изменении, прежде чем начинать новое изменение документа. Блокировка для чтения устанавливается и снимается с помощью метода render. Блокировка для записи устанавливается методами, изменяющими документ, и удерживается в течение всего вызова метода. Уведомление отправляется в потоке, выполнившем изменение, и на время отправки уведомления этому потоку предоставляется полный доступ к документу для чтения, тогда как остальные читатели не допускаются к нему, пока отправка уведомления не завершится. Уведомление представляет собой уведомление о событии Beans, которое не допускает дальнейших изменений до тех пор, пока уведомления не получат все слушатели.
Любые модели, являющиеся подклассами этого класса и используемые совместно с текстовым компонентом, реализация внешнего вида которого основана на BasicTextUI, можно безопасно обновлять асинхронно, поскольку BasicTextUI сериализует все обращения к иерархии View, если документ имеет тип AbstractDocument. Блокировка предполагает, что независимый поток будет обращаться к иерархии View только из методов 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 в пакете java.beans появилась поддержка долгосрочного хранения всех JavaBeans. См. XMLEncoder.
Краткое описание вложенных классов
| Модификатор и тип | Класс | Описание |
|---|---|---|
class |
AbstractDocument.AbstractElement |
Реализует абстрактную часть элемента. |
static interface |
AbstractDocument.AttributeContext |
Интерфейс, позволяющий реализациям MutableAttributeSet использовать подключаемые методы сжатия атрибутов. |
class |
AbstractDocument.BranchElement |
Реализует составной элемент, содержащий другие элементы. |
static interface |
AbstractDocument.Content |
Интерфейс для описания редактируемой последовательности символьного содержимого. |
class |
AbstractDocument.DefaultDocumentEvent |
Сохраняет изменения документа по мере его редактирования. |
static class |
AbstractDocument.ElementEdit |
Реализация ElementChange, которую можно добавить к событию документа. |
class |
AbstractDocument.LeafElement |
Реализует элемент, непосредственно представляющий содержимое некоторого типа. |
Краткое описание полей
| Модификатор и тип | Поле | Описание |
|---|---|---|
protected static final String |
BAD_LOCATION |
Сообщение об ошибке, указывающее на неверное расположение. |
static final String |
BidiElementName |
Имя элементов, используемых для хранения однонаправленного диапазона |
static final String |
ContentElementName |
Имя элементов, используемых для представления содержимого |
static final String |
ElementNameAttribute |
Имя атрибута, используемого для задания имён элементов. |
protected EventListenerList |
listenerList |
Список слушателей событий документа. |
static final String |
ParagraphElementName |
Имя элементов, используемых для представления абзацев |
static final String |
SectionElementName |
Имя элементов, используемых для хранения секций (строк/абзацев). |
Поля, объявленные в интерфейсе Document
StreamDescriptionProperty, TitleProperty
Краткое описание конструкторов
| Модификатор | Конструктор | Описание |
|---|---|---|
protected |
Создаёт новый AbstractDocument, обёрнутый вокруг указанного механизма хранения содержимого. |
|
protected |
Создаёт новый AbstractDocument, обёрнутый вокруг указанного механизма хранения содержимого. |
Краткое описание методов
| Модификатор и тип | Метод | Описание |
|---|---|---|
void |
addDocumentListener |
Добавляет слушателя документа для получения уведомлений обо всех изменениях. |
void |
addUndoableEditListener |
Добавляет слушателя отмены изменений для получения уведомлений обо всех изменениях. |
protected Element |
createBranchElement |
Создаёт ветвевой элемент документа, который может содержать другие элементы. |
protected Element |
createLeafElement |
Создаёт конечный элемент документа. |
Position |
createPosition |
Возвращает позицию, отслеживающую изменения документа. |
void |
dump |
Выводит диагностические данные. |
protected void |
fireChangedUpdate |
Уведомляет всех слушателей, зарегистрировавших интерес к уведомлениям о событиях этого типа. |
protected void |
fireInsertUpdate |
Уведомляет всех слушателей, зарегистрировавших интерес к уведомлениям о событиях этого типа. |
protected void |
fireRemoveUpdate |
Уведомляет всех слушателей, зарегистрировавших интерес к уведомлениям о событиях этого типа. |
protected void |
fireUndoableEditUpdate |
Уведомляет всех слушателей, зарегистрировавших интерес к уведомлениям о событиях этого типа. |
int |
getAsynchronousLoadPriority() |
Возвращает приоритет асинхронной загрузки. |
protected final AbstractDocument.AttributeContext |
getAttributeContext() |
Получает контекст для управления атрибутами. |
Element |
getBidiRootElement() |
Возвращает корневой элемент двунаправленной структуры этого документа. |
protected final AbstractDocument.Content |
getContent() |
Возвращает содержимое документа. |
protected final Thread |
getCurrentWriter() |
Возвращает текущий поток записи, если он существует. |
abstract Element |
getDefaultRootElement() |
Возвращает корневой элемент, на котором должны основываться представления, если не предоставлен иной механизм назначения представлений структурам элементов. |
DocumentFilter |
getDocumentFilter() |
Возвращает DocumentFilter, отвечающий за фильтрацию вставки и удаления. |
DocumentListener[] |
getDocumentListeners() |
Возвращает массив всех слушателей документа, зарегистрированных в этом документе. |
Dictionary |
getDocumentProperties() |
Обеспечивает управление набором свойств. |
final Position |
getEndPosition() |
Возвращает позицию, соответствующую концу документа. |
int |
getLength() |
Возвращает длину данных. |
<T extends EventListener> |
getListeners |
Возвращает массив всех объектов, зарегистрированных в данный момент в качестве FooListener этого документа. |
abstract Element |
getParagraphElement |
Возвращает элемент абзаца, содержащий указанную позицию. |
final Object |
getProperty |
Вспомогательный метод для получения значения свойства. |
Element[] |
getRootElements() |
Возвращает все определённые корневые элементы. |
final Position |
getStartPosition() |
Возвращает позицию, соответствующую началу документа. |
String |
getText |
Возвращает последовательность текста из документа. |
void |
getText |
Получает текст, содержащийся в указанной части документа. |
UndoableEditListener[] |
getUndoableEditListeners() |
Возвращает массив всех слушателей отменяемых изменений, зарегистрированных в этом документе. |
void |
insertString |
Вставляет содержимое в документ. |
protected void |
insertUpdate |
Обновляет структуру документа в результате вставки текста. |
protected void |
postRemoveUpdate |
Обновляет структуру документа в результате удаления текста. |
final void |
putProperty |
Вспомогательный метод для сохранения значения свойства. |
final void |
readLock() |
Устанавливает блокировку для чтения состояния документа. |
final void |
readUnlock() |
Снимает блокировку для чтения. |
void |
remove |
Удаляет содержимое из документа. |
void |
removeDocumentListener |
Удаляет слушателя документа. |
void |
removeUndoableEditListener |
Удаляет слушателя отмены изменений. |
protected void |
removeUpdate |
Обновляет структуру документа в результате удаления текста. |
void |
render |
Позволяет безопасно отображать модель при наличии параллельного доступа, если модель поддерживает асинхронное обновление. |
void |
replace |
Удаляет область текста от offset до offset + length и заменяет её на text. |
void |
setAsynchronousLoadPriority |
Задаёт приоритет асинхронной загрузки. |
void |
setDocumentFilter |
Задаёт DocumentFilter. |
void |
setDocumentProperties |
Заменяет словарь свойств этого документа. |
protected final void |
writeLock() |
Устанавливает блокировку для изменения защищаемого ею документа. |
protected final void |
writeUnlock() |
Снимает блокировку для записи, ранее установленную с помощью writeLock. |
Подробное описание полей
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 для добавления к документу свойств, относящихся ко всему документу.- Возвращает:
- не-
nullDictionary - См. также:
setDocumentProperties
public void setDocumentProperties(Dictionary<Object,Object> x)
- Параметры:
-
x— новый словарь - См. также:
fireInsertUpdate
protected void fireInsertUpdate(DocumentEvent e)
- Параметры:
-
e— событие - См. также:
fireChangedUpdate
protected void fireChangedUpdate(DocumentEvent e)
- Параметры:
-
e— событие - См. также:
fireRemoveUpdate
protected void fireRemoveUpdate(DocumentEvent e)
- Параметры:
-
e— событие - См. также:
fireUndoableEditUpdate
protected void fireUndoableEditUpdate(UndoableEditEvent e)
- Параметры:
-
e— событие - См. также:
getListeners
public <T extends EventListener> T[] getListeners(Class<T> listenerType)
FooListener этого документа. Слушатели FooListener регистрируются с помощью метода addFooListener. В качестве аргумента listenerType можно указать литерал класса, например FooListener.class. Например, можно запросить слушателей документа d, выполнив следующий код:
DocumentListener[] mls = (DocumentListener[])(d.getListeners(DocumentListener.class));Если таких слушателей нет, этот метод возвращает пустой массив.
- Параметры типа:
T— тип слушателя- Параметры:
-
listenerType— тип запрашиваемых слушателей - Возвращает:
- массив всех объектов, зарегистрированных в качестве слушателей
FooListenerэтого компонента, или пустой массив, если такие слушатели не добавлены - Вызывает:
-
ClassCastException— еслиlistenerTypeне указывает класс или интерфейс, реализующийjava.util.EventListener - С версии:
- 1.3
- См. также:
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
public DocumentFilter getDocumentFilter()
DocumentFilter, отвечающий за фильтрацию вставки/удаления. Возвращаемое значение null означает, что фильтрация выполняться не будет.- Возвращает:
- DocumentFilter
- С версии:
- 1.4
- См. также:
render
public void render(Runnable r)
Реализация захватывает блокировку чтения на время выполнения объекта Runnable. Одновременно могут выполняться несколько объектов Runnable, а все операции записи будут заблокированы, пока активны объекты Runnable, выполняющие отображение. Если объект Runnable выбрасывает исключение, его блокировка будет безопасно освобождена. Защита от объекта Runnable, который никогда не завершает выполнение, не предусмотрена; в этом случае документ фактически останется заблокированным на всё время своего существования.
Если переданный объект Runnable попытается внести изменения в этой реализации, возникнет взаимная блокировка. Отслеживание отдельных потоков отображения для обнаружения такой ситуации не ведётся, однако подкласс может понести дополнительные расходы на их отслеживание и выбрасывать ошибку.
Этот метод является потокобезопасным, хотя большинство методов Swing таковыми не являются. Дополнительные сведения см. в разделе Параллелизм в Swing.
getLength
addDocumentListener
public void addDocumentListener(DocumentListener listener)
- Определено в:
-
addDocumentListenerв интерфейсеDocument - Параметры:
-
listener— добавляемыйDocumentListener - См. также:
removeDocumentListener
public void removeDocumentListener(DocumentListener listener)
- Определено в:
-
removeDocumentListenerв интерфейсеDocument - Параметры:
-
listener— удаляемыйDocumentListener - См. также:
getDocumentListeners
public DocumentListener[] getDocumentListeners()
- Возвращает:
- все слушатели
DocumentListenerэтого документа или пустой массив, если слушатели документа не зарегистрированы - С версии:
- 1.4
- См. также:
addUndoableEditListener
public void addUndoableEditListener(UndoableEditListener listener)
UndoableEdit, приводят к генерации соответствующего DocumentEvent, чтобы представления оставались синхронизированными с моделью.- Определено в:
-
addUndoableEditListenerв интерфейсеDocument - Параметры:
-
listener— добавляемыйUndoableEditListener - См. также:
removeUndoableEditListener
public void removeUndoableEditListener(UndoableEditListener listener)
- Определено в:
-
removeUndoableEditListenerв интерфейсеDocument - Параметры:
-
listener— удаляемыйUndoableEditListener - См. также:
getUndoableEditListeners
public UndoableEditListener[] getUndoableEditListeners()
- Возвращает:
- все слушатели
UndoableEditListenerэтого документа или пустой массив, если слушатели отменяемых изменений не зарегистрированы - С версии:
- 1.4
- См. также:
getProperty
public final Object getProperty(Object key)
getDocumentProperties().get(key);
- Определено в:
-
getPropertyв интерфейсеDocument - Параметры:
-
key— ключ свойства, не являющийсяnull - Возвращает:
- значение этого свойства или
null - См. также:
putProperty
public final void putProperty(Object key, Object value)
getDocumentProperties().put(key, value);Если
value равно null, этот метод удалит свойство.- Определено в:
-
putPropertyв интерфейсеDocument - Параметры:
-
key— ключ, не являющийсяnull -
value— значение свойства - См. также:
remove
public void remove(int offs, int len) throws BadLocationException
Этот метод является потокобезопасным, хотя большинство методов Swing таковыми не являются. Дополнительные сведения см. в разделе Параллелизм в Swing.
- Определено в:
-
removeв интерфейсеDocument - Параметры:
-
offs— начальное смещение >= 0 -
len— количество удаляемых символов >= 0 - Вызывает:
-
BadLocationException— указанная позиция удаления не является допустимой позицией в документе - См. также:
replace
public void replace(int offset, int length, String text, AttributeSet attrs) throws BadLocationException
offset до offset + length и заменяет её на text. Способ реализации определяется конкретной реализацией: некоторые реализации могут рассматривать эту операцию как две отдельные операции — удаление с последующей вставкой, тогда как другие могут выполнять замену как одну атомарную операцию.- Параметры:
-
offset— индекс дочернего элемента -
length— длина удаляемого текста; значение 0 означает, что ничего удалять не нужно -
text— вставляемый текст;nullозначает, что текст вставлять не нужно -
attrs— AttributeSet, задающий атрибуты вставляемого текста; значениеnullдопустимо и обычно рассматривается как пустой набор атрибутов, однако точная интерпретация определяется подклассом - Вызывает:
-
BadLocationException— указанная позиция не является допустимой позицией в документе - С версии:
- 1.4
insertString
public void insertString(int offs, String str, AttributeSet a) throws BadLocationException
Этот метод является потокобезопасным, хотя большинство методов Swing таковыми не являются. Дополнительные сведения см. в разделе Параллелизм в Swing.
- Определено в:
-
insertStringв интерфейсеDocument - Параметры:
-
offs— начальное смещение >= 0 -
str— вставляемая строка; если строка равна null или пуста, ничего не происходит -
a— атрибуты вставляемого содержимого - Вызывает:
-
BadLocationException— указанная позиция вставки не является допустимой позицией в документе - См. также:
getText
public String getText(int offset, int length) throws BadLocationException
- Определено в:
-
getTextв интерфейсеDocument - Параметры:
-
offset— начальное смещение >= 0 -
length— количество извлекаемых символов >= 0 - Возвращает:
- текст
- Вызывает:
-
BadLocationException— указанный диапазон включает позицию, которая не является допустимой позицией в документе - См. также:
getText
public void getText(int offset, int length, Segment txt) throws BadLocationException
Если свойство partialReturn параметра txt имеет значение false, данные, возвращаемые в Segment, будут иметь всю запрошенную длину и могут быть копией или не быть ею — это зависит от способа хранения данных. Если свойство partialReturn имеет значение true, возвращается только тот объём текста, который можно вернуть без создания копии. Частичное возвращение обеспечивает более высокую производительность при сканировании больших частей документа. Ниже приведён пример использования частичного возвращения для доступа ко всему документу:
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
Этот метод является потокобезопасным, хотя большинство методов Swing таковыми не являются. Дополнительные сведения см. в разделе Параллелизм в Swing.
- Определено в:
-
createPositionв интерфейсеDocument - Параметры:
-
offs— позиция в модели >= 0 - Возвращает:
- позиция
- Вызывает:
-
BadLocationException— если указанная позиция не является допустимым расположением в связанном документе - См. также:
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 - Возвращает:
- корневой элемент
- См. также:
getBidiRootElement
public Element getBidiRootElement()
- Возвращает:
- корневой элемент двунаправленной структуры этого документа
getParagraphElement
public abstract Element getParagraphElement(int pos)
- Параметры:
-
pos— начальное смещение >= 0 - Возвращает:
- элемент
getAttributeContext
protected final AbstractDocument.AttributeContext getAttributeContext()
- Возвращает:
- контекст
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()
writeLock, если он не пытается получить дополнительные writeLock из уведомления документа. Попытка получить writeLock во время уведомления DocumentListener приведет к IllegalStateException. Возможность получать более одной writeLock для каждого потока позволяет подклассам получить блокировку на запись, выполнить несколько операций, а затем освободить блокировку. Вызовы writeLock должны уравновешиваться вызовами writeUnlock, иначе Document останется заблокированным, и чтение или запись будут невозможны.
- Выбрасывает:
-
IllegalStateException— выбрасывается при недопустимой попытке получить блокировку. Если документ реализован правильно, это может произойти только в том случае, если слушатель документа пытается изменить документ. Такая ситуация нарушает модель событий bean-компонентов, в которой порядок доставки не гарантируется и все слушатели должны быть уведомлены до того, как будут разрешены дальнейшие изменения.
writeUnlock
protected final void writeUnlock()
writeLock. После уменьшения счетчика блокировок, если не осталось активных блокировок, доступ к документу будет разрешен новому потоку записи или потокам чтения.- См. также:
readLock
public final void readLock()
readUnlock.- См. также:
readUnlock
public final void readUnlock()
readLock();
try {
// do something
} finally {
readUnlock();
}
- См. также:
© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/25/docs/api/java.desktop/javax/swing/text/AbstractDocument.html