Properties (Java Platform SE 6)

概要

パッケージ

クラス

使用

階層ツリー

非推奨 API

索引

ヘルプ

Java^TM Platform
Standard Ed. 6

前のクラス 次のクラス

フレームあり フレームなし

概要: 入れ子 | フィールド | コンストラクタ | メソッド

詳細: フィールド | コンストラクタ | メソッド

java.util
クラス Properties

java.lang.Object
  java.util.Dictionary<K,V>
      java.util.Hashtable<Object,Object>
          java.util.Properties

すべての実装されたインタフェース:: Serializable, Cloneable, Map<Object,Object>

直系の既知のサブクラス:: Provider

public class Properties
extends Hashtable<Object,Object>
extends Hashtable<Object,Object>

Properties クラスは、不変のプロパティーセットを表します。Properties を、ストリームへ保管したり、ストリームからロードしたりできます。プロパティーリストの各キー、およびそれに対応する値は文字列です。

プロパティリストには、その「デフォルト値」として別のプロパティリストを持つことができます。元のプロパティリストでプロパティキーが見つからないと、この 2 番目のプロパティリストが検索されます。

Properties は Hashtable を継承するので、Properties オブジェクトに対して put メソッドおよび putAll メソッドを適用できます。しかし、これらのメソッドを使用することは推奨されません。これらのメソッドを使うと、呼び出し側にキーまたは値が String ではないエントリを挿入させるからです。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 文字エンコーディングでエンコードされる点だけは異なります。このエンコーディングで直接表現できない文字は、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>

導入されたバージョン:: JDK1.0
関連項目:: Solaris 用 native2ascii ツール, Windows 用 native2ascii ツール
このクラスはスレッドセーフです。外部の同期化を行わなくても、複数のスレッドで単一の 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()` メインプロパティーリストに同じ名前のキーが見つからない場合は、デフォルトのプロパティーリストにある個別のキーを含む、キーとそれに対応する値が文字列であるようなこのプロパティーリスト内のキーのセットを返します。

クラス java.util.Hashtable から継承されたメソッド
`clear, clone, contains, containsKey, containsValue, elements, entrySet, equals, get, hashCode, isEmpty, keys, keySet, put, putAll, rehash, remove, size, toString, values`

クラス java.lang.Object から継承されたメソッド
`finalize, getClass, notify, notifyAll, wait, wait, wait`

フィールドの詳細

defaults

protected Properties defaults

プロパティリストにないキーのデフォルト値を持つプロパティリストです。

コンストラクタの詳細

Properties

public Properties()

デフォルト値を持たない空のプロパティリストを作成します。

Properties

public Properties(Properties defaults)

指定されたデフォルト値を持つ空のプロパティリストを作成します。

パラメータ:: defaults - デフォルト値

メソッドの詳細

setProperty

public Object setProperty(String key,
                          String value)

Hashtable の put メソッドを呼び出します。getProperty メソッドと対になります。プロパティーのキーおよび値に文字列を使うことを義務付けます。返された値は put への Hashtable 呼び出しの結果です。

パラメータ:: key - プロパティリストに配置されるキー; value - key に対応する値
戻り値:: このプロパティーリスト内での指定されたキーの以前の値。このキーが値を持っていなかった場合は null
導入されたバージョン:: 1.2
関連項目:: getProperty(java.lang.String)

load

public void load(Reader reader)
          throws IOException

プロパティーリスト (キーと要素のペア) を入力文字ストリームから単純な行指向形式で読み込みます。

プロパティーは行単位で処理されます。行には「自然行」と「論理行」の 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 エスケープとの違いは、次のとおりです。

8 進数のエスケープは認識されない
文字シーケンス \b は、バックスペース文字を表さない
このメソッドは、無効なエスケープ文字の前のバックスラッシュ文字 \ をエラーとして処理しない。バックスラッシュは単に削除される。たとえば、Java の文字列にシーケンス「\z」が含まれていると、コンパイル時にエラーが発生する。これに対し、このメソッドは何の通知もなくバックスラッシュを削除する。このため、このメソッドでは 2 文字のシーケンス「\b」は単一の文字「b」と等価であると見なされる
単一引用符および二重引用符では、エスケープは不要である。ただし、前述の規則に従って、バックスラッシュに続く単一および二重引用符文字も、それぞれ単一引用符文字と二重引用符文字として処理される
1 つの Uniocde エスケープシーケンス内に含めることのできる「u」文字は、1 つだけである。

指定されたストリームは、このメソッドが復帰したあとも開いたままです。

パラメータ:: reader - 入力文字ストリーム
例外:: IOException - 入力ストリームからの読み込み中にエラーが発生した場合; IllegalArgumentException - 不正な Unicode エスケープが入力内に現れた場合
導入されたバージョン:: 1.6

load

public void load(InputStream inStream)
          throws IOException

入力バイトストリームからキーと要素が対になったプロパティーリストを読み込みます。入力ストリームは load(Reader) で規定された単純な行指向形式であり、ISO 8859-1 文字エンコーディングを使用しているものとみなされます。つまり、各バイトが 1 個の Latin1 文字になります。Latin1 に含まれない文字やいくつかの特殊文字は、キーや要素内では Unicode エスケープを使って表されます。

指定されたストリームは、このメソッドが復帰したあとも開いたままです。

パラメータ:: inStream - 入力ストリーム
例外:: IOException - 入力ストリームからの読み込み中にエラーが発生した場合; IllegalArgumentException - 入力ストリームに不正な Unicode エスケープシーケンスが含まれる場合
導入されたバージョン:: 1.2

save

@Deprecated
public void save(OutputStream out,
                            String comments)

推奨されていません。 このメソッドは、プロパティーリストの保存中に入出力エラーが発生しても、IOException をスローしません。プロパティーリストの保存方法としては、store(OutputStream out, String comments) メソッドまたは storeToXML(OutputStream os, String comment) メソッドの使用が推奨されます。

store(OutputStream out, String comments) メソッドを呼び出して、スローされた IOExceptions を抑止します。

パラメータ:: out - 出力ストリーム; comments - プロパティリストの記述
例外:: ClassCastException - この Properties オブジェクトに、String ではないキーまたは値が格納されている場合

store

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 行ずつ書き出されます。各エントリのキー文字列、ASCII 文字の =、関連した要素文字列が書き込まれます。キーの場合、すべての空白文字は、前に \ 文字を付けて書き込まれます。要素の場合、埋め込み空白文字でも後書き空白文字でもない先行空白文字は、前に \ を付けて書き込まれます。キーと要素の文字 #、!、=、および :は、必ず正しくロードされるように、前にバックスラッシュを付けて書き込まれます。

エントリが書き込まれたあとで、出力ストリームがフラッシュされます。出力ストリームはこのメソッドから復帰したあとも開いたままです。

パラメータ:: writer - 出力文字ストリームライター; comments - プロパティリストの記述
例外:: IOException - このプロパティリストを指定した出力ストリームに書き込んで、IOException がスローされた場合; ClassCastException - この Properties オブジェクトに、String ではないキーまたは値が格納されている場合; NullPointerException - writer が null の場合
導入されたバージョン:: 1.6

store

public void store(OutputStream out,
                  String comments)
           throws IOException

Properties テーブル内のプロパティーリスト (キーと要素のペア) を、load(InputStream) メソッドを使用して Properties テーブルにロードするのに適切なフォーマットで出力ストリームに書き込みます。

Properties テーブル (存在する場合) のデフォルトテーブルからのプロパティは、このメソッドによっては書き込まれません。

このメソッドは、コメントおよびプロパティーのキーと値を、store(Writer) で規定されたのと同じ形式で出力します。ただし、次の点が異なります。

ストリームは、ISO 8859-1 文字エンコーディングを使用して書き込まれます。
コメント内の Latin-1 でない文字は、適切な Unicode 16 進値 xxxx を使用して \uxxxx として書き込まれる。
プロパティーのキーまたは値に含まれる \u0020 より小さい文字および \u007E より大きい文字は、適切な 16 進値 xxxx を使用して \uxxxx として書き込まれる。

エントリが書き込まれたあとで、出力ストリームがフラッシュされます。出力ストリームはこのメソッドから復帰したあとも開いたままです。

パラメータ:: out - 出力ストリーム; comments - プロパティリストの記述
例外:: IOException - このプロパティリストを指定した出力ストリームに書き込んで、IOException がスローされた場合; ClassCastException - この Properties オブジェクトに、String ではないキーまたは値が格納されている場合; NullPointerException - out が null の場合
導入されたバージョン:: 1.2

loadFromXML

public void loadFromXML(InputStream in)
                 throws IOException,
                        InvalidPropertiesFormatException

指定された入力ストリーム上の XML ドキュメントにより表されるすべてのプロパティーを、このプロパティーテーブルにロードします。

XML ドキュメントには、次の DOCTYPE 宣言が必要です。

 <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">

さらに、ドキュメントは前述のプロパティー DTD を満たす必要があります。

このメソッドが戻ると、指定されたストリームが閉じられます。

パラメータ:: in - XML ドキュメントの読み込み元の入力ストリーム
例外:: IOException - 指定された入力ストリームからの読み取り時に IOException が発生した場合; InvalidPropertiesFormatException - 入力ストリーム上のデータが、要求されたドキュメント型を持つ有効な XML ドキュメントにならない場合; NullPointerException - in が null の場合
導入されたバージョン:: 1.5
関連項目:: storeToXML(OutputStream, String, String)

storeToXML

public void storeToXML(OutputStream os,
                       String comment)
                throws IOException

このテーブルに含まれるすべてのプロパティーを表す XML ドキュメントを発行します。

このメソッドを props.storeToXML(os, comment) の形式で呼び出した場合、props.storeToXML(os, comment, "UTF-8"); の呼び出しと同じ結果が得られます。

パラメータ:: os - XML ドキュメントの発行先の出力ストリーム; comment - プロパティーリストの説明。コメントが必要ない場合は null
例外:: IOException - 指定された出力ストリームへの書き込み時に IOException が発生した場合; NullPointerException - os が null の場合; ClassCastException - この Properties オブジェクトに、String ではないキーまたは値が格納されている場合
導入されたバージョン:: 1.5
関連項目:: loadFromXML(InputStream)

storeToXML

public void storeToXML(OutputStream os,
                       String comment,
                       String encoding)
                throws IOException

このテーブルに含まれるすべてのプロパティーを表す XML ドキュメントを、指定されたエンコーディングを使用して発行します。

この XML ドキュメントでは、次の DOCTYPE が宣言されます。

 <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">

指定されたコメントが null の場合、ドキュメントにコメントは格納されません。

指定されたストリームは、このメソッドが復帰したあとも開いたままです。

パラメータ:: os - XML ドキュメントの発行先の出力ストリーム; comment - プロパティーリストの説明。コメントが必要ない場合は null
例外:: IOException - 指定された出力ストリームへの書き込み時に IOException が発生した場合; NullPointerException - os が null の場合、または encoding が null の場合; ClassCastException - この Properties オブジェクトに、String ではないキーまたは値が格納されている場合
導入されたバージョン:: 1.5
関連項目:: loadFromXML(InputStream)

getProperty

public String getProperty(String key)

指定されたキーを持つプロパティーを、プロパティーリストから探します。そのキーがプロパティーリストにないと、デフォルトのプロパティーリスト、さらにそのデフォルト値が繰り返し調べられます。そのプロパティーが見つからない場合は、null が返されます。

パラメータ:: key - プロパティキー
戻り値:: 指定されたキー値を持つこのプロパティリストの値
関連項目:: setProperty(java.lang.String, java.lang.String), defaults

getProperty

public String getProperty(String key,
                          String defaultValue)

指定されたキーを持つプロパティーを、プロパティーリストから探します。そのキーがプロパティーリストにないと、デフォルトのプロパティーリスト、さらにそのデフォルト値が繰り返し調べられます。そのプロパティーが見つからない場合は、デフォルト値の引数が返されます。

パラメータ:: key - ハッシュテーブルキー; defaultValue - デフォルト値
戻り値:: 指定されたキー値を持つこのプロパティリストの値
関連項目:: setProperty(java.lang.String, java.lang.String), defaults

propertyNames

public Enumeration<?> propertyNames()

メインプロパティーリストに同じ名前のキーが見つからない場合は、デフォルトのプロパティーリストにある個別のキーを含む、このプロパティーリストにあるすべてのキーのリストを返します。

戻り値:: プロパティリストにあるすべてのキーのリスト。デフォルトのプロパティリストにあるキーを含む
例外:: ClassCastException - 文字列でないキーがこのプロパティーリスト内に存在する場合
関連項目:: Enumeration, defaults, stringPropertyNames()

stringPropertyNames

public Set<String> stringPropertyNames()

メインプロパティーリストに同じ名前のキーが見つからない場合は、デフォルトのプロパティーリストにある個別のキーを含む、キーとそれに対応する値が文字列であるようなこのプロパティーリスト内のキーのセットを返します。キーまたは値が型 String でないプロパティーは省略されます。

返されたセットは、Properties オブジェクトに関連付けられていません。この Properties への変更はセットには反映されません。その逆も同様です。

戻り値:: キーとそれに対応する値が文字列であるようなこのプロパティーリスト内のキーのセット。デフォルトプロパティーリスト内のキーも含む
導入されたバージョン:: 1.6
関連項目:: defaults

list

public void list(PrintStream out)

指定された出力ストリームに、プロパティーリストを出力します。このメソッドはデバッグに便利です。

パラメータ:: out - 出力ストリーム
例外:: ClassCastException - 文字列でないキーがこのプロパティーリスト内に存在する場合

list

public void list(PrintWriter out)

指定された出力ストリームに、プロパティーリストを出力します。このメソッドはデバッグに便利です。

パラメータ:: out - 出力ストリーム
例外:: ClassCastException - 文字列でないキーがこのプロパティーリスト内に存在する場合
導入されたバージョン:: JDK1.1

概要

パッケージ

クラス

使用

階層ツリー

非推奨 API

索引

ヘルプ

Java^TM Platform
Standard Ed. 6

前のクラス 次のクラス

フレームあり フレームなし

概要: 入れ子 | フィールド | コンストラクタ | メソッド

詳細: フィールド | コンストラクタ | メソッド

バグの報告と機能のリクエスト
さらに詳しい API リファレンスおよび開発者ドキュメントについては、Java SE 開発者用ドキュメントを参照してください。開発者向けの詳細な解説、概念の概要、用語の定義、バグの回避策、およびコード実例が含まれています。

java.util クラス Properties

defaults

Properties

Properties

setProperty

load

load

save

store

store

loadFromXML

storeToXML

storeToXML

getProperty

getProperty

propertyNames

stringPropertyNames

list

list

java.util
クラス Properties