Java tutorial
/* * Copyright 2017 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package ratpack.file; import com.google.common.collect.ImmutableSet; import io.netty.buffer.ByteBuf; import io.netty.buffer.ByteBufAllocator; import io.netty.buffer.CompositeByteBuf; import org.reactivestreams.Publisher; import ratpack.exec.Blocking; import ratpack.exec.Execution; import ratpack.exec.Operation; import ratpack.exec.Promise; import ratpack.file.internal.FileReadingPublisher; import ratpack.file.internal.FileWritingSubscriber; import ratpack.stream.TransformablePublisher; import ratpack.stream.bytebuf.ByteBufStreams; import java.nio.channels.AsynchronousFileChannel; import java.nio.channels.CompletionHandler; import java.nio.file.OpenOption; import java.nio.file.Path; import java.nio.file.attribute.FileAttribute; import java.util.Set; import java.util.concurrent.ExecutorService; /** * Utilities for streaming to and from files. * * @since 1.5 */ public class FileIo { private FileIo() { } /** * Creates a promise for an (open) async file channel. * <p> * Uses {@link AsynchronousFileChannel#open(Path, Set, ExecutorService, FileAttribute[])}, * but uses the current execution's event loop as the executor service and no file attributes. * * @param file The path of the file to open or create * @param options Options specifying how the file is opened * @see AsynchronousFileChannel#open(Path, Set, ExecutorService, FileAttribute[]) * @see #open(Path, Set, FileAttribute[]) * @return a promise for an open async file channel */ public static Promise<AsynchronousFileChannel> open(Path file, OpenOption... options) { return open(file, ImmutableSet.copyOf(options)); } /** * Creates a promise for an (open) async file channel. * <p> * Uses {@link AsynchronousFileChannel#open(Path, Set, ExecutorService, FileAttribute[])}, * but uses the current execution's event loop as the executor service. * * @param file The path of the file to open or create * @param options Options specifying how the file is opened * @param attrs An optional list of file attributes to set atomically when creating the file * @see AsynchronousFileChannel#open(Path, Set, ExecutorService, FileAttribute[]) * @see #open(Path, OpenOption...) * @return a promise for an open async file channel */ public static Promise<AsynchronousFileChannel> open(Path file, Set<? extends OpenOption> options, FileAttribute<?>... attrs) { return Blocking .get(() -> AsynchronousFileChannel.open(file, options, Execution.current().getEventLoop(), attrs)); } /** * Writes the bytes of the given publisher to the given file starting at the start, returning the number of bytes written. * <p> * Use {@link #open(Path, Set, FileAttribute[])} to create a file promise. * <p> * The file channel is closed on success or failure. * <p> * As file system writes are expensive, * you may want to consider using {@link ByteBufStreams#buffer(Publisher, long, int, ByteBufAllocator)} * to buffer?the data in memory before writing to disk. * * @param publisher the bytes to write * @param file a promise for the file to write to * @return a promise for the number of bytes written */ public static Promise<Long> write(Publisher<? extends ByteBuf> publisher, Promise<? extends AsynchronousFileChannel> file) { return write(publisher, 0, file); } /** Writes the bytes of the given publisher to the given file, returning the number of bytes written. * <p> * Use {@link #open(Path, Set, FileAttribute[])} to create a file promise. * <p> * The file channel is closed on success or failure. * <p> * As file system writes are expensive, * you may want to consider using {@link ByteBufStreams#buffer(Publisher, long, int, ByteBufAllocator)} * to buffer?the data in memory before writing to disk. * * @param publisher the bytes to write * @param position the position in the file to start writing (must be >= 0) * @param file a promise for the file to write to * @return a promise for the number of bytes written */ public static Promise<Long> write(Publisher<? extends ByteBuf> publisher, long position, Promise<? extends AsynchronousFileChannel> file) { return file.flatMap(fileChannel -> Promise .<Long>async(down -> publisher.subscribe(new FileWritingSubscriber(fileChannel, position, down))) .close(Blocking.op(((AsynchronousFileChannel) fileChannel)::close))); } /** * Writes the given bytes to the given file, starting at the start. * Use {@link #open(Path, Set, FileAttribute[])} to create a file promise. * <p> * The file channel is closed on success or failure. * * @param bytes the bytes to write * @param file the file to write to * @return a write operation */ public static Operation write(ByteBuf bytes, Promise<? extends AsynchronousFileChannel> file) { return write(bytes, 0, file); } /** * Writes the given bytes to the given file, starting at the given position. * Use {@link #open(Path, Set, FileAttribute[])} to create a file promise. * <p> * The file channel is closed on success or failure. * * @param bytes the bytes to write * @param position the position in the file to start writing * @param file the file to write to * @return a write operation */ public static Operation write(ByteBuf bytes, long position, Promise<? extends AsynchronousFileChannel> file) { return file.flatMap(channel -> Promise.async( down -> channel.write(bytes.nioBuffer(), position, null, new CompletionHandler<Integer, Void>() { @Override public void completed(Integer result, Void attachment) { bytes.readerIndex(bytes.readerIndex() + result); down.success(null); } @Override public void failed(Throwable exc, Void attachment) { down.error(exc); } })).close(bytes::release).close(Blocking.op(((AsynchronousFileChannel) channel)::close))) .operation(); } /** * Streams the contents of a file. * <p> * Use {@link #open(Path, Set, FileAttribute[])} to create a file promise. * <p> * The file channel is closed on success or failure. * * @param file a promise for the file to write to * @param allocator the allocator of byte bufs * @param bufferSize the read buffer size (i.e. the size of each emitted buffer) * @param start the position in the file to start reading from (must be >= 0) * @param stop the position in the file to read up to (any value < 1 is treated as EOF) * @see #readStream(Promise, ByteBufAllocator, int) * @return a publisher of the byte bufs */ public static TransformablePublisher<ByteBuf> readStream(Promise<? extends AsynchronousFileChannel> file, ByteBufAllocator allocator, int bufferSize, long start, long stop) { return new FileReadingPublisher(file, allocator, bufferSize, start, stop); } /** * Streams the entire contents of a file. * <p> * Use {@link #open(Path, Set, FileAttribute[])} to create a file promise. * <p> * The file channel is closed on success or failure. * * @param file a promise for the file to write to * @param allocator the allocator of byte bufs * @param bufferSize the read buffer size (i.e. the size of each emitted buffer) * @see #readStream(Promise, ByteBufAllocator, int, long, long) * @return a publisher of the byte bufs */ public static TransformablePublisher<ByteBuf> readStream(Promise<? extends AsynchronousFileChannel> file, ByteBufAllocator allocator, int bufferSize) { return new FileReadingPublisher(file, allocator, bufferSize, 0, 0); } /** * Read the contents of a file. * <p> * Use {@link #open(Path, Set, FileAttribute[])} to create a file promise. * <p> * The file channel is closed on success or failure. * * @param file a promise for the file to write to * @param allocator the allocator of byte bufs * @param bufferSize the read buffer size (i.e. the size of buffer used for each read operation) * @see #readStream(Promise, ByteBufAllocator, int) * @see #read(Promise, ByteBufAllocator, int) * @return a publisher of the byte bufs */ public static Promise<CompositeByteBuf> read(Promise<? extends AsynchronousFileChannel> file, ByteBufAllocator allocator, int bufferSize, long start, long stop) { return ByteBufStreams.compose(readStream(file, allocator, bufferSize, start, stop), allocator); } /** * Read the contents of a file from the given start until the given stop. * <p> * Use {@link #open(Path, Set, FileAttribute[])} to create a file promise. * <p> * The file channel is closed on success or failure. * * @param file a promise for the file to write to * @param allocator the allocator of byte bufs * @param bufferSize the read buffer size (i.e. the size of buffer used for each read operation) * @see #readStream(Promise, ByteBufAllocator, int, long, long) * @see #read(Promise, ByteBufAllocator, int, long, long) * @return a publisher of the byte bufs */ public static Promise<CompositeByteBuf> read(Promise<? extends AsynchronousFileChannel> file, ByteBufAllocator allocator, int bufferSize) { return ByteBufStreams.compose(readStream(file, allocator, bufferSize), allocator); } }