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 文字エンコーディングが使用されますが、必要に応じてエンコーディングを指定できます。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()
メインプロパティーリストに同じ名前のキーが見つからない場合は、デフォルトのプロパティーリストにある個別のキーを含む、キーとそれに対応する値が文字列であるようなこのプロパティーリスト内のキーのセットを返します。
|
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™ 言語仕様」のセクション 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 を満たす必要があります。
このメソッドが戻ると、指定されたストリームが閉じられます。
in
- XML ドキュメントの読み込み元の入力ストリーム。IOException
- 指定された入力ストリームからの読み込み時に IOException が発生した場合。InvalidPropertiesFormatException
- 入力ストリーム上のデータが、要求されたドキュメント型を持つ有効な XML ドキュメントにならない場合。NullPointerException
- in
が null である場合。storeToXML(OutputStream, String, String)
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
ではないキーまたは値が含まれている場合。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
の場合、ドキュメントにコメントは格納されません。
指定されたストリームは、このメソッドが復帰したあとも開いたままです。
os
- XML ドキュメントの発行先の出力ストリームcomment
- プロパティーリストの記述。コメントが必要ない場合は null
。encoding
- サポートされる文字エンコーディングの名前IOException
- 指定された出力ストリームへの書き込み時に IOException が発生した場合。NullPointerException
- os
が null
、または encoding
が null
の場合。ClassCastException
- この Properties
オブジェクトに、Strings
ではないキーまたは値が含まれている場合。loadFromXML(InputStream)
public 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, 2013, Oracle and/or its affiliates. All rights reserved.