Класс 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

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

Modifier and Type	Field	Description
`static final int`	`MAX_KEY_LENGTH`	Максимальная длина строки, разрешенной в качестве ключа (80 символов).
`static final int`	`MAX_NAME_LENGTH`	Максимальная длина имени узла (80 символов).
`static final int`	`MAX_VALUE_LENGTH`	Максимальная длина строки, разрешенной в качестве значения (8192 символа).

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

Preferences()

Modifier	Constructor	Description
`protected`	Единственный конструктор.

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

Modifier and Type	Method	Description
`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)`	Возвращает двойное значение, представленное строкой, связанной с указанным ключом в данном узле настроек.
`abstract float`	`getFloat(String key, float def)`	Возвращает значение с плавающей точкой, представленное строкой, связанной с указанным ключом в данном узле настроек.
`abstract int`	`getInt(String key, int def)`	Возвращает целочисленное значение, представленное строкой, связанной с указанным ключом в данном узле настроек.
`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)`	Связывает строку, представляющую указанное двойное значение, с указанным ключом в данном узле настроек.
`abstract void`	`putFloat(String key, float value)`	Связывает строку, представляющую указанное значение с плавающей точкой, с указанным ключом в данном узле настроек.
`abstract void`	`putInt(String key, int value)`	Связывает строку, представляющую указанное целочисленное значение, с указанным ключом в данном узле настроек.
`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.

SecurityException — если менеджер безопасности присутствует и отказывается от RuntimePermission("preferences").

См. также:

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.

SecurityException — если менеджер безопасности присутствует и отказывается от RuntimePermission("preferences").

См. также:

userRoot

public static Preferences userRoot()

Возвращает корневой узел предпочтений для текущего пользователя.

Возвращает:

корневой узел предпочтений для текущего пользователя.

Исключения:

SecurityException — Если менеджер безопасности присутствует и отказывается от RuntimePermission("preferences").

См. также:

systemRoot

public static Preferences systemRoot()

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

Возвращает:

корневой узел предпочтений для системы.

Исключения:

SecurityException — Если менеджер безопасности присутствует и отказывается от RuntimePermission("preferences").

См. также:

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, если ни с чем не связано, или хранилище недоступно.
Исключения:: 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.

очистить

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", представляющая истину, и "false", представляющая ложь. Регистр игнорируется, поэтому, например, "TRUE" и "False" также допустимы. Данный метод предназначен для использования совместно с putBoolean(java.lang.String, boolean).

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

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

Parameters:

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

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

Returns:

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

Throws:

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

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

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

See Also:

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 как в Double.parseDouble(String). Возвращает указанное значение по умолчанию, если нет значения, связанного с ключом, хранилище недоступно или Double.parseDouble(String) выбросит исключение NumberFormatException, если связанное значение было передано. Данный метод предназначен для использования совместно с putDouble(java.lang.String, double).

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

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:

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() вызывается для этого узла, но не для других.

Throws:

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

See Also:

sync

public abstract void sync() throws BackingStoreException

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

Throws:

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

See Also:

addPreferenceChangeListener

public abstract void addPreferenceChangeListener(PreferenceChangeListener pcl)

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

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

Parameters:

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

Throws:

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

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

See Also:

removePreferenceChangeListener

public abstract void removePreferenceChangeListener(PreferenceChangeListener pcl)

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

Parameters:

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

Throws:

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

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

See Also:

addNodeChangeListener

public abstract void addNodeChangeListener(NodeChangeListener ncl)

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

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

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

Parameters:

ncl - Слушатель NodeChangeListener для добавления.

Throws:

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

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

See Also:

removeNodeChangeListener

public abstract void removeNodeChangeListener(NodeChangeListener ncl)

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

Parameters:

ncl - Слушатель NodeChangeListener для удаления.

Throws:

IllegalArgumentException - если ncl не был зарегистрированным слушателем NodeChangeListener для этого узла.

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

See Also:

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.

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

Parameters:

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

Throws:

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

BackingStoreException - если данные предпочтений не могут быть прочитаны из базового хранилища.

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

See Also:

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.

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

Parameters:

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

Throws:

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

BackingStoreException - если данные предпочтений не могут быть прочитаны из базового хранилища.

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

See Also:

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

Parameters:

is - поток ввода, из которого необходимо прочитать XML-документ.

Throws:

IOException - если чтение из указанного потока ввода приводит к IOException.

InvalidPreferencesFormatException - Данные в потоке ввода не составляют допустимый XML-документ с требуемым типом документа.

SecurityException - Если присутствует менеджер безопасности, и он отклоняет RuntimePermission("preferences").

See Also:

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