java.nio.file.attribute

インタフェース UserDefinedFileAttributeView

すべてのスーパーインタフェース:

AttributeView、FileAttributeView

public interface UserDefinedFileAttributeView
extends FileAttributeView

拡張属性と呼ばれることもある、ファイルのユーザー定義属性のビューを提供するファイル属性ビューです。ユーザー定義のファイル属性は、ファイルシステムにとっては意味のないファイルを含むメタデータを格納するために使用されます。それは主に、そのような機能を直接サポートしているが、エミュレートされることもあるファイルシステム実装用です。そのようなエミュレーションの詳細は、実装によって大きく異なるため、特定できません。

この FileAttributeView は、ファイルのユーザー定義属性のビューを一連の名前と値のペアとして提供します。ここでの属性名は String で表されます。実装では、属性へのアクセス時に、プラットフォームまたはファイルシステム表現からのエンコードやデコードが必要な場合があります。値には不透明な内容が含まれます。この属性ビューは、ByteBuffer に値を読み込んだり、そこから値を書き出したりする read および write メソッドを定義します。この FileAttributeView は、属性値のサイズが Integer.MAX_VALUE よりも大きい場合には使用できません。

ユーザー定義属性は、セキュリティー関連の属性を格納するために一部の実装で使用されることがあるため、結果として、少なくともデフォルトユーザーの場合で、セキュリティーマネージャーがインストールされているときは、ユーザー定義の属性にアクセスするすべてのメソッドに RuntimePermission("accessUserDefinedAttributes") アクセス権が必要です。

supportsFileAttributeView メソッドは、特定の FileStore がユーザー定義属性の格納をサポートするかどうかを判定するために使用できます。

ファイル属性への動的アクセスが必要な場合は、getAttribute メソッドを使用してその属性値を読み取ることができます。属性値はバイト配列 (byte[]) として返されます。setAttribute メソッドは、(write メソッドを呼び出したかのように) バッファー、つまりバイト配列 (byte[]) からユーザー定義属性の値を書き出すために使用できます。

導入されたバージョン:

1.7

メソッドのサマリー

メソッド

修飾子と型	メソッドと説明
void	delete(String name) ユーザー定義属性を削除します。
List<String>	list() ユーザー定義属性の名前を含むリストを返します。
String	name() この属性ビューの名前を返します。
int	read(String name, ByteBuffer dst) ユーザー定義属性の値をバッファーに読み込みます。
int	size(String name) ユーザー定義属性の値のサイズを返します。
int	write(String name, ByteBuffer src) ユーザー定義属性の値をバッファーから書き出します。

メソッドの詳細

name

String name()

この属性ビューの名前を返します。この型の属性ビューは "user" という名前です。

定義:

name、インタフェース: AttributeView

list

List<String> list()
                  throws IOException

ユーザー定義属性の名前を含むリストを返します。

戻り値:

ファイルのユーザー定義属性の名前を含む変更不可能なリスト

例外:

IOException - 入出力エラーが発生した場合

SecurityException - デフォルトプロバイダで、セキュリティーマネージャーがインストールされていて、それが RuntimePermission("accessUserDefinedAttributes") を拒否するか、またはその checkRead メソッドがファイルへの読み取りアクセスを拒否する場合。

size

int size(String name)
         throws IOException

ユーザー定義属性の値のサイズを返します。

パラメータ:

name - 属性名

戻り値:

属性値のサイズ (バイト数)。

例外:

ArithmeticException - その属性のサイズが Integer.MAX_VALUE よりも大きい場合

IOException - 入出力エラーが発生した場合

SecurityException - デフォルトプロバイダで、セキュリティーマネージャーがインストールされていて、それが RuntimePermission("accessUserDefinedAttributes") を拒否するか、またはその checkRead メソッドがファイルへの読み取りアクセスを拒否する場合。

read

int read(String name,
       ByteBuffer dst)
         throws IOException

ユーザー定義属性の値をバッファーに読み込みます。

このメソッドは、その属性の値を指定されたバッファーにバイトのシーケンスとして読み込み、バッファー内に残っているバイト数が完全な属性値の読み込みに不十分である場合は失敗します。バッファーに転送されるバイト数は n であり、n は属性値のサイズです。シーケンス内の最初のバイトはインデックス p で、最後のバイトはインデックス p + n - 1 です。ここでの p はバッファーの位置です。復帰すると、バッファーの位置は p + n に等しくなります。その上限に変化はありません。

使用例: 「user.mimetype」という名前のユーザー定義属性として格納されているファイルの MIME タイプを読み込むとします。

    UserDefinedFileAttributeView view =
        Files.getFileAttributeView(path, UserDefinedFileAttributeView.class);
    String name = "user.mimetype";
    ByteBuffer buf = ByteBuffer.allocate(view.size(name));
    view.read(name, buf);
    buf.flip();
    String value = Charset.defaultCharset().decode(buf).toString();
 

パラメータ:

name - 属性名

dst - 宛先バッファー

戻り値:

読み込まれるバイト数。ゼロの場合もある

例外:

IllegalArgumentException - 宛先バッファーが読み取り専用である場合

IOException - 入出力エラーが発生したか、その属性値を格納できるだけの容量が宛先バッファーにない場合

SecurityException - デフォルトプロバイダで、セキュリティーマネージャーがインストールされていて、それが RuntimePermission("accessUserDefinedAttributes") を拒否するか、またはその checkRead メソッドがファイルへの読み取りアクセスを拒否する場合。

関連項目:

size(java.lang.String)

write

int write(String name,
        ByteBuffer src)
          throws IOException

ユーザー定義属性の値をバッファーから書き出します。

このメソッドは、その属性の値を指定されたバッファーからバイトのシーケンスとして書き出します。転送する値のサイズは r であり、r はバッファー内に残っているバイト数、すなわち src.remaining() です。バイトのシーケンスは、インデックス p から始まるバッファーから転送され、ここでの p はバッファーの位置です。復帰すると、バッファーの位置は p + n に等しくなり、ここでの n は転送されたバイト数です。その上限に変化はありません。

指定された名前の属性がすでに存在する場合は、その値が置換されます。その属性が存在しない場合は、それが作成されます。属性の存在をチェックするテストや属性の作成がほかのファイルシステムアクティビティーに関して原子的であるかどうかは実装に固有のものです。

属性を格納できるだけの容量がない場合、あるいは属性名または属性値が実装固有の最大サイズを超えている場合は、IOException がスローされます。

使用例: ファイルの MIME タイプをユーザー定義属性として書き出すとします。

    UserDefinedFileAttributeView view =
        FIles.getFileAttributeView(path, UserDefinedFileAttributeView.class);
    view.write("user.mimetype", Charset.defaultCharset().encode("text/html"));
 

パラメータ:

name - 属性名

src - 属性値を含むバッファー

戻り値:

書き込まれるバイト数。ゼロの場合もある

例外:

IOException - 入出力エラーが発生した場合

SecurityException - デフォルトプロバイダで、セキュリティーマネージャーがインストールされていて、それが RuntimePermission("accessUserDefinedAttributes") を拒否するか、またはその checkWrite メソッドがファイルへの書き込みアクセスを拒否する場合。

delete

void delete(String name)
            throws IOException

ユーザー定義属性を削除します。

パラメータ:

name - 属性名

例外:

IOException - 入出力エラーが発生した場合またはその属性が存在しない場合

SecurityException - デフォルトプロバイダで、セキュリティーマネージャーがインストールされていて、それが RuntimePermission("accessUserDefinedAttributes") を拒否するか、またはその checkWrite メソッドがファイルへの書き込みアクセスを拒否する場合。