Класс AbstractPreferences

java.lang.Object

java.util.prefs.Preferences

java.util.prefs.AbstractPreferences

public abstract class AbstractPreferences extends 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's Preferences идентификатор пользователя наследуется от операционной системы и не меняется в течение всего срока службы виртуальной машины. Признаётся, что в реализациях Preferences на стороне сервера идентификатор пользователя может изменяться от запроса к запросу, неявно передаваясь в методы Preferences с помощью статического экземпляра ThreadLocal. Разработчикам таких реализаций настоятельно рекомендуется определять пользователя в момент доступа к настройкам (например, с помощью метода get(String,String) или put(String,String)) вместо постоянного связывания пользователя с каждым экземпляром Preferences. Последнее поведение противоречит нормальному использованию Preferences и приведёт к большой путанице.

Since:

1.4

See Also:

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

Модификатор и тип	Поле	Описание
`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)

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

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

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

put

public void put(String key, String value)

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

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

Specified by:: put в классе Preferences
Parameters:: key - ключ, с которым должно быть связано указанное значение.; value - значение, которое должно быть связано с указанным ключом.
Throws:: 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.

Specified by:: get в классе Preferences
Parameters:: key - ключ, связанное значение которого должно быть возвращено.; def - значение, которое должно быть возвращено в случае, если у этого узла настроек нет значения, связанного с key.
Returns:: значение, связанное с key, или def если со key не связано никакого значения.
Throws:: IllegalStateException - если этот узел (или предок) был удалён методом removeNode().; NullPointerException - если ключ является null. (Допускается null значение по умолчанию).; IllegalArgumentException - если ключ содержит нулевой управляющий символ, код U+0000.

remove

public void remove(String key)

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

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

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

clear

public void clear() throws BackingStoreException

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

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

Specified by:

clear в классе Preferences

Throws:

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

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

See Also:

putInt

public void putInt(String key, int value)

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

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

Specified by:

putInt в классе Preferences

Parameters:

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

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

Throws:

NullPointerException - если ключ является null.

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

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

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

See Also:

getInt

public int getInt(String key, int def)

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

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

Specified by:

getInt в классе Preferences

Parameters:

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

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

Returns:

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

Throws:

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

NullPointerException - если key является null.

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

See Also:

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) для результата.

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

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 - если длина ключа превышает 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[]).

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

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().

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

childrenNames

public String[] childrenNames() throws BackingStoreException

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

Эта реализация получает блокировку этого узла предпочтений, проверяет, что узел не удалён, создаёт набор, инициализированный именами дочерних элементов (детей в кэше детей узла), вызывает 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 на токены и рекурсивно обходит путь от этого узла до указанного узла, "потребляя" имя и слеш на каждом шаге обхода. На каждом шаге текущий узел блокируется, и кэш дочерних узлов проверяется на наличие указанного узла. Если его нет, проверяется, что длина имени не превышает MAX_NAME_LENGTH. Затем вызывается метод childSpi(String), и результат сохраняется в кэше дочерних узлов этого узла. Если созданный объект Preferences имеет значение true для поля newNode и существуют слушатели изменений узла, событие уведомления добавляется в очередь для обработки в потоке диспетчеризации событий.

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

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

Specified by:

node в классе Preferences

Parameters:

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

Returns:

указанный узел предпочтений.

Throws:

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

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

See Also:

nodeExists

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 не является пустой строкой ("").

removeNode

public void removeNode() throws BackingStoreException

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

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

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

Specified by:

removeNode в классе Preferences

Throws:

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

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

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

See Also:

name

public String name()

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

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

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

absolutePath

public String absolutePath()

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

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

Specified by:: absolutePath в классе Preferences
Returns:: абсолютный путь к узлу предпочтений.

isUserNode

public boolean isUserNode()

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

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

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

addPreferenceChangeListener

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

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

Specified by:

removePreferenceChangeListener в классе Preferences

Parameters:

pcl - Слушатель изменений предпочтений для удаления.

See Also:

addNodeChangeListener

public void addNodeChangeListener(NodeChangeListener ncl)

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

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

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

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

Specified by:

addNodeChangeListener в классе Preferences

Parameters:

ncl - Добавляемый NodeChangeListener.

See Also:

removeNodeChangeListener

public void removeNodeChangeListener(NodeChangeListener ncl)

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

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

Specified by:

removeNodeChangeListener в классе Preferences

Parameters:

ncl - Удаляемый NodeChangeListener.

See Also:

putSpi

protected abstract void putSpi(String key, String value)

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

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

Parameters:: key - ключ; value - значение

getSpi

protected abstract String getSpi(String key)

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

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

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

Parameters:: key - ключ
Returns:: значение, связанное с указанным ключом в этом узле настроек, или null, если для этого ключа нет ассоциации или ассоциация не может быть определена в данный момент.

removeSpi

protected abstract void removeSpi(String key)

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

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

Parameters:: key - ключ

removeNodeSpi

protected abstract void removeNodeSpi() throws BackingStoreException

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

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

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

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

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

keysSpi

protected abstract String[] keysSpi() throws BackingStoreException

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

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

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

Returns:: массив ключей, для которых существует связанное значение в этом узле настроек.
Throws:: BackingStoreException - если это действие не может быть завершено из-за сбоя в базовом хранилище или невозможности с ним взаимодействовать.

childrenNamesSpi

protected abstract String[] childrenNamesSpi() throws BackingStoreException

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

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

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

Returns:: массив, содержащий имена дочерних узлов этого узла настроек.
Throws:: BackingStoreException - если это действие не может быть завершено из-за сбоя в базовом хранилище или невозможности с ним взаимодействовать.

getChild

protected AbstractPreferences getChild(String nodeName) throws BackingStoreException

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

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

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

Parameters:: nodeName - имя дочернего узла для поиска.
Returns:: дочерний узел с указанным именем, если он существует, или null, если его нет.
Throws:: 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()

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

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

sync

public void sync() throws BackingStoreException

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

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

Указано в:

sync в классе Preferences

Исключения:

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

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, 2023, 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/21/docs/api/java.prefs/java/util/prefs/AbstractPreferences.html