- すべての実装されたインタフェース:
Closeable,AutoCloseable,ByteChannel,Channel,GatheringByteChannel,InterruptibleChannel,ReadableByteChannel,ScatteringByteChannel,SeekableByteChannel,WritableByteChannel
ファイル・チャネルは、ファイルに接続されるSeekableByteChannelです。 これは、ファイル内に、照会および変更が可能な現在の位置を持っています。 ファイル自体には、読み込み/書き込みと現在のサイズの照会が可能な可変長のバイト・シーケンスが含まれています。 ファイルのサイズは、現在のサイズを上回るバイト数が書き込まれると大きくなり、切り詰めによって小さくなります。 ファイルには、アクセス許可、コンテンツ・タイプ、最終更新時間などのメタデータも関連付けられています。このクラスは、メタデータ・アクセスのためのメソッドを定義しません。
このクラスは、バイト・チャネルに対する一般的な操作(読み込み、書き込み、クローズ)のほかに、次のようなファイル固有の操作を定義します。
ファイルのリージョンは、メモリーに直接
mappedになる場合があります。大規模ファイルの場合は、通常のreadまたはwriteメソッドを呼び出すよりもはるかに効率的です。ファイルの更新は、基礎となっている記憶装置に
forced outされます。したがって、システムがクラッシュしてもデータの損失は回避されます。バイトはファイルから
ほかのチャネルへ転送できる。反対に、ほかのチャネルから転送することもできる。多くのオペレーティング・システムでは、ファイル・システムのキャッシュとの間で非常に高速で直接転送することにより、この転送を最適化できる。ファイルの領域は、その他のプログラムからアクセスできないように
ロックされます。
ファイル・チャネルは、複数の並行スレッドで安全に使用できます。 closeメソッドは、Channelインタフェースの指定どおりにいつでも呼び出せます。 チャネルの位置を使用する操作、またはファイル・サイズを変更する可能性がある操作は、1つずつ実行することになっています。前の操作の進行中に同じような操作を新しく開始しようとすると、最初の操作が終わるまで新しい操作はブロックされます。 その他の操作、とりわけ明示的な位置を使用する操作は、前の操作と同時並行で実行できます。同時並行処理が行われるかどうかは基礎となる実装によって決まるため、未指定です。
このクラスのインスタンスによって提供されたファイルのビューは、同じプログラム内のその他のインスタンスによって提供された同じファイルのビューと矛盾しないことが保証されています。 しかし、基礎となるオペレーティング・システムのキャッシュ処理や、ネットワーク・ファイル・システム・プロトコルによる遅延が原因で、このクラスのインスタンスによって提供されたビューと、並行して実行されているプログラムで認識されるその他のビューが矛盾する可能性がないわけではありません。 この問題は、これらのプログラムを記述している言語の違いや、これらが同一マシンで実行されているかどうかとは関係なく発生します。 こうした矛盾は、システムによって生じるものであるため未指定です。
ファイル・チャネルは、このクラスによって定義されるopenメソッドの1つを呼び出すことによって作成されます。 ファイル・チャネルは、既存のFileInputStream、FileOutputStreamまたはRandomAccessFileオブジェクトからも取得できます。そのオブジェクトのgetChannelメソッドを呼び出すと、同じ基礎となるファイルに接続されているファイル・チャネルが返されます。 ファイル・チャネルが既存のストリームまたはランダム・アクセス・ファイルから取得される場合、ファイル・チャネルの状態は、getChannelメソッドがチャネルを返したオブジェクトの状態と直結的に接続されます。 たとえば、チャネルの位置を明示的に、あるいはバイトの読込みや書込みによって変更すると、発生元のオブジェクトのファイル位置が変わります(逆も同様)。 ファイル・チャネルからファイルの長さを変更すると、発生元オブジェクトから見たときの長さが変わります(逆も同様)。 バイトの書込みによってファイルのコンテンツを変更すると、元のオブジェクトから見たときのコンテンツが変わります(逆も同様)。 チャネルを閉じると、元のオブジェクトが閉じます。
このクラスは、さまざまな点で、「読込み可能」、「書込み可能」、または「読み込みと書込みが可能」であるインスタンスが必要なことを指定しています。 FileInputStreamインスタンスのgetChannelメソッドで取得されたチャネルは読込み可能です。 FileOutputStreamインスタンスのgetChannelメソッドで取得されたチャネルは書込み可能です。 最後に、RandomAccessFileインスタンスのgetChannelメソッドを介して取得されたチャネルは、インスタンスがモード"r"で作成された場合、読取り用にオープンされ、インスタンスがモード"rw"で作成された場合、読取りおよび書込み用にオープンされます。
書込み用にオープンしているファイル・チャネルは、たとえば、FileOutputStream(File,boolean)コンストラクタを呼び出して2番目のパラメータにtrueを渡すことによって作成されたファイル出力ストリームから取得された場合、「追加モード」にあります。 このモードで関連した書込み操作を呼び出すと、まず位置がファイルの末尾まで進みます。その後、要求されたデータが書き込まれます。 このような位置の移動とデータの書込みは、不可分な単一の操作として行われます。この操作は、システムに依存しているため未指定です。 このモードでは、「指定された位置に書き込む」に対するメソッドの動作もシステムに依存します。
- 導入されたバージョン:
- 1.4
- 関連項目:
-
ネストされたクラスのサマリー
ネストされたクラス -
コンストラクタのサマリー
コンストラクタ -
メソッドのサマリー
修飾子と型メソッド説明abstract voidforce(boolean metaData) このチャネルのファイルの更新内容は、その記憶装置に強制的に書き込まれます。final FileLocklock()このチャネルのファイル上に排他ロックを設定します。abstract FileLocklock(long position, long size, boolean shared) このチャネルのファイルの指定された領域をロックします。abstract MappedByteBuffermap(FileChannel.MapMode mode, long position, long size) このチャネルのファイルの領域を直接メモリーにマッピングします。map(FileChannel.MapMode mode, long offset, long size, Arena arena) 指定されたオフセット、サイズおよびアリーナを使用して、このチャネルのファイルのリージョンを新しいマップされたメモリー・セグメントにマップします。static FileChannelopen(Path path, OpenOption... options) ファイルを開くか作成し、そのファイルにアクセスするためのファイル・チャネルを返します。static FileChannelopen(Path path, Set<? extends OpenOption> options, FileAttribute<?>... attrs) ファイルを開くか作成し、そのファイルにアクセスするためのファイル・チャネルを返します。abstract longposition()このチャネルのファイル位置を返します。abstract FileChannelposition(long newPosition) このチャネルのファイル位置を設定します。abstract intread(ByteBuffer dst) このチャネルのバイト・シーケンスを指定のバッファに読み込みます。final longread(ByteBuffer[] dsts) このチャネルのバイト・シーケンスを指定されたバッファに読み込みます。abstract longread(ByteBuffer[] dsts, int offset, int length) このチャネルのバイト・シーケンスを指定されたバッファのサブシーケンスに読み込みます。abstract intread(ByteBuffer dst, long position) このチャネルのバイト・シーケンスを、指定されたファイル位置からバッファに読み込みます。abstract longsize()このチャネルのファイルの現在のサイズを返します。abstract longtransferFrom(ReadableByteChannel src, long position, long count) 指定された読込み可能なバイト・チャネルからこのチャネルのファイルへバイトを転送します。abstract longtransferTo(long position, long count, WritableByteChannel target) このチャネルのファイルから指定された書込み可能なバイト・チャネルへバイトを転送します。abstract FileChanneltruncate(long size) このチャネルのファイルの末尾を切詰め、指定されたサイズにします。final FileLocktryLock()このチャネルのファイル上で排他ロックを獲得しようとします。abstract FileLocktryLock(long position, long size, boolean shared) このチャネルのファイルの指定された領域でロックを獲得しようとします。abstract intwrite(ByteBuffer src) このチャネルのバイト・シーケンスを指定のバッファから書き出します。final longwrite(ByteBuffer[] srcs) このチャネルのバイト・シーケンスを指定されたバッファから書き出します。abstract longwrite(ByteBuffer[] srcs, int offset, int length) このチャネルのバイト・シーケンスを指定されたバッファのサブシーケンスから書き出します。abstract intwrite(ByteBuffer src, long position) 指定されたバッファのバイト・シーケンスをこのチャネルの指定されたファイル位置に書き込みます。クラスjava.nio.channels.spi.AbstractInterruptibleChannelで宣言されたメソッド
begin, close, end, implCloseChannel, isOpen
-
コンストラクタの詳細
-
FileChannel
protected FileChannel()このクラスの新しいインスタンスを初期化します。
-
-
メソッドの詳細
-
open
public static FileChannel open(Path path, Set<? extends OpenOption> options, FileAttribute<?>... attrs) throws IOException ファイルを開くか作成し、そのファイルにアクセスするためのファイル・チャネルを返します。optionsパラメータはファイルを開く方法を決定します。READとWRITEオプションにより、ファイルを読み取りまたは書込みで開くべきかどうかが決定されます。 いずれのオプション(またはAPPENDオプション)も配列に含まれていない場合、ファイルは読取り可能です。 デフォルトでは、読み取りまたは書込みはファイルの最初から始まります。READおよびWRITE以外に、次のオプションが存在する場合があります。オプション 説明 APPENDこのオプションが存在する場合は、ファイルは書込みのために開かれ、チャネルの writeメソッドの各呼出しは、まず位置をファイルの終わりに進めてから要求されたデータを書き込みます。 このような位置の移動とデータの書込みは、不可分な単一の操作として行われます。この操作は、システムに依存しているため未指定です。 このオプションを使用した「特定の位置に書き込む」の効果は指定されていません。 このオプションは、READまたはTRUNCATE_EXISTINGオプションと同時には使用できません。TRUNCATE_EXISTINGこのオプションが存在する場合は、既存のファイルはサイズが0バイトに切り詰められます。 このオプションは、ファイルを読取り専用に開いた場合は無視されます。 CREATE_NEWこのオプションがある場合、新しい空のファイルが作成され、ファイルがすでに存在する場合は失敗します。 ファイルの作成時に、ファイルがあるかどうかのチェックや、ない場合のファイルの生成は、ほかのファイル・システムの操作に対して原子的です。 このオプションは、ファイルを読取り専用に開いた場合は無視されます。 CREATEこのオプションが存在する場合は、既存のファイルが存在する場合はそれが開かれ、そうでない場合は新しいファイルが作成されます。 ファイルの作成時に、ファイルがあるかどうかのチェックや、ない場合のファイルの生成は、ほかのファイル・システムの操作に対して原子的です。 このオプションは、 CREATE_NEWオプションも存在する場合またはファイルを読取り専用に開いた場合は無視されます。DELETE_ON_CLOSEこのオプションが存在する場合、実装は、ファイルが closeメソッドによって閉じられるときに、ベスト・エフォートでファイルを削除しようとします。closeメソッドが呼び出されない場合、Java仮想マシンの終了時にファイルを削除するためのベスト・エフォートの試みが行われます。SPARSE新しいファイルの作成時に、このオプションは新しいファイルがスパースであることのヒントになります。 このオプションは、新しいファイルを作成しない場合は無視されます。 SYNCファイルの内容またはメタデータの更新は、基本となる記憶装置に同期的に書き込まれることを必要とします。(「同期入出力ファイル整合性」を参照)。 DSYNCファイルの内容の更新は、基本となる記憶装置に同期的に書き込まれることを必要とします。(「同期入出力ファイル整合性」を参照)。 実装は、追加のオプションをサポートする場合もあります。
attrsパラメータは、ファイルの作成時に原子的に設定される、ファイルfile-attributesのオプションの配列です。新しいチャネルは、
Pathを作成したプロバイダ上でnewFileChannelメソッドを呼び出すことによって作成されます。- パラメータ:
path- 開くまたは作成するファイルのパスoptions- ファイルを開く方法を指定するオプションattrs- ファイルの作成時に原子的に設定されるファイル属性のオプションのリスト- 戻り値:
- 新しいファイル・チャネル
- 例外:
IllegalArgumentException- セットにオプションの無効な組み合わせが含まれる場合UnsupportedOperationException-pathが、ファイル・チャネルの作成をサポートしないプロバイダに関連付けられている場合、未サポートのオープン・オプションが指定された場合、またはファイルの作成時に原子的に設定できない属性が配列に含まれる場合FileAlreadyExistsException- その名前のファイルがすでに存在し、CREATE_NEWオプションが指定され、そのファイルが「(optional specific exception)の書き込みのために開かれている場合」IOException- 入出力エラーが発生した場合SecurityException- セキュリティ・マネージャがインストールされ、それが実装によって必要とされる未指定のアクセス権を拒否する場合。 デフォルト・プロバイダで、ファイルが読取り用に開かれた場合は、SecurityManager.checkRead(String)メソッドが呼び出されてファイルへの読取りアクセスがチェックされます。 ファイルが書込み用に開かれた場合は、SecurityManager.checkWrite(String)メソッドが呼び出されて書込みアクセスがチェックされます。- 導入されたバージョン:
- 1.7
-
open
public static FileChannel open(Path path, OpenOption... options) throws IOException ファイルを開くか作成し、そのファイルにアクセスするためのファイル・チャネルを返します。このメソッド呼出しの動作は、次の呼出しの動作とまったく同一です。
ここで、fc.open(file, opts, new FileAttribute<?>[0]);optsは、options配列で指定されたオプションのセットです。- パラメータ:
path- 開くまたは作成するファイルのパスoptions- ファイルを開く方法を指定するオプション- 戻り値:
- 新しいファイル・チャネル
- 例外:
IllegalArgumentException- セットにオプションの無効な組み合わせが含まれる場合UnsupportedOperationException-pathがファイル・チャネルの作成をサポートしないプロバイダに関連付けられている場合、または未サポートのオープン・オプションが指定された場合FileAlreadyExistsException- その名前のファイルがすでに存在し、CREATE_NEWオプションが指定され、そのファイルが「(optional specific exception)の書き込みのために開かれている場合」IOException- 入出力エラーが発生した場合SecurityException- セキュリティ・マネージャがインストールされ、それが実装によって必要とされる未指定のアクセス権を拒否する場合。 デフォルト・プロバイダで、ファイルが読取り用に開かれた場合は、SecurityManager.checkRead(String)メソッドが呼び出されてファイルへの読取りアクセスがチェックされます。 ファイルが書込み用に開かれた場合は、SecurityManager.checkWrite(String)メソッドが呼び出されて書込みアクセスがチェックされます。- 導入されたバージョン:
- 1.7
-
read
public abstract int read(ByteBuffer dst) throws IOException このチャネルのバイト・シーケンスを指定のバッファに読み込みます。バイトの読込みは、このチャネルの現在のファイル位置から開始されます。その後、実際に読み込まれたバイト数によりファイル位置が更新されます。 それ以外の場合は、このメソッドは
ReadableByteChannelインタフェースの指定どおりに動作します。- 定義:
read、インタフェースReadableByteChannel- 定義:
read、インタフェースSeekableByteChannel- パラメータ:
dst- バイトの転送先バッファ- 戻り値:
- 読み取られたバイト数。ゼロの場合もあれば、チャネルがストリームの最後に達した場合は
-1 - 例外:
ClosedChannelException- このチャネルがクローズしている場合AsynchronousCloseException- 読取り操作の進行中に、別のスレッドによってこのチャネルがクローズされた場合ClosedByInterruptException- 読取り操作の進行中に、別のスレッドからの割込みがあったためにチャネルがクローズし、現在のスレッドの割込みステータスが設定された場合NonReadableChannelException- このチャネルが読取り可能でない場合IOException- その他の入出力エラーが発生した場合
-
read
public abstract long read(ByteBuffer[] dsts, int offset, int length) throws IOException このチャネルのバイト・シーケンスを指定されたバッファのサブシーケンスに読み込みます。バイトの読込みは、このチャネルの現在のファイル位置から開始されます。その後、実際に読み込まれたバイト数によりファイル位置が更新されます。 それ以外の場合は、このメソッドは
ScatteringByteChannelインタフェースの指定どおりに動作します。- 定義:
read、インタフェースScatteringByteChannel- パラメータ:
dsts- バイトの転送先バッファoffset- 最初のバイトの転送先となるバッファ配列内のオフセット。dsts.length以下の負でない値length- アクセスするバッファの最大数。負以外で、dsts.length以下である必要があります -offset- 戻り値:
- 読み取られたバイト数。ゼロの場合もあれば、チャネルがストリームの最後に達した場合は
-1 - 例外:
ClosedChannelException- このチャネルがクローズしている場合AsynchronousCloseException- 読取り操作の進行中に、別のスレッドによってこのチャネルがクローズされた場合ClosedByInterruptException- 読取り操作の進行中に、別のスレッドからの割込みがあったためにチャネルがクローズし、現在のスレッドの割込みステータスが設定された場合NonReadableChannelException- このチャネルが読取り可能でない場合IOException- その他の入出力エラーが発生した場合
-
read
public final long read(ByteBuffer[] dsts) throws IOException このチャネルのバイト・シーケンスを指定されたバッファに読み込みます。バイトの読込みは、このチャネルの現在のファイル位置から開始されます。その後、実際に読み込まれたバイト数によりファイル位置が更新されます。 それ以外の場合は、このメソッドは
ScatteringByteChannelインタフェースの指定どおりに動作します。- 定義:
read、インタフェースScatteringByteChannel- パラメータ:
dsts- バイトの転送先バッファ- 戻り値:
- 読み取られたバイト数。ゼロの場合もあれば、チャネルがストリームの最後に達した場合は
-1 - 例外:
ClosedChannelException- このチャネルがクローズしている場合AsynchronousCloseException- 読取り操作の進行中に、別のスレッドによってこのチャネルがクローズされた場合ClosedByInterruptException- 読取り操作の進行中に、別のスレッドからの割込みがあったためにチャネルがクローズし、現在のスレッドの割込みステータスが設定された場合NonReadableChannelException- このチャネルが読取り可能でない場合IOException- その他の入出力エラーが発生した場合
-
write
public abstract int write(ByteBuffer src) throws IOException このチャネルのバイト・シーケンスを指定のバッファから書き出します。チャネルが追加モード以外の場合、バイトの書出しは、このチャネルの現在のファイル位置から開始されます。追加モードでは、最初に、位置がファイルの末尾まで進みます。 ファイルのサイズは、書き込まれたバイト数に合わせ、必要であれば大きくなります。ファイル位置は、実際に書き込まれたバイト数によって更新されます。 それ以外の場合は、このメソッドは
WritableByteChannelインタフェースの指定どおりに動作します。- 定義:
write、インタフェースSeekableByteChannel- 定義:
write、インタフェースWritableByteChannel- パラメータ:
src- バイトの取得先バッファ- 戻り値:
- 書き込まれるバイト数。ゼロの場合もある
- 例外:
ClosedChannelException- このチャネルがクローズしている場合AsynchronousCloseException- 書込み操作の進行中に別のスレッドによってこのチャネルがクローズされた場合ClosedByInterruptException- 書込み中に別のスレッドからの割込みがあったためにチャネルがクローズし、現在のスレッドの割込みステータスが設定された場合NonWritableChannelException- このチャネルが書込み可能でない場合IOException- その他の入出力エラーが発生した場合
-
write
public abstract long write(ByteBuffer[] srcs, int offset, int length) throws IOException このチャネルのバイト・シーケンスを指定されたバッファのサブシーケンスから書き出します。チャネルが追加モード以外の場合、バイトの書出しは、このチャネルの現在のファイル位置から開始されます。追加モードでは、最初に、位置がファイルの末尾まで進みます。 ファイルのサイズは、書き込まれたバイト数に合わせ、必要であれば大きくなります。ファイル位置は、実際に書き込まれたバイト数によって更新されます。 それ以外の場合は、このメソッドは
GatheringByteChannelインタフェースの指定どおりに動作します。- 定義:
write、インタフェースGatheringByteChannel- パラメータ:
srcs- バイトの取得先バッファoffset- 最初のバイトの取得先となるバッファ配列内のオフセット。srcs.length以下の負でない値length- アクセスするバッファの最大数。負以外で、srcs.length以下である必要があります -offset- 戻り値:
- 書き込まれるバイト数。ゼロの場合もある
- 例外:
ClosedChannelException- このチャネルがクローズしている場合AsynchronousCloseException- 書込み操作の進行中に別のスレッドによってこのチャネルがクローズされた場合ClosedByInterruptException- 書込み中に別のスレッドからの割込みがあったためにチャネルがクローズし、現在のスレッドの割込みステータスが設定された場合NonWritableChannelException- このチャネルが書込み可能でない場合IOException- その他の入出力エラーが発生した場合
-
write
public final long write(ByteBuffer[] srcs) throws IOException このチャネルのバイト・シーケンスを指定されたバッファから書き出します。チャネルが追加モード以外の場合、バイトの書出しは、このチャネルの現在のファイル位置から開始されます。追加モードでは、最初に、位置がファイルの末尾まで進みます。 ファイルのサイズは、書き込まれたバイト数に合わせ、必要であれば大きくなります。ファイル位置は、実際に書き込まれたバイト数によって更新されます。 それ以外の場合は、このメソッドは
GatheringByteChannelインタフェースの指定どおりに動作します。- 定義:
write、インタフェースGatheringByteChannel- パラメータ:
srcs- バイトの取得先バッファ- 戻り値:
- 書き込まれるバイト数。ゼロの場合もある
- 例外:
ClosedChannelException- このチャネルがクローズしている場合AsynchronousCloseException- 書込み操作の進行中に別のスレッドによってこのチャネルがクローズされた場合ClosedByInterruptException- 書込み中に別のスレッドからの割込みがあったためにチャネルがクローズし、現在のスレッドの割込みステータスが設定された場合NonWritableChannelException- このチャネルが書込み可能でない場合IOException- その他の入出力エラーが発生した場合
-
position
public abstract long position() throws IOExceptionこのチャネルのファイル位置を返します。- 定義:
position、インタフェースSeekableByteChannel- 戻り値:
- このチャネルのファイル位置。ファイルの先頭から現在の位置までのバイト数を示す負でない整数
- 例外:
ClosedChannelException- このチャネルがクローズしている場合IOException- その他の入出力エラーが発生した場合
-
position
public abstract FileChannel position(long newPosition) throws IOException このチャネルのファイル位置を設定します。位置の値をファイルの現在のサイズより大きい値に設定するのは正当な処理です。しかし、この処理によってファイルのサイズが変更されるわけではありません。 ファイルの現在のサイズより大きい値が設定されている位置でバイトを読み取ろうとすると、即座にファイルの終わりが通知されます。 同じ位置でバイトを書き込もうとすると、新しいバイトに合わせてファイルのサイズが大きくなります。以前のファイルの終わりから新しく書き込まれたバイトまでの間に存在するバイトの値は未指定です。
- 定義:
position、インタフェースSeekableByteChannel- パラメータ:
newPosition- 新しい位置。ファイルの先頭からのバイト数を示す負でない整数- 戻り値:
- このファイル・チャネル
- 例外:
ClosedChannelException- このチャネルがクローズしている場合IllegalArgumentException- 新しい位置が負の値の場合IOException- その他の入出力エラーが発生した場合
-
size
public abstract long size() throws IOExceptionこのチャネルのファイルの現在のサイズを返します。- 定義:
size、インタフェースSeekableByteChannel- 戻り値:
- このチャネルのファイルの現在のサイズ(バイト単位)
- 例外:
ClosedChannelException- このチャネルがクローズしている場合IOException- その他の入出力エラーが発生した場合
-
truncate
public abstract FileChannel truncate(long size) throws IOException このチャネルのファイルの末尾を切詰め、指定されたサイズにします。指定されたサイズが現在のファイル・サイズよりも小さい場合、ファイルの末尾が切り詰められ、新しいファイルの終わりに収まらないバイトが破棄されます。 指定されたサイズが現在のファイル・サイズと同じか、それよりも大きい場合、ファイル・サイズは変更されません。 どちらの場合も、このチャネルのファイル位置が指定されたサイズよりも大きい場合、そのサイズに合わせてファイル・サイズが変更されます。
- 定義:
truncate、インタフェースSeekableByteChannel- パラメータ:
size- 新しいサイズ。負ではないバイト数- 戻り値:
- このファイル・チャネル
- 例外:
NonWritableChannelException- このチャネルが書込み可能でない場合ClosedChannelException- このチャネルがクローズしている場合IllegalArgumentException- 新しいサイズが負の値の場合IOException- その他の入出力エラーが発生した場合
-
force
public abstract void force(boolean metaData) throws IOException このチャネルのファイルの更新内容は、その記憶装置に強制的に書き込まれます。このチャネルのファイルがローカルの記憶装置上にある場合、このメソッドの戻り値から、このチャネルの作成時またはこのメソッドの一番最近の呼出し以降のファイルの変更内容がすべてそのデバイスに書き込まれていることがわかります。 この方法により、システムがクラッシュしたとき、重要な情報を損失から保護できます。
一方、ファイルがローカルの記憶装置上にない場合、書込みは行われません。
metaDataパラメータを使って、このメソッドで実行しなければならない入出力操作の数を制限できます。 このパラメータにfalseを渡した場合、ストレージに書き込む必要があるのは、ファイルのコンテンツの更新内容だけです。trueを渡した場合は、ファイルのコンテンツとメタデータの両方の更新内容を書き込む必要があります。これには、通常1個以上の入出力操作が必要です。 このパラメータに実効性があるかどうかは、基礎となるオペレーティング・システムによって決まるため、未指定です。このメソッドを呼び出すと、チャネルが読込み専用であっても入出力操作が発生します。 たとえば、ファイルのメタデータとして最終アクセス時刻を保存し、ファイルの読込みのたびに更新するようなオペレーティング・システムもあります。 この処理が実際に行われるかどうかはシステムによって決まるため、未指定です。
このメソッドは、このクラスで定義されたメソッド、またはチャネルが
getChannelメソッドで取得されたときにFileOutputStreamまたはRandomAccessFileで定義されるメソッドを介して、このチャネル・ファイルに対して行われた変更のみを強制的に行うことが保証されます。mapメソッド呼出しによって取得したマップされたbyteバッファのコンテンツの変更によって生じる変更は、必ずしも強制されません。 マップされたbyteバッファのforceメソッドを呼び出すと、バッファ・コンテンツに対する変更内容が強制的に書き込まれます。- パラメータ:
metaData-trueの場合、このメソッドは、ファイルのコンテンツおよびメタデータの両方に対する変更をストレージに強制的に書き込む必要がある。それ以外の場合はコンテンツの変更のみを強制的に書き込む必要がある- 例外:
ClosedChannelException- このチャネルがクローズしている場合IOException- その他の入出力エラーが発生した場合
-
transferTo
public abstract long transferTo(long position, long count, WritableByteChannel target) throws IOException このチャネルのファイルから指定された書込み可能なバイト・チャネルへバイトを転送します。このチャネルのファイルの指定された
positionから開始して、ターゲット・チャネルに書き込もうとすると、最大countバイトが読み取られます。 このメソッドを呼び出しても、チャネルの本来の性質や状態によって、要求されたバイトの一部が転送されない場合もあります。 指定されたpositionから始まるcountバイト未満のチャンネルのファイルが含まれている場合、またはターゲット・チャネルが非ブロッキングで、その出力バッファで解放されるcountバイトより少ない場合、リクエストされたバイト数より少ない転送が行われます。このメソッドはこのチャネルの位置を変更しません。 指定された位置がファイルの現在のサイズ以上の場合、バイトは転送されません。 ターゲット・チャネルに位置が指定されている場合、バイトはその位置から書き込まれます。その後、書き込まれたバイト数に合わせて位置が増加します。
このチャネルからデータを読み込んでターゲット・チャネルに書き込むという単純なループよりも、このメソッドのほうがずっと効率的に処理できる可能性があります。 多くのオペレーティング・システムは、ファイル・システム・キャッシュからターゲット・チャネルへバイトを直接転送できます。このとき、バイトのコピーは行われません。
- パラメータ:
position- 転送が開始されるファイル内の位置。負でない値である必要がありますcount- 転送される最大バイト数。負でない値である必要がありますtarget- ターゲット・チャネル- 戻り値:
- 実際に転送されたバイト数。ゼロの場合もある
- 例外:
IllegalArgumentException- 上記のパラメータの前提条件が満たされていない場合NonReadableChannelException- このチャネルが読取り可能でない場合NonWritableChannelException- ターゲット・チャネルが書込み可能でない場合ClosedChannelException- このチャネルまたはターゲット・チャネルがクローズしている場合AsynchronousCloseException- 転送中に、別のスレッドによっていずれかのチャネルがクローズされた場合ClosedByInterruptException- 転送操作の進行中に別のスレッドからの割込みがあったために両方のチャネルがクローズし、現在のスレッドの割込みステータスが設定された場合IOException- その他の入出力エラーが発生した場合
-
transferFrom
public abstract long transferFrom(ReadableByteChannel src, long position, long count) throws IOException 指定された読込み可能なバイト・チャネルからこのチャネルのファイルへバイトを転送します。ソース・チャネルから最大
countバイトを読み取って、指定されたpositionからこのチャネルのファイルに書き込もうとしました。 このメソッドを呼び出しても、チャネルの本来の性質や状態によって、要求されたバイトの一部が転送されない場合もあります。 ソース・チャネルの残りのバイト数がcountバイトより少ない場合、またはソース・チャネルが非ブロッキングで、その入力バッファですぐに使用可能なバイト数がcountバイトより少ない場合、リクエストされたバイト数より少ない数で転送されます。 ソースがストリームの終わりに達した場合、バイトは転送されず、ゼロが返されます。このメソッドはこのチャネルの位置を変更しません。 指定された位置がファイルの現在のサイズ以上である場合、ファイルは新しいバイトに対応するように拡張されます。前のファイルの終わりと新しく書き込まれたバイトの間のバイトの値は指定されません。 ソース・チャネルに位置が指定されている場合、バイトはその位置から読み取られます。その後、読み取られたバイト数に合わせて位置が増加します。
ソース・チャネルからデータを読み込んでこのチャネルに書き込むという単純なループよりも、このメソッドのほうがずっと効率的に処理できる可能性があります。 多くのオペレーティング・システムは、ソース・チャネルからファイル・システム・キャッシュへバイトを直接転送できます。このとき、バイトのコピーは行われません。
- パラメータ:
src- ソース・チャネルposition- 転送が開始されるファイル位置。負でない値である必要がありますcount- 転送される最大バイト数。負でない値である必要があります- 戻り値:
- 実際に転送されたバイト数。ゼロの場合もある
- 例外:
IllegalArgumentException- 上記のパラメータの前提条件が満たされていない場合NonReadableChannelException- ソース・チャネルが読込み可能でない場合NonWritableChannelException- このチャネルが書込み可能でない場合ClosedChannelException- このチャネルまたはソース・チャネルがクローズしている場合AsynchronousCloseException- 転送中に、別のスレッドによっていずれかのチャネルがクローズされた場合ClosedByInterruptException- 転送操作の進行中に別のスレッドからの割込みがあったために両方のチャネルがクローズし、現在のスレッドの割込みステータスが設定された場合IOException- その他の入出力エラーが発生した場合
-
read
public abstract int read(ByteBuffer dst, long position) throws IOException このチャネルのバイト・シーケンスを、指定されたファイル位置からバッファに読み込みます。このメソッドは、バイトがチャネルの現在位置ではなく指定されたファイル位置から読み取られるという点を除けば、
read(ByteBuffer)メソッドと同じ方法で動作します。 このメソッドはこのチャネルの位置を変更しません。 指定された位置がファイルの現在のサイズ以上の場合、バイトは読み取られません。- パラメータ:
dst- バイトの転送先バッファposition- 転送が開始されるファイル位置。負でない値である必要があります- 戻り値:
- 指定された位置がファイルの現在のサイズ以上である場合、読み取られたバイト数(ゼロの場合もある)、または
-1 - 例外:
IllegalArgumentException- positionが負であるか、またはバッファが読取り専用の場合NonReadableChannelException- このチャネルが読取り可能でない場合ClosedChannelException- このチャネルがクローズしている場合AsynchronousCloseException- 読取り操作の進行中に、別のスレッドによってこのチャネルがクローズされた場合ClosedByInterruptException- 読取り操作の進行中に、別のスレッドからの割込みがあったためにチャネルがクローズし、現在のスレッドの割込みステータスが設定された場合IOException- その他の入出力エラーが発生した場合
-
write
public abstract int write(ByteBuffer src, long position) throws IOException 指定されたバッファのバイト・シーケンスをこのチャネルの指定されたファイル位置に書き込みます。このメソッドは、バイトがチャネルの現在位置ではなく指定されたファイル位置から書き込まれるという点を除けば、
write(ByteBuffer)メソッドと同じ方法で動作します。 このメソッドはこのチャネルの位置を変更しません。 指定された位置がファイルの現在のサイズ以上である場合、ファイルは新しいバイトに対応するように拡張されます。前のファイルの終わりと新しく書き込まれたバイトの間のバイトの値は指定されません。ファイルが「追加モード」で開いている場合、このメソッドを呼び出す効果は指定されません。
- パラメータ:
src- バイトの転送元バッファposition- 転送が開始されるファイル位置。負でない値である必要があります- 戻り値:
- 書き込まれるバイト数。ゼロの場合もある
- 例外:
IllegalArgumentException- 位置が負の値の場合NonWritableChannelException- このチャネルが書込み可能でない場合ClosedChannelException- このチャネルがクローズしている場合AsynchronousCloseException- 書込み操作の進行中に別のスレッドによってこのチャネルがクローズされた場合ClosedByInterruptException- 書込み中に別のスレッドからの割込みがあったためにチャネルがクローズし、現在のスレッドの割込みステータスが設定された場合IOException- その他の入出力エラーが発生した場合
-
map
public abstract MappedByteBuffer map(FileChannel.MapMode mode, long position, long size) throws IOException このチャネルのファイルの領域を直接メモリーにマッピングします。modeパラメータで、ファイルのリージョンのマップ方法を指定します。次のいずれかのモードになります:読込み専用: 結果のバッファを修正しようとすると
ReadOnlyBufferExceptionがスローされる。 (MapMode.READ_ONLY)読み込み/書き込み: 結果のバッファへの変更は最終的にファイルに伝達される。この変更は、同じファイルをマッピングしているその他のプログラムによって認識される場合と、認識されない場合がある。 (
MapMode.READ_WRITE)非公開: 結果のバッファへの変更はファイルに伝達されず、同じファイルをマッピングしているその他のプログラムによって認識されることもない。その代わりに、バッファの変更された部分の非公開のコピーが作成される。 (
MapMode.PRIVATE)
実装では、追加のマップ・モードをサポートできます。
このチャネルは、読込み専用のマッピングの場合は読み込み、読み込み/書込みのマッピングまたは非公開マッピングの場合は読み込みと書込みの両方が可能になっていなければいけません。
このメソッドから返される
mapped byte bufferの位置は0、制限および容量はsizeです。そのマークは未定義になります。 バッファとこのバッファが示すマッピングは、バッファ自体がガベージ・コレクトされるまで有効です。マッピングの結果は、その作成に使用されたファイル・チャネルには依存しません。 たとえば、チャネルをクローズしても、マッピングの有効性は変わりません。
多くの場合、メモリーにマッピングされたファイルの詳細は、本質的に基礎となるオペレーティング・システムに依存するため、未指定です。 要求された領域がこのチャネルのファイル内に完全には含まれていない場合、このメソッドの動作は未指定です。 基礎となるファイルのコンテンツまたはサイズのどちらが変更されたか、このプログラムによる変更または別のプログラムによる変更のどちらか、および、変更がバッファに伝達されるかどうかは未指定です。 バッファの変更がファイルに伝達される速度は未指定です。
ほとんどのオペレーティング・システムでは、ファイルをメモリーにマッピングするほうが、通常の
readメソッドまたはwriteメソッドを使って数十キロバイトのデータの読み込みまたは書込みを行うよりも負荷が大きくなります。 性能を重視するなら、比較的大きめのファイルだけをマッピングすることをお薦めします。- パラメータ:
mode-FileChannel.MapModeクラスに定義された定数READ_ONLY、READ_WRITEまたはPRIVATEの1つ。ファイルがそれぞれ読取り専用、読取り/書込みまたは非公開(copy-on-write)のいずれか、あるいは実装固有のマップ・モードかに基づきます。position- ファイル内のマッピングされた領域の開始位置。負でないsize- マッピングされる領域のサイズ。負でない、Integer.MAX_VALUE以下の値- 戻り値:
- マッピングされるbyteバッファ
- 例外:
NonReadableChannelException-modeがREAD_ONLYの場合、または読取りアクセスが必要な実装固有のマップ・モードの場合、このチャネルは読取り用にオープンされませんでしたNonWritableChannelException-modeがREAD_WRITE、PRIVATEまたは書込みアクセスが必要な実装固有のマップ・モードの場合、このチャネルは読取りと書込みの両方に対してオープンされませんでしたIllegalArgumentException- 上記のパラメータの前提条件が満たされていない場合UnsupportedOperationException- サポートされていないマップ・モードが指定された場合IOException- その他の入出力エラーが発生した場合- 関連項目:
-
map
public MemorySegment map(FileChannel.MapMode mode, long offset, long size, Arena arena) throws IOException 指定されたオフセット、サイズおよびアリーナを使用して、このチャネルのファイルのリージョンを新しいマップされたメモリー・セグメントにマップします。 返されるメモリー・セグメントのaddressは、セグメントを裏付けるマップされたオフ・ヒープ・リージョンの開始アドレスです。返されるセグメントの存続期間は、指定されたアリーナによって制御されます。 たとえば、指定されたアリーナがクローズ可能なアリーナである場合、指定されたクローズ可能なアリーナがclosedの場合、返されたセグメントはマップ解除されます。
指定されたマッピング・モードがREAD_ONLYの場合、結果のセグメントは読取り専用(
MemorySegment.isReadOnly()を参照してください)になります。マップされたメモリー・セグメントの内容は、マップされたファイルの対応するリージョンの内容がこの(または別の)プログラムによって変更される場合など、いつでも変更できます。 このような変更が発生したかどうか、および発生した場合、オペレーティング・システムに依存するため未指定です。
マップされたメモリー・セグメントのすべてまたは一部は、バッキング・マップ・ファイルが切り捨てられた場合など、いつでもアクセスできなくなる可能性があります。 マップされたメモリー・セグメントのアクセス不可能なリージョンにアクセスしようとしても、セグメントの内容は変更されず、アクセス時または後で未指定の例外がスローされます。 したがって、ファイルの内容の読取りまたは書込みを除き、この(または別の)プログラムによるマップ済ファイルの操作を回避するために、適切な注意を払うことを強くお薦めします。
- 実装要件:
- このメソッドのデフォルト実装は
UnsupportedOperationExceptionをスローします。 - 実装上のノート:
- 新しく作成されたファイル・チャネルからマップされたセグメントを取得する場合、返されたマップ済メモリー・セグメントに関連付けられたマップ済メモリーのブロックの内容の初期化状態は指定されず、依存しないでください。
- パラメータ:
mode- ファイル・マッピング・モード(map(FileChannel.MapMode, long, long)を参照)。マッピング・モードは、戻されたメモリー・マップ・セグメント(MemorySegment.force()を参照してください)の動作に影響を与える可能性があります。offset- マップされたセグメントを開始するファイル内のオフセット(バイトで表されます。)size- メモリー・セグメントをバッキングするマップ済メモリーのサイズ(バイト単位)arena- セグメント・アリーナ- 戻り値:
- 新しいマップ済メモリー・セグメント
- 例外:
IllegalArgumentException-offset < 0、size < 0またはoffset + sizeがlongの範囲をオーバーフローする場合IllegalStateException-arena.isAlive() == falseの場合WrongThreadException-arenaが限定スコープ・アリーナで、このメソッドが、スコープ・アリーナの所有者スレッド以外のスレッドTからコールされる場合NonReadableChannelException-modeがREAD_ONLYの場合、または読取りアクセスが必要な実装固有のマップ・モードの場合、このチャネルは読取り用にオープンされませんでしたNonWritableChannelException-modeがREAD_WRITE、PRIVATEまたは書込みアクセスが必要な実装固有のマップ・モードの場合、このチャネルは読取りと書込みの両方に対してオープンされませんでしたIOException- その他の入出力エラーが発生した場合UnsupportedOperationException- サポートされていないマップ・モードが指定された場合- 導入されたバージョン:
- 22
-
lock
public abstract FileLock lock(long position, long size, boolean shared) throws IOException このチャネルのファイルの指定された領域をロックします。このメソッドの呼出しは、領域がロックされるか、このチャネルがクローズされるか、呼出し元スレッドに割込みが発生するまでブロックされます。
このメソッドの呼出し中にこのチャネルが別のスレッドによってクローズされると、
AsynchronousCloseExceptionがスローされます。ロックの獲得を待機中に呼出し元スレッドに割込みが発生した場合、割込みステータスが設定され、
FileLockInterruptionExceptionがスローされます。 このメソッドの呼出し時に呼出し元の割込み状態が設定されると、ただちに例外がスローされます。スレッドの割込み状態は変更されません。positionパラメータとsizeパラメータで指定された領域が、実際の基礎となるファイルに含まれていたり、そのファイルとオーバーラップしたりしている必要はありません。 ロック領域のサイズは固定です。初期状態ではファイルの終わりがロック領域内に含まれていても、ファイル・サイズがこの領域より大きくなってしまった場合、新しい部分にはロックが適用されません。 ファイル全体にロックを適用する必要があるにもかかわらず、ファイル・サイズが大きくなる可能性がある場合は、ゼロから予測される最大ファイル・サイズ以上までの領域をロックします。 ゼロ引数のlock()メソッドは、単純にサイズLong.MAX_VALUEの領域をロックします。positionが負でない場合、sizeがゼロの場合は、サイズLong.MAX_VALUE - positionのロックが返されます。共有ロックをサポートしないオペレーティング・システムでは、共有ロック要求が排他ロック要求に自動的に変換されます。 新しく獲得したロックが共有ロックであるか排他ロックであるかは、結果として得られるロック・オブジェクトの
isSharedメソッドを呼び出すことで判断できます。ファイル・ロックはJava仮想マシン全体のために保持されます。 これらは、同一仮想マシン内の複数スレッドによるファイルへのアクセスを制御するのには適していません。
- パラメータ:
position- ロック領域が開始されるファイル位置。負でない値である必要がありますsize- ロック領域のサイズ。負でない値である必要があります。position+sizeも負でない値である必要があります 値ゼロは、ファイルがその後拡張されたか切り捨てられたかに関係なく、指定された開始位置からファイルの終了までのすべてのバイトをロックすることを意味shared- 共有ロックを要求する場合はtrue。この場合、このチャネルは読取りが(場合によっては書き込みも)可能である必要があります。排他ロックを要求する場合はfalse。この場合、このチャネルは書込みが(場合によっては読取りも)可能である必要があります- 戻り値:
- 新規獲得ロックを表すロック・オブジェクト
- 例外:
IllegalArgumentException- 上記のパラメータの前提条件が満たされていない場合ClosedChannelException- このチャネルがクローズしている場合AsynchronousCloseException- このメソッド内で呼出し元スレッドがブロックされている間に、別のスレッドによってこのチャネルがクローズされた場合FileLockInterruptionException- このメソッド内でブロックされている間に、呼出し元スレッドに割込みが発生した場合OverlappingFileLockException- 要求された領域をオーバーラップするロックがこのJava仮想マシンにすでに確保されている場合。または、このメソッド内でブロックされている別のスレッドがオーバーラップした領域をロックしようとしている場合NonReadableChannelException-sharedがtrueの場合、このチャネルは読取り用にオープンされませんでしたNonWritableChannelException-sharedがfalseの場合、このチャネルは書込み用にオープンされていませんIOException- その他の入出力エラーが発生した場合- 関連項目:
-
lock
public final FileLock lock() throws IOException- 戻り値:
- 新規獲得ロックを表すロック・オブジェクト
- 例外:
ClosedChannelException- このチャネルがクローズしている場合AsynchronousCloseException- このメソッド内で呼出し元スレッドがブロックされている間に、別のスレッドによってこのチャネルがクローズされた場合FileLockInterruptionException- このメソッド内でブロックされている間に、呼出し元スレッドに割込みが発生した場合- +
OverlappingFileLockException- 要求された領域をオーバーラップするロックがこのJava仮想マシンにすでに確保されている場合。または、このメソッド内でブロックされている別のスレッドが同じファイルのオーバーラップした領域をロックしようとしている場合 NonWritableChannelException- このチャネルが書込み可能でない場合IOException- その他の入出力エラーが発生した場合- 関連項目:
-
tryLock
public abstract FileLock tryLock(long position, long size, boolean shared) throws IOException このチャネルのファイルの指定された領域でロックを獲得しようとします。このメソッドはブロックされません。 このメソッドを呼び出すと、要求された領域でロックを獲得したか、ロックの獲得に失敗したかを示す結果がただちに返されます。 オーバーラップしたロックが別のプログラムによって保持されていたためロックの獲得に失敗した場合、
nullが返されます。 その他の原因でロックに失敗した場合は、適切な例外がスローされます。positionパラメータとsizeパラメータで指定された領域が、実際の基礎となるファイルに含まれていたり、そのファイルとオーバーラップしたりしている必要はありません。 ロック領域のサイズは固定です。初期状態ではファイルの終わりがロック領域内に含まれていても、ファイル・サイズがこの領域より大きくなってしまった場合、新しい部分にはロックが適用されません。 ファイル全体にロックを適用する必要があるにもかかわらず、ファイル・サイズが大きくなる可能性がある場合は、ゼロから予測される最大ファイル・サイズ以上までの領域をロックします。 ゼロ引数のtryLock()メソッドは、単純にサイズLong.MAX_VALUEの領域をロックします。positionが負でない場合、sizeがゼロの場合は、サイズLong.MAX_VALUE - positionのロックが返されます。共有ロックをサポートしないオペレーティング・システムでは、共有ロック要求が排他ロック要求に自動的に変換されます。 新しく獲得したロックが共有ロックであるか排他ロックであるかは、結果として得られるロック・オブジェクトの
isSharedメソッドを呼び出すことで判断できます。ファイル・ロックはJava仮想マシン全体のために保持されます。 これらは、同一仮想マシン内の複数スレッドによるファイルへのアクセスを制御するのには適していません。
- パラメータ:
position- ロック領域が開始されるファイル位置。負でない値である必要がありますsize- ロック領域のサイズ。負でない値である必要があります。position+sizeも負でない値である必要があります 値ゼロは、ファイルがその後拡張されたか切り捨てられたかに関係なく、指定された開始位置からファイルの終了までのすべてのバイトをロックすることを意味shared- 共有ロックを要求する場合はtrue、排他ロックを要求する場合はfalse- 戻り値:
- 新規獲得ロックを表すロック・オブジェクト。オーバーラップしたロックが別のプログラムによって確保されていたためロックに失敗した場合は
null - 例外:
IllegalArgumentException- 上記のパラメータの前提条件が満たされていない場合ClosedChannelException- このチャネルがクローズしている場合- +
OverlappingFileLockException- 要求された領域をオーバーラップするロックがこのJava仮想マシンにすでに確保されている場合。または、このメソッド内でブロックされている別のスレッドが同じファイルのオーバーラップした領域をロックしようとしている場合 NonReadableChannelException-sharedがtrueの場合、このチャネルは読取り用にオープンされませんでしたNonWritableChannelException-sharedがfalseの場合、このチャネルは書込み用にオープンされていませんIOException- その他の入出力エラーが発生した場合- 関連項目:
-
tryLock
public final FileLock tryLock() throws IOExceptionこのチャネルのファイル上で排他ロックを獲得しようとします。fc.tryLock()形式のこのメソッドの起動は、起動とまったく同じように動作fc.tryLock(0L, Long.MAX_VALUE, false)- 戻り値:
- 新規獲得ロックを表すロック・オブジェクト。オーバーラップしたロックが別のプログラムによって確保されていたためロックに失敗した場合は
null - 例外:
ClosedChannelException- このチャネルがクローズしている場合OverlappingFileLockException- 要求された領域をオーバーラップするロックがこのJava仮想マシンにすでに確保されている場合。または、このメソッド内でブロックされている別のスレッドがオーバーラップした領域をロックしようとしている場合NonWritableChannelException- このチャネルが書込み可能でない場合IOException- その他の入出力エラーが発生した場合- 関連項目:
-