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.spi.io;
20
21 import java.io.*;
22 import java.nio.ByteBuffer;
23 import java.nio.file.Files;
24 import java.nio.file.NoSuchFileException;
25 import java.nio.file.Path;
26
27 /**
28 * A utility component to perform file-based operations.
29 *
30 * @since 2.0.0
31 */
32 public interface PathProcessor {
33 /**
34 * Returns last modified of path in milliseconds, if exists.
35 *
36 * @param path The path, may be {@code null}.
37 * @throws UncheckedIOException If an I/O error occurs.
38 */
39 default long lastModified(Path path, long defValue) {
40 try {
41 return Files.getLastModifiedTime(path).toMillis();
42 } catch (NoSuchFileException e) {
43 return defValue;
44 } catch (IOException e) {
45 throw new UncheckedIOException(e);
46 }
47 }
48
49 /**
50 * Sets last modified of path in milliseconds, if exists.
51 *
52 * @param path The path, may be {@code null}.
53 * @throws IOException If an I/O error occurs. Some exceptions/reasons of failure to set mtime may be swallowed,
54 * and can be multiple, ranging from "file not found" to cases when FS does not support the setting the mtime.
55 * @since 2.0.0
56 */
57 void setLastModified(Path path, long value) throws IOException;
58
59 /**
60 * Returns size of file, if exists.
61 *
62 * @param path The path, may be {@code null}.
63 * @throws UncheckedIOException If an I/O error occurs.
64 */
65 default long size(Path path, long defValue) {
66 try {
67 return Files.size(path);
68 } catch (NoSuchFileException e) {
69 return defValue;
70 } catch (IOException e) {
71 throw new UncheckedIOException(e);
72 }
73 }
74
75 /**
76 * Writes the given data to a file. UTF-8 is assumed as encoding for the data. Creates the necessary directories for
77 * the target file. In case of an error, the created directories will be left on the file system.
78 *
79 * @param target The file to write to, must not be {@code null}. This file will be overwritten.
80 * @param data The data to write, may be {@code null}.
81 * @throws IOException If an I/O error occurs.
82 */
83 void write(Path target, String data) throws IOException;
84
85 /**
86 * Writes the given stream to a file. Creates the necessary directories for the target file. In case of an error,
87 * the created directories will be left on the file system.
88 *
89 * @param target The file to write to, must not be {@code null}. This file will be overwritten.
90 * @param source The stream to write to the file, must not be {@code null}.
91 * @throws IOException If an I/O error occurs.
92 */
93 void write(Path target, InputStream source) throws IOException;
94
95 /**
96 * Moves the specified source file to the given target file. If the target file already exists, it is overwritten.
97 * Creates the necessary directories for the target file. In case of an error, the created directories will be left
98 * on the file system.
99 *
100 * @param source The file to move from, must not be {@code null}.
101 * @param target The file to move to, must not be {@code null}.
102 * @throws IOException If an I/O error occurs.
103 */
104 void move(Path source, Path target) throws IOException;
105
106 /**
107 * Copies the specified source file to the given target file. Creates the necessary directories for the target file.
108 * In case of an error, the created directories will be left on the file system.
109 *
110 * @param source The file to copy from, must not be {@code null}.
111 * @param target The file to copy to, must not be {@code null}.
112 * @throws IOException If an I/O error occurs.
113 */
114 default void copy(Path source, Path target) throws IOException {
115 copy(source, target, null);
116 }
117
118 /**
119 * Same as {@link #copy(Path, Path)} but sets source file last modified timestamp on target as well.
120 *
121 * @param source The file to copy from, must not be {@code null}.
122 * @param target The file to copy to, must not be {@code null}.
123 * @throws IOException If an I/O error occurs.
124 * @see #setLastModified(Path, long)
125 * @since 2.0.0
126 */
127 default void copyWithTimestamp(Path source, Path target) throws IOException {
128 copy(source, target, null);
129 setLastModified(target, Files.getLastModifiedTime(source).toMillis());
130 }
131
132 /**
133 * Copies the specified source file to the given target file. Creates the necessary directories for the target file.
134 * In case of an error, the created directories will be left on the file system.
135 *
136 * @param source The file to copy from, must not be {@code null}.
137 * @param target The file to copy to, must not be {@code null}.
138 * @param listener The listener to notify about the copy progress, may be {@code null}.
139 * @return The number of copied bytes.
140 * @throws IOException If an I/O error occurs.
141 */
142 long copy(Path source, Path target, ProgressListener listener) throws IOException;
143
144 /**
145 * A listener object that is notified for every progress made while copying files.
146 *
147 * @see PathProcessor#copy(Path, Path, ProgressListener)
148 */
149 interface ProgressListener {
150
151 void progressed(ByteBuffer buffer) throws IOException;
152 }
153 }