Класс 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 int`	`MAX_KEY_LENGTH`	Максимальная длина строки, разрешенной в качестве ключа (80 символов).
`static int`	`MAX_NAME_LENGTH`	Максимальная длина имени узла (80 символов).
`static int`	`MAX_VALUE_LENGTH`	Максимальная длина строки, разрешенной в качестве значения (8192 символов).

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

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

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

Класс Preferences

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

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

Методы

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

Поля

MAX_KEY_LENGTH

MAX_VALUE_LENGTH

MAX_NAME_LENGTH

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

Preferences

Методы

userNodeForPackage

systemNodeForPackage

userRoot

systemRoot

put

get

remove

clear

putInt

getInt

putLong

getLong

putBoolean

getBoolean

putFloat

getFloat

putDouble

getDouble

putByteArray

getByteArray

keys

childrenNames

parent

node

nodeExists

removeNode

name

absolutePath

isUserNode

toString

flush

sync

addPreferenceChangeListener

removePreferenceChangeListener

addNodeChangeListener

removeNodeChangeListener

exportNode

exportSubtree

importPreferences