/*
 * Copyright (c) 2011-2019 Contributors to the Eclipse Foundation
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
 * which is available at https://www.apache.org/licenses/LICENSE-2.0.
 *
 * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
 */

package io.vertx.core.file;

import io.vertx.codegen.annotations.Fluent;
import io.vertx.codegen.annotations.VertxGen;
import io.vertx.core.AsyncResult;
import io.vertx.core.Future;
import io.vertx.core.Handler;
import io.vertx.core.buffer.Buffer;
import io.vertx.core.streams.ReadStream;
import io.vertx.core.streams.WriteStream;

Represents a file on the file-system which can be read from, or written to asynchronously.

This class also implements ReadStream and WriteStream. This allows the data to be piped to and from other streams, e.g. an HttpClientRequest instance, using the Pipe class

Author:Tim Fox
/** * Represents a file on the file-system which can be read from, or written to asynchronously. * <p> * This class also implements {@link io.vertx.core.streams.ReadStream} and * {@link io.vertx.core.streams.WriteStream}. This allows the data to be piped to and from * other streams, e.g. an {@link io.vertx.core.http.HttpClientRequest} instance, * using the {@link io.vertx.core.streams.Pipe} class * * @author <a href="http://tfox.org">Tim Fox</a> */
@VertxGen public interface AsyncFile extends ReadStream<Buffer>, WriteStream<Buffer> { @Override AsyncFile handler(Handler<Buffer> handler); @Override AsyncFile pause(); @Override AsyncFile resume(); @Override AsyncFile endHandler(Handler<Void> endHandler); @Override AsyncFile setWriteQueueMaxSize(int maxSize); @Override AsyncFile drainHandler(Handler<Void> handler); @Override AsyncFile exceptionHandler(Handler<Throwable> handler); @Override AsyncFile fetch(long amount);
Close the file. The actual close happens asynchronously.
Returns:a future completed with the result
/** * Close the file. The actual close happens asynchronously. * * @return a future completed with the result */
Future<Void> close();
Close the file. The actual close happens asynchronously. The handler will be called when the close is complete, or an error occurs.
Params:
  • handler – the handler
/** * Close the file. The actual close happens asynchronously. * The handler will be called when the close is complete, or an error occurs. * * @param handler the handler */
void close(Handler<AsyncResult<Void>> handler);
Write a Buffer to the file at position position in the file, asynchronously.

If position lies outside of the current size of the file, the file will be enlarged to encompass it.

When multiple writes are invoked on the same file there are no guarantees as to order in which those writes actually occur

The handler will be called when the write is complete, or if an error occurs.

Params:
  • buffer – the buffer to write
  • position – the position in the file to write it at
  • handler – the handler to call when the write is complete
/** * Write a {@link io.vertx.core.buffer.Buffer} to the file at position {@code position} in the file, asynchronously. * <p> * If {@code position} lies outside of the current size * of the file, the file will be enlarged to encompass it. * <p> * When multiple writes are invoked on the same file * there are no guarantees as to order in which those writes actually occur * <p> * The handler will be called when the write is complete, or if an error occurs. * * @param buffer the buffer to write * @param position the position in the file to write it at * @param handler the handler to call when the write is complete */
void write(Buffer buffer, long position, Handler<AsyncResult<Void>> handler);
Like write(Buffer, long, Handler<AsyncResult<Void>>) but returns a Future of the asynchronous result
/** * Like {@link #write(Buffer, long, Handler)} but returns a {@code Future} of the asynchronous result */
Future<Void> write(Buffer buffer, long position);
Reads length bytes of data from the file at position position in the file, asynchronously.

The read data will be written into the specified Buffer buffer at position offset.

If data is read past the end of the file then zero bytes will be read.

When multiple reads are invoked on the same file there are no guarantees as to order in which those reads actually occur.

The handler will be called when the close is complete, or if an error occurs.

Params:
  • buffer – the buffer to read into
  • offset – the offset into the buffer where the data will be read
  • position – the position in the file where to start reading
  • length – the number of bytes to read
  • handler – the handler to call when the write is complete
Returns:a reference to this, so the API can be used fluently
/** * Reads {@code length} bytes of data from the file at position {@code position} in the file, asynchronously. * <p> * The read data will be written into the specified {@code Buffer buffer} at position {@code offset}. * <p> * If data is read past the end of the file then zero bytes will be read.<p> * When multiple reads are invoked on the same file there are no guarantees as to order in which those reads actually occur. * <p> * The handler will be called when the close is complete, or if an error occurs. * * @param buffer the buffer to read into * @param offset the offset into the buffer where the data will be read * @param position the position in the file where to start reading * @param length the number of bytes to read * @param handler the handler to call when the write is complete * @return a reference to this, so the API can be used fluently */
@Fluent AsyncFile read(Buffer buffer, int offset, long position, int length, Handler<AsyncResult<Buffer>> handler);
Like read(Buffer, int, long, int, Handler<AsyncResult<Buffer>>) but returns a Future of the asynchronous result
/** * Like {@link #read(Buffer, int, long, int, Handler)} but returns a {@code Future} of the asynchronous result */
Future<Buffer> read(Buffer buffer, int offset, long position, int length);
Flush any writes made to this file to underlying persistent storage.

If the file was opened with flush set to true then calling this method will have no effect.

The actual flush will happen asynchronously.

Returns:a future completed with the result
/** * Flush any writes made to this file to underlying persistent storage. * <p> * If the file was opened with {@code flush} set to {@code true} then calling this method will have no effect. * <p> * The actual flush will happen asynchronously. * * @return a future completed with the result */
Future<Void> flush();
Same as flush but the handler will be called when the flush is complete or if an error occurs
/** * Same as {@link #flush} but the handler will be called when the flush is complete or if an error occurs */
@Fluent AsyncFile flush(Handler<AsyncResult<Void>> handler);
Sets the position from which data will be read from when using the file as a ReadStream.
Params:
  • readPos – the position in the file
Returns:a reference to this, so the API can be used fluently
/** * Sets the position from which data will be read from when using the file as a {@link io.vertx.core.streams.ReadStream}. * * @param readPos the position in the file * @return a reference to this, so the API can be used fluently */
@Fluent AsyncFile setReadPos(long readPos);
Sets the number of bytes that will be read when using the file as a ReadStream.
Params:
  • readLength – the bytes that will be read from the file
Returns:a reference to this, so the API can be used fluently
/** * Sets the number of bytes that will be read when using the file as a {@link io.vertx.core.streams.ReadStream}. * * @param readLength the bytes that will be read from the file * @return a reference to this, so the API can be used fluently */
@Fluent AsyncFile setReadLength(long readLength);
Returns:the number of bytes that will be read when using the file as a ReadStream
/** * @return the number of bytes that will be read when using the file as a {@link io.vertx.core.streams.ReadStream} */
long getReadLength();
Sets the position from which data will be written when using the file as a WriteStream.
Params:
  • writePos – the position in the file
Returns:a reference to this, so the API can be used fluently
/** * Sets the position from which data will be written when using the file as a {@link io.vertx.core.streams.WriteStream}. * * @param writePos the position in the file * @return a reference to this, so the API can be used fluently */
@Fluent AsyncFile setWritePos(long writePos);
Returns:the current write position the file is at
/** * @return the current write position the file is at */
long getWritePos();
Sets the buffer size that will be used to read the data from the file. Changing this value will impact how much the data will be read at a time from the file system.
Params:
  • readBufferSize – the buffer size
Returns:a reference to this, so the API can be used fluently
/** * Sets the buffer size that will be used to read the data from the file. Changing this value will impact how much * the data will be read at a time from the file system. * @param readBufferSize the buffer size * @return a reference to this, so the API can be used fluently */
@Fluent AsyncFile setReadBufferSize(int readBufferSize); }