Spec-Zone .ru
спецификации, руководства, описания, API
|
public abstract class Preferences extends Object
Есть два отдельных дерева привилегированных узлов, один для пользовательских настроек и один для установок системы. У каждого пользователя есть отдельное дерево пользовательской настройки, и все пользователи в данной системе совместно используют то же самое системное привилегированное дерево. Точное описание "пользователя" и "системы" изменится от реализации до реализации. Типичная информация, хранившая в дереве пользовательской настройки, могла бы включать выбор шрифта, цветной выбор, или предпочла расположение окна и размер для определенного приложения. Типичная информация, хранившая в системном привилегированном дереве, могла бы включать данные конфигурации установки для приложения.
Узлы в привилегированном дереве называют подобным способом к каталогам в иерархической файловой системе. У каждого узла в привилегированном дереве есть имя узла (который не обязательно уникален), уникальный абсолютный путь, и путь относительно каждого предка включая себя.
У корневого узла есть имя узла пустой строки (""). У любого узла есть произвольное имя узла, определенное в то время, когда он создается. Единственные ограничения на это имя - то, что это не может быть пустая строка, и это не может содержать символ наклонной черты (' / ').
У корневого узла есть абсолютный путь "/". У дочерних элементов корневого узла есть абсолютные пути "/" + <имя узла>. У всех других узлов есть абсолютные пути <абсолютный путь родителя> + "/" + <имя узла>. Отметьте, что все абсолютные пути начинаются с символа наклонной черты.
Путь n's узла относительно его предка просто строка, которая должна быть добавлена к абсолютному пути a, чтобы сформировать абсолютный путь n с начальным символом наклонной черты, (если есть) удаленным. Отметьте что:
Отметьте наконец что:
Всем методам, которые изменяют привилегированные данные, разрешают работать асинхронно; они могут сразу возвратиться, и изменения в конечном счете распространят к персистентному запоминающему устройству с зависящей от реализации задержкой. Метод flush может использоваться, чтобы синхронно вызвать обновления к запоминающему устройству. Нормальное завершение виртуальной машины Java не будет приводить к потере обновлений на ожидании - явный вызов flush не требуется после завершения гарантировать, что обновления на ожидании делаются персистентными.
Все методы, которые читают предпочтение из объекта Preferences, требуют, чтобы invoker обеспечил значение по умолчанию. Значение по умолчанию возвращается, если никакое значение не было ранее установлено или если запоминающее устройство недоступно. Намерение состоит в том, чтобы позволить приложениям работать, хотя с немного ухудшенной функциональностью, даже если запоминающее устройство становится недоступным. У нескольких методов, как flush, есть семантика, которые препятствуют тому, чтобы они работали, если запоминающее устройство недоступно. У обычных приложений не должно быть никакой потребности вызвать любой из этих методов, которые могут быть идентифицированы фактом, что они, как объявляют, бросают BackingStoreException
.
Методы в этом class могут быть вызваны одновременно многократными потоками в единственной JVM без потребности во внешней синхронизации, и результаты будут эквивалентны некоторому последовательному выполнению. Если этот class будет использоваться одновременно многократными JVM, которые хранят их привилегированные данные в том же самом запоминающем устройстве, то хранилище данных не будет повреждено, но никакие другие гарантии не делаются относительно непротиворечивости привилегированных данных.
Этот class содержит средство экспорта/импорта, позволяя предпочтение быть "экспортированным" в 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 (ТМ), реализация SE должна обеспечить некоторые средства определения, какая реализация PreferencesFactory используется, чтобы генерировать корневые привилегированные узлы. Это позволяет администратору заменять привилегированную реализацию значения по умолчанию альтернативной реализацией. Примечание реализации: В JRE Sun реализация PreferencesFactory располагается следующим образом:
Если системное свойство java.util.prefs.PreferencesFactory определяется, то оно берется, чтобы быть полностью определенным именем class, реализовывая интерфейс PreferencesFactory. class загружается и инстанцируется; если этот процесс перестал работать тогда, неустановленная ошибка бросается.
Если реализация PreferencesFactory, файл class был установлен в файле фляги, который видим к system class loader
, и тот файл фляги содержит конфигурационный файл провайдера под названием java.util.prefs.PreferencesFactory в каталоге META-INF/services ресурса, тогда первое имя class, определенное в том файле, берется. Если больше чем один такой файл фляги будет обеспечен, то первый найденный будет использоваться. class загружается и инстанцируется; если этот процесс перестал работать тогда, неустановленная ошибка бросается.
Наконец, если ни вышеупомянутое системное свойство, ни файл фляги расширения не обеспечиваются, то значение по умолчанию в масштабе всей системы реализация PreferencesFactory для базовой платформы загружается и инстанцируется.
Модификатор и Тип | Поле и Описание |
---|---|
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)
Возвращает двойное значение, представленное строкой, связанной с указанным ключом в этом привилегированном узле.
|
abstract float |
getFloat(String key, float def)
Возвращает значение плавающее, представленное строкой, связанной с указанным ключом в этом привилегированном узле.
|
abstract int |
getInt(String key, int def)
Возвращает международное значение, представленное строкой, связанной с указанным ключом в этом привилегированном узле.
|
abstract long |
getLong(String key, long def)
Возвращает длинное значение, представленное строкой, связанной с указанным ключом в этом привилегированном узле.
|
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)
Связывает строку, представляющую указанное длинное значение с указанным ключом в этом привилегированном узле.
|
abstract void |
remove(String key)
Удаляет значение, связанное с указанным ключом в этом привилегированном узле, если любой.
|
abstract void |
removeNode()
Удаляет этот привилегированный узел и всех его потомков, лишая законной силы любое предпочтение, содержавшееся в удаленных узлах.
|
abstract void |
removeNodeChangeListener(NodeChangeListener ncl)
Удаляет указанный NodeChangeListener, таким образом, он больше не получает события изменения.
|
abstract void |
removePreferenceChangeListener(PreferenceChangeListener pcl)
Удаляет указанного привилегированного слушателя изменения, таким образом, это больше не получает привилегированные события изменения.
|
abstract void |
sync()
Гарантирует, что будущие чтения от этого привилегированного узла и его потомков отражают любые изменения, которые посвящали себя персистентному хранилищу (от любого VM) до вызова sync.
|
static Preferences |
systemNodeForPackage(Class<?> c)
Возвращает привилегированный узел из системного привилегированного дерева, которое связывается (условно) с пакетом указанного class.
|
static Preferences |
systemRoot()
Возвращает корневой привилегированный узел для системы.
|
abstract String |
toString()
Возвращает строковое представление этого привилегированного узла, как будто вычисленный expression:(this.isUserNode() ? "User" : "System") + " Preference Node: " + this.absolutePath().
|
static Preferences |
userNodeForPackage(Class<?> c)
Возвращает привилегированный узел из пользовательского привилегированного дерева вызова, которое связывается (условно) с пакетом указанного class.
|
static Preferences |
userRoot()
Возвращает корневой привилегированный узел для пользователя вызова.
|
public static final int MAX_KEY_LENGTH
public static final int MAX_VALUE_LENGTH
public static final int MAX_NAME_LENGTH
protected Preferences()
public static Preferences userNodeForPackage(Class<?> c)
Это соглашение не применяется к неназванному пакету, связанным привилегированным узлом которого является <unnamed>. Этот узел не предназначается для долгосрочного использования, но для удобства в ранней разработке программ, которые еще не принадлежат пакету, и для "холостых" программ. Ценные данные не должны храниться в этом узле, поскольку это совместно используется всеми программами, которые используют это.
class Foo, желающий получить доступ к предпочтению, имеющему отношение к его пакету, может получить привилегированный узел следующим образом:
static Preferences prefs = Preferences.userNodeForPackage(Foo.class);Эта идиома устраняет потребность в использовании строки, чтобы описать привилегированный узел и уменьшает вероятность отказа времени выполнения. (Если имя class будет написано c орфографическими ошибками, то оно будет обычно приводить к ошибке времени компиляции.)
Вызов этого метода приведет к созданию возвращенного узла и его предков, если они не будут уже существовать. Если возвращенный узел не существовал до этого вызова, этот узел и любые предки, которые создавались этим вызовом, как гарантируют, не станут постоянными, пока метод flush не вызовут на возвращенном узле (или один из его предков или потомков).
c
- class, для пакета которого требуется узел пользовательской настройки.NullPointerException
- если c является null.SecurityException
- если менеджер безопасности присутствует, и он отрицает RuntimePermission("preferences").RuntimePermission
public static Preferences systemNodeForPackage(Class<?> c)
Это соглашение не применяется к неназванному пакету, связанным привилегированным узлом которого является <unnamed>. Этот узел не предназначается для долгосрочного использования, но для удобства в ранней разработке программ, которые еще не принадлежат пакету, и для "холостых" программ. Ценные данные не должны храниться в этом узле, поскольку это совместно используется всеми программами, которые используют это.
class Foo, желающий получить доступ к предпочтению, имеющему отношение к его пакету, может получить привилегированный узел следующим образом:
static Preferences prefs = Preferences.systemNodeForPackage(Foo.class);Эта идиома устраняет потребность в использовании строки, чтобы описать привилегированный узел и уменьшает вероятность отказа времени выполнения. (Если имя class будет написано c орфографическими ошибками, то оно будет обычно приводить к ошибке времени компиляции.)
Вызов этого метода приведет к созданию возвращенного узла и его предков, если они не будут уже существовать. Если возвращенный узел не существовал до этого вызова, этот узел и любые предки, которые создавались этим вызовом, как гарантируют, не станут постоянными, пока метод flush не вызовут на возвращенном узле (или один из его предков или потомков).
c
- class, для пакета которого требуется системный привилегированный узел.NullPointerException
- если c является null.SecurityException
- если менеджер безопасности присутствует, и он отрицает RuntimePermission("preferences").RuntimePermission
public static Preferences userRoot()
SecurityException
- Если менеджер безопасности присутствует, и он отрицает RuntimePermission("preferences").RuntimePermission
public static Preferences systemRoot()
SecurityException
- Если менеджер безопасности присутствует, и он отрицает RuntimePermission("preferences").RuntimePermission
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()
метод.public abstract String get(String key, String def)
Некоторые реализации могут сохранить значения по умолчанию в своих запоминающих устройствах. Если нет никакого значения, связанного с указанным ключом, но есть такое сохраненное значение по умолчанию, он возвращается в предпочтении к указанному значению по умолчанию.
key
- ключ, присваиваемое значение которого должно быть возвращено.def
- значение, которое будет возвращено, когда у этого привилегированного узла нет никакого значения, связанного с key.IllegalStateException
- если этот узел (или предок) был удален с removeNode()
метод.NullPointerException
- если key является null. (Значение null для def разрешается.)public abstract void remove(String key)
Если эта реализация будет поддерживать сохраненные значения по умолчанию, и есть такое значение по умолчанию для указанного предпочтения, то сохраненное значение по умолчанию будет "представлено" этим вызовом, в том смысле, что это будет возвращено последующим звонком в get.
key
- ключ, отображение которого должно быть удалено из привилегированного узла.NullPointerException
- если key является null.IllegalStateException
- если этот узел (или предок) был удален с removeNode()
метод.public abstract void clear() throws BackingStoreException
Если эта реализация будет поддерживать сохраненные значения по умолчанию, и этот узел в привилегированной иерархии содержит любые такие значения по умолчанию, то сохраненные значения по умолчанию будут "представлены" этим вызовом, в том смысле, что они будут возвращены, следуя за звонками в get.
BackingStoreException
- если эта работа не может быть завершена из-за отказа в запоминающем устройстве, или неспособности связаться с этим.IllegalStateException
- если этот узел (или предок) был удален с removeNode()
метод.removeNode()
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()
метод.getInt(String,int)
public abstract int getInt(String key, int def)
Integer.parseInt(String)
. Возвращает указанное значение по умолчанию, если бы нет никакого значения, связанного с ключом, запоминающее устройство недоступно, или если Integer.parseInt(String) бросил бы a NumberFormatException
если присваиваемое значение передали. Этот метод предназначается для использования в соединении с putInt(java.lang.String, int)
. Если реализация поддерживает сохраненные значения по умолчанию, и такое значение по умолчанию существует, доступно, и могло бы быть преобразовано в интервал с Integer.parseInt, этот интервал возвращается в предпочтении к указанному значению по умолчанию.
key
- ключ, присваиваемое значение которого должно быть возвращено как интервал.def
- значение, которое будет возвращено, когда у этого привилегированного узла нет никакого значения, связанного с key или присваиваемым значением, не может быть интерпретировано как интервал, или запоминающее устройство недоступно.IllegalStateException
- если этот узел (или предок) был удален с removeNode()
метод.NullPointerException
- если key является null.putInt(String,int)
, get(String,String)
public abstract void putLong(String key, long value)
Long.toString(long)
. Этот метод предназначается для использования в соединении с getLong(java.lang.String, long)
.key
- ключ, с которым должна быть связана строковая форма имеющая значение.value
- оцените, чья строковая форма должна быть связана с ключом.NullPointerException
- если key является null.IllegalArgumentException
- если key.length() превышает MAX_KEY_LENGTH.IllegalStateException
- если этот узел (или предок) был удален с removeNode()
метод.getLong(String,long)
public abstract long getLong(String key, long def)
Long.parseLong(String)
. Возвращает указанное значение по умолчанию, если бы нет никакого значения, связанного с ключом, запоминающее устройство недоступно, или если Long.parseLong(String) бросил бы a NumberFormatException
если присваиваемое значение передали. Этот метод предназначается для использования в соединении с putLong(java.lang.String, long)
. Если реализация поддерживает сохраненные значения по умолчанию, и такое значение по умолчанию существует, доступно, и могло бы быть преобразовано в длинное с Long.parseLong, это долго возвращается в предпочтении к указанному значению по умолчанию.
key
- ключ, присваиваемое значение которого должно быть возвращено как длинное.def
- значение, которое будет возвращено, когда у этого привилегированного узла нет никакого значения, связанного с key или присваиваемым значением, не может быть интерпретировано как длинное, или запоминающее устройство недоступно.IllegalStateException
- если этот узел (или предок) был удален с removeNode()
метод.NullPointerException
- если key является null.putLong(String,long)
, get(String,String)
public abstract void putBoolean(String key, boolean value)
getBoolean(java.lang.String, boolean)
.key
- ключ, с которым должна быть связана строковая форма имеющая значение.value
- оцените, чья строковая форма должна быть связана с ключом.NullPointerException
- если key является null.IllegalArgumentException
- если key.length() превышает MAX_KEY_LENGTH.IllegalStateException
- если этот узел (или предок) был удален с removeNode()
метод.getBoolean(String,boolean)
, get(String,String)
public abstract boolean getBoolean(String key, boolean def)
putBoolean(java.lang.String, boolean)
. Возвращает указанное значение по умолчанию, если нет никакого значения, связанного с ключом, запоминающее устройство недоступно, или если присваиваемое значение - что-то другое чем "true" или "false", игнорируя регистр.
Если реализация поддерживает сохраненные значения по умолчанию, и такое значение по умолчанию существует и доступно, это используется в предпочтении к указанному значению по умолчанию, если сохраненное значение по умолчанию не что-то другое чем "true" или "false", игнорируя регистр, когда указанное значение по умолчанию используется.
key
- ключ, присваиваемое значение которого должно быть возвращено как булево.def
- значение, которое будет возвращено, когда у этого привилегированного узла нет никакого значения, связанного с key или присваиваемым значением, не может быть интерпретировано как булево, или запоминающее устройство недоступно.IllegalStateException
- если этот узел (или предок) был удален с removeNode()
метод.NullPointerException
- если key является null.get(String,String)
, putBoolean(String,boolean)
public abstract void putFloat(String key, float value)
Float.toString(float)
. Этот метод предназначается для использования в соединении с getFloat(java.lang.String, float)
.key
- ключ, с которым должна быть связана строковая форма имеющая значение.value
- оцените, чья строковая форма должна быть связана с ключом.NullPointerException
- если key является null.IllegalArgumentException
- если key.length() превышает MAX_KEY_LENGTH.IllegalStateException
- если этот узел (или предок) был удален с removeNode()
метод.getFloat(String,float)
public abstract float getFloat(String key, float def)
Float.parseFloat(String)
. Возвращает указанное значение по умолчанию, если бы нет никакого значения, связанного с ключом, запоминающее устройство недоступно, или если Float.parseFloat(String) бросил бы a NumberFormatException
если присваиваемое значение передали. Этот метод предназначается для использования в соединении с putFloat(java.lang.String, float)
. Если реализация поддерживает сохраненные значения по умолчанию, и такое значение по умолчанию существует, доступно, и могло бы быть преобразовано в плавание с Float.parseFloat, это плавание возвращается в предпочтении к указанному значению по умолчанию.
key
- ключ, присваиваемое значение которого должно быть возвращено как плавание.def
- значение, которое будет возвращено, когда у этого привилегированного узла нет никакого значения, связанного с key или присваиваемым значением, не может быть интерпретировано как плавание, или запоминающее устройство недоступно.IllegalStateException
- если этот узел (или предок) был удален с removeNode()
метод.NullPointerException
- если key является null.putFloat(String,float)
, get(String,String)
public abstract void putDouble(String key, double value)
Double.toString(double)
. Этот метод предназначается для использования в соединении с getDouble(java.lang.String, double)
.key
- ключ, с которым должна быть связана строковая форма имеющая значение.value
- оцените, чья строковая форма должна быть связана с ключом.NullPointerException
- если key является null.IllegalArgumentException
- если key.length() превышает MAX_KEY_LENGTH.IllegalStateException
- если этот узел (или предок) был удален с removeNode()
метод.getDouble(String,double)
public abstract double getDouble(String key, double def)
Double.parseDouble(String)
. Возвращает указанное значение по умолчанию, если бы нет никакого значения, связанного с ключом, запоминающее устройство недоступно, или если Double.parseDouble(String) бросил бы a NumberFormatException
если присваиваемое значение передали. Этот метод предназначается для использования в соединении с putDouble(java.lang.String, double)
. Если реализация поддерживает сохраненные значения по умолчанию, и такое значение по умолчанию существует, доступно, и могло бы быть преобразовано в двойное с Double.parseDouble, это удваивается, возвращается в предпочтении к указанному значению по умолчанию.
key
- ключ, присваиваемое значение которого должно быть возвращено как двойное.def
- значение, которое будет возвращено, когда у этого привилегированного узла нет никакого значения, связанного с key или присваиваемым значением, не может быть интерпретировано как двойное, или запоминающее устройство недоступно.IllegalStateException
- если этот узел (или предок) был удален с removeNode()
метод.NullPointerException
- если key является null.putDouble(String,double)
, get(String,String)
public abstract void putByteArray(String key, byte[] value)
getByteArray(java.lang.String, byte[])
.key
- ключ, с которым должна быть связана строковая форма имеющая значение.value
- оцените, чья строковая форма должна быть связана с ключом.NullPointerException
- если ключом или значением является null.IllegalArgumentException
- если key.length () превышает MAX_KEY_LENGTH или если value.length превышает MAX_VALUE_LENGTH*3/4.IllegalStateException
- если этот узел (или предок) был удален с removeNode()
метод.getByteArray(String,byte[])
, get(String,String)
public abstract byte[] getByteArray(String key, byte[] def)
putByteArray(java.lang.String, byte[])
. Возвращает указанное значение по умолчанию, если нет никакого значения, связанного с ключом, запоминающее устройство недоступно, или если присваиваемое значение не является допустимым Base64 закодированный байтовый массив (как определено выше).
Если реализация поддерживает сохраненные значения по умолчанию, и такое значение по умолчанию существует и доступно, это используется в предпочтении к указанному значению по умолчанию, если сохраненное значение по умолчанию не является допустимым Base64 закодированный байтовый массив (как определено выше), когда указанное значение по умолчанию используется.
key
- ключ, присваиваемое значение которого должно быть возвращено как байтовый массив.def
- значение, которое будет возвращено, когда у этого привилегированного узла нет никакого значения, связанного с key или присваиваемым значением, не может быть интерпретировано как байтовый массив, или запоминающее устройство недоступно.IllegalStateException
- если этот узел (или предок) был удален с removeNode()
метод.NullPointerException
- если key является null. (Значение null для def разрешается.)get(String,String)
, putByteArray(String,byte[])
public abstract String[] keys() throws BackingStoreException
Если реализация поддерживает сохраненные значения по умолчанию и есть любые такие значения по умолчанию в этом узле, которые не были переопределены явным предпочтением, значения по умолчанию возвращаются в массиве в дополнение к любому явному предпочтению.
BackingStoreException
- если эта работа не может быть завершена из-за отказа в запоминающем устройстве, или неспособности связаться с этим.IllegalStateException
- если этот узел (или предок) был удален с removeNode()
метод.public abstract String[] childrenNames() throws BackingStoreException
BackingStoreException
- если эта работа не может быть завершена из-за отказа в запоминающем устройстве, или неспособности связаться с этим.IllegalStateException
- если этот узел (или предок) был удален с removeNode()
метод.public abstract Preferences parent()
IllegalStateException
- если этот узел (или предок) был удален с removeNode()
метод.public abstract Preferences node(String pathName)
Если возвращенный узел не существовал до этого вызова, этот узел и любые предки, которые создавались этим вызовом, как гарантируют, не станут постоянными, пока метод flush не вызовут на возвращенном узле (или один из его предков или потомков).
pathName
- путь привилегированного узла, чтобы возвратиться.IllegalArgumentException
- если путь недопустим (то есть, он содержит многократные последовательные символы наклонной черты, или заканчивается символом наклонной черты и является больше чем одним символом долго).NullPointerException
- если путем является null.IllegalStateException
- если этот узел (или предок) был удален с removeNode()
метод.flush()
public abstract boolean nodeExists(String pathName) throws BackingStoreException
Если этот узел (или предок) был уже удален с removeNode()
метод, законно вызвать этот метод, но только с путем ""; вызов возвратит false. Таким образом, идиома, которую p.nodeExists("") может использоваться, чтобы протестировать, был ли p удален.
pathName
- путь узла, существование которого должно быть проверено.BackingStoreException
- если эта работа не может быть завершена из-за отказа в запоминающем устройстве, или неспособности связаться с этим.IllegalArgumentException
- если путь недопустим (то есть, он содержит многократные последовательные символы наклонной черты, или заканчивается символом наклонной черты и является больше чем одним символом долго).NullPointerException
- если путем является null.IllegalStateException
- если этот узел (или предок) был удален с removeNode()
метод и pathName не являются пустой строкой ("").public abstract void removeNode() throws BackingStoreException
name()
, absolutePath()
, isUserNode()
, flush()
или nodeExists("")
на соответствующем Preferences экземпляр перестанет работать с IllegalStateException. (Методы, определенные на Object
может все еще быть вызван на узел после того, как он был удален; они не будут бросать IllegalStateException.) Удаление, как гарантируют, не будет персистентным, пока метод flush не вызовут на этом узле (или предок).
Если эта реализация поддерживает сохраненные значения по умолчанию, удаляя узел представляет любые сохраненные значения по умолчанию в или ниже этого узла. Таким образом последующий звонок в nodeExists на пути этого узла может возвратить true, и последующий звонок в node на этом пути может возвратить (различный) экземпляр Preferences, представляющий непустой набор предпочтения и/или дочерних элементов.
BackingStoreException
- если эта работа не может быть завершена из-за отказа в запоминающем устройстве, или неспособности связаться с этим.IllegalStateException
- если этот узел (или предок) был уже удален с removeNode()
метод.UnsupportedOperationException
- если этот метод вызывается на корневой узел.flush()
public abstract String name()
public abstract String absolutePath()
public abstract boolean isUserNode()
public abstract String toString()
public abstract void flush() throws BackingStoreException
Реализации свободны сбросить изменения в персистентное хранилище в любое время. Они не должны ожидать этого метода, который вызовут.
Когда сброс происходит на недавно создаваемом узле, это делается персистентным, как любые предки (и потомки), которые должны все же быть сделаны персистентными. Отметьте однако, что любые привилегированные изменения значения в предках, как гарантируют, не будут делаться персистентными.
Если этот метод вызывается на узел, который был удален с removeNode()
метод, flushSpi () вызывается на этот узел, но не на других.
BackingStoreException
- если эта работа не может быть завершена из-за отказа в запоминающем устройстве, или неспособности связаться с этим.sync()
public abstract void sync() throws BackingStoreException
BackingStoreException
- если эта работа не может быть завершена из-за отказа в запоминающем устройстве, или неспособности связаться с этим.IllegalStateException
- если этот узел (или предок) был удален с removeNode()
метод.flush()
public abstract void addPreferenceChangeListener(PreferenceChangeListener pcl)
removeNode()
метод, который генерирует событие изменения узла. Привилегированные события изменения сгенерированы методом clear.) События только гарантируются для изменений, произведенных в пределах той же самой JVM как зарегистрированный слушатель, хотя некоторые реализации могут генерировать события для изменений, произведенных вне этой JVM. События могут быть сгенерированы прежде, чем изменения делались персистентными. События не сгенерированы, когда предпочтение изменяется в потомках этого узла; вызывающая сторона, требуя таких событий должна зарегистрироваться в каждом потомке.
pcl
- Привилегированный слушатель изменения, чтобы добавить.NullPointerException
- если pcl является нулем.IllegalStateException
- если этот узел (или предок) был удален с removeNode()
метод.removePreferenceChangeListener(PreferenceChangeListener)
, addNodeChangeListener(NodeChangeListener)
public abstract void removePreferenceChangeListener(PreferenceChangeListener pcl)
pcl
- Привилегированный слушатель изменения, чтобы удалить.IllegalArgumentException
- если pcl не был зарегистрированным привилегированным слушателем изменения на этом узле.IllegalStateException
- если этот узел (или предок) был удален с removeNode()
метод.addPreferenceChangeListener(PreferenceChangeListener)
public abstract void addNodeChangeListener(NodeChangeListener ncl)
removeNode()
результаты вызова в многократных событиях изменения узла, один для каждого узла в поддереве базировались в удаленном узле.) События только гарантируются для изменений, произведенных в пределах той же самой JVM как зарегистрированный слушатель, хотя некоторые реализации могут генерировать события для изменений, произведенных вне этой JVM. События могут быть сгенерированы прежде, чем изменения стали постоянными. События не сгенерированы, когда косвенные потомки этого узла добавляются или удаляются; вызывающая сторона, требуя таких событий должна зарегистрироваться в каждом потомке.
Немного гарантий могут быть сделаны относительно создания узла. Поскольку узлы создаются неявно на доступ, возможно, не выполнимо для реализации определить, существовал ли дочерний узел в запоминающем устройстве до доступа (например, потому что запоминающее устройство недостижимо, или кэшируемая информация является устаревшей). При этих обстоятельствах реализации ни не требуются генерировать события изменения узла, ни мешаются делать так.
ncl
- NodeChangeListener, чтобы добавить.NullPointerException
- если ncl является нулем.IllegalStateException
- если этот узел (или предок) был удален с removeNode()
метод.removeNodeChangeListener(NodeChangeListener)
, addPreferenceChangeListener(PreferenceChangeListener)
public abstract void removeNodeChangeListener(NodeChangeListener ncl)
ncl
- NodeChangeListener, чтобы удалить.IllegalArgumentException
- если ncl не был зарегистрированный NodeChangeListener на этом узле.IllegalStateException
- если этот узел (или предок) был удален с removeNode()
метод.addNodeChangeListener(NodeChangeListener)
public abstract void exportNode(OutputStream os) throws IOException, BackingStoreException
У XML-документа будет следующее объявление DOCTYPE:
<!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">Кодировка символов UTF-8 будет использоваться.
Этот метод является исключением к общему правилу, что результаты параллельного выполнения многократных методов в этом class приводят к результатам, эквивалентным некоторому последовательному выполнению. Если предпочтение в этом узле изменяется одновременно с вызовом этого метода, экспортируемое предпочтение включает "нечеткий снимок" предпочтения, содержавшегося в узле; некоторые из параллельных модификаций могут быть отражены в экспортируемых данных, в то время как другие не могут.
os
- поток вывода, о котором можно испустить XML-документ.IOException
- если запись в указанный поток вывода приводит к IOException.BackingStoreException
- если привилегированные данные не могут быть считаны из запоминающего устройства.IllegalStateException
- если этот узел (или предок) был удален с removeNode()
метод.importPreferences(InputStream)
public abstract void exportSubtree(OutputStream os) throws IOException, BackingStoreException
У XML-документа будет следующее объявление DOCTYPE:
<!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">Кодировка символов UTF-8 будет использоваться.
Этот метод является исключением к общему правилу, что результаты параллельного выполнения многократных методов в этом class приводят к результатам, эквивалентным некоторому последовательному выполнению. Если предпочтение или узлы в поддереве, базированном в этом узле, изменяются одновременно с вызовом этого метода, экспортируемое предпочтение включает "нечеткий снимок" поддерева; некоторые из параллельных модификаций могут быть отражены в экспортируемых данных, в то время как другие не могут.
os
- поток вывода, о котором можно испустить XML-документ.IOException
- если запись в указанный поток вывода приводит к IOException.BackingStoreException
- если привилегированные данные не могут быть считаны из запоминающего устройства.IllegalStateException
- если этот узел (или предок) был удален с removeNode()
метод.importPreferences(InputStream)
, exportNode(OutputStream)
public static void importPreferences(InputStream is) throws IOException, InvalidPreferencesFormatException
У XML-документа должно быть следующее объявление DOCTYPE:
<!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">(Этот метод разрабатывается для использования в соединении с
exportNode(OutputStream)
и exportSubtree(OutputStream)
. Этот метод является исключением к общему правилу, что результаты параллельного выполнения многократных методов в этом class приводят к результатам, эквивалентным некоторому последовательному выполнению. Метод ведет себя как будто реализованный сверху других открытых методов в этом class, особенно node(String)
и put(String, String)
.
is
- входной поток, из которого можно считать XML-документ.IOException
- если чтение из указанного входного потока приводит к IOException.InvalidPreferencesFormatException
- Данные на входном потоке не составляют допустимый XML-документ с переданным под мандат типом документа.SecurityException
- Если менеджер безопасности присутствует, и он отрицает RuntimePermission("preferences").RuntimePermission
Для дальнейшей ссылки API и документации разработчика, см. Java Документация SE. Та документация содержит более подробные, предназначенные разработчиком описания, с концептуальными краткими обзорами, определениями сроков, обходных решений, и рабочих примеров кода.
Авторское право © 1993, 2013, Oracle и/или его филиалы. Все права защищены.
Проект сборка-b92