モジュール java.base

パッケージ 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メソッドによってファイルへの書込みアクセスが拒否されます。