public abstract class FileChannel extends AbstractInterruptibleChannel implements SeekableByteChannel, GatheringByteChannel, ScatteringByteChannel
ファイル・チャネルは、ファイルに接続されるSeekableByteChannel
です。これは、ファイル内に、照会
および変更
が可能な現在の位置を持っています。ファイル自体には、読み込み/書き込みと現在のサイズ
の照会が可能な可変長のバイト・シーケンスが含まれています。ファイルのサイズは、現在のサイズを上回るバイト数が書き込まれると大きくなり、切り詰め
によって小さくなります。ファイルには、アクセス許可、コンテンツ・タイプ、最終更新時間などのメタデータも関連付けられています。このクラスは、メタデータ・アクセスのためのメソッドを定義しません。
このクラスは、バイト・チャネルに対する一般的な操作(読み込み、書き込み、クローズ)のほかに、次のようなファイル固有の操作を定義します。
ファイルの領域はメモリーに直接マッピング
される。ファイルのサイズが大きい場合は、通常の読み込みメソッドや書き込みメソッドを呼び出すより、この方法のほうが効率的。
ファイルの更新は、基礎となっている記憶装置にforced out
されます。したがって、システムがクラッシュしてもデータの損失は回避されます。
バイトはファイルからほかのチャネルへ
転送できる。反対に、ほかのチャネルから
転送することもできる。多くのオペレーティング・システムでは、ファイル・システムのキャッシュとの間で非常に高速で直接転送することにより、この転送を最適化できる。
ファイルの領域は、その他のプログラムからアクセスできないようにロック
されます。
ファイル・チャネルは、複数の並行スレッドで安全に使用できます。close
メソッドは、Channel
インタフェースの指定どおりにいつでも呼び出せます。チャネルの位置を使用する操作、またはファイル・サイズを変更する可能性がある操作は、1つずつ実行することになっています。前の操作の進行中に同じような操作を新しく開始しようとすると、最初の操作が終わるまで新しい操作はブロックされます。その他の操作、とりわけ明示的な位置を使用する操作は、前の操作と同時並行で実行できます。同時並行処理が行われるかどうかは基礎となる実装によって決まるため、未指定です。
このクラスのインスタンスによって提供されたファイルのビューは、同じプログラム内のその他のインスタンスによって提供された同じファイルのビューと矛盾しないことが保証されています。しかし、基礎となるオペレーティング・システムのキャッシュ処理や、ネットワーク・ファイル・システム・プロトコルによる遅延が原因で、このクラスのインスタンスによって提供されたビューと、並行して実行されているプログラムで認識されるその他のビューが矛盾する可能性がないわけではありません。この問題は、これらのプログラムを記述している言語の違いや、これらが同一マシンで実行されているかどうかとは関係なく発生します。こうした矛盾は、システムによって生じるものであるため未指定です。
ファイル・チャネルは、このクラスによって定義されるopen
メソッドの1つを呼び出すことによって作成されます。ファイル・チャネルは、同じ基本となるファイルに接続されているファイル・チャネルを返す、オブジェクトのgetChannelメソッドを呼び出すことで、既存のFileInputStream
、FileOutputStream
、またはRandomAccessFile
オブジェクトから取得することもできます。ファイル・チャネルを既存のストリームまたはランダム・アクセス・ファイルから取得する場合、ファイル・チャネルの状態は、チャネルを返したgetChannelメソッドを持つオブジェクトの状態と密接な関係にあります。たとえば、チャネルの位置を明示的に、あるいはバイトの読込みや書込みによって変更すると、発生元のオブジェクトのファイル位置が変わります(逆も同様)。ファイル・チャネルからファイルの長さを変更すると、発生元オブジェクトから見たときの長さが変わります(逆も同様)。バイトの書込みによってファイルのコンテンツを変更すると、元のオブジェクトから見たときのコンテンツが変わります(逆も同様)。
このクラスは、さまざまな点で、「読込み可能」、「書込み可能」、または「読み込みと書込みが可能」であるインスタンスが必要なことを指定しています。FileInputStream
インスタンスのgetChannel
メソッドで取得されたチャネルは読込み可能です。FileOutputStream
インスタンスのgetChannel
メソッドで取得されたチャネルは書込み可能です。そして、RandomAccessFile
インスタンスのgetChannel
メソッドで取得したチャネルは、インスタンスがモード「r」で作成された場合は読込み可能、モード「rw」で作成された場合は読み込みと書込みが可能です。
たとえば、FileOutputStream(File,boolean)
コンストラクタを呼び出して2番目のパラメータにtrueを渡すことによってファイル出力ストリームを作成した場合、このストリームから取得した書込み可能なファイル・チャネルは、追加モードになります。このモードで関連した書込み操作を呼び出すと、まず位置がファイルの末尾まで進みます。その後、要求されたデータが書き込まれます。このような位置の移動とデータの書込みは、不可分な単一の操作として行われます。この操作は、システムに依存しているため未指定です。
FileInputStream.getChannel()
, FileOutputStream.getChannel()
, RandomAccessFile.getChannel()
修飾子と型 | クラスと説明 |
---|---|
static class |
FileChannel.MapMode
ファイル・マッピング・モードの型保証された列挙です。
|
修飾子 | コンストラクタと説明 |
---|---|
protected |
FileChannel()
このクラスの新しいインスタンスを初期化します。
|
修飾子と型 | メソッドと説明 |
---|---|
abstract void |
force(boolean metaData)
このチャネルのファイルの更新内容は、その記憶装置に強制的に書き込まれます。
|
FileLock |
lock()
このチャネルのファイル上に排他ロックを設定します。
|
abstract FileLock |
lock(long position, long size, boolean shared)
このチャネルのファイルの指定された領域をロックします。
|
abstract MappedByteBuffer |
map(FileChannel.MapMode mode, long position, long size)
このチャネルのファイルの領域を直接メモリーにマッピングします。
|
static FileChannel |
open(Path path, OpenOption... options)
ファイルを開くか作成し、そのファイルにアクセスするためのファイル・チャネルを返します。
|
static FileChannel |
open(Path path, Set<? extends OpenOption> options, FileAttribute<?>... attrs)
ファイルを開くか作成し、そのファイルにアクセスするためのファイル・チャネルを返します。
|
abstract long |
position()
このチャネルのファイル位置を返します。
|
abstract FileChannel |
position(long newPosition)
このチャネルのファイル位置を設定します。
|
abstract int |
read(ByteBuffer dst)
このチャネルのバイト・シーケンスを指定のバッファに読み込みます。
|
long |
read(ByteBuffer[] dsts)
このチャネルのバイト・シーケンスを指定されたバッファに読み込みます。
|
abstract long |
read(ByteBuffer[] dsts, int offset, int length)
このチャネルのバイト・シーケンスを指定されたバッファのサブシーケンスに読み込みます。
|
abstract int |
read(ByteBuffer dst, long position)
このチャネルのバイト・シーケンスを、指定されたファイル位置からバッファに読み込みます。
|
abstract long |
size()
このチャネルのファイルの現在のサイズを返します。
|
abstract long |
transferFrom(ReadableByteChannel src, long position, long count)
指定された読込み可能なバイト・チャネルからこのチャネルのファイルへバイトを転送します。
|
abstract long |
transferTo(long position, long count, WritableByteChannel target)
このチャネルのファイルから指定された書込み可能なバイト・チャネルへバイトを転送します。
|
abstract FileChannel |
truncate(long size)
このチャネルのファイルの末尾を切詰め、指定されたサイズにします。
|
FileLock |
tryLock()
このチャネルのファイル上で排他ロックを獲得しようとします。
|
abstract FileLock |
tryLock(long position, long size, boolean shared)
このチャネルのファイルの指定された領域でロックを獲得しようとします。
|
abstract int |
write(ByteBuffer src)
このチャネルのバイト・シーケンスを指定のバッファから書き出します。
|
long |
write(ByteBuffer[] srcs)
このチャネルのバイト・シーケンスを指定されたバッファから書き出します。
|
abstract long |
write(ByteBuffer[] srcs, int offset, int length)
このチャネルのバイト・シーケンスを指定されたバッファのサブシーケンスから書き出します。
|
abstract int |
write(ByteBuffer src, long position)
指定されたバッファのバイト・シーケンスをこのチャネルの指定されたファイル位置に書き込みます。
|
begin, close, end, implCloseChannel, isOpen
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
が、ファイル・チャネルの作成をサポートしないプロバイダに関連付けられている場合、未サポートのオープン・オプションが指定された場合、またはファイルの作成時に原子的に設定できない属性が配列に含まれる場合IOException
- 入出力エラーが発生した場合SecurityException
- セキュリティ・マネージャがインストールされ、それが実装によって必要とされる未指定のアクセス権を拒否する場合。デフォルト・プロバイダで、ファイルが読取り用に開かれた場合は、SecurityManager.checkRead(String)
メソッドが呼び出されてファイルへの読取りアクセスがチェックされます。ファイルが書込み用に開かれた場合は、SecurityManager.checkWrite(String)
メソッドが呼び出されて書込みアクセスがチェックされます。public static FileChannel open(Path path, OpenOption... options) throws IOException
このメソッド呼出しの動作は、次の呼出しの動作とまったく同一です。
fc.open
(file, opts, new FileAttribute<?>[0]);
ここで、opts
はoptions
配列で指定されたオプション・セットです。path
- 開くまたは作成するファイルのパスoptions
- ファイルを開く方法を指定するオプションIllegalArgumentException
- セットにオプションの無効な組み合わせが含まれる場合UnsupportedOperationException
- path
がファイル・チャネルの作成をサポートしないプロバイダに関連付けられている場合、または未サポートのオープン・オプションが指定された場合IOException
- 入出力エラーが発生した場合SecurityException
- セキュリティ・マネージャがインストールされ、それが実装によって必要とされる未指定のアクセス権を拒否する場合。デフォルト・プロバイダで、ファイルが読取り用に開かれた場合は、SecurityManager.checkRead(String)
メソッドが呼び出されてファイルへの読取りアクセスがチェックされます。ファイルが書込み用に開かれた場合は、SecurityManager.checkWrite(String)
メソッドが呼び出されて書込みアクセスがチェックされます。public abstract int read(ByteBuffer dst) throws IOException
バイトの読込みは、このチャネルの現在のファイル位置から開始されます。その後、実際に読み込まれたバイト数によりファイル位置が更新されます。それ以外の場合は、このメソッドはReadableByteChannel
インタフェースの指定どおりに動作します。
read
、インタフェース: ReadableByteChannel
read
、インタフェース: SeekableByteChannel
dst
- バイトの転送先バッファClosedChannelException
- このチャネルがクローズしている場合AsynchronousCloseException
- 読取り操作の進行中に、別のスレッドによってこのチャネルがクローズされた場合ClosedByInterruptException
- 読取り操作の進行中に、別のスレッドからの割込みがあったためにチャネルがクローズし、現在のスレッドの割込みステータスが設定された場合IOException
- その他の入出力エラーが発生した場合public abstract long read(ByteBuffer[] dsts, int offset, int length) throws IOException
バイトの読込みは、このチャネルの現在のファイル位置から開始されます。その後、実際に読み込まれたバイト数によりファイル位置が更新されます。それ以外の場合は、このメソッドはScatteringByteChannel
インタフェースの指定どおりに動作します。
read
、インタフェース: ScatteringByteChannel
dsts
- バイトの転送先バッファoffset
- 最初のバイトの転送先となるバッファ配列内のオフセット。dsts.length以下の負でない値length
- アクセスされる最大バッファ数。dsts.length - offset以下の負でない値ClosedChannelException
- このチャネルがクローズしている場合AsynchronousCloseException
- 読取り操作の進行中に、別のスレッドによってこのチャネルがクローズされた場合ClosedByInterruptException
- 読取り操作の進行中に、別のスレッドからの割込みがあったためにチャネルがクローズし、現在のスレッドの割込みステータスが設定された場合IOException
- その他の入出力エラーが発生した場合public final long read(ByteBuffer[] dsts) throws IOException
バイトの読込みは、このチャネルの現在のファイル位置から開始されます。その後、実際に読み込まれたバイト数によりファイル位置が更新されます。それ以外の場合は、このメソッドはScatteringByteChannel
インタフェースの指定どおりに動作します。
read
、インタフェース: ScatteringByteChannel
dsts
- バイトの転送先バッファClosedChannelException
- このチャネルがクローズしている場合AsynchronousCloseException
- 読取り操作の進行中に、別のスレッドによってこのチャネルがクローズされた場合ClosedByInterruptException
- 読取り操作の進行中に、別のスレッドからの割込みがあったためにチャネルがクローズし、現在のスレッドの割込みステータスが設定された場合IOException
- その他の入出力エラーが発生した場合public abstract int write(ByteBuffer src) throws IOException
チャネルが追加モード以外の場合、バイトの書出しは、このチャネルの現在のファイル位置から開始されます。追加モードでは、最初に、位置がファイルの末尾まで進みます。ファイルのサイズは、書き込まれたバイト数に合わせ、必要であれば大きくなります。ファイル位置は、実際に書き込まれたバイト数によって更新されます。それ以外の場合は、このメソッドはWritableByteChannel
インタフェースの指定どおりに動作します。
write
、インタフェース: SeekableByteChannel
write
、インタフェース: WritableByteChannel
src
- バイトの取得先バッファClosedChannelException
- このチャネルがクローズしている場合AsynchronousCloseException
- 書込み操作の進行中に別のスレッドによってこのチャネルがクローズされた場合ClosedByInterruptException
- 書込み中に別のスレッドからの割込みがあったためにチャネルがクローズし、現在のスレッドの割込みステータスが設定された場合IOException
- その他の入出力エラーが発生した場合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
- 書込み中に別のスレッドからの割込みがあったためにチャネルがクローズし、現在のスレッドの割込みステータスが設定された場合IOException
- その他の入出力エラーが発生した場合public final long write(ByteBuffer[] srcs) throws IOException
チャネルが追加モード以外の場合、バイトの書出しは、このチャネルの現在のファイル位置から開始されます。追加モードでは、最初に、位置がファイルの末尾まで進みます。ファイルのサイズは、書き込まれたバイト数に合わせ、必要であれば大きくなります。ファイル位置は、実際に書き込まれたバイト数によって更新されます。それ以外の場合は、このメソッドはGatheringByteChannel
インタフェースの指定どおりに動作します。
write
、インタフェース: GatheringByteChannel
srcs
- バイトの取得先バッファClosedChannelException
- このチャネルがクローズしている場合AsynchronousCloseException
- 書込み操作の進行中に別のスレッドによってこのチャネルがクローズされた場合ClosedByInterruptException
- 書込み中に別のスレッドからの割込みがあったためにチャネルがクローズし、現在のスレッドの割込みステータスが設定された場合IOException
- その他の入出力エラーが発生した場合public abstract long position() throws IOException
position
、インタフェース: SeekableByteChannel
ClosedChannelException
- このチャネルがクローズしている場合IOException
- その他の入出力エラーが発生した場合public abstract FileChannel position(long newPosition) throws IOException
位置の値をファイルの現在のサイズより大きい値に設定するのは正当な処理です。しかし、この処理によってファイルのサイズが変更されるわけではありません。ファイルの現在のサイズより大きい値が設定されている位置でバイトを読み取ろうとすると、即座にファイルの終わりが通知されます。同じ位置でバイトを書き込もうとすると、新しいバイトに合わせてファイルのサイズが大きくなります。以前のファイルの終わりから新しく書き込まれたバイトまでの間に存在するバイトの値は未指定です。
position
、インタフェース: SeekableByteChannel
newPosition
- 新しい位置。ファイルの先頭からのバイト数を示す負でない整数ClosedChannelException
- このチャネルがクローズしている場合IllegalArgumentException
- 新しい位置が負の値の場合IOException
- その他の入出力エラーが発生した場合public abstract long size() throws IOException
size
、インタフェース: SeekableByteChannel
ClosedChannelException
- このチャネルがクローズしている場合IOException
- その他の入出力エラーが発生した場合public abstract FileChannel truncate(long size) throws IOException
指定されたサイズが現在のファイル・サイズよりも小さい場合、ファイルの末尾が切り詰められ、新しいファイルの終わりに収まらないバイトが破棄されます。指定されたサイズが現在のファイル・サイズと同じか、それよりも大きい場合、ファイル・サイズは変更されません。どちらの場合も、このチャネルのファイル位置が指定されたサイズよりも大きい場合、そのサイズに合わせてファイル・サイズが変更されます。
truncate
、インタフェース: SeekableByteChannel
size
- 新しいサイズ。負ではないバイト数NonWritableChannelException
- このチャネルが書込み可能でない場合ClosedChannelException
- このチャネルがクローズしている場合IllegalArgumentException
- 新しいサイズが負の値の場合IOException
- その他の入出力エラーが発生した場合public abstract void force(boolean metaData) throws IOException
このチャネルのファイルがローカルの記憶装置上にある場合、このメソッドの戻り値から、このチャネルの作成時またはこのメソッドの一番最近の呼出し以降のファイルの変更内容がすべてそのデバイスに書き込まれていることがわかります。この方法により、システムがクラッシュしたとき、重要な情報を損失から保護できます。
一方、ファイルがローカルの記憶装置上にない場合、書込みは行われません。
metaDataパラメータを使って、このメソッドで実行しなければならない入出力操作の数を制限できます。このパラメータにfalseを渡した場合、ストレージに書き込む必要があるのは、ファイルのコンテンツの更新内容だけです。trueを渡した場合は、ファイルのコンテンツとメタデータの両方の更新内容を書き込む必要があります。これには、通常1個以上の入出力操作が必要です。このパラメータに実効性があるかどうかは、基礎となるオペレーティング・システムによって決まるため、未指定です。
このメソッドを呼び出すと、チャネルが読込み専用であっても入出力操作が発生します。たとえば、ファイルのメタデータとして最終アクセス時刻を保存し、ファイルの読込みのたびに更新するようなオペレーティング・システムもあります。この処理が実際に行われるかどうかはシステムによって決まるため、未指定です。
このメソッドは、このクラスに定義されたメソッドによってこのチャネルのファイルに加えられた変更を強制するだけです。map
メソッド呼出しによって取得したマップされたbyteバッファ
のコンテンツの変更によって生じる変更は、必ずしも強制されません。マップされたbyteバッファのforce
メソッドを呼び出すと、バッファ・コンテンツに対する変更内容が強制的に書き込まれます。
metaData
- trueの場合、このメソッドは、ファイルのコンテンツおよびメタデータの両方に対する変更をストレージに強制的に書き込む必要がある。それ以外の場合はコンテンツの変更のみを強制的に書き込む必要があるClosedChannelException
- このチャネルがクローズしている場合IOException
- その他の入出力エラーが発生した場合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
- その他の入出力エラーが発生した場合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
- その他の入出力エラーが発生した場合public abstract int read(ByteBuffer dst, long position) throws IOException
このメソッドは、バイトがチャネルの現在位置ではなく指定されたファイル位置から読み取られるという点を除けば、read(ByteBuffer)
メソッドと同じ方法で動作します。このメソッドはこのチャネルの位置を変更しません。指定された位置がファイルの現在のサイズより大きい場合、バイトは一切読み取られません。
dst
- バイトの転送先バッファposition
- 転送が開始されるファイル位置。負でない値である必要がありますIllegalArgumentException
- 位置が負の値の場合NonReadableChannelException
- このチャネルが読取り可能でない場合ClosedChannelException
- このチャネルがクローズしている場合AsynchronousCloseException
- 読取り操作の進行中に、別のスレッドによってこのチャネルがクローズされた場合ClosedByInterruptException
- 読取り操作の進行中に、別のスレッドからの割込みがあったためにチャネルがクローズし、現在のスレッドの割込みステータスが設定された場合IOException
- その他の入出力エラーが発生した場合public abstract int write(ByteBuffer src, long position) throws IOException
このメソッドは、バイトがチャネルの現在位置ではなく指定されたファイル位置から書き込まれるという点を除けば、write(ByteBuffer)
メソッドと同じ方法で動作します。このメソッドはこのチャネルの位置を変更しません。指定された位置が現在のファイル・サイズより大きい場合、ファイル・サイズは新しいバイトに合わせて大きくなります。以前のファイルの終わりと新しく書き込まれたバイトの間のバイトの値は未指定です。
src
- バイトの転送元バッファposition
- 転送が開始されるファイル位置。負でない値である必要がありますIllegalArgumentException
- 位置が負の値の場合NonWritableChannelException
- このチャネルが書込み可能でない場合ClosedChannelException
- このチャネルがクローズしている場合AsynchronousCloseException
- 書込み操作の進行中に別のスレッドによってこのチャネルがクローズされた場合ClosedByInterruptException
- 書込み中に別のスレッドからの割込みがあったためにチャネルがクローズし、現在のスレッドの割込みステータスが設定された場合IOException
- その他の入出力エラーが発生した場合public abstract MappedByteBuffer map(FileChannel.MapMode mode, long position, long size) throws IOException
ファイルの領域をメモリーにマッピングする処理は、次の3つのモードうちいずれかで行われます。
読込み専用: 結果のバッファを修正しようとするとReadOnlyBufferException
がスローされる。(MapMode.READ_ONLY
)
読み込み/書き込み: 結果のバッファへの変更は最終的にファイルに伝達される。この変更は、同じファイルをマッピングしているその他のプログラムによって認識される場合と、認識されない場合がある。(MapMode.READ_WRITE
)
非公開: 結果のバッファへの変更はファイルに伝達されず、同じファイルをマッピングしているその他のプログラムによって認識されることもない。その代わりに、バッファの変更された部分の非公開のコピーが作成される。(MapMode.PRIVATE
)
このチャネルは、読込み専用のマッピングの場合は読み込み、読み込み/書込みのマッピングまたは非公開マッピングの場合は読み込みと書込みの両方が可能になっていなければいけません。
このメソッドが返すマップされたbyteバッファ
の位置はゼロ、リミットと容量はsizeです。マークは未定義になります。バッファとこのバッファが示すマッピングは、バッファ自体がガベージ・コレクトされるまで有効です。
マッピングの結果は、その作成に使用されたファイル・チャネルには依存しません。たとえば、チャネルをクローズしても、マッピングの有効性は変わりません。
多くの場合、メモリーにマッピングされたファイルの詳細は、本質的に基礎となるオペレーティング・システムに依存するため、未指定です。要求された領域がこのチャネルのファイル内に完全には含まれていない場合、このメソッドの動作は未指定です。基礎となるファイルのコンテンツまたはサイズのどちらが変更されたか、このプログラムによる変更または別のプログラムによる変更のどちらか、および、変更がバッファに伝達されるかどうかは未指定です。バッファの変更がファイルに伝達される速度は未指定です。
ほとんどのオペレーティング・システムでは、ファイルをメモリーにマッピングするほうが、通常のread
メソッドまたはwrite
メソッドを使って数十キロバイトのデータの読み込みまたは書込みを行うよりも負荷が大きくなります。性能を重視するなら、比較的大きめのファイルだけをマッピングすることをお薦めします。
mode
- ファイルのマッピングを読込み専用モードで行う場合はFileChannel.MapMode
に定義されている定数READ_ONLY
、読み込み/書込みモードで行う場合は同クラスに定義されている定数READ_WRITE
、または非公開(copy-on-write)モードで行う場合は同クラスに定義されている定数PRIVATE
position
- ファイル内のマッピングされた領域の開始位置。負でないsize
- マッピングされる領域のサイズ。負でない、Integer.MAX_VALUE
以下の値NonReadableChannelException
- modeがREAD_ONLY
であるがこのチャネルが読取り不可であった場合NonWritableChannelException
- modeがREAD_WRITE
またはPRIVATE
であるがこのチャネルが読み取り/書込み不可であった場合IllegalArgumentException
- 上記のパラメータの前提条件が満たされていない場合IOException
- その他の入出力エラーが発生した場合FileChannel.MapMode
, MappedByteBuffer
public abstract FileLock lock(long position, long size, boolean shared) throws IOException
このメソッドの呼出しは、領域がロックされるか、このチャネルがクローズされるか、呼出し元スレッドに割込みが発生するまでブロックされます。
このメソッドの呼出し中にこのチャネルが別のスレッドによってクローズされると、AsynchronousCloseException
がスローされます。
ロックの獲得を待機中に呼出し元スレッドに割込みが発生した場合、割込みステータスが設定され、FileLockInterruptionException
がスローされます。このメソッドの呼出し時に呼出し元の割込み状態が設定されると、ただちに例外がスローされます。スレッドの割込み状態は変更されません。
positionパラメータとsizeパラメータで指定された領域が、基礎にあるファイルに含まれていたり、そのファイルとオーバーラップしたりしている必要はありません。ロック領域のサイズは固定です。初期状態ではファイルの終わりがロック領域内に含まれていても、ファイル・サイズがこの領域より大きくなってしまった場合、新しい部分にはロックが適用されません。ファイル全体にロックを適用する必要があるにもかかわらず、ファイル・サイズが大きくなる可能性がある場合は、ゼロから予測される最大ファイル・サイズ以上までの領域をロックします。ゼロ引数のlock()
メソッドは、単純にサイズLong.MAX_VALUE
の領域をロックします。
共有ロックをサポートしないオペレーティング・システムでは、共有ロック要求が排他ロック要求に自動的に変換されます。新しく獲得したロックが共有ロックであるか排他ロックであるかは、結果として得られるロック・オブジェクトのisShared
メソッドを呼び出すことで判断できます。
ファイル・ロックはJava仮想マシン全体のために保持されます。これらは、同一仮想マシン内の複数スレッドによるファイルへのアクセスを制御するのには適していません。
position
- ロック領域が開始されるファイル位置。負でない値である必要がありますsize
- ロック領域のサイズ。負でない値である必要があります。position + sizeも負でない値である必要がありますshared
- 共有ロックを要求する場合はtrue。この場合、このチャネルは読取りが(場合によっては書き込みも)可能である必要があります。排他ロックを要求する場合はfalse。この場合、このチャネルは書込みが(場合によっては読取りも)可能である必要がありますIllegalArgumentException
- 上記のパラメータの前提条件が満たされていない場合ClosedChannelException
- このチャネルがクローズしている場合AsynchronousCloseException
- このメソッド内で呼出し元スレッドがブロックされている間に、別のスレッドによってこのチャネルがクローズされた場合FileLockInterruptionException
- このメソッド内でブロックされている間に、呼出し元スレッドに割込みが発生した場合OverlappingFileLockException
- 要求された領域をオーバーラップするロックがこのJava仮想マシンにすでに確保されている場合。または、このメソッド内でブロックされている別のスレッドがオーバーラップした領域をロックしようとしている場合NonReadableChannelException
- sharedがtrueで、このチャネルが読取り不可であった場合NonWritableChannelException
- sharedがfalseであるがこのチャネルが書込み不可であった場合IOException
- その他の入出力エラーが発生した場合lock()
, tryLock()
, tryLock(long,long,boolean)
public final FileLock lock() throws IOException
このメソッドをfc.lock()の形式で呼び出した場合、次の呼び出しと同じ結果が得られます
fc.lock
(0L, Long.MAX_VALUE, false)
ClosedChannelException
- このチャネルがクローズしている場合AsynchronousCloseException
- このメソッド内で呼出し元スレッドがブロックされている間に、別のスレッドによってこのチャネルがクローズされた場合FileLockInterruptionException
- このメソッド内でブロックされている間に、呼出し元スレッドに割込みが発生した場合OverlappingFileLockException
- 要求された領域をオーバーラップするロックがこのJava仮想マシンにすでに確保されている場合。または、このメソッド内でブロックされている別のスレッドが同じファイルのオーバーラップした領域をロックしようとしている場合NonWritableChannelException
- このチャネルが書込み可能でない場合IOException
- その他の入出力エラーが発生した場合lock(long,long,boolean)
, tryLock()
, tryLock(long,long,boolean)
public abstract FileLock tryLock(long position, long size, boolean shared) throws IOException
このメソッドはブロックされません。このメソッドを呼び出すと、要求された領域でロックを獲得したか、ロックの獲得に失敗したかを示す結果がただちに返されます。オーバーラップしたロックが別のプログラムによって保持されていたためロックの取得に失敗した場合、nullが返されます。その他の原因でロックに失敗した場合は、適切な例外がスローされます。
positionパラメータとsizeパラメータで指定された領域が、基礎にあるファイルに含まれていたり、そのファイルとオーバーラップしたりしている必要はありません。ロック領域のサイズは固定です。初期状態ではファイルの終わりがロック領域内に含まれていても、ファイル・サイズがこの領域より大きくなってしまった場合、新しい部分にはロックが適用されません。ファイル全体にロックを適用する必要があるにもかかわらず、ファイル・サイズが大きくなる可能性がある場合は、ゼロから予測される最大ファイル・サイズ以上までの領域をロックします。ゼロ引数のtryLock()
メソッドは、単純にサイズLong.MAX_VALUE
の領域をロックします。
共有ロックをサポートしないオペレーティング・システムでは、共有ロック要求が排他ロック要求に自動的に変換されます。新しく獲得したロックが共有ロックであるか排他ロックであるかは、結果として得られるロック・オブジェクトのisShared
メソッドを呼び出すことで判断できます。
ファイル・ロックはJava仮想マシン全体のために保持されます。これらは、同一仮想マシン内の複数スレッドによるファイルへのアクセスを制御するのには適していません。
position
- ロック領域が開始されるファイル位置。負でない値である必要がありますsize
- ロック領域のサイズ。負でない値である必要があります。position + sizeも負でない値である必要がありますshared
- 共有ロックを要求する場合はtrue、排他ロックを要求する場合はfalseIllegalArgumentException
- 上記のパラメータの前提条件が満たされていない場合ClosedChannelException
- このチャネルがクローズしている場合OverlappingFileLockException
- 要求された領域をオーバーラップするロックがこのJava仮想マシンにすでに確保されている場合。または、このメソッド内でブロックされている別のスレッドが同じファイルのオーバーラップした領域をロックしようとしている場合IOException
- その他の入出力エラーが発生した場合lock()
, lock(long,long,boolean)
, tryLock()
public final FileLock tryLock() throws IOException
このメソッドをfc.tryLock()の形式で呼び出した場合、次の呼び出しと同じ結果が得られます
fc.tryLock
(0L, Long.MAX_VALUE, false)
ClosedChannelException
- このチャネルがクローズしている場合OverlappingFileLockException
- 要求された領域をオーバーラップするロックがこのJava仮想マシンにすでに確保されている場合。または、このメソッド内でブロックされている別のスレッドがオーバーラップした領域をロックしようとしている場合IOException
- その他の入出力エラーが発生した場合lock()
, lock(long,long,boolean)
, tryLock(long,long,boolean)
バグまたは機能を送信
詳細なAPIリファレンスおよび開発者ドキュメントについては、Java SEのドキュメントを参照してください。そのドキュメントには、概念的な概要、用語の定義、回避方法、有効なコード例などの、開発者を対象にしたより詳細な説明が含まれています。
Copyright © 1993, 2017, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Documentation Redistribution Policyも参照してください。