Класс 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 требуют от реализации чтения или записи информации в узле настроек. Разработчику следует помнить о том, что другая виртуальная машина может одновременно удалить этот узел из хранилища данных. Это ответственность реализации — воссоздать узел, если он был удалён.

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

Since:

1.4

См. также:

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

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

Поля, объявленные в классе java.util.prefs.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()`	Возвращает полное имя пути этого узла параметров.

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

importPreferences, systemNodeForPackage, systemRoot, userNodeForPackage, userRoot

Методы, объявленные в классе java.lang.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.

Возвращает:

значение 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) на результате.

Specified by:

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.

Specified by:

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[]).

Specified by:

putByteArray в классе Preferences

Параметры:

key - ключ, с которым будет связана строковая форма значения.

value - значение, строковая форма которого будет связана с ключом.

Исключения:

NullPointerException - если ключ или значение равны null.

IllegalArgumentException - если длина ключа превышает MAX_KEY_LENGTH или длина значения превышает MAX_VALUE_LENGTH*3/4.

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

IllegalStateException - если этот узел (или предковый) был удалён методом removeNode().

См. также:

getByteArray

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

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

Specified by:

getByteArray в классе Preferences

Параметры:

key - ключ, связанное значение которого должно быть возвращено в виде массива байтов.

Возвращает:

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

Исключения:

IllegalStateException - если этот узел (или предковый) был удалён методом removeNode().

NullPointerException - если key равно null. (Значение типа null для def разрешено.)

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

См. также:

keys

public String[] keys() throws BackingStoreException

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

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

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

childrenNames

public String[] childrenNames() throws BackingStoreException

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

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

Specified by:

childrenNames в классе Preferences

Возвращает:

Имена дочерних узлов этого узла предпочтений.

Исключения:

BackingStoreException - если это действие не может быть выполнено из-за ошибки в базовом хранилище или невозможности связи с ним.

IllegalStateException - если этот узел (или предковый) был удалён методом removeNode().

См. также:

cachedChildren

protected final AbstractPreferences[] cachedChildren()

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

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

parent

public Preferences parent()

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

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

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

узел

public Preferences node(String path)

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

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

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

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

Specified by:

node в классе Preferences

Parameters:

path - имя пути узла настроек для возврата.

Returns:

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

Throws:

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

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

See Also:

существуетУзел

public boolean nodeExists(String path) throws BackingStoreException

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

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

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

удалитьУзел

public void removeNode() throws BackingStoreException

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

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

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

Specified by:

removeNode в классе Preferences

Throws:

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

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

BackingStoreException - если данная операция не может быть завершена из-за ошибки в хранилище или невозможности с ним связаться.

See Also:

имя

public String name()

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

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

Specified by:: name в классе Preferences
Returns:: имя узла настроек, относительно его родителя.

абсолютныйПуть

public String absolutePath()

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

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

Specified by:: absolutePath в классе Preferences
Returns:: абсолютное имя пути узла настроек.

являетсяУзломПользователя

public boolean isUserNode()

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

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

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

добавитьСлушателяИзмененийНастроек

public void addPreferenceChangeListener(PreferenceChangeListener pcl)

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

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

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

Specified by:

addPreferenceChangeListener в классе Preferences

Parameters:

pcl - Слушатель изменений настроек для добавления.

See Also:

removePreferenceChangeListener

public void removePreferenceChangeListener(PreferenceChangeListener pcl)

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

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

Указано в:

removePreferenceChangeListener в классе Preferences

Параметры:

pcl - Удаляемый слушатель изменений настроек.

См. также:

addNodeChangeListener

public void addNodeChangeListener(NodeChangeListener ncl)

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

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

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

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

Указано в:

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(java.lang.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 на этом узле или на одном из его предков (или потомков).

Этот метод вызывается с захваченным замком на этом узле.

Parameters:: name - Имя дочернего узла, который нужно вернуть, относительно этого узла предпочтений.
Returns:: Узел с заданным именем.

toString

public String toString()

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

Specified by:: toString in class Preferences
Returns:: строковое представление объекта

sync

public void sync() throws BackingStoreException

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

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

Specified by:

sync in class Preferences

Throws:

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

IllegalStateException - если этот узел (или предок) был удален методом removeNode().

See Also:

syncSpi

protected abstract void syncSpi() throws BackingStoreException

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

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

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

flush

public void flush() throws BackingStoreException

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

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

Если этот метод вызывается для узла, который был удален методом removeNode(), flushSpi() вызывается для этого узла, но не для других.

Specified by:

flush in class Preferences

Throws:

See Also:

flushSpi

protected abstract void flushSpi() throws BackingStoreException

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

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

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

isRemoved

protected boolean isRemoved()

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

Returns:: true, если этот узел (или его предок) был удален методом removeNode().

exportNode

public void exportNode(OutputStream os) throws IOException, BackingStoreException

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

Specified by:

exportNode in class Preferences

Parameters:

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

Throws:

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

BackingStoreException - если данные предпочтений не могут быть считаны из базового хранилища.

See Also:

exportSubtree

public void exportSubtree(OutputStream os) throws IOException, BackingStoreException

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

Specified by:

exportSubtree in class Preferences

Parameters:

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

Throws:

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

BackingStoreException - если данные предпочтений не могут быть считаны из базового хранилища.

See Also:

© 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://download.java.net/java/early_access/jdk24/docs/api/java.prefs/java/util/prefs/AbstractPreferences.html