Класс 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()`	Возвращает корневой узел предпочтений для вызывающего пользователя.

Методы, объявленные в классе java.lang.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 — если ключ или значение содержат нулевой управляющий символ, код 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)

Связывает строку, представляющую заданное целое значение, с заданным ключом в этом узле настроек. Связанная строка — это та, которая была бы возвращена, если бы целое значение было передано в Integer.toString(int). Этот метод предназначен для совместного использования с getInt(java.lang.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)

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

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

Параметры:

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

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

Возвращает:

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

Исключения:

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

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

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

См. также:

putLong

public abstract void putLong(String key, long value)

Связывает строку, представляющую заданное значение типа long, с заданным ключом в этом узле настроек. Связанная строка — это та, которая была бы возвращена, если бы значение типа long было передано в Long.toString(long). Этот метод предназначен для совместного использования с getLong(java.lang.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(java.lang.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(java.lang.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(java.lang.String, boolean).

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

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

Параметры:

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

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

Возвращает:

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

Исключения:

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

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

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

См. также:

putFloat

public abstract void putFloat(String key, float value)

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

Parameters:

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

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

Throws:

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

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

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

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

See Also:

getFloat

public abstract float getFloat(String key, float def)

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

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

Parameters:

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

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

Returns:

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

Throws:

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

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

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

See Also:

putDouble

public abstract void putDouble(String key, double value)

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

Parameters:

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

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

Throws:

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

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

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

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

See Also:

getDouble

public abstract double getDouble(String key, double def)

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

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

Parameters:

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

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

Returns:

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

Throws:

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

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

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

See Also:

putByteArray

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

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

Parameters:

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

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

Throws:

NullPointerException — если ключ или значение равно null.

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

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

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

See Also:

END_OF_DOCUMENT_MARKER

getByteArray

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

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

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

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

Parameters:

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

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

Returns:

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

Throws:

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

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

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

See Also:

keys

public abstract String[] keys() throws BackingStoreException

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

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

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

childrenNames

public abstract String[] childrenNames() throws BackingStoreException

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

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

parent

public abstract Preferences parent()

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

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

node

public abstract Preferences node(String pathName)

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

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

Parameters:

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

Returns:

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

Throws:

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

NullPointerException - если имя пути null.

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

See Also:

nodeExists

public abstract boolean nodeExists(String pathName) throws BackingStoreException

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

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

Parameters:: pathName - имя пути узла, существование которого нужно проверить.
Returns:: true, если указанный узел существует.
Throws:: 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, представляющий непустой набор настроек и/или дочерних узлов.

Throws:

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

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

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

See Also:

name

public abstract String name()

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

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

absolutePath

public abstract String absolutePath()

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

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

isUserNode

public abstract boolean isUserNode()

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

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

toString

public abstract String toString()

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

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

Overrides:: toString в классе Object
Returns:: строковое представление объекта

flush

public abstract void flush() throws BackingStoreException

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

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

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

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

Исключение:

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

См. также:

sync

public abstract void sync() throws BackingStoreException

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

Исключение:

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

См. также:

addPreferenceChangeListener

public abstract void addPreferenceChangeListener(PreferenceChangeListener pcl)

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

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

Параметры:

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() приводит к нескольким событиям изменения узла, по одному для каждого узла в поддереве, укоренённом в удалённом узле.)

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

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

Параметры:

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