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