public class Properties extends Hashtable<Object,Object>
Properties
クラスは、プロパティの永続セットを表します。Properties
を、ストリームへ保管したり、ストリームからロードしたりできます。プロパティ・リストの各キー、およびそれに対応する値は文字列です。
プロパティ・リストには、その「デフォルト値」として別のプロパティ・リストを含めることができます。元のプロパティ・リストでプロパティ・キーが見つからない場合は、この2番目のプロパティ・リストが検索されます。
Properties
はHashtable
を継承するので、Properties
オブジェクトに対してput
メソッドおよびputAll
メソッドを適用できます。しかし、これらのメソッドを使用することは推奨されません。これらのメソッドを使うと、呼出し側はキーまたは値がStrings
ではないエントリを挿入できるからです。setProperty
メソッドを代わりに使用してください。String
以外のキーまたは値を格納する「安全性の低い」Properties
オブジェクトでstore
メソッドまたはsave
メソッドが呼び出されると、その呼出しは失敗します。同様に、String
以外のキーを格納する「安全性の低い」Properties
オブジェクトでpropertyNames
またはlist
メソッドが呼び出されると、その呼出しは失敗します。
load(Reader)
/store(Writer, String)
メソッドは、以下に示す単純行指向のフォーマットでプロパティを文字ベース・ストリームに対してロードおよび格納します。load(InputStream)
/store(OutputStream, String)
メソッドはload(Reader)/store(Writer, String)ペアと同様に動作しますが、入力/出力ストリームがISO 8859-1文字エンコーディングでエンコードされる点が異なります。このエンコーディングで直接表現できない文字は、『Java™言語仕様』のセクション3.3で定義されているUnicodeエスケープを使用して記述できます。エスケープ・シーケンスで許可されるのは、単一「u」文字だけです。native2asciiツールを使用すると、プロパティ・ファイルをほかの文字エンコーディングに変換したり、その逆を実行できます。
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)にはアクセスしません。システムURIは、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オブジェクトを共有できます。
修飾子と型 | フィールドと説明 |
---|---|
protected Properties |
defaults
プロパティ・リストにないキーのデフォルト値を持つプロパティ・リストです。
|
コンストラクタと説明 |
---|
Properties()
デフォルト値を持たない空のプロパティ・リストを作成します。
|
Properties(Properties defaults)
指定されたデフォルト値を持つ空のプロパティ・リストを作成します。
|
修飾子と型 | メソッドと説明 |
---|---|
String |
getProperty(String key)
指定されたキーを持つプロパティを、プロパティ・リストから探します。
|
String |
getProperty(String key, String defaultValue)
指定されたキーを持つプロパティを、プロパティ・リストから探します。
|
void |
list(PrintStream out)
指定された出力ストリームに、プロパティ・リストを出力します。
|
void |
list(PrintWriter out)
指定された出力ストリームに、プロパティ・リストを出力します。
|
void |
load(InputStream inStream)
入力バイト・ストリームからキーと要素が対になったプロパティ・リストを読み込みます。
|
void |
load(Reader reader)
プロパティ・リスト(キーと要素のペア)を入力文字ストリームから単純な行指向形式で読み込みます。
|
void |
loadFromXML(InputStream in)
指定された入力ストリーム上のXMLドキュメントにより表されるすべてのプロパティを、このプロパティ表にロードします。
|
Enumeration<?> |
propertyNames()
メイン・プロパティ・リストに同じ名前のキーが見つからない場合は、デフォルトのプロパティ・リストにある個別のキーを含む、このプロパティ・リストにあるすべてのキーの列挙を返します。
|
void |
save(OutputStream out, String comments)
非推奨。
このメソッドは、プロパティ・リストの保存中に入出力エラーが発生しても、IOExceptionをスローしません。プロパティ・リストの保存に推奨される方法は、
store(OutputStream out, String comments) メソッドまたはstoreToXML(OutputStream os, String comment) メソッドを使用することです。 |
Object |
setProperty(String key, String value)
Hashtableのメソッド
put を呼び出します。 |
void |
store(OutputStream out, String comments)
この
Properties 表内のこのプロパティ・リスト(キーと要素のペア)を、load(InputStream) メソッドを使用してProperties 表にロードするのに適した形式で出力ストリームに書き込みます。 |
void |
store(Writer writer, String comments)
この
Properties 表内のこのプロパティ・リスト(キーと要素のペア)を、load(Reader) メソッドを使用するのに適した形式で出力文字ストリームに書き込みます。 |
void |
storeToXML(OutputStream os, String comment)
この表に含まれるすべてのプロパティを表すXMLドキュメントを発行します。
|
void |
storeToXML(OutputStream os, String comment, String encoding)
この表に含まれるすべてのプロパティを表すXMLドキュメントを、指定されたエンコーディングを使用して発行します。
|
Set<String> |
stringPropertyNames()
メイン・プロパティ・リストに同じ名前のキーが見つからない場合は、デフォルトのプロパティ・リストにある個別のキーを含む、キーとそれに対応する値が文字列であるようなこのプロパティ・リスト内のキーのセットを返します。
|
clear, clone, compute, computeIfAbsent, computeIfPresent, contains, containsKey, containsValue, elements, entrySet, equals, forEach, get, getOrDefault, hashCode, isEmpty, keys, keySet, merge, put, putAll, putIfAbsent, rehash, remove, remove, replace, replace, replaceAll, size, toString, values
protected Properties defaults
public Properties()
public Properties(Properties defaults)
defaults
- デフォルト値。public Object setProperty(String key, String value)
put
を呼び出します。getPropertyメソッドと対になります。プロパティのキーおよび値に文字列を使うことを義務付けます。返される値はput
へのHashtable呼出しの結果です。key
- プロパティ・リストに配置されるキー。value
- keyに対応する値。null
。getProperty(java.lang.String)
public void load(Reader reader) throws IOException
Propertiesは行単位で処理されます。行には自然行と論理行の2種類があります。自然行は、行末記号(\n
、\r
、または\r\n
)のセットまたはストリームの末尾で区切られた1行の文字列として定義されます。自然行は、空白の行やコメント行であるか、キーと要素のペアの全部または一部を保持する場合があります。論理行は、キーと要素のペアの全データを保持します。バックスラッシュ文字\
を使用して行末記号シーケンスをエスケープすることで、隣接する複数の自然行にまたがる場合があります。コメント行を、この方法で複数行にまたがらせることはできません。後述するように、コメントであるすべての自然行には、それぞれにコメント・インジケータが必要です。行は、ストリームの終わりに達するまで入力から読み込まれます。
空白文字だけを含む自然行は、空白と見なされて無視されます。コメント行には、ASCII '#'
または'!'
が最初の非空白文字として含まれます。コメント行も無視され、キーと要素の情報はエンコードされません。このフォーマットは、行終了文字に加え、文字スペース(' '
、'\u0020'
)、タブ('\t'
、'\u0009'
)、およびフォーム・フィード('\f'
、'\u000C'
)を空白と見なします。
論理行が複数の自然行にまたがる場合、行末記号シーケンスをエスケープするバックスラッシュ、行末記号シーケンス、および次の行の先頭の空白文字は、キーまたは要素の値に何の影響も及ぼしません。(ロード時の)キーと要素の構文解析に関する残りの記述では、行継続文字が削除されたあとで、キーと要素を構成するすべての文字が単一の自然行に表示されることを前提として説明します。行末記号がエスケープされているかどうかを判定する場合、行末記号シーケンスの前の文字を調べるだけでは十分ではありません。行末記号がエスケープされるためには、連続した奇数のバックスラッシュが存在する必要があります。入力は左から右に処理されるため、行末記号の前(またはほかの場所)に連続したバックスラッシュが2n (ゼロでない偶数)個存在する場合、エスケープ処理後にn個のバックスラッシュがエンコードされます。
キーには最初の非空白文字から、最初のエスケープされていない'='
、':'
、または空白文字の手前までの文字すべて(行末記号を除く)が含まれます。これらキーの終わりを示す文字はすべて、バックスラッシュを前に付けてエスケープすることでキーに含めることができます。たとえば、
\:\=
には、2文字のキー":="
が含まれます。行末記号は、エスケープ・シーケンス\r
および\n
を使用して含めることができます。キーのあとの空白はすべてスキップされます。キーに続く最初の非空白文字が'='
または':'
である場合、これは無視され、その後の空白文字もすべてスキップされます。行上の残りのすべての文字は、関連付けられた要素文字列の一部になります。残りの文字がない場合、その要素は空の文字列""
です。キーと要素を構成する生の文字シーケンスが識別されると、エスケープ処理が前述の方法で実行されます。
たとえば、次の3行はそれぞれキー"Truth"
と、関連した要素値"Beauty"
を表します。
Truth = Beauty Truth:Beauty Truth :Beautyまた、次の3行は1つのプロパティを表します。
fruits apple, banana, pear, \ cantaloupe, watermelon, \ kiwi, mangoキーは
"fruits"
で、次の要素に関連付けれられています。
"apple, banana, pear, cantaloupe, watermelon, kiwi, mango"最終的な結果でカンマのあとに必ずスペースが表示されるように、各
\
の前にスペースがあります。行の終わりを示す\
と、継続行の先頭にある空白は破棄され、ほかの文字に置換されません。
また、次の3番目の例では、行:
cheesesは、キーが
"cheeses"
で、関連付けられている要素が空の文字列""
であることを表します。
キーと要素に含まれる文字は、文字リテラルや文字列リテラルで使用されるエスケープ・シーケンスに似たシーケンスで表現できます(「Java(tm)言語仕様」のセクション3.3と3.10.6を参照)。文字および文字列で使用される文字エスケープ・シーケンスやUnicodeエスケープとの違いは、次のとおりです。
\b
は、バックスペース文字を表さない。
\
をエラーとして処理しない。バックスラッシュは自動的に削除される。たとえば、Java文字列にシーケンス"\z"
が含まれていると、コンパイル時にエラーが発生する。これに対し、このメソッドは自動的にバックスラッシュを削除する。このため、このメソッドでは2文字のシーケンス"\b"
は単一の文字'b'
と等価であると見なされる。
指定されたストリームは、このメソッドが復帰したあとも開いたままです。
reader
- 入力文字ストリーム。IOException
- 入力ストリームからの読込み中にエラーが発生した場合。IllegalArgumentException
- 形式が不正なUnicodeエスケープが入力内に現れた場合。public void load(InputStream inStream) throws IOException
load(Reader)
で規定される単純行指向フォーマットで、ISO 8859-1文字エンコーディングを使用することが前提されます。つまり、各バイトは1つのLatin1文字です。Latin1にない文字、および一部の特殊文字は、キーや要素内で『Java™言語仕様』のセクション3.3で定義されているUnicodeエスケープを使用して表現されます。
指定されたストリームは、このメソッドが復帰したあとも開いたままです。
inStream
- 入力ストリーム。IOException
- 入力ストリームからの読込み中にエラーが発生した場合。IllegalArgumentException
- 入力ストリームに形式が不正なUnicodeエスケープ・シーケンスが含まれる場合。@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
ではないキーまたは値が含まれている場合。public void store(Writer writer, String comments) throws IOException
Properties
表内のこのプロパティ・リスト(キーと要素のペア)を、load(Reader)
メソッドを使用するのに適した形式で出力文字ストリームに書き込みます。
このProperties
表(存在する場合)のデフォルト表からのプロパティは、このメソッドによって書き込まれません。
comments引数がnullでない場合は、ASCII文字の#
、commentsの文字列、および行区切り文字が最初に出力ストリームに書き込まれます。このため、comments
は識別コメントとして使うことができます。改行(「\n」)、キャリッジ・リターン(「\r」)、改行が直後に続くキャリッジ・リターン、のいずれかがコメント内に現れると、それは、Writer
によって生成された1個の行区切り文字で置き換えられます。そして、コメント内の次の文字が文字#
でも文字!
でもなかった場合、その行区切り文字のあとにASCII #
が書き出されます。
次に、ASCII文字の#
、現在の日時(Date
のtoString
メソッドによって現在時刻が生成されるのと同様)、およびWriter
によって生成される行区切り文字からなるコメント行が書き込まれます。
続いて、このProperties
表内のすべてのエントリが1行に1つずつ書き出されます。各エントリのキー文字列、ASCII文字の=
、関連付けられた要素文字列が書き込まれます。キーの場合、すべての空白文字は、前に\
文字を付けて書き込まれます。要素の場合、埋込み空白文字でも後書き空白文字でもない先行空白文字は、前に\
を付けて書き込まれます。キーと要素の文字#
、!
、=
、および:
は、必ず正しくロードされるように、前にバックスラッシュを付けて書き込まれます。
エントリが書き込まれたあとで、出力ストリームがフラッシュされます。出力ストリームはこのメソッドから復帰したあとも開いたままです。
writer
- 出力文字ストリーム・ライター。comments
- プロパティ・リストの記述。IOException
- 指定された出力ストリームへのこのプロパティ・リストの書込み時にIOExceptionがスローされた場合。ClassCastException
- このProperties
オブジェクトに、Strings
ではないキーまたは値が含まれている場合。NullPointerException
- writer
がnullである場合。public void store(OutputStream out, String comments) throws IOException
Properties
表内のこのプロパティ・リスト(キーと要素のペア)を、load(InputStream)
メソッドを使用してProperties
表にロードするのに適した形式で出力ストリームに書き込みます。
このProperties
表(存在する場合)のデフォルト表からのプロパティは、このメソッドによって書き込まれません。
このメソッドは、コメントおよびプロパティのキーと値を、store(Writer)
で規定されたのと同じ形式で出力します。ただし、次の点が異なります。
\u
xxxxとして書き込まれる。
\u0020
より小さい文字および\u007E
より大きい文字は、適切な16進値xxxxを使用して\u
xxxxとして書き込まれる。
エントリが書き込まれたあとで、出力ストリームがフラッシュされます。出力ストリームはこのメソッドから復帰したあとも開いたままです。
out
- 出力ストリーム。comments
- プロパティ・リストの記述。IOException
- 指定された出力ストリームへのこのプロパティ・リストの書込み時にIOExceptionがスローされた場合。ClassCastException
- このProperties
オブジェクトに、Strings
ではないキーまたは値が含まれている場合。NullPointerException
- out
がnullである場合。public void loadFromXML(InputStream in) throws IOException, InvalidPropertiesFormatException
XMLドキュメントには、次のDOCTYPE宣言が必要です。
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">さらに、ドキュメントは前述のプロパティDTDを満たす必要があります。
実装は、UTF-8
またはUTF-16
エンコーディングを使用するXMLドキュメントを読み取る必要があります。実装は追加のエンコーディングをサポートできます。
このメソッドが戻ると、指定されたストリームが閉じられます。
in
- XMLドキュメントの読込み元の入力ストリーム。IOException
- 指定された入力ストリームからの読込み時にIOExceptionが発生した場合。UnsupportedEncodingException
- ドキュメントのエンコーディング宣言を読み取ることができ、そこにサポートされていないエンコーディングが指定されている場合InvalidPropertiesFormatException
- 入力ストリーム上のデータが、要求されたドキュメント型を持つ有効なXMLドキュメントにならない場合。NullPointerException
- in
がnullである場合。storeToXML(OutputStream, String, String)
、Character Encoding in Entitiespublic 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
ではないキーまたは値が含まれている場合。loadFromXML(InputStream)
public void storeToXML(OutputStream os, String comment, String encoding) throws IOException
このXMLドキュメントでは、次のDOCTYPEが宣言されます。
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
指定されたコメントがnull
の場合、ドキュメントにコメントは格納されません。
実装は、UTF-8
またはUTF-16
エンコーディングを使用するXMLドキュメントの書込みをサポートする必要があります。実装は追加のエンコーディングをサポートできます。
指定されたストリームは、このメソッドが復帰したあとも開いたままです。
os
- XMLドキュメントの発行先の出力ストリームcomment
- プロパティ・リストの記述。コメントが必要ない場合はnull
。encoding
- サポートされる文字エンコーディングの名前IOException
- 指定された出力ストリームへの書込み時にIOExceptionが発生した場合。UnsupportedEncodingException
- エンコーディングが実装によってサポートされない場合。NullPointerException
- os
がnull
、またはencoding
がnull
の場合。ClassCastException
- このProperties
オブジェクトに、Strings
ではないキーまたは値が含まれている場合。loadFromXML(InputStream)
、Character Encoding in Entitiespublic String getProperty(String key)
null
が返されます。key
- プロパティ・キーsetProperty(java.lang.String, java.lang.String)
, defaults
public String getProperty(String key, String defaultValue)
key
- ハッシュ表キー。defaultValue
- デフォルト値。setProperty(java.lang.String, java.lang.String)
, defaults
public Enumeration<?> propertyNames()
ClassCastException
- 文字列でないキーがこのプロパティ・リスト内に存在する場合。Enumeration
, defaults
, stringPropertyNames()
public Set<String> stringPropertyNames()
返されたセットは、Propertiesオブジェクトに関連付けられていません。このPropertiesへの変更はセットには反映されません。その逆も同様です。
defaults
public void list(PrintStream out)
out
- 出力ストリーム。ClassCastException
- 文字列でないキーがこのプロパティ・リスト内に存在する場合。public void list(PrintWriter out)
out
- 出力ストリーム。ClassCastException
- 文字列でないキーがこのプロパティ・リスト内に存在する場合。 バグまたは機能を送信
詳細なAPIリファレンスおよび開発者ドキュメントについては、Java SEのドキュメントを参照してください。そのドキュメントには、概念的な概要、用語の定義、回避方法、有効なコード例などの、開発者を対象にしたより詳細な説明が含まれています。
Copyright© 1993, 2014, Oracle and/or its affiliates. All rights reserved.