Класс 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 должны вернуть false, так как возвращение true означало бы, что все предыдущие операции успешно стали постоянными.

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

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

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

Since:: 1.4
See Also:: Preferences

Поля

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

Поля, унаследованные от класса java.util.prefs.Preferences

MAX_KEY_LENGTH, MAX_NAME_LENGTH, MAX_VALUE_LENGTH

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

Модификатор	Конструктор и описание
`protected`	`AbstractPreferences(AbstractPreferences parent, String name)` Создаёт узел настроек с указанным родителем и указанным именем относительно родителя.

Методы

Модификатор и тип	Метод и описание
`String`	`absolutePath()` Реализует метод `absolutePath` в соответствии со спецификацией в `Preferences.absolutePath()`.
`void`	`addNodeChangeListener(NodeChangeListener ncl)` Регистрирует указанный слушатель для получения событий изменения узла для данного узла.
`void`	`addPreferenceChangeListener(PreferenceChangeListener pcl)` Регистрирует указанный слушатель для получения событий изменения настроек для данного узла настроек.
`protected 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.; 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 допускается.)

remove

public void remove(String key)

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

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

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

clear

public void clear()
           throws BackingStoreException

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

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

Определено в:: clear в классе Preferences
Исключения:: BackingStoreException - если эту операцию невозможно завершить из-за сбоя в базовом хранилище или невозможности связи с ним.; IllegalStateException - если этот узел (или его предок) был удален с помощью метода removeNode().
См. также:: Preferences.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.; IllegalStateException - если этот узел (или его предок) был удален с помощью метода removeNode().
См. также:: Preferences.getInt(String,int)

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.
Возвращает:: целочисленное значение, представленное строкой, связанной с key в этом узле предпочтений, или def, если связанное значение не существует или не может быть интерпретировано как int.
Исключения:: IllegalStateException - если этот узел (или его предок) был удален с помощью метода removeNode().; NullPointerException - если key является null.
См. также:: Preferences.putInt(String,int), Preferences.get(String,String)

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.; IllegalStateException - если этот узел (или его предок) был удален с помощью метода removeNode().
См. также:: Preferences.getLong(String,long)

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.
См. также:: Preferences.putLong(String,long), Preferences.get(String,String)

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.; IllegalStateException - если этот узел (или предковый) был удален методом removeNode().
См. также:: Preferences.getBoolean(String,boolean), Preferences.get(String,String)

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.
См. также:: Preferences.get(String,String), Preferences.putBoolean(String,boolean)

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.; IllegalStateException - если этот узел (или предковый) был удален методом removeNode().
См. также:: Preferences.getFloat(String,float)

getFloat

public float getFloat(String key,
                      float def)

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

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

Определено в:: getFloat в классе Preferences
Параметры:: key - ключ, значение которого должно быть возвращено как float.; def - значение, которое должно быть возвращено в случае, если этот узел настроек не имеет значения, связанного с key, или связанное значение не может быть интерпретировано как float.
Возвращает:: значение float, представленное строкой, связанной с key в этом узле настроек, или def если связанного значения не существует или оно не может быть интерпретировано как float.
Исключение:: IllegalStateException - если этот узел (или предковый) был удален методом removeNode().; NullPointerException - если key равно null.
См. также:: Preferences.putFloat(String,float), Preferences.get(String,String)

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.; IllegalStateException - если этот узел (или предковый) был удален методом removeNode().
См. также:: Preferences.getDouble(String,double)

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.
См. также:: Preferences.putDouble(String,double), Preferences.get(String,String)

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.; IllegalStateException - если этот узел (или предковый) был удален с помощью метода removeNode().
См. также:: Preferences.getByteArray(String,byte[]), Preferences.get(String,String)

getByteArray

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

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

Указано:: getByteArray в классе Preferences
Параметры:: key - ключ, связанное значение которого должно быть возвращено в виде массива байтов.; def - значение, которое должно быть возвращено в случае, если у этого узла предпочтений нет значения, связанного с key, или связанное значение не может быть интерпретировано как массив байтов.
Возвращает:: массив байтов, представленный строкой, связанной с key в этом узле предпочтений, или def, если связанное значение не существует или не может быть интерпретировано как массив байтов.
Выбрасывает:: IllegalStateException - если этот узел (или предковый) был удален с помощью метода removeNode().; NullPointerException - если key является null. (Значение типа null для def разрешено.)
См. также:: Preferences.get(String,String), Preferences.putByteArray(String,byte[])

keys

public String[] keys()
              throws BackingStoreException

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

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

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

childrenNames

public String[] childrenNames()
                       throws BackingStoreException

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

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

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

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

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

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

Указано:: node в классе Preferences
Параметры:: path - имя пути узла предпочтений, который нужно вернуть.
Возвращает:: указанный узел предпочтений.
Выбрасывает:: IllegalArgumentException - если имя пути некорректно (то есть содержит несколько последовательных слешей или заканчивается слешем и имеет более одного символа).; IllegalStateException - если этот узел (или предковый) был удалён с помощью метода removeNode().
См. также:: Preferences.flush()

nodeExists

public boolean nodeExists(String path)
                   throws BackingStoreException

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

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

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

removeNode

public void removeNode()
                throws BackingStoreException

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

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

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

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

name

public String name()

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

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

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

absolutePath

public String absolutePath()

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

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

Указано:: absolutePath в классе Preferences
Возвращает:: абсолютное имя пути узла предпочтений.

isUserNode

public boolean isUserNode()

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

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

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

addPreferenceChangeListener

public void addPreferenceChangeListener(PreferenceChangeListener pcl)

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

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

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

Указано:: addPreferenceChangeListener в классе Preferences
Параметры:: pcl - слушатель изменения предпочтения для добавления.
См. также:: Preferences.removePreferenceChangeListener(PreferenceChangeListener), Preferences.addNodeChangeListener(NodeChangeListener)

removePreferenceChangeListener

public void removePreferenceChangeListener(PreferenceChangeListener pcl)

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

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

Указано:: removePreferenceChangeListener в классе Preferences
Параметры:: pcl - слушатель изменения предпочтения для удаления.
См. также:: Preferences.addPreferenceChangeListener(PreferenceChangeListener)

addNodeChangeListener

public void addNodeChangeListener(NodeChangeListener ncl)

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

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

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

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

Указано:: addNodeChangeListener в классе Preferences
Параметры:: ncl - NodeChangeListener для добавления.
См. также:: Preferences.removeNodeChangeListener(NodeChangeListener), Preferences.addPreferenceChangeListener(PreferenceChangeListener)

removeNodeChangeListener

public void removeNodeChangeListener(NodeChangeListener ncl)

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

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

Указано:: removeNodeChangeListener в классе Preferences
Параметры:: ncl - NodeChangeListener для удаления.
См. также:: Preferences.addNodeChangeListener(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 не вызывается на этом узле или одном из его предков (или потомков).

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

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

toString

public String toString()

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

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

sync

public void sync()
          throws BackingStoreException

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

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

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

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
Исключения:: BackingStoreException - если эта операция не может быть завершена из-за сбоя в базовом хранилище или невозможности с ним связаться.
См. также:: flush()

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 - если данные настроек не могут быть прочитаны из хранилища.
См. также:: Preferences.importPreferences(InputStream)

exportSubtree

public void exportSubtree(OutputStream os)
                   throws IOException,
                          BackingStoreException

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

Определено в:: exportSubtree в классе Preferences
Параметры:: os - поток вывода, в который выводится XML-документ.
Исключения:: IOException - если запись в указанный поток вывода приводит к IOException.; BackingStoreException - если данные настроек не могут быть прочитаны из хранилища.
См. также:: Preferences.importPreferences(InputStream), Preferences.exportNode(OutputStream)

© 1993, 2020, 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.