View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *   http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  package org.eclipse.aether.util;
20  
21  import java.io.Closeable;
22  import java.io.IOException;
23  import java.io.InputStream;
24  import java.io.OutputStream;
25  import java.nio.ByteBuffer;
26  import java.nio.channels.FileChannel;
27  import java.nio.file.Files;
28  import java.nio.file.Path;
29  import java.nio.file.StandardCopyOption;
30  import java.nio.file.StandardOpenOption;
31  import java.util.concurrent.ThreadLocalRandom;
32  import java.util.concurrent.atomic.AtomicBoolean;
33  
34  import static java.util.Objects.requireNonNull;
35  
36  /**
37   * A utility class to write files.
38   *
39   * @since 1.9.0
40   */
41  public final class FileUtils {
42      // Logic borrowed from Commons-Lang3: we really need only this, to decide do we fsync on directories or not
43      private static final boolean IS_WINDOWS =
44              System.getProperty("os.name", "unknown").startsWith("Windows");
45  
46      private FileUtils() {
47          // hide constructor
48      }
49  
50      /**
51       * A temporary file, that is removed when closed.
52       */
53      public interface TempFile extends Closeable {
54          /**
55           * Returns the path of the created temp file.
56           */
57          Path getPath();
58      }
59  
60      /**
61       * A collocated temporary file, that resides next to a "target" file, and is removed when closed.
62       */
63      public interface CollocatedTempFile extends TempFile {
64          /**
65           * Upon close, atomically moves temp file to target file it is collocated with overwriting target (if exists).
66           * Invocation of this method merely signals that caller ultimately wants temp file to replace the target
67           * file, but when this method returns, the move operation did not yet happen, it will happen when this
68           * instance is closed.
69           */
70          void move() throws IOException;
71      }
72  
73      /**
74       * Creates a {@link TempFile} instance and backing temporary file on file system. It will be located in the default
75       * temporary-file directory. Returned instance should be handled in try-with-resource construct and created
76       * temp file is removed (if exists) when returned instance is closed.
77       * <p>
78       * This method uses {@link Files#createTempFile(String, String, java.nio.file.attribute.FileAttribute[])} to create
79       * the temporary file on file system.
80       */
81      public static TempFile newTempFile() throws IOException {
82          Path tempFile = Files.createTempFile("resolver", "tmp");
83          return new TempFile() {
84              @Override
85              public Path getPath() {
86                  return tempFile;
87              }
88  
89              @Override
90              public void close() throws IOException {
91                  Files.deleteIfExists(tempFile);
92              }
93          };
94      }
95  
96      /**
97       * Creates a {@link CollocatedTempFile} instance for given file without backing file. The path will be located in
98       * same directory where given file is, and will reuse its name for generated (randomized) name. Returned instance
99       * should be handled in try-with-resource and created temp path is removed (if exists) when returned instance is
100      * closed. The {@link CollocatedTempFile#move()} makes possible to atomically replace passed in file with the
101      * processed content written into a file backing the {@link CollocatedTempFile} instance.
102      * <p>
103      * The {@code file} nor it's parent directories have to exist. The parent directories are created if needed.
104      * <p>
105      * This method uses {@link Path#resolve(String)} to create the temporary file path in passed in file parent
106      * directory, but it does NOT create backing file on file system.
107      */
108     public static CollocatedTempFile newTempFile(Path file) throws IOException {
109         Path parent = requireNonNull(file.getParent(), "file must have parent");
110         Files.createDirectories(parent);
111         Path tempFile = parent.resolve(file.getFileName() + "."
112                 + Long.toUnsignedString(ThreadLocalRandom.current().nextLong()) + ".tmp");
113         return new CollocatedTempFile() {
114             private final AtomicBoolean wantsMove = new AtomicBoolean(false);
115 
116             @Override
117             public Path getPath() {
118                 return tempFile;
119             }
120 
121             @Override
122             public void move() {
123                 wantsMove.set(true);
124             }
125 
126             @Override
127             public void close() throws IOException {
128                 if (wantsMove.get() && Files.isReadable(tempFile)) {
129                     if (IS_WINDOWS) {
130                         copy(tempFile, file);
131                     } else {
132                         fsyncFile(tempFile);
133                         Files.move(tempFile, file, StandardCopyOption.ATOMIC_MOVE);
134                         fsyncParent(tempFile);
135                     }
136                 }
137                 Files.deleteIfExists(tempFile);
138             }
139         };
140     }
141 
142     /**
143      * On Windows we use pre-NIO2 way to copy files, as for some reason it works. Beat me why.
144      */
145     private static void copy(Path source, Path target) throws IOException {
146         ByteBuffer buffer = ByteBuffer.allocate(1024 * 32);
147         byte[] array = buffer.array();
148         try (InputStream is = Files.newInputStream(source);
149                 OutputStream os = Files.newOutputStream(target)) {
150             while (true) {
151                 int bytes = is.read(array);
152                 if (bytes < 0) {
153                     break;
154                 }
155                 os.write(array, 0, bytes);
156             }
157         }
158     }
159 
160     /**
161      * Performs fsync: makes sure no OS "dirty buffers" exist for given file.
162      *
163      * @param target Path that must not be {@code null}, must exist as plain file.
164      */
165     private static void fsyncFile(Path target) throws IOException {
166         try (FileChannel file = FileChannel.open(target, StandardOpenOption.WRITE)) {
167             file.force(true);
168         }
169     }
170 
171     /**
172      * Performs directory fsync: not usable on Windows, but some other OSes may also throw, hence thrown IO exception
173      * is just ignored.
174      *
175      * @param target Path that must not be {@code null}, must exist as plain file, and must have parent.
176      */
177     private static void fsyncParent(Path target) throws IOException {
178         try (FileChannel parent = FileChannel.open(target.getParent(), StandardOpenOption.READ)) {
179             try {
180                 parent.force(true);
181             } catch (IOException e) {
182                 // ignore
183             }
184         }
185     }
186 
187     /**
188      * A file writer, that accepts a {@link Path} to write some content to. Note: the file denoted by path may exist,
189      * hence implementation have to ensure it is able to achieve its goal ("replace existing" option or equivalent
190      * should be used).
191      */
192     @FunctionalInterface
193     public interface FileWriter {
194         void write(Path path) throws IOException;
195     }
196 
197     /**
198      * Writes file without backup.
199      *
200      * @param target that is the target file (must be file, the path must have parent).
201      * @param writer the writer that will accept a {@link Path} to write content to.
202      * @throws IOException if at any step IO problem occurs.
203      */
204     public static void writeFile(Path target, FileWriter writer) throws IOException {
205         writeFile(target, writer, false);
206     }
207 
208     /**
209      * Writes file with backup copy (appends ".bak" extension).
210      *
211      * @param target that is the target file (must be file, the path must have parent).
212      * @param writer the writer that will accept a {@link Path} to write content to.
213      * @throws IOException if at any step IO problem occurs.
214      */
215     public static void writeFileWithBackup(Path target, FileWriter writer) throws IOException {
216         writeFile(target, writer, true);
217     }
218 
219     /**
220      * Utility method to write out file to disk in "atomic" manner, with optional backups (".bak") if needed. This
221      * ensures that no other thread or process will be able to read not fully written files. Finally, this methos
222      * may create the needed parent directories, if the passed in target parents does not exist.
223      *
224      * @param target   that is the target file (must be an existing or non-existing file, the path must have parent).
225      * @param writer   the writer that will accept a {@link Path} to write content to.
226      * @param doBackup if {@code true}, and target file is about to be overwritten, a ".bak" file with old contents will
227      *                 be created/overwritten.
228      * @throws IOException if at any step IO problem occurs.
229      */
230     private static void writeFile(Path target, FileWriter writer, boolean doBackup) throws IOException {
231         requireNonNull(target, "target is null");
232         requireNonNull(writer, "writer is null");
233         Path parent = requireNonNull(target.getParent(), "target must have parent");
234 
235         try (CollocatedTempFile tempFile = newTempFile(target)) {
236             writer.write(tempFile.getPath());
237             if (doBackup && Files.isRegularFile(target)) {
238                 Files.copy(target, parent.resolve(target.getFileName() + ".bak"), StandardCopyOption.REPLACE_EXISTING);
239             }
240             tempFile.move();
241         }
242     }
243 }