Класс Preferences

java.lang.Object

java.util.prefs.Preferences

Прямые известные подклассы:: AbstractPreferences

public abstract class Preferences extends Object

Узел в иерархической коллекции данных настроек. Этот класс позволяет приложениям сохранять и получать пользовательские и системные настройки и данные конфигурации. Эти данные постоянно хранятся в хранилище, зависящем от реализации. Типичные реализации включают обычные файлы, реестры, специфичные для ОС, серверы каталогов и базы данных SQL. Пользователю этого класса не нужно беспокоиться о деталях хранилища.

Существуют два отдельных дерева узлов настроек: одно для пользовательских настроек, другое — для системных. У каждого пользователя есть отдельное дерево пользовательских настроек, а все пользователи одной системы совместно используют одно и то же дерево системных настроек. Точное определение понятий «пользователь» и «система» различается в зависимости от реализации. Типичная информация, хранящаяся в дереве пользовательских настроек, может включать выбор шрифта и цвета, а также предпочтительные расположение и размер окна для конкретного приложения. Типичная информация, хранящаяся в дереве системных настроек, может включать данные конфигурации установки приложения.

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

Имя корневого узла — пустая строка (""). У любого другого узла произвольное имя, задаваемое при его создании. Единственные ограничения на это имя: оно не может быть пустой строкой и не может содержать символ косой черты ('/').

Абсолютное имя пути корневого узла — "/". Абсолютные имена путей дочерних узлов корневого узла имеют вид "/" + <имя узла>. Абсолютные имена путей всех остальных узлов имеют вид <абсолютное имя пути родительского узла> + "/" + <имя узла>. Обратите внимание, что все абсолютные имена путей начинаются с символа косой черты.

Имя пути узла n относительно его предка a — это строка, которую необходимо добавить к абсолютному имени пути a, чтобы получить абсолютное имя пути n, удалив начальный символ косой черты (если он есть). Обратите внимание:

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

И наконец, обратите внимание:

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

Все методы, изменяющие данные настроек, могут выполняться асинхронно: они могут возвращать управление немедленно, а изменения будут записаны в постоянное хранилище с зависящей от реализации задержкой. Для принудительной синхронной записи изменений в хранилище можно использовать метод flush. Нормальное завершение работы виртуальной машины Java не приведёт к потере ожидающих записи изменений — при завершении не требуется явный вызов flush, чтобы гарантировать сохранение ожидающих изменений.

Для всех методов, считывающих настройки из объекта Preferences, вызывающий код должен указать значение по умолчанию. Это значение возвращается, если значение ранее не было задано или если хранилище недоступно. Это позволяет приложениям продолжать работу, хотя и с несколько ограниченной функциональностью, даже если хранилище станет недоступным. Семантика некоторых методов, например flush, не позволяет им работать при недоступности хранилища. Обычным приложениям не требуется вызывать такие методы; их можно определить по тому, что в их объявлении указано исключение BackingStoreException.

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

Этот класс содержит средства экспорта и импорта, позволяющие «экспортировать» настройки в документ XML и «импортировать» в систему обратно документы XML, представляющие настройки. Эти средства можно использовать для резервного копирования всего дерева настроек или его части и последующего восстановления из резервной копии.

Документ XML содержит следующее объявление DOCTYPE:

<!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">

Обратите внимание, что системный URI (http://java.sun.com/dtd/preferences.dtd) не используется при экспорте или импорте настроек; он служит лишь строкой для уникальной идентификации DTD, которая имеет вид:

   <?xml version="1.0" encoding="UTF-8"?>

   <!-- DTD for a Preferences tree. -->

   <!-- The preferences element is at the root of an XML document
        representing a Preferences tree. -->
   <!ELEMENT preferences (root)>

   <!-- The preferences element contains an optional version attribute,
         which specifies version of DTD. -->
   <!ATTLIST preferences EXTERNAL_XML_VERSION CDATA "0.0" >

   <!-- The root element has a map representing the root's preferences
        (if any), and one node for each child of the root (if any). -->
   <!ELEMENT root (map, node*) >

   <!-- Additionally, the root contains a type attribute, which
        specifies whether it's the system or user root. -->
   <!ATTLIST root
             type (system|user) #REQUIRED >

   <!-- Each node has a map representing its preferences (if any),
        and one node for each child (if any). -->
   <!ELEMENT node (map, node*) >

   <!-- Additionally, each node has a name attribute -->
   <!ATTLIST node
             name CDATA #REQUIRED >

   <!-- A map represents the preferences stored at a node (if any). -->
   <!ELEMENT map (entry*) >

   <!-- An entry represents a single preference, which is simply
         a key-value pair. -->
   <!ELEMENT entry EMPTY >
   <!ATTLIST entry
             key   CDATA #REQUIRED
             value CDATA #REQUIRED >

Каждая реализация Preferences должна иметь соответствующую реализацию PreferencesFactory. Каждая реализация Java(TM) SE должна предоставлять способ указать, какая реализация PreferencesFactory используется для создания корневых узлов настроек. Это позволяет администратору заменить реализацию настроек по умолчанию альтернативной реализацией.

Примечание по реализации:

Реализация PreferencesFactory находится следующим образом:

Если задано системное свойство java.util.prefs.PreferencesFactory, оно считается полным именем класса, реализующего интерфейс PreferencesFactory. Класс загружается и создаётся его экземпляр; если этот процесс завершается с ошибкой, выбрасывается исключение, не определённое спецификацией.
Если файл класса реализации PreferencesFactory установлен в JAR-файл, доступный для system class loader, и этот JAR-файл содержит файл конфигурации поставщика с именем java.util.prefs.PreferencesFactory в каталоге ресурсов META-INF/services, то используется первое указанное в этом файле имя класса. Если предоставлено несколько таких JAR-файлов, будет использован первый найденный. Класс загружается и создаётся его экземпляр; если этот процесс завершается с ошибкой, выбрасывается исключение, не определённое спецификацией.
Наконец, если не задано ни указанное выше системное свойство, ни файл JAR с расширением, загружается и создаётся экземпляр системной реализации PreferencesFactory по умолчанию для используемой платформы.

С версии:

1.4

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

Модификатор и тип	Поле	Описание
`static final int`	`MAX_KEY_LENGTH`	Максимальная длина строки, допустимой в качестве ключа (80 символов).
`static final int`	`MAX_NAME_LENGTH`	Максимальная длина имени узла (80 символов).
`static final int`	`MAX_VALUE_LENGTH`	Максимальная длина строки, допустимой в качестве значения (8192 символа).

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

Preferences()

Модификатор	Конструктор	Описание
`protected`	Единственный конструктор.

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

Модификатор и тип	Метод	Описание
`abstract String`	`absolutePath()`	Возвращает абсолютное имя пути этого узла настроек.
`abstract void`	`addNodeChangeListener(NodeChangeListener ncl)`	Регистрирует указанный прослушиватель для получения событий изменения узла для этого узла.
`abstract void`	`addPreferenceChangeListener(PreferenceChangeListener pcl)`	Регистрирует указанный прослушиватель для получения событий изменения настроек для этого узла настроек.
`abstract String[]`	`childrenNames()`	Возвращает имена дочерних узлов этого узла настроек относительно данного узла.
`abstract void`	`clear()`	Удаляет все настройки (связи ключ-значение) из этого узла настроек.
`abstract void`	`exportNode(OutputStream os)`	Записывает в указанный выходной поток документ XML, представляющий все настройки, содержащиеся в этом узле (но не в его потомках).
`abstract void`	`exportSubtree(OutputStream os)`	Создаёт документ XML, представляющий все настройки, содержащиеся в этом узле и всех его потомках.
`abstract void`	`flush()`	Принудительно сохраняет в постоянном хранилище все изменения содержимого этого узла настроек и его потомков.
`abstract String`	`get(String key, String def)`	Возвращает значение, связанное с указанным ключом в этом узле настроек.
`abstract boolean`	`getBoolean(String key, boolean def)`	Возвращает логическое значение, представленное строкой, связанной с указанным ключом в этом узле настроек.
`abstract byte[]`	`getByteArray(String key, byte[] def)`	Возвращает массив байтов, представленный строкой, связанной с указанным ключом в этом узле настроек.
`abstract double`	`getDouble(String key, double def)`	Возвращает значение типа double, представленное строкой, связанной с указанным ключом в этом узле настроек.
`abstract float`	`getFloat(String key, float def)`	Возвращает значение типа float, представленное строкой, связанной с указанным ключом в этом узле настроек.
`abstract int`	`getInt(String key, int def)`	Возвращает значение типа int, представленное строкой, связанной с указанным ключом в этом узле настроек.
`abstract long`	`getLong(String key, long def)`	Возвращает значение типа long, представленное строкой, связанной с указанным ключом в этом узле настроек.
`static void`	`importPreferences(InputStream is)`	Импортирует все настройки, представленные документом XML в указанном входном потоке.
`abstract boolean`	`isUserNode()`	Возвращает `true`, если этот узел настроек находится в дереве пользовательских настроек, и `false`, если он находится в дереве системных настроек.
`abstract String[]`	`keys()`	Возвращает все ключи, с которыми в этом узле настроек связано значение.
`abstract String`	`name()`	Возвращает имя этого узла настроек относительно его родительского узла.
`abstract Preferences`	`node(String pathName)`	Возвращает именованный узел настроек в том же дереве, что и этот узел, создавая его и всех его предков, если они ещё не существуют.
`abstract boolean`	`nodeExists(String pathName)`	Возвращает true, если именованный узел настроек существует в том же дереве, что и этот узел.
`abstract Preferences`	`parent()`	Возвращает родительский узел этого узла настроек или `null`, если этот узел является корневым.
`abstract void`	`put(String key, String value)`	Связывает указанное значение с указанным ключом в этом узле настроек.
`abstract void`	`putBoolean(String key, boolean value)`	Связывает строку, представляющую указанное логическое значение, с указанным ключом в этом узле настроек.
`abstract void`	`putByteArray(String key, byte[] value)`	Связывает строку, представляющую указанный массив байтов, с указанным ключом в этом узле настроек.
`abstract void`	`putDouble(String key, double value)`	Связывает строку, представляющую указанное значение типа double, с указанным ключом в этом узле настроек.
`abstract void`	`putFloat(String key, float value)`	Связывает строку, представляющую указанное значение типа float, с указанным ключом в этом узле настроек.
`abstract void`	`putInt(String key, int value)`	Связывает строку, представляющую указанное значение типа int, с указанным ключом в этом узле настроек.
`abstract void`	`putLong(String key, long value)`	Связывает строку, представляющую указанное значение типа long, с указанным ключом в этом узле настроек.
`abstract void`	`remove(String key)`	Удаляет значение, связанное с указанным ключом в этом узле настроек, если оно есть.
`abstract void`	`removeNode()`	Удаляет этот узел настроек и всех его потомков, делая недействительными все настройки, содержащиеся в удалённых узлах.
`abstract void`	`removeNodeChangeListener(NodeChangeListener ncl)`	Удаляет указанный `NodeChangeListener`, чтобы он больше не получал события изменения.
`abstract void`	`removePreferenceChangeListener(PreferenceChangeListener pcl)`	Удаляет указанный прослушиватель изменений настроек, чтобы он больше не получал события изменения настроек.
`abstract void`	`sync()`	Гарантирует, что при последующих чтениях из этого узла настроек и его потомков будут учитываться все изменения, зафиксированные в постоянном хранилище (из любой виртуальной машины) до вызова `sync`.
`static Preferences`	`systemNodeForPackage(Class<?> c)`	Возвращает узел из дерева системных настроек, связанный (по соглашению) с пакетом указанного класса.
`static Preferences`	`systemRoot()`	Возвращает корневой узел настроек системы.
`abstract String`	`toString()`	Возвращает строковое представление этого узла настроек, как если бы оно было вычислено выражением:`(this.isUserNode() ? "User" : "System") + " Preference Node: " + this.absolutePath()`.
`static Preferences`	`userNodeForPackage(Class<?> c)`	Возвращает узел из дерева настроек вызывающего пользователя, связанный (по соглашению) с пакетом указанного класса.
`static Preferences`	`userRoot()`	Возвращает корневой узел настроек вызывающего пользователя.

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

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

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

MAX_KEY_LENGTH

public static final int MAX_KEY_LENGTH

Максимальная длина строки, допустимой в качестве ключа (80 символов).

См. также:

MAX_VALUE_LENGTH

public static final int MAX_VALUE_LENGTH

Максимальная длина строки, допустимой в качестве значения (8192 символа).

См. также:

MAX_NAME_LENGTH

public static final int MAX_NAME_LENGTH

Максимальная длина имени узла (80 символов).

См. также:

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

Preferences

protected Preferences()

Единственный конструктор. (Вызывается конструкторами подклассов, обычно неявно.)

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

userNodeForPackage

public static Preferences userNodeForPackage(Class<?> c)

Возвращает узел настроек из дерева настроек вызывающего пользователя, связанный (согласно соглашению) с пакетом указанного класса. Соглашение таково: абсолютное имя пути узла представляет собой полное имя пакета, перед которым стоит косая черта ('/'), а каждая точка ('.') заменена косой чертой. Например, абсолютное имя пути узла, связанного с классом com.acme.widget.Foo, — /com/acme/widget.

Это соглашение не применяется к безымянному пакету, связанный с которым узел настроек — <unnamed>. Этот узел предназначен не для долгосрочного использования, а для удобства на ранних этапах разработки программ, которые еще не принадлежат пакету, а также для временных программ. Не следует хранить ценные данные в этом узле, поскольку он является общим для всех использующих его программ.

Класс Foo, которому требуется получить доступ к настройкам своего пакета, может получить узел настроек следующим образом:

   static Preferences prefs = Preferences.userNodeForPackage(Foo.class);

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

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

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

systemNodeForPackage

public static Preferences systemNodeForPackage(Class<?> c)

Возвращает узел настроек из системного дерева настроек, связанный (согласно соглашению) с пакетом указанного класса. Соглашение таково: абсолютное имя пути узла представляет собой полное имя пакета, перед которым стоит косая черта ('/'), а каждая точка ('.') заменена косой чертой. Например, абсолютное имя пути узла, связанного с классом com.acme.widget.Foo, — /com/acme/widget.

 static Preferences prefs = Preferences.systemNodeForPackage(Foo.class);

Параметры:: c — класс, для пакета которого требуется узел системных настроек.
Возвращает:: узел системных настроек, связанный с пакетом, членом которого является c.
Исключения:: NullPointerException — если c равно null.

userRoot

public static Preferences userRoot()

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

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

systemRoot

public static Preferences systemRoot()

Возвращает корневой узел системных настроек.

Возвращает:: корневой узел системных настроек.

put

public abstract void put(String key, String value)

Связывает указанное значение с указанным ключом в этом узле настроек.

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

get

public abstract String get(String key, String def)

Возвращает значение, связанное с указанным ключом в этом узле настроек. Если с ключом не связано никакое значение или хранилище данных недоступно, возвращает указанное значение по умолчанию.

Некоторые реализации могут хранить значения по умолчанию в своих хранилищах данных. Если с указанным ключом не связано никакое значение, но такое сохраненное значение по умолчанию существует, оно возвращается вместо указанного значения по умолчанию.

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

remove

public abstract void remove(String key)

Удаляет значение, если оно существует, связанное с указанным ключом в этом узле настроек.

Если эта реализация поддерживает сохраненные значения по умолчанию и для указанного параметра существует такое значение по умолчанию, этот вызов «проявит» сохраненное значение по умолчанию: оно будет возвращено при следующем вызове get.

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

clear

public abstract void clear() throws BackingStoreException

Удаляет все настройки (соответствия ключ-значение) в этом узле настроек. Этот вызов не влияет на потомков данного узла.

Если эта реализация поддерживает сохраненные значения по умолчанию и в этом узле иерархии настроек содержатся такие значения по умолчанию, этот вызов «проявит» их: они будут возвращаться при последующих вызовах get.

Исключения:

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

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

См. также:

putInt

public abstract void putInt(String key, int value)

Связывает с указанным ключом в этом узле настроек строку, представляющую указанное значение типа int. Связанная строка — это строка, которая была бы возвращена, если бы значение типа int было передано методу Integer.toString(int). Этот метод предназначен для использования совместно с getInt(String, int).

Параметры:

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

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

Исключения:

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

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

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

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

См. также:

getInt

public abstract int getInt(String key, int def)

Возвращает значение типа int, представленное строкой, связанной с указанным ключом в этом узле настроек. Строка преобразуется в целое число так же, как методом Integer.parseInt(String). Возвращает указанное значение по умолчанию, если с ключом не связано никакое значение, хранилище данных недоступно или если при передаче связанного значения методу Integer.parseInt(String) было бы выброшено исключение NumberFormatException. Этот метод предназначен для использования совместно с putInt(String, int).

Если реализация поддерживает сохраненные значения по умолчанию и такое значение существует, доступно и может быть преобразовано в int с помощью Integer.parseInt, это значение int возвращается вместо указанного значения по умолчанию.

Параметры:

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

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

Возвращает:

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

Исключения:

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

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

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

См. также:

putLong

public abstract void putLong(String key, long value)

Связывает с указанным ключом в этом узле настроек строку, представляющую указанное значение типа long. Связанная строка — это строка, которая была бы возвращена, если бы значение типа long было передано методу Long.toString(long). Этот метод предназначен для использования совместно с getLong(String, long).

Параметры:

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

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

Исключения:

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

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

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

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

См. также:

getLong

public abstract long getLong(String key, long def)

Возвращает значение типа long, представленное строкой, связанной с указанным ключом в этом узле настроек. Строка преобразуется в long так же, как методом Long.parseLong(String). Возвращает указанное значение по умолчанию, если с ключом не связано никакое значение, хранилище данных недоступно или если при передаче связанного значения методу Long.parseLong(String) было бы выброшено исключение NumberFormatException. Этот метод предназначен для использования совместно с putLong(String, long).

Если реализация поддерживает сохраненные значения по умолчанию и такое значение существует, доступно и может быть преобразовано в long с помощью Long.parseLong, это значение long возвращается вместо указанного значения по умолчанию.

Параметры:

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

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

Возвращает:

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

Исключения:

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

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

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

См. также:

putBoolean

public abstract void putBoolean(String key, boolean value)

Связывает с указанным ключом в этом узле настроек строку, представляющую указанное логическое значение. Связанная строка — "true", если значение равно true, и "false", если оно равно false. Этот метод предназначен для использования совместно с getBoolean(String, boolean).

Параметры:

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

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

Исключения:

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

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

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

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

См. также:

getBoolean

public abstract boolean getBoolean(String key, boolean def)

Возвращает логическое значение, представленное строкой, связанной с указанным ключом в этом узле настроек. Допустимы строки "true", представляющая true, и "false", представляющая false. Регистр не учитывается, поэтому, например, "TRUE" и "False" также являются допустимыми значениями. Этот метод предназначен для использования совместно с putBoolean(String, boolean).

Возвращает указанное значение по умолчанию, если с ключом не связано никакое значение, хранилище данных недоступно или связанное значение отличается от "true" и "false" без учета регистра.

Если реализация поддерживает сохраненные значения по умолчанию и такое значение существует и доступно, оно используется вместо указанного значения по умолчанию, если только сохраненное значение по умолчанию не отличается от "true" и "false" без учета регистра; в этом случае используется указанное значение по умолчанию.

Параметры:

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

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

Возвращает:

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

Исключения:

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

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

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

См. также:

putFloat

public abstract void putFloat(String key, float value)

Связывает с указанным ключом в этом узле настроек строку, представляющую указанное значение типа float. Связанная строка — это строка, которая была бы возвращена, если бы значение типа float было передано методу Float.toString(float). Этот метод предназначен для использования совместно с getFloat(String, float).

Параметры:

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

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

Исключения:

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

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

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

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

См. также:

getFloat

public abstract float getFloat(String key, float def)

Возвращает значение типа float, представленное строкой, связанной с указанным ключом в этом узле настроек. Строка преобразуется в целое число так же, как методом Float.parseFloat(String). Возвращает указанное значение по умолчанию, если с ключом не связано никакое значение, хранилище данных недоступно или если при передаче связанного значения методу Float.parseFloat(String) было бы выброшено исключение NumberFormatException. Этот метод предназначен для использования совместно с putFloat(String, float).

Если реализация поддерживает сохраненные значения по умолчанию и такое значение существует, доступно и может быть преобразовано в float с помощью Float.parseFloat, это значение float возвращается вместо указанного значения по умолчанию.

Параметры:

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

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

Возвращает:

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

Исключения:

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

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

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

См. также:

putDouble

public abstract void putDouble(String key, double value)

Связывает с указанным ключом в этом узле настроек строку, представляющую указанное значение типа double. Связанная строка — это строка, которая была бы возвращена, если бы значение типа double было передано методу Double.toString(double). Этот метод предназначен для использования совместно с getDouble(String, double).

Параметры:

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

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

Исключения:

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

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

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

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

См. также:

getDouble

public abstract double getDouble(String key, double def)

Возвращает значение типа double, представленное строкой, связанной с указанным ключом в этом узле настроек. Строка преобразуется в целое число так же, как методом Double.parseDouble(String). Возвращает указанное значение по умолчанию, если с ключом не связано никакое значение, хранилище данных недоступно или если при передаче связанного значения методу Double.parseDouble(String) было бы выброшено исключение NumberFormatException. Этот метод предназначен для использования совместно с putDouble(String, double).

Если реализация поддерживает сохраненные значения по умолчанию и такое значение существует, доступно и может быть преобразовано в double с помощью Double.parseDouble, это значение double возвращается вместо указанного значения по умолчанию.

Параметры:

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

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

Возвращает:

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

Исключения:

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

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

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

См. также:

putByteArray

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

Связывает строку, представляющую указанный массив байтов, с указанным ключом в этом узле настроек. Связанная строка представляет собой представление массива байтов в кодировке Base64, определённой в RFC 2045, разделе 6.8, с одним незначительным изменением: строка будет состоять исключительно из символов алфавита Base64; она не будет содержать символов новой строки. Обратите внимание, что максимальная длина массива байтов ограничена тремя четвертями от MAX_VALUE_LENGTH, чтобы длина строки в кодировке Base64 не превышала MAX_VALUE_LENGTH. Этот метод предназначен для использования совместно с getByteArray(String, byte[]).

Параметры:

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

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

Исключения:

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

IllegalArgumentException - если длина key превышает MAX_KEY_LENGTH или длина value превышает MAX_VALUE_LENGTH*3/4.

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

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

См. также:

getByteArray

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

Возвращает значение в виде массива байтов, представленное строкой, связанной с указанным ключом в этом узле настроек. Допустимые строки представляют собой двоичные данные в кодировке Base64, определённой в RFC 2045, разделе 6.8, с одним незначительным изменением: строка должна состоять исключительно из символов алфавита Base64; символы новой строки и посторонние символы не допускаются. Этот метод предназначен для использования совместно с putByteArray(String, byte[]).

Возвращает указанное значение по умолчанию, если с ключом не связано никакое значение, хранилище недоступно или связанное значение не является допустимым массивом байтов в кодировке Base64 (как описано выше).

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

Параметры:

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

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

Возвращает:

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

Исключения:

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

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

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

См. также:

keys

public abstract String[] keys() throws BackingStoreException

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

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

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

childrenNames

public abstract String[] childrenNames() throws BackingStoreException

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

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

parent

public abstract Preferences parent()

Возвращает родительский узел этого узла настроек или null, если это корневой узел.

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

node

public abstract Preferences node(String pathName)

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

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

Параметры:

pathName - имя пути узла настроек, который требуется вернуть.

Возвращает:

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

Исключения:

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

NullPointerException - если имя пути равно null.

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

См. также:

nodeExists

public abstract boolean nodeExists(String pathName) throws BackingStoreException

Возвращает true, если именованный узел настроек существует в том же дереве, что и этот узел. Относительные имена пути (не начинающиеся с символа косой черты ('/')) интерпретируются относительно этого узла настроек.

Если этот узел (или его предок) уже был удалён методом removeNode(), вызов этого метода разрешён, но только с именем пути ""; вызов вернёт false. Таким образом, идиому p.nodeExists("") можно использовать для проверки того, был ли удалён p.

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

removeNode

public abstract void removeNode() throws BackingStoreException

Удаляет этот узел настроек и всех его потомков, делая недействительными все настройки, содержащиеся в удалённых узлах. После удаления узла вызов любого метода, кроме name(), absolutePath(), isUserNode(), flush() или nodeExists(""), для соответствующего экземпляра Preferences завершится с ошибкой IllegalStateException. (Методы, определённые в Object, по-прежнему можно вызывать для узла после его удаления; они не вызовут IllegalStateException.)

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

Если эта реализация поддерживает сохранённые значения по умолчанию, удаление узла открывает доступ ко всем сохранённым значениям по умолчанию в этом узле и ниже него. Поэтому последующий вызов nodeExists для имени пути этого узла может вернуть true, а последующий вызов node для этого имени пути может вернуть (другой) экземпляр Preferences, представляющий непустую коллекцию настроек и/или дочерних узлов.

Исключения:

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

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

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

См. также:

name

public abstract String name()

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

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

absolutePath

public abstract String absolutePath()

Возвращает абсолютное имя пути этого узла настроек.

Возвращает:: абсолютное имя пути этого узла настроек.

isUserNode

public abstract boolean isUserNode()

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

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

toString

public abstract String toString()

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

(this.isUserNode() ? "User" :
"System") + " Preference Node: " + this.absolutePath()

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

flush

public abstract void flush() throws BackingStoreException

Принудительно записывает все изменения содержимого этого узла настроек и его потомков в постоянное хранилище. После успешного возврата этого метода можно считать, что все изменения, внесённые в поддерево с корнем в этом узле до вызова метода, стали постоянными.

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

При вызове flush для вновь созданного узла он становится постоянным, как и все его предки (и потомки), которые ещё не стали постоянными. Однако изменения значений настроек в предках не гарантированно становятся постоянными.

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

Исключения:

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

См. также:

sync

public abstract void sync() throws BackingStoreException

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

Исключения:

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

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

См. также:

addPreferenceChangeListener

public abstract void addPreferenceChangeListener(PreferenceChangeListener pcl)

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

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

Параметры:

pcl - обработчик изменения настроек, который требуется добавить.

Исключения:

NullPointerException - если pcl равен null.

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

См. также:

removePreferenceChangeListener

public abstract void removePreferenceChangeListener(PreferenceChangeListener pcl)

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

Параметры:

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

Исключения:

IllegalArgumentException - если pcl не был зарегистрирован в качестве обработчика изменения настроек этого узла.

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

См. также:

addNodeChangeListener

public abstract void addNodeChangeListener(NodeChangeListener ncl)

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

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

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

Параметры:

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

Исключения:

NullPointerException - если ncl равен null.

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

См. также:

removeNodeChangeListener

public abstract void removeNodeChangeListener(NodeChangeListener ncl)

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

Параметры:

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

Исключения:

IllegalArgumentException - если ncl не был зарегистрирован в качестве NodeChangeListener этого узла.

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

См. также:

exportNode

public abstract void exportNode(OutputStream os) throws IOException, BackingStoreException

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

XML-документ будет содержать следующее объявление DOCTYPE:

<!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">

Будет использоваться кодировка символов UTF-8.

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

Параметры:

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

Исключения:

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

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

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

См. также:

exportSubtree

public abstract void exportSubtree(OutputStream os) throws IOException, BackingStoreException

Выводит XML-документ, представляющий все настройки, содержащиеся в этом узле и всех его потомках. Этот XML-документ фактически представляет собой автономную резервную копию поддерева с корнем в данном узле.

XML-документ будет содержать следующее объявление DOCTYPE:

<!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">

Будет использоваться кодировка символов UTF-8.

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

Параметры:

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

Исключения:

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

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

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

См. также:

importPreferences

public static void importPreferences(InputStream is) throws IOException, InvalidPreferencesFormatException

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

XML-документ должен содержать следующее объявление DOCTYPE:

<!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">

(Этот метод предназначен для использования совместно с exportNode(OutputStream) и exportSubtree(OutputStream).

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

Параметры:: is - поток ввода, из которого считывается XML-документ.
Исключения:: IOException - если чтение из указанного потока ввода приводит к IOException.; InvalidPreferencesFormatException - данные во входном потоке не образуют допустимый XML-документ с обязательным типом документа.

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/25/docs/api/java.prefs/java/util/prefs/Preferences.html