JavaTM 2 Platform
Standard Ed. 5.0

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>

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

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

PropertiesHashtable を継承するので、Properties オブジェクトに対して put メソッドおよび putAll メソッドを適用できます。しかし、これらのメソッドを使用することは推奨されません。これらのメソッドを使うと、呼び出し側にキーまたは値が String ではないエントリを挿入させるからです。setProperty メソッドを代わりに使用してください。String 以外のキーまたは値を格納する「妥協的」な Properties オブジェクトで store メソッドまたは save メソッドが呼び出されると、その呼び出しは失敗します。

load および store メソッドは、以下に示す簡潔な行指向のフォーマットでプロパティをロードおよび格納します。このフォーマットでは、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
関連項目:
native2ascii tool for Solaris, native2ascii tool for Windows, 直列化された形式

フィールドの概要
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 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)
          Hashtableput メソッドを呼び出します。
 void store(OutputStream out, String comments)
          Properties テーブル内のプロパティリスト (キーと要素のペア) を、load メソッドを使用して Properties テーブルにロードするのに適切なフォーマットで出力ストリームに書き込みます。
 void storeToXML(OutputStream os, String comment)
          このテーブルに含まれるすべてのプロパティを表す XML ドキュメントを発行します。
 void storeToXML(OutputStream os, String comment, String encoding)
          このテーブルに含まれるすべてのプロパティを表す XML ドキュメントを、指定されたエンコーディングを使用して発行します。
 
クラス 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)
Hashtableput メソッドを呼び出します。getProperty メソッドと対になります。プロパティのキーおよび値に文字列を使うことを義務付けます。返された値は put への Hashtable 呼び出しの結果です。

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

load

public void load(InputStream inStream)
          throws IOException
入力ストリームからキーと要素が対になったプロパティリストを読み込みます。ストリームは、ISO 8859-1 文字エンコーディングを使用している (各バイトが 1 つの Latin1 文字である) とみなされます。Latin1 以外の文字および一部の特殊文字は、文字および文字列リテラルで使用されるエスケープシーケンスに似たエスケープシーケンスを使用してキーおよび要素内で表現できます (「Java 言語仕様」の §3.3 および §3.10.6 を参照)。 文字および文字列で使用される文字エスケープシーケンスとの違いは、次のとおりです。 入力内に不正な Unicode エスケープが存在する場合は、IllegalArgumentException がスローされます。

このメソッドは、行単位で入力を処理します。通常、入力行の終わりは、行末記号 (\n\r、または \r\n) のセットまたはファイルの終わりです。自然行は、空白の行やコメント行であるか、キーと要素のペアの一部を保持する場合があります。バックスラッシュ文字 \ を使用して行末記号シーケンスをエスケープすることで、キーと要素のペアの全データを保持する論理行が隣接する複数の自然行にまたがることが可能になります。コメント行を、この方法で複数行にまたがらせることはできません。次に示すように、コメントを含む自然行ごとに独自のコメントインジケータを指定する必要があります。行は、ファイルの終わりに達するまで入力ストリームから読み込まれます。

空白文字だけを含む自然行は、空白と見なされて無視されます。コメント行には、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
 
キーは、"cheeses" で、関連要素は空の文字列 "" であることを指定しています。

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

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(OutputStream out,
                  String comments)
           throws IOException
Properties テーブル内のプロパティリスト (キーと要素のペア) を、load メソッドを使用して Properties テーブルにロードするのに適切なフォーマットで出力ストリームに書き込みます。ストリームは、ISO 8859-1 文字セットを使用して書き込まれます。

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

comments 引数が null でない場合は、ASCII 文字の #、comments の文字列、および行区切り文字が最初に出力ストリームに書き込まれます。このため、comments は識別コメントとして使うことができます。

次に、ASCII 文字の #、現在の日時 (DatetoString メソッドによって現在時刻が生成されるのと同様)、および Writer によって生成される行区切りからなるコメント行が書き込まれます。

続いて、Properties テーブル内のすべてのエントリが 1 行ずつ書き出されます。各エントリのキー文字列、ASCII 文字の =、関連した要素文字列が書き込まれます。キーおよび要素文字列の各文字は、エスケープシーケンスとして描画する必要があるかどうか確認されます。ASCII 文字の \、タブ、フォームフィード、改行、および復帰はそれぞれ \\\t\f\n、および \r として書き込まれます。\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 の場合
導入されたバージョン:
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 - osnull、または encodingnull の場合
導入されたバージョン:
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()
メインプロパティリストに同じ名前のキーが見つからない場合は、デフォルトのプロパティリストにある個別のキーを含む、このプロパティリストにあるすべてのキーのリストを返します。

戻り値:
プロパティリストにあるすべてのキーのリスト。デフォルトのプロパティリストにあるキーを含む
関連項目:
Enumeration, defaults

list

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

パラメータ:
out - 出力ストリーム

list

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

パラメータ:
out - 出力ストリーム
導入されたバージョン:
JDK1.1

JavaTM 2 Platform
Standard Ed. 5.0

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

Copyright 2004 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。