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.filefilter;
18
19 import java.io.File;
20 import java.io.Serializable;
21 import java.nio.file.FileVisitResult;
22 import java.nio.file.Files;
23 import java.nio.file.Path;
24 import java.nio.file.attribute.BasicFileAttributes;
25
26 /**
27 * This filter accepts {@link File}s that are symbolic links.
28 * <p>
29 * For example, here is how to print out a list of the real files
30 * within the current directory:
31 * </p>
32 * <h2>Using Classic IO</h2>
33 * <pre>
34 * File dir = FileUtils.current();
35 * String[] files = dir.list(SymbolicLinkFileFilter.INSTANCE);
36 * for (String file : files) {
37 * System.out.println(file);
38 * }
39 * </pre>
40 *
41 * <h2>Using NIO</h2>
42 * <pre>
43 * final Path dir = PathUtils.current();
44 * final AccumulatorPathVisitor visitor = AccumulatorPathVisitor.withLongCounters(SymbolicLinkFileFilter.INSTANCE);
45 * //
46 * // Walk one dir
47 * Files.<b>walkFileTree</b>(dir, Collections.emptySet(), 1, visitor);
48 * System.out.println(visitor.getPathCounters());
49 * System.out.println(visitor.getFileList());
50 * //
51 * visitor.getPathCounters().reset();
52 * //
53 * // Walk dir tree
54 * Files.<b>walkFileTree</b>(dir, visitor);
55 * System.out.println(visitor.getPathCounters());
56 * System.out.println(visitor.getDirList());
57 * System.out.println(visitor.getFileList());
58 * </pre>
59 * <h2>Deprecating Serialization</h2>
60 * <p>
61 * <em>Serialization is deprecated and will be removed in 3.0.</em>
62 * </p>
63 *
64 * @since 2.11.0
65 * @see FileFilterUtils#fileFileFilter()
66 */
67 public class SymbolicLinkFileFilter extends AbstractFileFilter implements Serializable {
68 /*
69 * Note to developers: The unit test needs to create symbolic links to files. However, on
70 * Windows, this can't be done without admin privileges. This class is designed to allow a
71 * unit test to works around this by doing two things: 1) This separates the class logic from
72 * the call to identify a symbolic link, and 2) It allows the unit test to override that
73 * symbolic link call on Windows only.
74 * This means we can write unit tests that will run on all machines. On Windows, the unit test
75 * can't create a symbolic link without admin privileges, so the unit tests won't
76 * completely test all the necessary behavior on Windows, but they will still test the class
77 * logic. Be careful not to break this, but be aware of it when writing unit tests. You can
78 * still maintain this class and its unit tests on Windows. The one method that won't get
79 * tested on Windows is not likely to change, and will be tested properly when it gets run
80 * on Apache servers.
81 */
82
83 /**
84 * Singleton instance of file filter.
85 */
86 public static final SymbolicLinkFileFilter INSTANCE = new SymbolicLinkFileFilter();
87
88 private static final long serialVersionUID = 1L;
89
90 /**
91 * Restrictive constructor.
92 */
93 protected SymbolicLinkFileFilter() {
94 }
95
96 /**
97 * Constructs a new instance.
98 *
99 * @param onAccept What to do on acceptance.
100 * @param onReject What to do on rejection.
101 * @since 2.12.0.
102 */
103 public SymbolicLinkFileFilter(final FileVisitResult onAccept, final FileVisitResult onReject) {
104 super(onAccept, onReject);
105 }
106
107 /**
108 * Checks to see if the file is a symbolic link.
109 *
110 * @param file the File to check
111 * @return true if the file exists and is a symbolic link to either another file or a directory,
112 * false otherwise.
113 */
114 @Override
115 public boolean accept(final File file) {
116 return isSymbolicLink(file.toPath());
117 }
118
119 /**
120 * Checks to see if the file is a symbolic link.
121 *
122 * @param path the File Path to check
123 * @return {@code onAccept} from {@link #SymbolicLinkFileFilter(FileVisitResult, FileVisitResult)} if the file exists and is a symbolic link to either
124 * another file or a directory; returns {@code onReject} otherwise.
125 */
126 @Override
127 public FileVisitResult accept(final Path path, final BasicFileAttributes attributes) {
128 return toFileVisitResult(isSymbolicLink(path));
129 }
130
131 /**
132 * Delegates to {@link Files#isSymbolicLink(Path)} for testing.
133 * <p>
134 * Using package access for unit tests. To facilitate unit testing, all calls to test if the file is a symbolic should go through this method. (See the unit
135 * test for why.)
136 * </p>
137 *
138 * @param filePath The filePath to test
139 * @return true if the file exists and is a symbolic link to either a file or directory, false otherwise.
140 */
141 boolean isSymbolicLink(final Path filePath) {
142 return Files.isSymbolicLink(filePath);
143 }
144 }