io.jsync.file.AsyncFile Maven / Gradle / Ivy
Show all versions of jsync.io Show documentation
/*
* Copyright (c) 2011-2013 The original author or authors
* ------------------------------------------------------
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* and Apache License v2.0 which accompanies this distribution.
*
* The Eclipse Public License is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* The Apache License v2.0 is available at
* http://www.opensource.org/licenses/apache2.0.php
*
* You may elect to redistribute this code under either of these licenses.
*/
package io.jsync.file;
import io.jsync.AsyncResult;
import io.jsync.Handler;
import io.jsync.buffer.Buffer;
import io.jsync.streams.ReadStream;
import io.jsync.streams.WriteStream;
/**
* Represents a file on the file-system which can be read from, or written to asynchronously.
* This class also implements {@link io.jsync.streams.ReadStream} and
* {@link io.jsync.streams.WriteStream}. This allows the data to be pumped to and from
* other streams, e.g. an {@link io.jsync.http.HttpClientRequest} instance,
* using the {@link io.jsync.streams.Pump} class
* Instances of AsyncFile are not thread-safe
*
* @author Tim Fox
*/
public interface AsyncFile extends ReadStream, WriteStream {
/**
* Close the file. The actual close happens asynchronously.
*/
void close();
/**
* Close the file. The actual close happens asynchronously.
* The handler will be called when the close is complete, or an error occurs.
*/
void close(Handler> handler);
/**
* Write a {@link Buffer} to the file at position {@code position} in the file, asynchronously.
* If {@code 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.
*/
AsyncFile write(Buffer buffer, long position, Handler> handler);
/**
* Reads {@code length} bytes of data from the file at position {@code position} in the file, asynchronously.
* The read data will be written into the specified {@code Buffer buffer} at position {@code 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.
*/
AsyncFile read(Buffer buffer, int offset, long position, int length, Handler> handler);
/**
* Flush any writes made to this file to underlying persistent storage.
* If the file was opened with {@code flush} set to {@code true} then calling this method will have no effect.
* The actual flush will happen asynchronously.
*/
AsyncFile flush();
/**
* Same as {@link #flush} but the handler will be called when the flush is complete or if an error occurs
*/
AsyncFile flush(Handler> handler);
}