Класс AbstractPreferences

java.lang.Object

java.util.prefs.Preferences

java.util.prefs.AbstractPreferences

public abstract class AbstractPreferences extends Preferences

Этот класс предоставляет каркасную реализацию класса Preferences, значительно упрощая задачу его реализации.

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

Разработчики должны переопределить девять абстрактных методов интерфейса поставщика услуг (SPI): getSpi(String), putSpi(String,String), removeSpi(String), childSpi(String), removeNodeSpi(), keysSpi(), childrenNamesSpi(), syncSpi() и flushSpi(). Все конкретные методы точно определяют, как они реализуются на основе этих методов SPI. Разработчик может по своему усмотрению переопределить один или несколько конкретных методов, если реализация по умолчанию по какой-либо причине неудовлетворительна, например из-за производительности.

Методы SPI подразделяются на три группы в зависимости от поведения при возникновении исключений. Метод getSpi никогда не должен выбрасывать исключения, однако это не имеет большого значения, поскольку любое исключение, выброшенное этим методом, будет перехвачено методом get(String,String), который вернёт вызывающему коду указанное значение по умолчанию. Методы removeNodeSpi, keysSpi, childrenNamesSpi, syncSpi и flushSpi должны выбрасывать BackingStoreException; реализация обязана выбросить это проверяемое исключение, если не может выполнить операцию. Исключение распространяется наружу, приводя к сбою соответствующего метода API.

Оставшиеся методы SPI putSpi(String,String), removeSpi(String) и childSpi(String) имеют более сложное поведение при возникновении исключений. Они не должны выбрасывать BackingStoreException, поскольку в общем случае могут выполнять свои контракты, даже если хранилище недоступно. Это возможно потому, что они не возвращают никаких сведений, а их результаты не обязаны становиться постоянными до последующего вызова Preferences.flush() или Preferences.sync(). Как правило, эти методы SPI не должны выбрасывать исключения. В некоторых реализациях могут возникнуть обстоятельства, при которых эти вызовы не могут даже поставить запрошенную операцию в очередь для последующей обработки. Даже в таких обстоятельствах обычно лучше просто проигнорировать вызов и вернуться, а не выбрасывать исключение. Однако в этом случае последующий вызов flush() или sync не будет означать, что все предыдущие операции были успешно сохранены постоянно.

Есть одно обстоятельство, при котором putSpi, removeSpi and childSpi следует выбросить исключение: если у вызывающего кода недостаточно привилегий в базовой операционной системе для выполнения запрошенной операции. Например, такое происходит в большинстве систем, когда непривилегированный пользователь пытается изменить системные настройки. (Необходимые привилегии различаются в разных реализациях. В некоторых реализациях это право изменять содержимое каталога файловой системы, в других — право изменять содержимое раздела реестра.) В подобных обстоятельствах обычно нежелательно позволять программе продолжать работу так, будто эти операции позднее станут постоянными. Хотя реализации не обязаны выбрасывать исключение в таких обстоятельствах, им рекомендуется это делать. Подходящим вариантом будет SecurityException.

Большинство методов SPI требуют от реализации считывать или записывать сведения в узел настроек. Разработчику следует учитывать, что другая виртуальная машина могла одновременно удалить этот узел из хранилища. Если узел был удалён, реализация обязана создать его заново.

Примечание по реализации: в стандартных реализациях Preferences Sun удостоверение личности пользователя наследуется от базовой операционной системы и не меняется в течение времени жизни виртуальной машины. Известно, что в серверных реализациях Preferences удостоверение личности пользователя может меняться от запроса к запросу и неявно передаваться методам Preferences с помощью статического экземпляра ThreadLocal. Авторам таких реализаций настоятельно рекомендуется определять пользователя в момент доступа к настройкам (например, в методе get(String,String) или put(String,String)), а не связывать пользователя с каждым экземпляром Preferences на постоянной основе. Последнее поведение противоречит обычному использованию Preferences и приведёт к большой путанице.

С версии:

1.4

См. также:

Краткое описание полей

Модификатор и тип	Поле	Описание
`protected final Object`	`lock`	Объект, монитор которого используется для блокировки этого узла.
`protected boolean`	`newNode`	Это поле должно иметь значение `true`, если до создания этого объекта данный узел отсутствовал в хранилище.

Поля, объявленные в классе Preferences

MAX_KEY_LENGTH, MAX_NAME_LENGTH, MAX_VALUE_LENGTH

Краткое описание конструкторов

AbstractPreferences(AbstractPreferences parent,
 String name)

Модификатор	Конструктор	Описание
`protected`	Создаёт узел настроек с указанным родительским узлом и указанным относительно него именем.

Краткое описание методов

Модификатор и тип	Метод	Описание
`String`	`absolutePath()`	Реализует метод `absolutePath` согласно спецификации в `Preferences.absolutePath()`.
`void`	`addNodeChangeListener(NodeChangeListener ncl)`	Регистрирует указанный прослушиватель для получения событий изменения узлов этого узла.
`void`	`addPreferenceChangeListener(PreferenceChangeListener pcl)`	Регистрирует указанный прослушиватель для получения событий изменения настроек этого узла настроек.
`protected final AbstractPreferences[]`	`cachedChildren()`	Возвращает все известные неудалённые дочерние узлы этого узла.
`String[]`	`childrenNames()`	Реализует метод `children` согласно спецификации в `Preferences.childrenNames()`.
`protected abstract String[]`	`childrenNamesSpi()`	Возвращает имена дочерних узлов этого узла настроек.
`protected abstract AbstractPreferences`	`childSpi(String name)`	Возвращает дочерний узел с указанным именем, создавая его, если он ещё не существует.
`void`	`clear()`	Реализует метод `clear` согласно спецификации в `Preferences.clear()`.
`void`	`exportNode(OutputStream os)`	Реализует метод `exportNode` согласно спецификации в `Preferences.exportNode(OutputStream)`.
`void`	`exportSubtree(OutputStream os)`	Реализует метод `exportSubtree` согласно спецификации в `Preferences.exportSubtree(OutputStream)`.
`void`	`flush()`	Реализует метод `flush` согласно спецификации в `Preferences.flush()`.
`protected abstract void`	`flushSpi()`	Этот метод вызывается, когда данный узел заблокирован.
`String`	`get(String key, String def)`	Реализует метод `get` согласно спецификации в `Preferences.get(String,String)`.
`boolean`	`getBoolean(String key, boolean def)`	Реализует метод `getBoolean` согласно спецификации в `Preferences.getBoolean(String,boolean)`.
`byte[]`	`getByteArray(String key, byte[] def)`	Реализует метод `getByteArray` согласно спецификации в `Preferences.getByteArray(String,byte[])`.
`protected AbstractPreferences`	`getChild(String nodeName)`	Возвращает дочерний узел с указанным именем, если он существует, или `null` в противном случае.
`double`	`getDouble(String key, double def)`	Реализует метод `getDouble` согласно спецификации в `Preferences.getDouble(String,double)`.
`float`	`getFloat(String key, float def)`	Реализует метод `getFloat` согласно спецификации в `Preferences.getFloat(String,float)`.
`int`	`getInt(String key, int def)`	Реализует метод `getInt` согласно спецификации в `Preferences.getInt(String,int)`.
`long`	`getLong(String key, long def)`	Реализует метод `getLong` согласно спецификации в `Preferences.getLong(String,long)`.
`protected abstract String`	`getSpi(String key)`	Возвращает значение, связанное с указанным ключом в этом узле настроек, или `null`, если с этим ключом ничего не связано либо в данный момент невозможно определить наличие связи.
`protected boolean`	`isRemoved()`	Возвращает `true`, если этот узел (или его предок) был удалён методом `removeNode()`.
`boolean`	`isUserNode()`	Реализует метод `isUserNode` согласно спецификации в `Preferences.isUserNode()`.
`String[]`	`keys()`	Реализует метод `keys` согласно спецификации в `Preferences.keys()`.
`protected abstract String[]`	`keysSpi()`	Возвращает все ключи, с которыми связано значение в этом узле настроек.
`String`	`name()`	Реализует метод `name` согласно спецификации в `Preferences.name()`.
`Preferences`	`node(String path)`	Реализует метод `node` согласно спецификации в `Preferences.node(String)`.
`boolean`	`nodeExists(String path)`	Реализует метод `nodeExists` согласно спецификации в `Preferences.nodeExists(String)`.
`Preferences`	`parent()`	Реализует метод `parent` согласно спецификации в `Preferences.parent()`.
`void`	`put(String key, String value)`	Реализует метод `put` согласно спецификации в `Preferences.put(String,String)`.
`void`	`putBoolean(String key, boolean value)`	Реализует метод `putBoolean` согласно спецификации в `Preferences.putBoolean(String,boolean)`.
`void`	`putByteArray(String key, byte[] value)`	Реализует метод `putByteArray` согласно спецификации в `Preferences.putByteArray(String,byte[])`.
`void`	`putDouble(String key, double value)`	Реализует метод `putDouble` согласно спецификации в `Preferences.putDouble(String,double)`.
`void`	`putFloat(String key, float value)`	Реализует метод `putFloat` согласно спецификации в `Preferences.putFloat(String,float)`.
`void`	`putInt(String key, int value)`	Реализует метод `putInt` согласно спецификации в `Preferences.putInt(String,int)`.
`void`	`putLong(String key, long value)`	Реализует метод `putLong` согласно спецификации в `Preferences.putLong(String,long)`.
`protected abstract void`	`putSpi(String key, String value)`	Добавляет указанную пару «ключ—значение» в этот узел настроек.
`void`	`remove(String key)`	Реализует метод `remove(String)` согласно спецификации в `Preferences.remove(String)`.
`void`	`removeNode()`	Реализует метод `removeNode()` согласно спецификации в `Preferences.removeNode()`.
`void`	`removeNodeChangeListener(NodeChangeListener ncl)`	Удаляет указанный `NodeChangeListener`, чтобы он больше не получал события об изменениях.
`protected abstract void`	`removeNodeSpi()`	Удаляет этот узел настроек, делая его и все содержащиеся в нём настройки недействительными.
`void`	`removePreferenceChangeListener(PreferenceChangeListener pcl)`	Удаляет указанный прослушиватель изменений настроек, чтобы он больше не получал события об изменении настроек.
`protected abstract void`	`removeSpi(String key)`	Удаляет связь (если она есть) с указанным ключом в этом узле настроек.
`void`	`sync()`	Реализует метод `sync` согласно спецификации в `Preferences.sync()`.
`protected abstract void`	`syncSpi()`	Этот метод вызывается, когда данный узел заблокирован.
`String`	`toString()`	Возвращает абсолютный путь к этому узлу настроек.

Методы, объявленные в классе Preferences

importPreferences, systemNodeForPackage, systemRoot, userNodeForPackage, userRoot

Методы, объявленные в классе Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Подробное описание полей

newNode

protected boolean newNode

Это поле должно быть true, если этого узла не существовало в базовом хранилище до создания данного объекта. Поле инициализируется значением false, но конструктор подкласса может установить для него значение true (после этого его не следует изменять). Это поле указывает, следует ли генерировать событие изменения узла по завершении его создания.

lock

protected final Object lock

Объект, монитор которого используется для блокировки этого узла. Этот объект предпочтительнее самого узла, чтобы снизить вероятность намеренного или непреднамеренного отказа в обслуживании из-за заблокированного узла. Во избежание взаимной блокировки поток никогда не блокирует узел, если он удерживает блокировку потомка этого узла.

Подробное описание конструкторов

AbstractPreferences

protected AbstractPreferences(AbstractPreferences parent, String name)

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

Параметры:: parent — родительский узел этого узла настроек или null, если это корневой узел.; name — имя этого узла настроек относительно родительского узла или "", если это корневой узел.
Исключения:: IllegalArgumentException — если name содержит косую черту ('/') или parent равен null, а имя не равно "".

Подробное описание методов

put

public void put(String key, String value)

Реализует метод put в соответствии со спецификацией в Preferences.put(String,String).

Эта реализация проверяет допустимость ключа и значения, получает блокировку этого узла настроек, проверяет, что узел не был удален, вызывает putSpi(String,String) и, если имеются слушатели изменений настроек, ставит в очередь событие уведомления для обработки потоком диспетчеризации событий.

Определено в:: put в классе Preferences
Параметры:: key — ключ, с которым связывается указанное значение.; value — значение, связываемое с указанным ключом.
Исключения:: NullPointerException — если ключ или значение равно null.; IllegalArgumentException — если key.length() превышает MAX_KEY_LENGTH или value.length превышает MAX_VALUE_LENGTH.; IllegalArgumentException — если ключ или значение содержит нулевой управляющий символ с кодовой точкой U+0000.; IllegalStateException — если этот узел (или его предок) был удален с помощью метода removeNode().

get

public String get(String key, String def)

Реализует метод get в соответствии со спецификацией в Preferences.get(String,String).

Сначала эта реализация проверяет, не равно ли key значению null, и в таком случае генерирует NullPointerException. Затем она получает блокировку этого узла настроек, проверяет, что узел не был удален, вызывает getSpi(String) и возвращает результат, если только вызов getSpi не возвращает null и не генерирует исключение; в таком случае этот вызов возвращает def.

Определено в:: get в классе Preferences
Параметры:: key — ключ, значение которого требуется вернуть.; def — значение, возвращаемое в том случае, если с key в этом узле настроек не связано никакое значение.
Возвращает:: значение, связанное с key, или def, если с key не связано никакое значение.
Исключения:: IllegalStateException — если этот узел (или его предок) был удален с помощью метода removeNode().; NullPointerException — если ключ равен null. (Значение по умолчанию null допускается.); IllegalArgumentException — если ключ содержит нулевой управляющий символ с кодовой точкой U+0000.

remove

public void remove(String key)

Реализует метод remove(String) в соответствии со спецификацией в Preferences.remove(String).

Эта реализация получает блокировку этого узла настроек, проверяет, что узел не был удален, вызывает removeSpi(String) и, если имеются слушатели изменений настроек, ставит в очередь событие уведомления для обработки потоком диспетчеризации событий.

Определено в:: remove в классе Preferences
Параметры:: key — ключ, отображение которого требуется удалить из узла настроек.
Исключения:: IllegalStateException — если этот узел (или его предок) был удален с помощью метода removeNode().; IllegalArgumentException — если ключ содержит нулевой управляющий символ с кодовой точкой U+0000.; NullPointerException — если key равно null.

clear

public void clear() throws BackingStoreException

Реализует метод clear в соответствии со спецификацией в Preferences.clear().

Эта реализация получает блокировку этого узла настроек, вызывает keys() для получения массива ключей и перебирает массив, вызывая remove(String) для каждого ключа.

Определено в:

clear в классе Preferences

Исключения:

BackingStoreException — если эту операцию невозможно выполнить из-за сбоя базового хранилища или невозможности связи с ним.

IllegalStateException — если этот узел (или его предок) был удален с помощью метода removeNode().

См. также:

putInt

public void putInt(String key, int value)

Реализует метод putInt в соответствии со спецификацией в Preferences.putInt(String,int).

Эта реализация преобразует value в строку с помощью Integer.toString(int) и вызывает для результата put(String,String).

Определено в:

putInt в классе Preferences

Параметры:

key — ключ, с которым связывается строковое представление значения.

value — значение, строковое представление которого связывается с ключом.

Исключения:

NullPointerException — если ключ равен null.

IllegalArgumentException — если key.length() превышает MAX_KEY_LENGTH.

IllegalArgumentException — если ключ содержит нулевой управляющий символ с кодовой точкой U+0000.

IllegalStateException — если этот узел (или его предок) был удален с помощью метода removeNode().

См. также:

getInt

public int getInt(String key, int def)

Реализует метод getInt в соответствии со спецификацией в Preferences.getInt(String,int).

Эта реализация вызывает get(key, null). Если возвращаемое значение не равно null, реализация пытается преобразовать его в int с помощью Integer.parseInt(String). Если попытка завершается успешно, этот метод возвращает преобразованное значение. В противном случае возвращается def.

Определено в:

getInt в классе Preferences

Параметры:

key — ключ, значение которого требуется вернуть как int.

def — значение, возвращаемое в том случае, если с key в этом узле настроек не связано никакое значение или связанное значение невозможно интерпретировать как int.

Возвращает:

значение типа int, представленное строкой, связанной с key в этом узле настроек, или def, если связанное значение отсутствует или его невозможно интерпретировать как int.

Исключения:

IllegalStateException — если этот узел (или его предок) был удален с помощью метода removeNode().

NullPointerException — если key равно null.

IllegalArgumentException — если ключ содержит нулевой управляющий символ с кодовой точкой U+0000.

См. также:

putLong

public void putLong(String key, long value)

Реализует метод putLong в соответствии со спецификацией в Preferences.putLong(String,long).

Эта реализация преобразует value в строку с помощью Long.toString(long) и вызывает для результата put(String,String).

Определено в:

putLong в классе Preferences

Параметры:

key — ключ, с которым связывается строковое представление значения.

value — значение, строковое представление которого связывается с ключом.

Исключения:

NullPointerException — если ключ равен null.

IllegalArgumentException — если key.length() превышает MAX_KEY_LENGTH.

IllegalArgumentException — если ключ содержит нулевой управляющий символ с кодовой точкой U+0000.

IllegalStateException — если этот узел (или его предок) был удален с помощью метода removeNode().

См. также:

getLong

public long getLong(String key, long def)

Реализует метод getLong в соответствии со спецификацией в Preferences.getLong(String,long).

Эта реализация вызывает get(key, null). Если возвращаемое значение не равно null, реализация пытается преобразовать его в long с помощью Long.parseLong(String). Если попытка завершается успешно, этот метод возвращает преобразованное значение. В противном случае возвращается def.

Определено в:

getLong в классе Preferences

Параметры:

key — ключ, значение которого требуется вернуть как long.

def — значение, возвращаемое в том случае, если с key в этом узле настроек не связано никакое значение или связанное значение невозможно интерпретировать как long.

Возвращает:

значение типа long, представленное строкой, связанной с key в этом узле настроек, или def, если связанное значение отсутствует или его невозможно интерпретировать как long.

Исключения:

IllegalStateException — если этот узел (или его предок) был удален с помощью метода removeNode().

NullPointerException — если key равно null.

IllegalArgumentException — если ключ содержит нулевой управляющий символ с кодовой точкой U+0000.

См. также:

putBoolean

public void putBoolean(String key, boolean value)

Реализует метод putBoolean в соответствии со спецификацией в Preferences.putBoolean(String,boolean).

Эта реализация преобразует value в строку с помощью String.valueOf(boolean) и вызывает для результата put(String,String).

Определено в:

putBoolean в классе Preferences

Параметры:

key — ключ, с которым связывается строковое представление значения.

value — значение, строковое представление которого связывается с ключом.

Исключения:

NullPointerException — если ключ равен null.

IllegalArgumentException — если key.length() превышает MAX_KEY_LENGTH.

IllegalArgumentException — если ключ содержит нулевой управляющий символ с кодовой точкой U+0000.

IllegalStateException — если этот узел (или его предок) был удален с помощью метода removeNode().

См. также:

getBoolean

public boolean getBoolean(String key, boolean def)

Реализует метод getBoolean в соответствии со спецификацией в Preferences.getBoolean(String,boolean).

Эта реализация вызывает get(key, null). Если возвращаемое значение не равно null, оно сравнивается с "true" с помощью String.equalsIgnoreCase(String). Если сравнение возвращает true, этот вызов возвращает true. В противном случае исходное возвращаемое значение сравнивается с "false", также с помощью String.equalsIgnoreCase(String). Если сравнение возвращает true, этот вызов возвращает false. В противном случае этот вызов возвращает def.

Определено в:

getBoolean в классе Preferences

Параметры:

key — ключ, значение которого требуется вернуть как boolean.

def — значение, возвращаемое в том случае, если с key в этом узле настроек не связано никакое значение или связанное значение невозможно интерпретировать как boolean.

Возвращает:

значение boolean, представленное строкой, связанной с key в этом узле настроек, или def, если связанное значение отсутствует или его невозможно интерпретировать как boolean.

Исключения:

IllegalStateException — если этот узел (или его предок) был удален с помощью метода removeNode().

NullPointerException — если key равно null.

IllegalArgumentException — если ключ содержит нулевой управляющий символ с кодовой точкой U+0000.

См. также:

putFloat

public void putFloat(String key, float value)

Реализует метод putFloat в соответствии со спецификацией в Preferences.putFloat(String,float).

Эта реализация преобразует value в строку с помощью Float.toString(float) и вызывает для результата put(String,String).

Определено в:

putFloat в классе Preferences

Параметры:

key — ключ, с которым связывается строковое представление значения.

value — значение, строковое представление которого связывается с ключом.

Исключения:

NullPointerException — если ключ равен null.

IllegalArgumentException — если key.length() превышает MAX_KEY_LENGTH.

IllegalArgumentException — если ключ содержит нулевой управляющий символ с кодовой точкой U+0000.

IllegalStateException — если этот узел (или его предок) был удален с помощью метода removeNode().

См. также:

getFloat

public float getFloat(String key, float def)

Реализует метод getFloat в соответствии со спецификацией в Preferences.getFloat(String,float).

Эта реализация вызывает get(key, null). Если возвращаемое значение не равно null, реализация пытается преобразовать его в float с помощью Float.parseFloat(String). Если попытка завершается успешно, этот метод возвращает преобразованное значение. В противном случае возвращается def.

Определено в:

getFloat в классе Preferences

Параметры:

key — ключ, значение которого требуется вернуть как float.

def — значение, возвращаемое в том случае, если с key в этом узле настроек не связано никакое значение или связанное значение невозможно интерпретировать как float.

Возвращает:

значение типа float, представленное строкой, связанной с key в этом узле настроек, или def, если связанное значение отсутствует или его невозможно интерпретировать как float.

Исключения:

IllegalStateException — если этот узел (или его предок) был удален с помощью метода removeNode().

NullPointerException — если key равно null.

IllegalArgumentException — если ключ содержит нулевой управляющий символ с кодовой точкой U+0000.

См. также:

putDouble

public void putDouble(String key, double value)

Реализует метод putDouble в соответствии со спецификацией в Preferences.putDouble(String,double).

Эта реализация преобразует value в строку с помощью Double.toString(double) и вызывает для результата put(String,String).

Определено в:

putDouble в классе Preferences

Параметры:

key — ключ, с которым связывается строковое представление значения.

value — значение, строковое представление которого связывается с ключом.

Исключения:

NullPointerException — если ключ равен null.

IllegalArgumentException — если key.length() превышает MAX_KEY_LENGTH.

IllegalArgumentException — если ключ содержит нулевой управляющий символ с кодовой точкой U+0000.

IllegalStateException — если этот узел (или его предок) был удален с помощью метода removeNode().

См. также:

getDouble

public double getDouble(String key, double def)

Реализует метод getDouble в соответствии со спецификацией в Preferences.getDouble(String,double).

Эта реализация вызывает get(key, null). Если возвращаемое значение не равно null, реализация пытается преобразовать его в double с помощью Double.parseDouble(String). Если попытка завершается успешно, этот метод возвращает преобразованное значение. В противном случае возвращается def.

Определено в:

getDouble в классе Preferences

Параметры:

key — ключ, значение которого требуется вернуть как double.

def — значение, возвращаемое в том случае, если с key в этом узле настроек не связано никакое значение или связанное значение невозможно интерпретировать как double.

Возвращает:

значение типа double, представленное строкой, связанной с key в этом узле настроек, или def, если связанное значение отсутствует или его невозможно интерпретировать как double.

Исключения:

IllegalStateException — если этот узел (или его предок) был удален с помощью метода removeNode().

NullPointerException — если key равно null.

IllegalArgumentException — если ключ содержит нулевой управляющий символ с кодовой точкой U+0000.

См. также:

putByteArray

public void putByteArray(String key, byte[] value)

Реализует метод putByteArray в соответствии со спецификацией в Preferences.putByteArray(String,byte[]).

Определено в:

putByteArray в классе Preferences

Параметры:

key — ключ, с которым связывается строковое представление значения.

value — значение, строковое представление которого связывается с ключом.

Исключения:

NullPointerException — если ключ или значение равно null.

IllegalArgumentException — если key.length() превышает MAX_KEY_LENGTH или value.length превышает MAX_VALUE_LENGTH*3/4.

IllegalArgumentException — если ключ содержит нулевой управляющий символ с кодовой точкой U+0000.

IllegalStateException — если этот узел (или его предок) был удален с помощью метода removeNode().

См. также:

getByteArray

public byte[] getByteArray(String key, byte[] def)

Реализует метод getByteArray в соответствии со спецификацией в Preferences.getByteArray(String,byte[]).

Определено в:

getByteArray в классе Preferences

Параметры:

key — ключ, значение которого требуется вернуть как массив байтов.

def — значение, возвращаемое в том случае, если с key в этом узле настроек не связано никакое значение или связанное значение невозможно интерпретировать как массив байтов.

Возвращает:

значение в виде массива байтов, представленное строкой, связанной с key в этом узле настроек, или def, если связанное значение отсутствует или его невозможно интерпретировать как массив байтов.

Исключения:

IllegalStateException — если этот узел (или его предок) был удален с помощью метода removeNode().

NullPointerException — если key равно null. (Значение null для def допускается.)

IllegalArgumentException — если ключ содержит нулевой управляющий символ с кодовой точкой U+0000.

См. также:

keys

public String[] keys() throws BackingStoreException

Реализует метод keys в соответствии со спецификацией в Preferences.keys().

Эта реализация получает блокировку этого узла настроек, проверяет, что узел не был удален, и вызывает keysSpi().

Определено в:: keys в классе Preferences
Возвращает:: массив ключей, с которыми в этом узле настроек связано значение.
Исключения:: BackingStoreException — если эту операцию невозможно выполнить из-за сбоя базового хранилища или невозможности связи с ним.; IllegalStateException — если этот узел (или его предок) был удален с помощью метода removeNode().

childrenNames

public String[] childrenNames() throws BackingStoreException

Реализует метод children согласно спецификации в Preferences.childrenNames().

Эта реализация получает блокировку данного узла настроек, проверяет, что узел не был удалён, создаёт TreeSet, инициализированное именами уже кэшированных дочерних узлов (дочерними узлами в «кэше дочерних узлов» этого узла), вызывает childrenNamesSpi() и добавляет в множество все возвращённые имена дочерних узлов. Элементы дерева сортировки помещаются в массив String с помощью метода toArray, после чего этот массив возвращается.

Определено в:

childrenNames в классе Preferences

Возвращает:

имена дочерних узлов этого узла настроек.

Исключения:

BackingStoreException — если эту операцию невозможно выполнить из-за сбоя в хранилище или невозможности установить с ним связь.

IllegalStateException — если этот узел (или его предок) был удалён с помощью метода removeNode().

См. также:

cachedChildren

protected final AbstractPreferences[] cachedChildren()

Возвращает все известные дочерние узлы этого узла, которые не были удалены.

Возвращает:: все известные дочерние узлы этого узла, которые не были удалены.

parent

public Preferences parent()

Реализует метод parent согласно спецификации в Preferences.parent().

Эта реализация получает блокировку данного узла настроек, проверяет, что узел не был удалён, и возвращает значение родительского узла, переданное конструктору этого узла.

Определено в:: parent в классе Preferences
Возвращает:: родительский узел этого узла настроек.
Исключения:: IllegalStateException — если этот узел (или его предок) был удалён с помощью метода removeNode().

node

public Preferences node(String path)

Реализует метод node согласно спецификации в Preferences.node(String).

Эта реализация получает блокировку данного узла настроек и проверяет, что узел не был удалён. Если path равно "", возвращается этот узел; если path равно "/", возвращается корневой узел этого узла. Если первый символ в path не является '/', реализация разбивает path на токены и рекурсивно проходит по пути от этого узла до указанного узла, «потребляя» имя и косую черту из path на каждом шаге обхода. На каждом шаге блокируется текущий узел и проверяется кэш его дочерних узлов на наличие указанного узла. Если узел не найден, проверяется, не превышает ли длина имени MAX_NAME_LENGTH. Затем вызывается метод childSpi(String), а результат сохраняется в кэше дочерних узлов этого узла. Если поле newNode вновь созданного объекта Preferences равно true и имеются слушатели изменения узлов, в очередь помещается событие-уведомление для обработки потоком диспетчеризации событий.

Когда токенов больше не остаётся, этот метод возвращает последнее значение, найденное в кэше дочерних узлов или возвращённое методом childSpi. Если во время обхода подряд встречаются два токена "/" или последний токен — "/" (а не имя), выбрасывается соответствующее исключение IllegalArgumentException.

Если первый символ path — '/' (что указывает на абсолютный путь), блокировка этого узла настроек снимается до разбиения path на токены, и этот метод рекурсивно проходит по пути от корневого узла, а не от текущего. В остальном обход выполняется так же, как для относительных путей. Снятие блокировки этого узла до начала обхода от корневого узла необходимо для предотвращения возможной взаимной блокировки, как указано в locking invariant.

Определено в:

node в классе Preferences

Параметры:

path — путь к возвращаемому узлу настроек.

Возвращает:

указанный узел настроек.

Исключения:

IllegalArgumentException — если путь недопустим (то есть содержит несколько косых черт подряд или заканчивается косой чертой и имеет длину больше одного символа).

IllegalStateException — если этот узел (или его предок) был удалён с помощью метода removeNode().

См. также:

nodeExists

public boolean nodeExists(String path) throws BackingStoreException

Реализует метод nodeExists согласно спецификации в Preferences.nodeExists(String).

Эта реализация очень похожа на node(String), за исключением того, что вместо childSpi(String) используется getChild(String).

Определено в:: nodeExists в классе Preferences
Параметры:: path — путь к узлу, существование которого нужно проверить.
Возвращает:: true, если указанный узел существует.
Исключения:: BackingStoreException — если эту операцию невозможно выполнить из-за сбоя в хранилище или невозможности установить с ним связь.; IllegalArgumentException — если путь недопустим (то есть содержит несколько косых черт подряд или заканчивается косой чертой и имеет длину больше одного символа).; IllegalStateException — если этот узел (или его предок) был удалён с помощью метода removeNode(), а pathname не является пустой строкой ("").

removeNode

public void removeNode() throws BackingStoreException

Реализует метод removeNode() согласно спецификации в Preferences.removeNode().

Эта реализация проверяет, является ли данный узел корневым; если да, выбрасывается соответствующее исключение. Затем она блокирует родительский узел и вызывает рекурсивный вспомогательный метод, обходящий поддерево с корнем в данном узле. Рекурсивный метод блокирует узел, для которого он вызван, проверяет, не был ли тот уже удалён, а затем убеждается, что все его дочерние узлы кэшированы: вызывается метод childrenNamesSpi(), и для каждого возвращённого имени дочернего узла проверяется его наличие в кэше дочерних узлов. Если дочерний узел ещё не кэширован, для создания экземпляра Preferences вызывается метод childSpi(String), после чего этот экземпляр помещается в кэш дочерних узлов. Затем вспомогательный метод рекурсивно вызывается для каждого узла в кэше дочерних узлов. Далее вызывается removeNodeSpi(), узел помечается как удалённый и удаляется из кэша дочерних узлов родителя. Наконец, если имеются слушатели изменения узлов, в очередь помещается событие-уведомление для обработки потоком диспетчеризации событий.

Обратите внимание, что вспомогательный метод всегда вызывается, когда заблокированы все предки вплоть до «ближайшего неудалённого предка».

Определено в:

removeNode в классе Preferences

Исключения:

IllegalStateException — если этот узел (или его предок) уже был удалён с помощью метода removeNode().

UnsupportedOperationException — если этот метод вызван для корневого узла.

См. также:

name

public String name()

Реализует метод name согласно спецификации в Preferences.name().

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

Определено в:: name в классе Preferences
Возвращает:: имя этого узла настроек относительно его родительского узла.

absolutePath

public String absolutePath()

Реализует метод absolutePath согласно спецификации в Preferences.absolutePath().

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

Определено в:: absolutePath в классе Preferences
Возвращает:: абсолютный путь этого узла настроек.

isUserNode

public boolean isUserNode()

Реализует метод isUserNode согласно спецификации в Preferences.isUserNode().

Эта реализация сравнивает корневой узел данного узла (хранящийся в закрытом поле) со значением, возвращаемым методом Preferences.userRoot(). Если ссылки на эти два объекта идентичны, метод возвращает true.

Определено в:: isUserNode в классе Preferences
Возвращает:: true, если этот узел настроек находится в дереве пользовательских настроек; false, если он находится в дереве системных настроек.

addPreferenceChangeListener

public void addPreferenceChangeListener(PreferenceChangeListener pcl)

Описание скопировано из класса: Preferences

Регистрирует указанный слушатель для получения событий изменения настроек этого узла настроек. Событие изменения настроек генерируется при добавлении или удалении настройки в этом узле, а также при изменении значения, связанного с настройкой. (События изменения настроек не генерируются методом Preferences.removeNode(), который генерирует событие изменения узла. События изменения настроек генерируются методом clear.)

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

Определено в:

addPreferenceChangeListener в классе Preferences

Параметры:

pcl — слушатель изменений настроек, который нужно добавить.

См. также:

removePreferenceChangeListener

public void removePreferenceChangeListener(PreferenceChangeListener pcl)

Описание скопировано из класса: Preferences

Удаляет указанный слушатель изменений настроек, после чего он перестаёт получать события изменения настроек.

Определено в:

removePreferenceChangeListener в классе Preferences

Параметры:

pcl — слушатель изменений настроек, который нужно удалить.

См. также:

addNodeChangeListener

public void addNodeChangeListener(NodeChangeListener ncl)

Описание скопировано из класса: Preferences

Регистрирует указанный слушатель для получения событий изменения узлов этого узла. Событие изменения узла генерируется при добавлении дочернего узла к этому узлу или его удалении. (Один вызов Preferences.removeNode() приводит к возникновению нескольких событий изменения узлов — по одному для каждого узла в поддереве с корнем в удалённом узле.)

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

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

Определено в:

addNodeChangeListener в классе Preferences

Параметры:

ncl — объект NodeChangeListener, который нужно добавить.

См. также:

removeNodeChangeListener

public void removeNodeChangeListener(NodeChangeListener ncl)

Описание скопировано из класса: Preferences

Удаляет указанный объект NodeChangeListener, после чего он перестаёт получать события изменений.

Определено в:

removeNodeChangeListener в классе Preferences

Параметры:

ncl — объект NodeChangeListener, который нужно удалить.

См. также:

putSpi

protected abstract void putSpi(String key, String value)

Помещает указанную пару «ключ-значение» в этот узел настроек. Гарантируется, что key и value не равны null и имеют допустимую длину. Также гарантируется, что этот узел не был удалён. (Реализатору не нужно проверять ни одно из этих условий.)

Этот метод вызывается, когда блокировка данного узла удерживается.

Параметры:: key — ключ; value — значение

getSpi

protected abstract String getSpi(String key)

Возвращает значение, связанное с указанным ключом в этом узле настроек, или null, если с этим ключом ничего не связано либо связь в данный момент невозможно определить. Гарантируется, что key не равно null. Также гарантируется, что этот узел не был удалён. (Реализатору не нужно проверять ни одно из этих условий.)

Как правило, этот метод не должен выбрасывать исключения ни при каких обстоятельствах. Однако если исключение всё же выбрасывается, оно перехватывается и рассматривается как возвращаемое значение null.

Этот метод вызывается, когда блокировка данного узла удерживается.

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

removeSpi

protected abstract void removeSpi(String key)

Удаляет связь (если она существует) с указанным ключом в этом узле настроек. Гарантируется, что key не равно null. Также гарантируется, что этот узел не был удалён. (Реализатору не нужно проверять ни одно из этих условий.)

Этот метод вызывается, когда блокировка данного узла удерживается.

Параметры:: key — ключ

removeNodeSpi

protected abstract void removeNodeSpi() throws BackingStoreException

Удаляет этот узел настроек, делая его недействительным, как и все содержащиеся в нём настройки. На момент вызова этого метода у именованного дочернего узла не должно быть потомков (то есть метод Preferences.removeNode() вызывает этот метод повторно снизу вверх, удаляя всех потомков узла до удаления самого узла).

Этот метод вызывается, когда удерживаются блокировки данного узла и его родительского узла (а также всех предков, удаляемых в результате одного вызова Preferences.removeNode()).

Удаление узла не обязательно должно стать постоянным до вызова метода flush для этого узла или одного из его предков.

Если этот узел выбрасывает BackingStoreException, исключение распространяется за пределы окружающего вызова removeNode().

Исключения:: BackingStoreException — если эту операцию невозможно выполнить из-за сбоя в хранилище или невозможности установить с ним связь.

keysSpi

protected abstract String[] keysSpi() throws BackingStoreException

Возвращает все ключи, с которыми в этом узле настроек связано значение. (Если в узле нет настроек, возвращаемый массив будет иметь нулевой размер.) Гарантируется, что этот узел не был удалён.

Этот метод вызывается, когда блокировка данного узла удерживается.

Если этот узел выбрасывает BackingStoreException, исключение распространяется за пределы окружающего вызова keys().

Возвращает:: массив ключей, с которыми в этом узле настроек связано значение.
Исключения:: BackingStoreException — если эту операцию невозможно выполнить из-за сбоя в хранилище или невозможности установить с ним связь.

childrenNamesSpi

protected abstract String[] childrenNamesSpi() throws BackingStoreException

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

Этот метод вызывается, когда блокировка данного узла удерживается.

Если этот узел выбрасывает BackingStoreException, исключение распространяется за пределы окружающего вызова childrenNames().

Возвращает:: массив, содержащий имена дочерних узлов этого узла настроек.
Исключения:: BackingStoreException — если эту операцию невозможно выполнить из-за сбоя в хранилище или невозможности установить с ним связь.

getChild

protected AbstractPreferences getChild(String nodeName) throws BackingStoreException

Возвращает именованный дочерний узел, если он существует, или null, если он не существует. Гарантируется, что nodeName не равно null, не является пустым, не содержит символ косой черты ('/') и имеет длину не более Preferences.MAX_NAME_LENGTH символов. Также гарантируется, что этот узел не был удалён. (Если реализатор решит переопределить этот метод, ему не нужно проверять ни одно из этих условий.)

Наконец, гарантируется, что указанный узел не возвращался предыдущим вызовом этого метода или childSpi(String) после последнего удаления этого узла. Иными словами, кэшированное значение всегда будет использоваться вместо вызова этого метода. (Если реализатор решит переопределить этот метод, ему не нужно поддерживать собственный кэш ранее возвращённых дочерних узлов.)

Эта реализация получает блокировку данного узла настроек, вызывает childrenNames(), чтобы получить массив имён дочерних узлов, и перебирает этот массив, сравнивая имя каждого дочернего узла с указанным именем узла. Если имя дочернего узла совпадает, вызывается метод childSpi(String) и возвращается полученный узел. Если перебор завершается, а указанное имя не найдено, возвращается null.

Параметры:: nodeName — имя искомого дочернего узла.
Возвращает:: именованный дочерний узел, если он существует, или null, если он не существует.
Исключения:: BackingStoreException — если эту операцию невозможно выполнить из-за сбоя в хранилище или невозможности установить с ним связь.

childSpi

protected abstract AbstractPreferences childSpi(String name)

Возвращает именованный дочерний узел этого узла настроек, создавая его, если он ещё не существует. Гарантируется, что name не равно null, не является пустым, не содержит символ косой черты ('/') и имеет длину не более Preferences.MAX_NAME_LENGTH символов. Также гарантируется, что этот узел не был удалён. (Реализатору не нужно проверять ни одно из этих условий.)

Наконец, гарантируется, что указанный узел не возвращался предыдущим вызовом этого метода или getChild(String) после последнего удаления этого узла. Иными словами, кэшированное значение всегда будет использоваться вместо вызова этого метода. Подклассам не нужно поддерживать собственный кэш ранее возвращённых дочерних узлов.

Реализатор должен гарантировать, что возвращаемый узел не был удалён. Если одноимённый дочерний узел этого узла был ранее удалён, реализатор должен вернуть вновь созданный узел AbstractPreferences; после удаления узел AbstractPreferences нельзя «оживить».

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

Этот метод вызывается, когда блокировка данного узла удерживается.

Параметры:: name — имя возвращаемого дочернего узла относительно этого узла настроек.
Возвращает:: именованный дочерний узел.

toString

public String toString()

Возвращает абсолютный путь этого узла настроек.

Определено в:: toString в классе Preferences
Возвращает:: строковое представление объекта

sync

public void sync() throws BackingStoreException

Реализует метод sync согласно спецификации в Preferences.sync().

Эта реализация вызывает рекурсивный вспомогательный метод, который блокирует этот узел, вызывает для него syncSpi(), снимает блокировку этого узла и рекурсивно вызывает этот метод для каждого «кэшированного дочернего узла». Кэшированный дочерний узел — это дочерний узел, созданный в данной виртуальной машине и не удалённый впоследствии. По сути, этот метод выполняет обход в глубину «кэшированного поддерева» с корнем в данном узле, вызывая syncSpi() для каждого узла поддерева и блокируя только текущий узел. Обратите внимание, что syncSpi() вызывается сверху вниз.

Определено в:

sync в классе Preferences

Исключения:

IllegalStateException — если этот узел (или его предок) был удалён с помощью метода removeNode().

См. также:

syncSpi

protected abstract void syncSpi() throws BackingStoreException

Этот метод вызывается, когда данный узел заблокирован. Он должен синхронизировать кэшированные настройки, хранящиеся в этом узле, с настройками в хранилище. Вполне возможно, что этого узла нет в хранилище: он мог быть удалён другой виртуальной машиной или ещё не создан. Обратите внимание, что этот метод не должен синхронизировать настройки в подузлах данного узла. Если хранилище автоматически синхронизирует всё поддерево целиком, реализатору рекомендуется переопределить sync(), а не только этот метод.

Если этот узел выбрасывает BackingStoreException, исключение распространяется за пределы окружающего вызова sync().

Исключения:: BackingStoreException — если эту операцию невозможно выполнить из-за сбоя в хранилище или невозможности установить с ним связь.

flush

public void flush() throws BackingStoreException

Реализует метод flush согласно спецификации в Preferences.flush().

Эта реализация вызывает рекурсивный вспомогательный метод, который блокирует этот узел, вызывает для него flushSpi(), снимает блокировку этого узла и рекурсивно вызывает этот метод для каждого «кэшированного дочернего узла». Кэшированный дочерний узел — это дочерний узел, созданный в данной виртуальной машине и не удалённый впоследствии. По сути, этот метод выполняет обход в глубину «кэшированного поддерева» с корнем в данном узле, вызывая flushSpi() для каждого узла поддерева и блокируя только текущий узел. Обратите внимание, что flushSpi() вызывается сверху вниз.

Если этот метод вызван для узла, удалённого с помощью метода removeNode(), flushSpi() вызывается для этого узла, но не для остальных.

Определено в:

flush в классе Preferences

Исключения:

См. также:

flushSpi

protected abstract void flushSpi() throws BackingStoreException

Этот метод вызывается, когда этот узел заблокирован. Контракт этого метода заключается в принудительной записи всех кэшированных изменений содержимого этого узла настроек в базовое хранилище, что гарантирует их сохранность. (Вполне возможно, что этого узла нет в базовом хранилище — либо потому, что он был удалён другой виртуальной машиной, либо потому, что он ещё не был создан.) Обратите внимание, что этот метод не должен сбрасывать настройки ни в одном из подузлов этого узла. Если базовое хранилище естественным образом сбрасывает всё поддерево целиком, рекомендуется переопределить flush(), а не только этот метод.

Если этот узел выбрасывает BackingStoreException, исключение выйдет за пределы заключающего вызова flush().

Выбрасывает:: BackingStoreException — если эту операцию невозможно завершить из-за сбоя базового хранилища или невозможности связаться с ним.

isRemoved

protected boolean isRemoved()

Возвращает true тогда и только тогда, когда этот узел (или его предок) был удалён методом removeNode(). Перед возвратом содержимого закрытого поля, используемого для отслеживания этого состояния, этот метод блокирует данный узел.

Возвращает:: true тогда и только тогда, когда этот узел (или его предок) был удалён методом removeNode().

exportNode

public void exportNode(OutputStream os) throws IOException, BackingStoreException

Реализует метод exportNode в соответствии со спецификацией в Preferences.exportNode(OutputStream).

Определено в:

exportNode в классе Preferences

Параметры:

os — поток вывода, в который записывается документ XML.

Выбрасывает:

IOException — если запись в указанный поток вывода приводит к IOException.

BackingStoreException — если данные настроек не удаётся прочитать из базового хранилища.

См. также:

exportSubtree

public void exportSubtree(OutputStream os) throws IOException, BackingStoreException

Реализует метод exportSubtree в соответствии со спецификацией в Preferences.exportSubtree(OutputStream).

Определено в:

exportSubtree в классе Preferences

Параметры:

os — поток вывода, в который записывается документ XML.

Выбрасывает:

IOException — если запись в указанный поток вывода приводит к IOException.

BackingStoreException — если данные настроек не удаётся прочитать из базового хранилища.

См. также:

© 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.prefs/java/util/prefs/AbstractPreferences.html