Свойства класса
- Все реализованные интерфейсы:
Serializable, Cloneable, Map<Object,Object>
- Прямые известные подклассы:
Provider
public class Properties extends Hashtable<Object,Object>
Properties представляет собой постоянный набор свойств. Properties можно сохранить в поток или загрузить из потока. Каждый ключ и соответствующее ему значение в списке свойств являются строками. Список свойств может содержать другой список свойств в качестве «значений по умолчанию»; поиск в этом втором списке выполняется, если ключ свойства не найден в исходном списке свойств.
Поскольку Properties наследует Hashtable, к объекту Properties можно применять методы put и putAll. Их использование настоятельно не рекомендуется, поскольку они позволяют вызывающему коду добавлять записи с ключами или значениями, которые не являются Strings. Вместо них следует использовать метод setProperty. Если вызвать метод store или save для «скомпрометированного» объекта Properties, содержащего ключ или значение, не являющиеся String, вызов завершится ошибкой. Аналогично, вызов метода propertyNames или list завершится ошибкой, если он будет выполнен для «скомпрометированного» объекта Properties, содержащего ключ, не являющийся String.
Итераторы, возвращаемые методом iterator для «представлений коллекций» этого класса (то есть entrySet(), keySet() и values()), могут не обнаруживать структурные изменения (в отличие от реализации Hashtable). Эти итераторы гарантированно обходят элементы, существовавшие на момент создания, ровно один раз; они могут отражать изменения, внесённые после создания, но такая возможность не гарантируется.
Методы load(Reader) / store(Writer, String) загружают свойства из символьного потока и сохраняют их в символьный поток в простом построчном формате, описанном ниже. Методы load(InputStream) / store(OutputStream, String) работают аналогично паре load(Reader)/store(Writer, String), за исключением того, что входной/выходной поток кодируется в ISO 8859-1. Символы, которые невозможно напрямую представить в этой кодировке, можно записать с помощью Unicode-последовательностей экранирования, определённых в разделе 3.3 документа Спецификация языка Java; в последовательности экранирования допускается только один символ 'u'.
Методы loadFromXML(InputStream) и storeToXML(OutputStream, String, String) загружают свойства и сохраняют их в простом формате XML. По умолчанию используется кодировка UTF-8, однако при необходимости можно указать конкретную кодировку. Реализации обязаны поддерживать UTF-8 и UTF-16 и могут поддерживать другие кодировки. Документ свойств XML содержит следующее объявление DOCTYPE:
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">Обратите внимание, что системный URI (http://java.sun.com/dtd/properties.dtd) не используется при экспорте или импорте свойств; он служит лишь строкой для уникальной идентификации DTD, который имеет следующий вид:
<?xml version="1.0" encoding="UTF-8"?> <!-- DTD for properties --> <!ELEMENT properties ( comment?, entry* ) > <!ATTLIST properties version CDATA #FIXED "1.0"> <!ELEMENT comment (#PCDATA) > <!ELEMENT entry (#PCDATA) > <!ATTLIST entry key CDATA #REQUIRED>
Этот класс является потокобезопасным: несколько потоков могут совместно использовать один объект Properties без необходимости во внешней синхронизации.
- Примечание к API:
- Класс
Propertiesне наследует от своего суперклассаHashtableпонятие коэффициента загрузки. - С момента:
- 1.0
- См. также:
Краткое описание полей
| Модификатор и тип | Поле | Описание |
|---|---|---|
protected Properties |
defaults |
Список свойств, содержащий значения по умолчанию для ключей, не найденных в этом списке свойств. |
Краткое описание конструкторов
| Конструктор | Описание |
|---|---|
Properties() |
Создаёт пустой список свойств без значений по умолчанию. |
Properties |
Создаёт пустой список свойств без значений по умолчанию и с начальным размером, позволяющим разместить указанное число элементов без необходимости динамического изменения размера. |
Properties |
Создаёт пустой список свойств с указанными значениями по умолчанию. |
Краткое описание методов
| Модификатор и тип | Метод | Описание |
|---|---|---|
String |
getProperty |
Ищет свойство с указанным ключом в этом списке свойств. |
String |
getProperty |
Ищет свойство с указанным ключом в этом списке свойств. |
void |
list |
Выводит этот список свойств в указанный выходной поток. |
void |
list |
Выводит этот список свойств в указанный выходной поток. |
void |
load |
Считывает список свойств (пары ключ—элемент) из входного байтового потока. |
void |
load |
Считывает список свойств (пары ключ—элемент) из входного символьного потока в простом построчном формате. |
void |
loadFromXML |
Загружает в эту таблицу свойств все свойства, представленные XML-документом в указанном входном потоке. |
Enumeration |
propertyNames() |
Возвращает перечисление всех ключей этого списка свойств, включая уникальные ключи из списка свойств по умолчанию, если ключ с таким же именем ещё не был найден в основном списке свойств. |
void |
save |
Устарело. Этот метод не выбрасывает IOException, если при сохранении списка свойств возникает ошибка ввода-вывода. |
Object |
setProperty |
Вызывает метод Hashtable put. |
void |
store |
Записывает этот список свойств (пары ключ—элемент) из таблицы Properties в выходной поток в формате, подходящем для загрузки в таблицу Properties с помощью метода load(InputStream). |
void |
store |
Записывает этот список свойств (пары ключ—элемент) из таблицы Properties в выходной символьный поток в формате, подходящем для использования метода load(Reader). |
void |
storeToXML |
Создаёт XML-документ, представляющий все свойства, содержащиеся в этой таблице. |
void |
storeToXML |
Создаёт XML-документ, представляющий все свойства, содержащиеся в этой таблице, с использованием указанной кодировки. |
void |
storeToXML |
Создаёт XML-документ, представляющий все свойства, содержащиеся в этой таблице, с использованием указанной кодировки. |
Set |
stringPropertyNames() |
Возвращает неизменяемый набор ключей из этого списка свойств, в котором ключи и соответствующие им значения являются строками; в набор также входят уникальные ключи из списка свойств по умолчанию, если ключ с таким же именем ещё не был найден в основном списке свойств. |
Методы, объявленные в классе Hashtable
clear, clone, compute, computeIfAbsent, computeIfPresent, contains, containsKey, containsValue, elements, entrySet, equals, get, hashCode, isEmpty, keys, keySet, merge, put, putAll, rehash, remove, size, toString, values
Методы, объявленные в интерфейсе Map
forEach, getOrDefault, putIfAbsent, remove, replace, replace, replaceAll
Подробное описание полей
defaults
protected volatile Properties defaults
Подробное описание конструкторов
Свойства
public Properties()
- Примечание по реализации:
- Начальная емкость объекта
Properties, созданного этим конструктором, не определена.
Свойства
public Properties(int initialCapacity)
- Параметры:
-
initialCapacity— размерPropertiesбудет достаточным для размещения этого числа элементов - Исключения:
-
IllegalArgumentException— если начальная емкость меньше нуля. - Начиная с версии:
- 10
Свойства
public Properties(Properties defaults)
- Примечание по реализации:
- Начальная емкость объекта
Properties, созданного этим конструктором, не определена. - Параметры:
-
defaults— значения по умолчанию.
Подробное описание методов
setProperty
public Object setProperty(String key, String value)
Hashtable put. Предоставлен для параллельного использования с методом getProperty. Обеспечивает использование строк для ключей и значений свойств. Возвращаемое значение является результатом вызова Hashtable метода put.- Параметры:
-
key— ключ, который будет добавлен в этот список свойств. -
value— значение, соответствующееkey. - Возвращает:
- предыдущее значение указанного ключа в этом списке свойств или
null, если такого значения не было. - Начиная с версии:
- 1.2
- См. также:
load
public void load(Reader reader) throws IOException
Свойства обрабатываются построчно. Существуют два вида строк: естественные строки и логические строки. Естественная строка определяется как строка символов, завершающаяся либо набором символов-разделителей строк (\n, \r или \r\n), либо концом потока. Естественная строка может быть пустой строкой, строкой-комментарием или содержать всю пару ключ—элемент либо ее часть. Логическая строка содержит все данные пары ключ—элемент, которые могут быть распределены по нескольким последовательным естественным строкам, если экранировать последовательность символов-разделителей строк символом обратной косой черты \. Обратите внимание, что строку-комментарий нельзя продолжить таким способом; каждая естественная строка-комментарий должна иметь собственный символ комментария, как описано ниже. Строки считываются из входного потока до достижения его конца.
Естественная строка, содержащая только пробельные символы, считается пустой и игнорируется. Строка-комментарий начинается с символа ASCII '#' или '!', являющегося первым непробельным символом; строки-комментарии также игнорируются и не содержат сведений о парах ключ—элемент. Помимо символов-разделителей строк, этот формат считает пробел (' ', '\u0020'), табуляцию ('\t', '\u0009') и символ перевода формата ('\f', '\u000C') пробельными символами.
Если логическая строка распределена по нескольким естественным строкам, обратная косая черта, экранирующая последовательность символов-разделителей строк, сама эта последовательность и все пробельные символы в начале следующей строки не влияют на значения ключа или элемента. Далее при обсуждении разбора ключа и элемента (при загрузке) предполагается, что все символы, составляющие ключ и элемент, расположены в одной естественной строке после удаления символов продолжения строки. Обратите внимание: недостаточно проверить только символ, предшествующий последовательности символов-разделителей строк, чтобы определить, экранирована ли она; для экранирования перед ней должно находиться нечетное число подряд идущих обратных косых черт. Поскольку входные данные обрабатываются слева направо, ненулевое четное число 2n подряд идущих обратных косых черт перед символом-разделителем строк (или в другом месте) после обработки экранирования кодирует n обратных косых черт.
Ключ содержит все символы строки, начиная с первого непробельного символа и до первого неэкранированного символа '=', ':' или пробельного символа, отличного от символа-разделителя строк, не включая его. Все эти символы, завершающие ключ, можно включить в ключ, экранировав их предшествующим символом обратной косой черты; например,
\:\=
будет двухсимвольным ключом ":=". Символы-разделители строк можно включить с помощью управляющих последовательностей \r и \n. Все пробельные символы после ключа пропускаются; если первый непробельный символ после ключа — '=' или ':', он игнорируется, а все следующие за ним пробельные символы также пропускаются. Все оставшиеся символы строки становятся частью соответствующей строки элемента; если символов не осталось, элементом является пустая строка "". После определения исходных последовательностей символов, составляющих ключ и элемент, выполняется обработка экранирования, описанная выше.
Например, каждая из следующих трех строк задает ключ "Truth" и соответствующее значение элемента "Beauty":
Truth = Beauty Truth:Beauty Truth :BeautyДругой пример: следующие три строки задают одно свойство:
fruits apple, banana, pear, \
cantaloupe, watermelon, \
kiwi, mango
Ключ — "fruits", а соответствующий элемент: "apple, banana, pear, cantaloupe, watermelon, kiwi, mango"Обратите внимание, что перед каждым
\ стоит пробел, поэтому после каждой запятой в итоговом результате будет пробел; \, символ-разделитель строк и начальные пробельные символы в строке-продолжении просто отбрасываются и не заменяются одним или несколькими другими символами. Третий пример — строка:
cheesesзадает ключ
"cheeses" и пустую строку в качестве соответствующего элемента "". Символы в ключах и элементах можно представлять управляющими последовательностями, аналогичными используемым в символьных и строковых литералах (см. разделы 3.3 и 3.10.6 документа Спецификация языка Java). Отличия от управляющих последовательностей для символов и Unicode-последовательностей, используемых для символов и строк, заключаются в следующем:
- Восьмеричные управляющие последовательности не распознаются.
- Последовательность символов
\bне представляет символ возврата на одну позицию. - Метод не считает ошибкой символ обратной косой черты
\перед недопустимым управляющим символом; обратная косая черта просто отбрасывается. Например, в строке Java последовательность"\z"вызвала бы ошибку компиляции. В отличие от этого, данный метод просто отбрасывает обратную косую черту. Поэтому этот метод считает последовательность из двух символов"\b"эквивалентной одному символу'b'. - Для одинарных и двойных кавычек управляющие последовательности не нужны; однако, согласно приведенному выше правилу, символы одинарной и двойной кавычки, которым предшествует обратная косая черта, все равно дают символы одинарной и двойной кавычки соответственно.
- В управляющей последовательности Unicode допускается только один символ 'u'.
Указанный поток остается открытым после возврата этого метода.
- Параметры:
-
reader— входной поток символов. - Исключения:
-
IOException— если при чтении из входного потока произошла ошибка. -
IllegalArgumentException— если во входных данных обнаружена некорректная управляющая последовательность Unicode. -
NullPointerException— еслиreaderимеет значение null. - Начиная с версии:
- 1.6
load
public void load(InputStream inStream) throws IOException
load(Reader), и предполагается, что он использует кодировку символов ISO 8859-1; то есть каждый байт соответствует одному символу Latin1. Символы, не входящие в Latin1, и некоторые специальные символы представляются в ключах и элементах с помощью управляющих последовательностей Unicode, описанных в разделе 3.3 документа Спецификация языка Java. Указанный поток остается открытым после возврата этого метода.
- Параметры:
-
inStream— входной поток. - Исключения:
-
IOException— если при чтении из входного потока произошла ошибка. -
IllegalArgumentException— если входной поток содержит некорректную управляющую последовательность Unicode. -
NullPointerException— еслиinStreamимеет значение null. - Начиная с версии:
- 1.2
save
@Deprecated public void save(OutputStream out, String comments)
store(OutputStream out,
String comments) или метод storeToXML(OutputStream os, String comment).store(OutputStream out, String comments) и подавляет выброшенные исключения IOException.- Параметры:
-
out— выходной поток. -
comments— описание списка свойств. - Исключения:
-
ClassCastException— если этот объектPropertiesсодержит ключи или значения, не являющиесяStrings.
store
public void store(Writer writer, String comments) throws IOException
Properties в выходной поток символов в формате, подходящем для использования метода load(Reader). Свойства из таблицы значений по умолчанию этой таблицы Properties (если таковые имеются) этим методом не записываются.
Если аргумент comments не равен null, в выходной поток сначала записываются символ ASCII #, строка комментария и разделитель строк. Таким образом, comments может служить комментарием, идентифицирующим список. Символ перевода строки (\n), возврата каретки (\r) или возврата каретки, за которым сразу следует символ перевода строки (\r\n), в комментарии заменяется на line separator; если следующий символ в комментарии не является символом # или !, после этого разделителя строк записывается символ ASCII #.
Если свойство java.properties.date задано в командной строке и не является пустым (как определено методом String.isEmpty), строка комментария записывается следующим образом. Сначала записывается символ #, затем содержимое свойства, а после него — разделитель строк. Любые символы-разделители строк в значении системного свойства обрабатываются так же, как описано выше для аргумента comments. Если системное свойство не задано или является пустым, строка комментария записывается следующим образом. Сначала записывается символ #, затем текущие дата и время в формате, используемом методом Date.toString, а после них — разделитель строк.
Затем каждая запись в этой таблице Properties записывается в отдельной строке. Для каждой записи сначала записывается строка ключа, затем символ ASCII =, а после него — соответствующая строка элемента. В ключе перед каждым символом пробела записывается символ \. В элементе символ \ записывается перед начальными пробелами, но не перед пробелами внутри строки или в ее конце. Перед символами ключа и элемента #, !, = и : записывается обратная косая черта, чтобы обеспечить их корректную загрузку.
После записи всех записей выходной поток очищается. Выходной поток остается открытым после возврата этого метода.
- Требования к реализации:
- Ключи и элементы записываются в естественном порядке сортировки ключей в
entrySet(), если только подкласс не переопределяетentrySet()так, чтобы он возвращал значение, отличное отsuper.entrySet(). - Параметры:
-
writer— средство записи в выходной поток символов. -
comments— описание списка свойств. - Исключения:
-
IOException— если при записи этого списка свойств в указанный выходной поток возникаетIOException. -
ClassCastException— если этот объектPropertiesсодержит ключи или значения, не являющиесяStrings. -
NullPointerException— еслиwriterимеет значение null. - Начиная с версии:
- 1.6
store
public void store(OutputStream out, String comments) throws IOException
Properties в выходной поток в формате, подходящем для загрузки в таблицу Properties с помощью метода load(InputStream). Свойства из таблицы значений по умолчанию этой таблицы Properties (если таковые имеются) этим методом не записываются.
Этот метод выводит комментарии, ключи и значения свойств в том же формате, который описан в store(Writer), со следующими отличиями:
- Поток записывается с использованием кодировки символов ISO 8859-1.
- Символы комментариев, не входящие в Latin-1, записываются как
\uxxxx, где xxxx — соответствующее шестнадцатеричное значение Unicode. - Символы в ключах или значениях свойств с кодами меньше
\u0020и больше\u007Eзаписываются как\uxxxx, где xxxx — соответствующее шестнадцатеричное значение.
После записи всех записей выходной поток очищается. Выходной поток остается открытым после возврата этого метода.
- Параметры:
-
out— выходной поток. -
comments— описание списка свойств. - Исключения:
-
IOException— если при записи этого списка свойств в указанный выходной поток возникаетIOException. -
ClassCastException— если этот объектPropertiesсодержит ключи или значения, не являющиесяStrings. -
NullPointerException— еслиoutимеет значение null. - Начиная с версии:
- 1.2
loadFromXML
public void loadFromXML(InputStream in) throws IOException, InvalidPropertiesFormatException
XML-документ должен содержать следующее объявление DOCTYPE:
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">Кроме того, документ должен соответствовать описанному выше DTD свойств.
Реализация обязана считывать XML-документы, использующие кодировку "UTF-8" или "UTF-16". Реализация может поддерживать дополнительные кодировки.
Указанный поток закрывается после возврата этого метода.
- Параметры:
-
in— входной поток, из которого считывается XML-документ. - Исключения:
-
IOException— если чтение из указанного входного потока приводит кIOException. -
UnsupportedEncodingException— если объявление кодировки документа удалось прочитать и в нем указана неподдерживаемая кодировка -
InvalidPropertiesFormatException— данные во входном потоке не являются допустимым XML-документом с обязательным типом документа. -
NullPointerException— еслиinимеет значение null. - Начиная с версии:
- 1.5
- Внешние спецификации
- См. также:
storeToXML
public void storeToXML(OutputStream os, String comment) throws IOException
Вызов этого метода в форме props.storeToXML(os,
comment) выполняет в точности те же действия, что и вызов props.storeToXML(os, comment, "UTF-8");.
- Параметры:
-
os— выходной поток, в который выводится XML-документ. -
comment— описание списка свойств илиnull, если комментарий не требуется. - Исключения:
-
IOException— если запись в указанный выходной поток приводит кIOException. -
NullPointerException— еслиosимеет значение null. -
ClassCastException— если этот объектPropertiesсодержит ключи или значения, не являющиесяStrings. - Начиная с версии:
- 1.5
- См. также:
storeToXML
public void storeToXML(OutputStream os, String comment, String encoding) throws IOException
XML-документ будет содержать следующее объявление DOCTYPE:
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
Если указанный комментарий равен null, комментарий не будет сохранен в документе.
Реализация обязана поддерживать запись XML-документов, использующих кодировку "UTF-8" или "UTF-16". Реализация может поддерживать дополнительные кодировки.
Указанный поток остается открытым после возврата этого метода.
Этот метод работает так же, как storeToXML(OutputStream os, String comment, Charset charset), за исключением того, что он будет искать кодировку по указанному имени.
- Параметры:
-
os— выходной поток, в который выводится XML-документ. -
comment— описание списка свойств илиnull, если комментарий не требуется. -
encoding— имя поддерживаемой кодировки символов - Исключения:
-
IOException— если запись в указанный выходной поток приводит кIOException. -
UnsupportedEncodingException— если реализация не поддерживает указанную кодировку. -
NullPointerException— еслиosравноnullилиencodingравноnull. -
ClassCastException— если этот объектPropertiesсодержит ключи или значения, не являющиесяStrings. - Начиная с версии:
- 1.5
- Внешние спецификации
- См. также:
storeToXML
public void storeToXML(OutputStream os, String comment, Charset charset) throws IOException
XML-документ будет содержать следующее объявление DOCTYPE:
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
Если указанный комментарий равен null, комментарий не будет сохранен в документе.
Реализация обязана поддерживать запись XML-документов, использующих кодировку "UTF-8" или "UTF-16". Реализация может поддерживать дополнительные кодировки.
Символы, которые невозможно отобразить в указанной кодировке, будут закодированы в виде числовых ссылок на символы.
Указанный поток остается открытым после возврата этого метода.
- Параметры:
-
os— выходной поток, в который выводится XML-документ. -
comment— описание списка свойств илиnull, если комментарий не требуется. -
charset— кодировка символов - Исключения:
-
IOException— если запись в указанный выходной поток приводит кIOException. -
NullPointerException— еслиosилиcharsetравноnull. -
ClassCastException— если этот объектPropertiesсодержит ключи или значения, не являющиесяStrings. - Начиная с версии:
- 10
- Внешние спецификации
- См. также:
getProperty
public String getProperty(String key)
null.- Параметры:
-
key— ключ свойства. - Возвращает:
- значение в этом списке свойств, соответствующее указанному ключу.
- См. также:
getProperty
public String getProperty(String key, String defaultValue)
- Параметры:
-
key— ключ хеш-таблицы. -
defaultValue— значение по умолчанию. - Возвращает:
- значение в этом списке свойств, соответствующее указанному ключу.
- См. также:
propertyNames
public Enumeration<?> propertyNames()
- Возвращает:
- перечисление всех ключей этого списка свойств, включая ключи из списка свойств по умолчанию.
- Исключения:
-
ClassCastException— если какой-либо ключ в этом списке свойств не является строкой. - См. также:
stringPropertyNames
public Set<String> stringPropertyNames()
String, исключаются. Возвращаемое множество не связано с этим объектом Properties. Изменения этого объекта Properties не отражаются в возвращаемом множестве.
- Возвращает:
- неизменяемое множество ключей этого списка свойств, в котором ключи и соответствующие им значения являются строками; оно включает ключи из списка свойств по умолчанию.
- Начиная с версии:
- 1.6
- См. также:
list
public void list(PrintStream out)
- Параметры:
-
out— выходной поток. - Исключения:
-
ClassCastException— если какой-либо ключ в этом списке свойств не является строкой.
list
public void list(PrintWriter out)
- Параметры:
-
out— выходной поток. - Исключения:
-
ClassCastException— если какой-либо ключ в этом списке свойств не является строкой. - Начиная с версии:
- 1.1
© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/Properties.html