Класс 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()`	Гарантирует, что при последующих чтениях из этого узла настроек и его потомков будут учитываться все изменения, зафиксированные в постоянном хранилище (из любой VM) до вызова `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

Модификатор и тип	Метод	Описание
`protected Object`	`clone()`	Создает и возвращает копию этого объекта.
`boolean`	`equals(Object obj)`	Указывает, равен ли этот объект некоторому другому объекту.
`protected void`	`finalize()`	Устарело, планируется удаление: этот элемент API может быть удален в будущей версии. Финализация устарела и может быть удалена в одном из следующих выпусков.
`final Class<?>`	`getClass()`	Возвращает класс времени выполнения этого `Object`.
`int`	`hashCode()`	Возвращает хеш-код этого объекта.
`final void`	`notify()`	Пробуждает один поток, ожидающий на мониторе этого объекта.
`final void`	`notifyAll()`	Пробуждает все потоки, ожидающие на мониторе этого объекта.
`final void`	`wait()`	Заставляет текущий поток ожидать пробуждения, обычно в результате вызова notify или прерывания.
`final void`	`wait(long timeoutMillis)`	Заставляет текущий поток ожидать пробуждения, обычно в результате вызова notify или прерывания, либо истечения заданного промежутка реального времени.
`final void`	`wait(long timeoutMillis, int nanos)`	Заставляет текущий поток ожидать пробуждения, обычно в результате вызова notify или прерывания, либо истечения заданного промежутка реального времени.

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

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 — если ключ или значение содержит нулевой управляющий символ с кодовой точкой 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 — если ключ содержит нулевой управляющий символ с кодовой точкой U+0000.

remove

public abstract void remove(String key)

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

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

Параметры:: key — ключ, сопоставление с которым требуется удалить из узла настроек.
Исключения:: NullPointerException — если key имеет значение null.; IllegalStateException — если этот узел (или его предок) был удален методом removeNode().; IllegalArgumentException — если ключ содержит нулевой управляющий символ с кодовой точкой 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 — если ключ содержит нулевой управляющий символ с кодовой точкой 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 — если ключ содержит нулевой управляющий символ с кодовой точкой 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 — если ключ содержит нулевой управляющий символ с кодовой точкой 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 — если ключ содержит нулевой управляющий символ с кодовой точкой 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 — если ключ содержит нулевой управляющий символ с кодовой точкой 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 — ключ, значение которого требуется вернуть как boolean.

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

Возвращает:

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

Исключения:

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

NullPointerException — если key имеет значение null.

IllegalArgumentException — если ключ содержит нулевой управляющий символ с кодовой точкой 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 — если ключ содержит нулевой управляющий символ с кодовой точкой 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 — если ключ содержит нулевой управляющий символ с кодовой точкой 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 — если ключ содержит нулевой управляющий символ с кодовой точкой 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 — если ключ содержит нулевой управляющий символ с кодовой точкой 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

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

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

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

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

Исключения:

См. также:

sync

public abstract void sync() throws BackingStoreException

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

Исключения:

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.