devonfw/IDEasy | Build 12708813826 | com/devonfw/tools/ide/io/FileAccess.java | Coveralls

1

package com.devonfw.tools.ide.io;

2

3

import java.nio.file.Path;

4

import java.nio.file.attribute.PosixFilePermission;

5

import java.util.List;

6

import java.util.Set;

7

import java.util.function.Consumer;

8

import java.util.function.Predicate;

9

10

/**

11

 * Interface that gives access to various operations on files.

12

*/

13

public interface FileAccess {

14

15

  /** {@link PosixFilePermission}s for "rwxr-xr-x" or 0755. */

17

      PosixFilePermission.GROUP_READ, PosixFilePermission.GROUP_EXECUTE, PosixFilePermission.OTHERS_READ, PosixFilePermission.OTHERS_EXECUTE);

18

19

/**

20

   * Downloads a file from an arbitrary location.

21

22

   * @param url the location of the binary file to download. May also be a local or remote path to copy from.

23

   * @param targetFile the {@link Path} to the target file to download to. Should not already exist. Missing parent directories will be created

24

   *     automatically.

25

*/

26

  void download(String url, Path targetFile);

27

28

/**

29

   * Creates the entire {@link Path} as directories if not already existing.

30

31

   * @param directory the {@link Path} to {@link java.nio.file.Files#createDirectories(Path, java.nio.file.attribute.FileAttribute...) create}.

32

*/

33

  void mkdirs(Path directory);

34

35

/**

36

   * @param file the {@link Path} to check.

37

   * @return {@code true} if the given {@code file} points to an existing file, {@code false} otherwise (the given {@link Path} does not exist or is a

38

   *     directory).

39

*/

40

  boolean isFile(Path file);

41

42

/**

43

   * @param folder the {@link Path} to check.

44

   * @return {@code true} if the given {@code folder} points to an existing directory, {@code false} otherwise (a warning is logged in this case).

45

*/

46

  boolean isExpectedFolder(Path folder);

47

48

/**

49

   * @param file the {@link Path} to compute the checksum of.

50

   * @return the computed checksum (SHA-266).

51

*/

52

  String checksum(Path file);

53

54

/**

55

   * Moves the given {@link Path} to the backup.

56

57

   * @param fileOrFolder the {@link Path} to move to the backup (soft-deletion).

58

*/

59

  void backup(Path fileOrFolder);

60

61

/**

62

   * @param source the source {@link Path file or folder} to move.

63

   * @param targetDir the {@link Path} with the directory to move {@code source} into.

64

*/

65

  void move(Path source, Path targetDir);

66

67

/**

68

   * Creates a symbolic link. If the given {@code targetLink} already exists and is a symbolic link or a Windows junction, it will be replaced. In case of

69

   * missing privileges, Windows Junctions may be used as fallback, which must point to absolute paths. Therefore, the created link will be absolute instead of

70

   * relative.

71

72

   * @param source the source {@link Path} to link to, may be relative or absolute.

73

   * @param targetLink the {@link Path} where the symbolic link shall be created pointing to {@code source}.

74

   * @param relative - {@code true} if the symbolic link shall be relative, {@code false} if it shall be absolute.

75

*/

76

  void symlink(Path source, Path targetLink, boolean relative);

77

78

/**

79

   * Creates a relative symbolic link. If the given {@code targetLink} already exists and is a symbolic link or a Windows junction, it will be replaced. In case

80

   * of missing privileges, Windows Junctions may be used as fallback, which must point to absolute paths. Therefore, the created link will be absolute instead

81

   * of relative.

82

83

   * @param source the source {@link Path} to link to, may be relative or absolute.

84

   * @param targetLink the {@link Path} where the symbolic link shall be created pointing to {@code source}.

85

*/

86

  default void symlink(Path source, Path targetLink) {

87

90

91

/**

92

   * @param source the source {@link Path file or folder} to copy.

93

   * @param target the {@link Path} to copy {@code source} to. See {@link #copy(Path, Path, FileCopyMode)} for details. Will always ensure that in the end

94

   *     you will find the same content of {@code source} in {@code target}.

95

*/

96

  default void copy(Path source, Path target) {

97

100

101

/**

102

   * @param source the source {@link Path file or folder} to copy.

103

   * @param target the {@link Path} to copy {@code source} to. Unlike the Linux {@code cp} command this method will not take the filename of {@code source}

104

   *     and copy that to {@code target} in case that is an existing folder. Instead it will always be simple and stupid and just copy from {@code source} to

105

   *     {@code target}. Therefore the result is always clear and easy to predict and understand. Also you can easily rename a file to copy. While

106

   *     {@code cp my-file target} may lead to a different result than {@code cp my-file target/} this method will always ensure that in the end you will find

107

   *     the same content of {@code source} in {@code target}.

108

   * @param mode the {@link FileCopyMode}.

109

*/

110

  default void copy(Path source, Path target, FileCopyMode mode) {

111

114

115

/**

116

   * @param source the source {@link Path file or folder} to copy.

117

   * @param target the {@link Path} to copy {@code source} to. Unlike the Linux {@code cp} command this method will not take the filename of {@code source}

118

   *     and copy that to {@code target} in case that is an existing folder. Instead it will always be simple and stupid and just copy from {@code source} to

119

   *     {@code target}. Therefore the result is always clear and easy to predict and understand. Also you can easily rename a file to copy. While

120

   *     {@code cp my-file target} may lead to a different result than {@code cp my-file target/} this method will always ensure that in the end you will find

121

   *     the same content of {@code source} in {@code target}.

122

   * @param mode the {@link FileCopyMode}.

123

   * @param listener the {@link PathCopyListener} that will be called for each copied {@link Path}.

124

*/

125

  void copy(Path source, Path target, FileCopyMode mode, PathCopyListener listener);

126

127

/**

128

   * @param archiveFile the {@link Path} to the file to extract.

129

   * @param targetDir the {@link Path} to the directory where to extract the {@code archiveFile} to.

130

*/

131

  default void extract(Path archiveFile, Path targetDir) {

132

135

136

/**

137

   * @param archiveFile the {@link Path} to the archive file to extract.

138

   * @param targetDir the {@link Path} to the directory where to extract the {@code archiveFile}.

139

   * @param postExtractHook the {@link Consumer} to be called after the extraction on the final folder before it is moved to {@code targetDir}.

140

*/

141

  default void extract(Path archiveFile, Path targetDir, Consumer<Path> postExtractHook) {

142

145

146

/**

147

   * @param archiveFile the {@link Path} to the archive file to extract.

148

   * @param targetDir the {@link Path} to the directory where to extract the {@code archiveFile}.

149

   * @param postExtractHook the {@link Consumer} to be called after the extraction on the final folder before it is moved to {@code targetDir}.

150

   * @param extract {@code true} if the {@code archiveFile} should be extracted (default), {@code false} otherwise.

151

*/

152

  void extract(Path archiveFile, Path targetDir, Consumer<Path> postExtractHook, boolean extract);

153

154

/**

155

   * Extracts a ZIP file what is the common archive format on Windows. Initially invented by PKZIP for MS-DOS and also famous from WinZIP software for Windows.

156

157

   * @param file the ZIP file to extract.

158

   * @param targetDir the {@link Path} with the directory to unzip to.

159

*/

160

  void extractZip(Path file, Path targetDir);

161

162

/**

163

   * @param file the ZIP file to extract.

164

   * @param targetDir the {@link Path} with the directory to unzip to.

165

   * @param compression the {@link TarCompression} to use.

166

*/

167

  void extractTar(Path file, Path targetDir, TarCompression compression);

168

169

/**

170

   * @param file the JAR file to extract.

171

   * @param targetDir the {@link Path} with the directory to extract to.

172

*/

173

  void extractJar(Path file, Path targetDir);

174

175

/**

176

   * Extracts an Apple DMG (Disk Image) file that is similar to an ISO image. DMG files are commonly used for software releases on MacOS. Double-clicking such

177

   * files on MacOS mounts them and show the application together with a symbolic link to the central applications folder and some help instructions. The user

178

   * then copies the application to the applications folder via drag and drop in order to perform the installation.

179

180

   * @param file the DMG file to extract.

181

   * @param targetDir the target directory where to extract the contents to.

182

*/

183

  void extractDmg(Path file, Path targetDir);

184

185

/**

186

   * Extracts an MSI (Microsoft Installer) file. MSI files are commonly used for software releases on Windows that allow an installation wizard and easy later

187

   * uninstallation.

188

189

   * @param file the MSI file to extract.

190

   * @param targetDir the target directory where to extract the contents to.

191

*/

192

  void extractMsi(Path file, Path targetDir);

193

194

/**

195

   * Extracts an Apple PKG (Package) file. PKG files are used instead of {@link #extractDmg(Path, Path) DMG files} if additional changes have to be performed

196

   * like drivers to be installed. Similar to what {@link #extractMsi(Path, Path) MSI} is on Windows. PKG files are internally a xar based archive with a

197

   * specific structure.

198

199

   * @param file the PKG file to extract.

200

   * @param targetDir the target directory where to extract the contents to.

201

*/

202

  void extractPkg(Path file, Path targetDir);

203

204

/**

205

   * @param path the {@link Path} to convert.

206

   * @return the absolute and physical {@link Path} (without symbolic links).

207

*/

208

  Path toRealPath(Path path);

209

210

/**

211

   * Deletes the given {@link Path} idempotent and recursive.

212

213

   * @param path the {@link Path} to delete.

214

*/

215

  void delete(Path path);

216

217

/**

218

   * Creates a new temporary directory. ATTENTION: The user of this method is responsible to do house-keeping and {@link #delete(Path) delete} it after the work

219

   * is done.

220

221

   * @param name the default name of the temporary directory to create. A prefix or suffix may be added to ensure uniqueness.

222

   * @return the {@link Path} to the newly created and unique temporary directory.

223

*/

224

  Path createTempDir(String name);

225

226

/**

227

   * @param dir the folder to search.

228

   * @param filter the {@link Predicate} used to find the {@link Predicate#test(Object) match}.

229

   * @param recursive - {@code true} to search recursive in all sub-folders, {@code false} otherwise.

230

   * @return the first child {@link Path} matching the given {@link Predicate} or {@code null} if no match was found.

231

*/

232

  Path findFirst(Path dir, Predicate<Path> filter, boolean recursive);

233

234

/**

235

   * @param dir the {@link Path} to the directory where to list the children.

236

   * @param filter the {@link Predicate} used to {@link Predicate#test(Object) decide} which children to include (if {@code true} is returned).

237

   * @return all children of the given {@link Path} that match the given {@link Predicate}. Will be the empty list of the given {@link Path} is not an existing

238

   *     directory.

239

*/

240

  List<Path> listChildren(Path dir, Predicate<Path> filter);

241

242

/**

243

   * Finds the existing file with the specified name in the given list of directories.

244

245

   * @param fileName The name of the file to find.

246

   * @param searchDirs The list of directories to search for the file.

247

   * @return The {@code Path} of the existing file, or {@code null} if the file is not found.

248

*/

249

  Path findExistingFile(String fileName, List<Path> searchDirs);

250

251

/**

252

   * Checks if the given directory is empty.

253

254

   * @param dir The {@link Path} object representing the directory to check.

255

   * @return {@code true} if the directory is empty, {@code false} otherwise.

256

*/

257

  boolean isEmptyDir(Path dir);

258

259

/**

260

   * Makes a file executable (analog to 'chmod a+x').

261

262

   * @param file {@link Path} to the file.

263

*/

264

  default void makeExecutable(Path file) {

265

268

269

/**

270

   * Makes a file executable (analog to 'chmod a+x').

271

272

   * @param file {@link Path} to the file.

273

   * @param confirm - {@code true} to get user confirmation before adding missing executable flags, {@code false} otherwise (always set missing flags).

274

*/

275

  void makeExecutable(Path file, boolean confirm);

276

277

/**

278

   * Like the linux touch command this method will update the modification time of the given {@link Path} to the current

279

   * {@link System#currentTimeMillis() system time}. In case the file does not exist, it will be created as empty file. If already the

280

   * {@link Path#getParent() parent folder} does not exist, the operation will fail.

281

282

   * @param file the {@link Path} to the file or folder.

283

*/

284

  void touch(Path file);

285

devonfw / IDEasy / 12708813826

Source File
Press 'n' to go to next uncovered line, 'b' for previous

1	package com.devonfw.tools.ide.io;
2
3	import java.nio.file.Path;
4	import java.nio.file.attribute.PosixFilePermission;
5	import java.util.List;
6	import java.util.Set;
7	import java.util.function.Consumer;
8	import java.util.function.Predicate;
9
10	/**
11	* Interface that gives access to various operations on files.
12	*/
13	public interface FileAccess {
14
15	/** {@link PosixFilePermission}s for "rwxr-xr-x" or 0755. */
16	Set<PosixFilePermission> RWX_RX_RX = Set.of(PosixFilePermission.OWNER_READ, PosixFilePermission.OWNER_WRITE, PosixFilePermission.OWNER_EXECUTE,	10✔
17	PosixFilePermission.GROUP_READ, PosixFilePermission.GROUP_EXECUTE, PosixFilePermission.OTHERS_READ, PosixFilePermission.OTHERS_EXECUTE);
18
19	/**
20	* Downloads a file from an arbitrary location.
21	*
22	* @param url the location of the binary file to download. May also be a local or remote path to copy from.
23	* @param targetFile the {@link Path} to the target file to download to. Should not already exist. Missing parent directories will be created
24	* automatically.
25	*/
26	void download(String url, Path targetFile);
27
28	/**
29	* Creates the entire {@link Path} as directories if not already existing.
30	*
31	* @param directory the {@link Path} to {@link java.nio.file.Files#createDirectories(Path, java.nio.file.attribute.FileAttribute...) create}.
32	*/
33	void mkdirs(Path directory);
34
35	/**
36	* @param file the {@link Path} to check.
37	* @return {@code true} if the given {@code file} points to an existing file, {@code false} otherwise (the given {@link Path} does not exist or is a
38	* directory).
39	*/
40	boolean isFile(Path file);
41
42	/**
43	* @param folder the {@link Path} to check.
44	* @return {@code true} if the given {@code folder} points to an existing directory, {@code false} otherwise (a warning is logged in this case).
45	*/
46	boolean isExpectedFolder(Path folder);
47
48	/**
49	* @param file the {@link Path} to compute the checksum of.
50	* @return the computed checksum (SHA-266).
51	*/
52	String checksum(Path file);
53
54	/**
55	* Moves the given {@link Path} to the backup.
56	*
57	* @param fileOrFolder the {@link Path} to move to the backup (soft-deletion).
58	*/
59	void backup(Path fileOrFolder);
60
61	/**
62	* @param source the source {@link Path file or folder} to move.
63	* @param targetDir the {@link Path} with the directory to move {@code source} into.
64	*/
65	void move(Path source, Path targetDir);
66
67	/**
68	* Creates a symbolic link. If the given {@code targetLink} already exists and is a symbolic link or a Windows junction, it will be replaced. In case of
69	* missing privileges, Windows Junctions may be used as fallback, which must point to absolute paths. Therefore, the created link will be absolute instead of
70	* relative.
71	*
72	* @param source the source {@link Path} to link to, may be relative or absolute.
73	* @param targetLink the {@link Path} where the symbolic link shall be created pointing to {@code source}.
74	* @param relative - {@code true} if the symbolic link shall be relative, {@code false} if it shall be absolute.
75	*/
76	void symlink(Path source, Path targetLink, boolean relative);
77
78	/**
79	* Creates a relative symbolic link. If the given {@code targetLink} already exists and is a symbolic link or a Windows junction, it will be replaced. In case
80	* of missing privileges, Windows Junctions may be used as fallback, which must point to absolute paths. Therefore, the created link will be absolute instead
81	* of relative.
82	*
83	* @param source the source {@link Path} to link to, may be relative or absolute.
84	* @param targetLink the {@link Path} where the symbolic link shall be created pointing to {@code source}.
85	*/
86	default void symlink(Path source, Path targetLink) {
87
88	symlink(source, targetLink, true);	5✔
89	}	1✔
90
91	/**
92	* @param source the source {@link Path file or folder} to copy.
93	* @param target the {@link Path} to copy {@code source} to. See {@link #copy(Path, Path, FileCopyMode)} for details. Will always ensure that in the end
94	* you will find the same content of {@code source} in {@code target}.
95	*/
96	default void copy(Path source, Path target) {
97
98	copy(source, target, FileCopyMode.COPY_TREE_FAIL_IF_EXISTS);	5✔
99	}	1✔
100
101	/**
102	* @param source the source {@link Path file or folder} to copy.
103	* @param target the {@link Path} to copy {@code source} to. Unlike the Linux {@code cp} command this method will not take the filename of {@code source}
104	* and copy that to {@code target} in case that is an existing folder. Instead it will always be simple and stupid and just copy from {@code source} to
105	* {@code target}. Therefore the result is always clear and easy to predict and understand. Also you can easily rename a file to copy. While
106	* {@code cp my-file target} may lead to a different result than {@code cp my-file target/} this method will always ensure that in the end you will find
107	* the same content of {@code source} in {@code target}.
108	* @param mode the {@link FileCopyMode}.
109	*/
110	default void copy(Path source, Path target, FileCopyMode mode) {
111
112	copy(source, target, mode, PathCopyListener.NONE);	6✔
113	}	1✔
114
115	/**
116	* @param source the source {@link Path file or folder} to copy.
117	* @param target the {@link Path} to copy {@code source} to. Unlike the Linux {@code cp} command this method will not take the filename of {@code source}
118	* and copy that to {@code target} in case that is an existing folder. Instead it will always be simple and stupid and just copy from {@code source} to
119	* {@code target}. Therefore the result is always clear and easy to predict and understand. Also you can easily rename a file to copy. While
120	* {@code cp my-file target} may lead to a different result than {@code cp my-file target/} this method will always ensure that in the end you will find
121	* the same content of {@code source} in {@code target}.
122	* @param mode the {@link FileCopyMode}.
123	* @param listener the {@link PathCopyListener} that will be called for each copied {@link Path}.
124	*/
125	void copy(Path source, Path target, FileCopyMode mode, PathCopyListener listener);
126
127	/**
128	* @param archiveFile the {@link Path} to the file to extract.
129	* @param targetDir the {@link Path} to the directory where to extract the {@code archiveFile} to.
130	*/
131	default void extract(Path archiveFile, Path targetDir) {
132
133	extract(archiveFile, targetDir, null);	5✔
134	}	1✔
135
136	/**
137	* @param archiveFile the {@link Path} to the archive file to extract.
138	* @param targetDir the {@link Path} to the directory where to extract the {@code archiveFile}.
139	* @param postExtractHook the {@link Consumer} to be called after the extraction on the final folder before it is moved to {@code targetDir}.
140	*/
141	default void extract(Path archiveFile, Path targetDir, Consumer<Path> postExtractHook) {
142
143	extract(archiveFile, targetDir, postExtractHook, true);	6✔
144	}	1✔
145
146	/**
147	* @param archiveFile the {@link Path} to the archive file to extract.
148	* @param targetDir the {@link Path} to the directory where to extract the {@code archiveFile}.
149	* @param postExtractHook the {@link Consumer} to be called after the extraction on the final folder before it is moved to {@code targetDir}.
150	* @param extract {@code true} if the {@code archiveFile} should be extracted (default), {@code false} otherwise.
151	*/
152	void extract(Path archiveFile, Path targetDir, Consumer<Path> postExtractHook, boolean extract);
153
154	/**
155	* Extracts a ZIP file what is the common archive format on Windows. Initially invented by PKZIP for MS-DOS and also famous from WinZIP software for Windows.
156	*
157	* @param file the ZIP file to extract.
158	* @param targetDir the {@link Path} with the directory to unzip to.
159	*/
160	void extractZip(Path file, Path targetDir);
161
162	/**
163	* @param file the ZIP file to extract.
164	* @param targetDir the {@link Path} with the directory to unzip to.
165	* @param compression the {@link TarCompression} to use.
166	*/
167	void extractTar(Path file, Path targetDir, TarCompression compression);
168
169	/**
170	* @param file the JAR file to extract.
171	* @param targetDir the {@link Path} with the directory to extract to.
172	*/
173	void extractJar(Path file, Path targetDir);
174
175	/**
176	* Extracts an Apple DMG (Disk Image) file that is similar to an ISO image. DMG files are commonly used for software releases on MacOS. Double-clicking such
177	* files on MacOS mounts them and show the application together with a symbolic link to the central applications folder and some help instructions. The user
178	* then copies the application to the applications folder via drag and drop in order to perform the installation.
179	*
180	* @param file the DMG file to extract.
181	* @param targetDir the target directory where to extract the contents to.
182	*/
183	void extractDmg(Path file, Path targetDir);
184
185	/**
186	* Extracts an MSI (Microsoft Installer) file. MSI files are commonly used for software releases on Windows that allow an installation wizard and easy later
187	* uninstallation.
188	*
189	* @param file the MSI file to extract.
190	* @param targetDir the target directory where to extract the contents to.
191	*/
192	void extractMsi(Path file, Path targetDir);
193
194	/**
195	* Extracts an Apple PKG (Package) file. PKG files are used instead of {@link #extractDmg(Path, Path) DMG files} if additional changes have to be performed
196	* like drivers to be installed. Similar to what {@link #extractMsi(Path, Path) MSI} is on Windows. PKG files are internally a xar based archive with a
197	* specific structure.
198	*
199	* @param file the PKG file to extract.
200	* @param targetDir the target directory where to extract the contents to.
201	*/
202	void extractPkg(Path file, Path targetDir);
203
204	/**
205	* @param path the {@link Path} to convert.
206	* @return the absolute and physical {@link Path} (without symbolic links).
207	*/
208	Path toRealPath(Path path);
209
210	/**
211	* Deletes the given {@link Path} idempotent and recursive.
212	*
213	* @param path the {@link Path} to delete.
214	*/
215	void delete(Path path);
216
217	/**
218	* Creates a new temporary directory. ATTENTION: The user of this method is responsible to do house-keeping and {@link #delete(Path) delete} it after the work
219	* is done.
220	*
221	* @param name the default name of the temporary directory to create. A prefix or suffix may be added to ensure uniqueness.
222	* @return the {@link Path} to the newly created and unique temporary directory.
223	*/
224	Path createTempDir(String name);
225
226	/**
227	* @param dir the folder to search.
228	* @param filter the {@link Predicate} used to find the {@link Predicate#test(Object) match}.
229	* @param recursive - {@code true} to search recursive in all sub-folders, {@code false} otherwise.
230	* @return the first child {@link Path} matching the given {@link Predicate} or {@code null} if no match was found.
231	*/
232	Path findFirst(Path dir, Predicate<Path> filter, boolean recursive);
233
234	/**
235	* @param dir the {@link Path} to the directory where to list the children.
236	* @param filter the {@link Predicate} used to {@link Predicate#test(Object) decide} which children to include (if {@code true} is returned).
237	* @return all children of the given {@link Path} that match the given {@link Predicate}. Will be the empty list of the given {@link Path} is not an existing
238	* directory.
239	*/
240	List<Path> listChildren(Path dir, Predicate<Path> filter);
241
242	/**
243	* Finds the existing file with the specified name in the given list of directories.
244	*
245	* @param fileName The name of the file to find.
246	* @param searchDirs The list of directories to search for the file.
247	* @return The {@code Path} of the existing file, or {@code null} if the file is not found.
248	*/
249	Path findExistingFile(String fileName, List<Path> searchDirs);
250
251	/**
252	* Checks if the given directory is empty.
253	*
254	* @param dir The {@link Path} object representing the directory to check.
255	* @return {@code true} if the directory is empty, {@code false} otherwise.
256	*/
257	boolean isEmptyDir(Path dir);
258
259	/**
260	* Makes a file executable (analog to 'chmod a+x').
261	*
262	* @param file {@link Path} to the file.
263	*/
264	default void makeExecutable(Path file) {
265
266	makeExecutable(file, false);	×
267	}	×
268
269	/**
270	* Makes a file executable (analog to 'chmod a+x').
271	*
272	* @param file {@link Path} to the file.
273	* @param confirm - {@code true} to get user confirmation before adding missing executable flags, {@code false} otherwise (always set missing flags).
274	*/
275	void makeExecutable(Path file, boolean confirm);
276
277	/**
278	* Like the linux touch command this method will update the modification time of the given {@link Path} to the current
279	* {@link System#currentTimeMillis() system time}. In case the file does not exist, it will be created as empty file. If already the
280	* {@link Path#getParent() parent folder} does not exist, the operation will fail.
281	*
282	* @param file the {@link Path} to the file or folder.
283	*/
284	void touch(Path file);
285	}

devonfw / IDEasy / 12708813826

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous