RandomAccessFileOutputStream.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */

  17. package org.apache.commons.io.output;

  18. import java.io.File;
  19. import java.io.IOException;
  20. import java.io.OutputStream;
  21. import java.io.RandomAccessFile;
  22. import java.nio.file.StandardOpenOption;

  23. import org.apache.commons.io.build.AbstractOrigin;
  24. import org.apache.commons.io.build.AbstractStreamBuilder;

  25. /**
  26.  * An {@link OutputStream} that writes to a {@link RandomAccessFile}.
  27.  *
  28.  * @since 2.18.0
  29.  */
  30. public final class RandomAccessFileOutputStream extends OutputStream {

  31.     // @formatter:off
  32.     /**
  33.      * Builds a new {@link RandomAccessFileOutputStream}.
  34.      * <p>
  35.      * For example:
  36.      * </p>
  37.      * <pre>{@code
  38.      * RandomAccessFileOutputStream s = RandomAccessFileOutputStream.builder()
  39.      *   .setFile("myfile.txt")
  40.      *   .setOpenOptions(StandardOpenOption.SYNC)
  41.      *   .get();}
  42.      * </pre>
  43.      * <p>
  44.      * The only super's aspect used is buffer size.
  45.      * </p>
  46.      *
  47.      * @see #get()
  48.      */
  49.     // @formatter:on
  50.     public static final class Builder extends AbstractStreamBuilder<RandomAccessFileOutputStream, Builder> {

  51.         /**
  52.          * Use {@link RandomAccessFileOutputStream#builder()}.
  53.          */
  54.         private Builder() {
  55.             setOpenOptions(StandardOpenOption.WRITE);
  56.         }

  57.         /**
  58.          * Builds a new {@link RandomAccessFileOutputStream}.
  59.          * <p>
  60.          * You must set an aspect that supports {@link RandomAccessFile} or {@link File}, otherwise, this method throws an exception. Only set one of
  61.          * RandomAccessFile or an origin that can be converted to a File.
  62.          * </p>
  63.          * <p>
  64.          * This builder uses the following aspects:
  65.          * </p>
  66.          * <ul>
  67.          * <li>{@link RandomAccessFile} is the target aspect.</li>
  68.          * <li>{@link File}</li>
  69.          * <li>closeOnClose</li>
  70.          * </ul>
  71.          *
  72.          * @return a new instance.
  73.          * @throws IllegalStateException         if the {@code origin} is {@code null}.
  74.          * @throws IllegalStateException         if both RandomAccessFile and origin are set.
  75.          * @throws UnsupportedOperationException if the origin cannot be converted to a {@link RandomAccessFile}.
  76.          * @throws IOException                   if an I/O error occurs converting to an {@link RandomAccessFile} using {@link #getRandomAccessFile()}.
  77.          * @see AbstractOrigin#getFile()
  78.          * @see #getUnchecked()
  79.          */
  80.         @Override
  81.         public RandomAccessFileOutputStream get() throws IOException {
  82.             return new RandomAccessFileOutputStream(this);
  83.         }

  84.     }

  85.     /**
  86.      * Constructs a new {@link Builder}.
  87.      *
  88.      * @return a new {@link Builder}.
  89.      */
  90.     public static Builder builder() {
  91.         return new Builder();
  92.     }

  93.     private final RandomAccessFile randomAccessFile;

  94.     private RandomAccessFileOutputStream(final Builder builder) throws IOException {
  95.         this.randomAccessFile = builder.getRandomAccessFile();
  96.     }

  97.     @Override
  98.     public void close() throws IOException {
  99.         this.randomAccessFile.close();
  100.         super.close();
  101.     }

  102.     @SuppressWarnings("resource")
  103.     @Override
  104.     public void flush() throws IOException {
  105.         randomAccessFile.getChannel().force(true);
  106.         super.flush();
  107.     }

  108.     /**
  109.      * Gets the underlying random access file.
  110.      *
  111.      * @return the underlying random access file.
  112.      * @since 2.19.0
  113.      */
  114.     public RandomAccessFile getRandomAccessFile() {
  115.         return randomAccessFile;
  116.     }

  117.     @Override
  118.     public void write(final int b) throws IOException {
  119.         randomAccessFile.write(b);
  120.     }

  121. }