Foundation 1.1.2

java.util
クラス Properties

java.lang.Object
  上位を拡張 java.util.Dictionary
      上位を拡張 java.util.Hashtable
          上位を拡張 java.util.Properties
すべての実装されたインタフェース:
Serializable, Cloneable, Map
直系の既知のサブクラス:
Provider

public class Properties
extends Hashtable

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

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

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

プロパティーをストリームに保管したり、ストリームからロードするときは、ISO 8859-1 文字エンコーディングを使用します。このエンコーディングで直接表現できない文字は、Unicode エスケープを使用します。ただし、エスケープシーケンスで使用できるのは、単一の文字 'u' だけです。native2ascii ツールを使用すると、プロパティーファイルをほかの文字エンコーディングに変換したり、その逆を実行できます。

導入されたバージョン:
JDK1.0
関連項目:
Solaris 用 native2ascii ツール, Windows 用 native2ascii ツール, 直列化された形式

フィールドの概要
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)
          入力ストリームからキーと要素が対になったプロパティーリストを読み込みます。
 Enumeration propertyNames()
          メインプロパティーリストに同じ名前のキーが見つからない場合は、デフォルトのプロパティーリストにある個別のキーを含む、このプロパティーリストにあるすべてのキーのリストを返します。
 void save(OutputStream out, String header)
          推奨されていません。 このメソッドは、プロパティーリストの保存中に入出力エラーが発生しても、IOException をスローしません。Java 2 プラットフォーム Version 1.2 以降、プロパティーリストの保存方法としては、store(OutputStream out, String header) メソッドの使用が推奨されます。
 Object setProperty(String key, String value)
          Hashtableput メソッドを呼び出します。
 void store(OutputStream out, String header)
          Properties テーブル内のプロパティーリスト (キーと要素のペア) を、load メソッドを使用して Properties テーブルにロードするのに適切なフォーマットで出力ストリームに書き込みます。
 
クラス 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 に対応する値
戻り値:
この propertylist の指定されたキーの前の値。それがない場合は 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
 

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

save

public void save(OutputStream out,
                 String header)
推奨されていません。 このメソッドは、プロパティーリストの保存中に入出力エラーが発生しても、IOException をスローしません。Java 2 プラットフォーム Version 1.2 以降、プロパティーリストの保存方法としては、store(OutputStream out, String header) メソッドの使用が推奨されます。

store(OutputStream out, String header) メソッドを呼び出すことにより、スローされた IOExceptions を抑止します。

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

store

public void store(OutputStream out,
                  String header)
           throws IOException
Properties テーブル内のプロパティーリスト (キーと要素のペア) を、load メソッドを使用して Properties テーブルにロードするのに適切なフォーマットで出力ストリームに書き込みます。ストリームは、ISO 8859-1 文字エンコーディングを使用して書き込まれます。  

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

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

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

続いて、Properties テーブル内のすべてのエントリが 1 行ずつ書き出されます。各エントリのキー文字列、ASCII 文字の =、関連した要素文字列が書き込まれます。キー文字列と要素文字内の各文字について、エスケープシーケンスにする必要があるかどうかが確認されます。ASCII 文字 \、タブ、フォームフィード、改行文字、およびキャリッジリターンは、それぞれ \\\t\f\n、および \r と記述されます。\u0020 より小さい文字および \u007E より大きい文字は、適切な 16 進値 xxxx を使用して \uxxxx として書き込まれます。キーの場合、すべての空白文字は、前に \ 文字を付けて書き込まれます。要素の場合、埋め込み空白文字でも後書き空白文字でもない先行空白文字は、前に \ を付けて書き込まれます。キーと要素の文字 #!=、および :は、必ず正しくロードされるように、前にバックスラッシュを付けて書き込まれます。  

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

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

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

Foundation 1.1.2

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

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